diff --git a/changelog/unreleased/exec-json-compat.md b/changelog/unreleased/exec-json-compat.md new file mode 100644 index 00000000..02a8a0dd --- /dev/null +++ b/changelog/unreleased/exec-json-compat.md @@ -0,0 +1,6 @@ +--- +category: Compatibility +--- + +- The human output of `agentctl exec`, `replay` and `fork` is for people and will change in a later + release. Scripts that parse it should move to `--json`; `exec` now supports it. diff --git a/changelog/unreleased/exec-json.md b/changelog/unreleased/exec-json.md new file mode 100644 index 00000000..05061fc0 --- /dev/null +++ b/changelog/unreleased/exec-json.md @@ -0,0 +1,10 @@ +--- +category: Added +--- + +- `agentctl exec --json` prints the turn as JSON Lines: one protobuf `ExecUpdate` per line as it + arrives, each a `session` or a committed `record`. The first line is the session, so a script + learns the UID of a session `exec` created; a turn paused for approval exits successfully and + ends with a `session` snapshot whose `pending_approval` names the call, unless a concurrent + approval has already resolved it. Only a recorded `EVENT_END` shows completion. Streamed model + chunks are left out; the `EVENT_OUTPUT` record carries the complete response. diff --git a/changelog/unreleased/exec-output-errors.md b/changelog/unreleased/exec-output-errors.md new file mode 100644 index 00000000..4547b2ee --- /dev/null +++ b/changelog/unreleased/exec-output-errors.md @@ -0,0 +1,7 @@ +--- +category: Fixed +--- + +- `agentctl exec` no longer exits successfully when writing to stdout fails. It stops writing, reads + the turn to its end so the turn is not cut short, then exits with an error noting that the turn's + records are committed. A closed pipe still ends `exec` with SIGPIPE, as before. diff --git a/client/client.go b/client/client.go index 4920d14c..2b2bd9c8 100644 --- a/client/client.go +++ b/client/client.go @@ -169,8 +169,8 @@ type ExecOptions struct { // OnRecord is called for each committed record as it arrives, for callers that want to react // during the turn rather than after it. OnRecord func(*v1.LogRecord) - // OnDelta is called for each streaming chunk. The server does not emit deltas yet, so this is - // wired for when it does rather than exercised today. + // OnDelta is called for each streaming chunk of a model call in progress. Chunks are not + // committed; a model call that completes records its complete response as an OUTPUT record. OnDelta func(*v1.Delta) } diff --git a/cmd/agentctl/delete_test.go b/cmd/agentctl/delete_test.go index 11d2896d..4f76fbbe 100644 --- a/cmd/agentctl/delete_test.go +++ b/cmd/agentctl/delete_test.go @@ -170,12 +170,12 @@ func TestEmbeddedDeleteAuditAndDescendants(t *testing.T) { } parent := mustRun("create", "--name", "parent") mustRun("exec", "--session", parent, "--input", "before") - fork := mustRun("fork", "--session", parent) - fields := strings.Fields(fork) - if len(fields) < 2 || fields[0] != "child" { - t.Fatalf("fork output: %s", fork) + fork := mustRun("fork", "--session", parent, "--json") + var forked v1.ForkResponse + if err := protojson.Unmarshal([]byte(fork), &forked); err != nil || len(forked.GetChildren()) != 1 { + t.Fatalf("fork output: %s %v", fork, err) } - child := fields[1] + child := forked.GetChildren()[0].GetMetadata().GetUid() deleted := mustRun("delete", "--session", parent) get := mustRun("get", "--session", parent) if detailValue(get, "Deletion") != "PENDING" || detailValue(get, "Deletion requested") == "" || strings.Contains(get, "deletion_completed") { @@ -184,7 +184,7 @@ func TestEmbeddedDeleteAuditAndDescendants(t *testing.T) { if retry := mustRun("delete", "--session", parent); retry != deleted { t.Fatalf("retry changed output/times:\n%s\n%s", deleted, retry) } - if replay := mustRun("replay", "--session", parent); !strings.Contains(replay, "EVENT_OUTPUT") || !strings.Contains(replay, "EVENT_LIFECYCLE") { + if replay := mustRun("replay", "--session", parent, "--json"); !strings.Contains(replay, `"EVENT_OUTPUT"`) || !strings.Contains(replay, `"LIFECYCLE_DELETE"`) { t.Fatalf("audit unavailable: %s", replay) } list := mustRun("list") diff --git a/cmd/agentctl/main.go b/cmd/agentctl/main.go index 244f4b24..ef6a88bb 100644 --- a/cmd/agentctl/main.go +++ b/cmd/agentctl/main.go @@ -23,6 +23,7 @@ import ( "bytes" "context" "encoding/json" + "errors" "flag" "fmt" "io" @@ -338,7 +339,7 @@ func cmdExec(args []string) error { return runExec(args, os.Stdout) } // runExec runs one turn and writes it to w as it happens. func runExec(args []string, w io.Writer) error { fs := flag.NewFlagSet("exec", flag.ExitOnError) - cfg := commonFlags(fs) + cfg := sessionFlags(fs) var sess, input, harness string fs.StringVar(&sess, "session", "", "session UID (created if empty)") fs.StringVar(&input, "input", "", "user input for this turn") @@ -352,49 +353,112 @@ func runExec(args []string, w io.Writer) error { // One call: an empty session is created by the server, and leaving ExpectedLastSeq nil appends // at the head. Records print as they commit rather than after the turn. - out := &execOutput{w: w} - defer out.endStream() - _, err = c.Exec(cmdCtx, client.ExecOptions{ + out := &execOutput{w: w, newSession: sess == ""} + opts := client.ExecOptions{ Session: sess, Inputs: []string{input}, Harness: harness, - OnSession: func(s *v1.Session) { - if sess == "" { - out.line(fmt.Sprintf("session %s", s.GetMetadata().GetUid())) - } - }, - OnRecord: func(r *v1.LogRecord) { out.line(formatRecord(r)) }, - OnDelta: out.delta, - }) + } + if cfg.json { + // Streamed deltas are left out: they are not committed, and a model call that completes + // records its complete response as an OUTPUT record. + opts.OnSession = out.jsonSession + opts.OnRecord = out.jsonRecord + } else { + opts.OnSession = out.textSession + opts.OnRecord = out.textRecord + opts.OnDelta = out.textDelta + } + result, err := c.Exec(cmdCtx, opts) + out.endStream() + if out.err != nil { + // Name the session and the store to read: replay with no --server or --journal would open the + // default local journal, not necessarily the one this turn used. + replay := "agentctl replay" + if result != nil && result.Session.GetMetadata().GetUid() != "" { + replay += " --session " + displayToken(result.Session.GetMetadata().GetUid()) + } + replay += " and the same --server or --journal" + if err != nil { + return errors.Join(err, fmt.Errorf("write exec output (see what was recorded with %s): %w", replay, out.err)) + } + return fmt.Errorf("write exec output (the turn was not interrupted and its records are committed; read them with %s): %w", replay, out.err) + } return err } // execOutput writes an exec turn as it arrives: whole lines (the session UID, committed records) -// and the model's streamed text. Streamed text is as untrusted as the committed message it -// previews, so it prints through the same escapeText and on its own "stream:" line, closed before -// the next whole line: a chunk cannot end the line, act on the terminal (hiding the tool call -// record that follows), or pass for a record. Each rune is escaped on its own, so a terminal -// sequence split across chunks (ESC in one, "[8m" in the next) is still inert. +// and the model's streamed text, or one ExecUpdate JSON object per line. Streamed text is as +// untrusted as the committed message it previews, so it prints through the same escapeText and on +// its own "stream:" line, closed before the next whole line: a chunk cannot end the line, act on +// the terminal (hiding the tool call record that follows), or pass for a record. Each rune is +// escaped on its own, so a terminal sequence split across chunks (ESC in one, "[8m" in the next) is +// still inert. +// +// After the first failed write it writes nothing more but keeps accepting updates, so the stream +// is still read to its end and the turn is not cut short by a failing stdout. type execOutput struct { - w io.Writer - streaming bool // a "stream:" line is open + w io.Writer + newSession bool // exec creates the session, so text output names it + streaming bool // a "stream:" line is open + err error // the first write or encoding error +} + +func (o *execOutput) write(s string) { + if o.err != nil { + return + } + if _, err := io.WriteString(o.w, s); err != nil { + o.err = err + } } func (o *execOutput) line(s string) { o.endStream() - _, _ = fmt.Fprintln(o.w, s) + o.write(s + "\n") +} + +// jsonSession and jsonRecord write a session frame or a committed record as an ExecUpdate line. +func (o *execOutput) jsonSession(s *v1.Session) { + o.jsonLine(&v1.ExecUpdate{Update: &v1.ExecUpdate_Session{Session: s}}) +} + +func (o *execOutput) jsonRecord(r *v1.LogRecord) { + o.jsonLine(&v1.ExecUpdate{Update: &v1.ExecUpdate_Record{Record: r}}) +} + +// jsonLine writes one ExecUpdate as a line of protobuf JSON. +func (o *execOutput) jsonLine(u *v1.ExecUpdate) { + if o.err != nil { + return + } + text, err := protoJSON(u) + if err != nil { + o.err = fmt.Errorf("encode protobuf JSON: %w", err) + return + } + o.line(text) } -// delta prints a chunk on the open stream line, opening one if needed, and closes the line when the -// model's response is done. The done frame is not relied on to close it: a failed model call sends -// none, so the next whole line or the end of the turn closes it instead. -func (o *execOutput) delta(d *v1.Delta) { +// textSession names a session that exec created; textRecord prints a committed record's line. +func (o *execOutput) textSession(s *v1.Session) { + if o.newSession { + o.line(fmt.Sprintf("session %s", s.GetMetadata().GetUid())) + } +} + +func (o *execOutput) textRecord(r *v1.LogRecord) { o.line(formatRecord(r)) } + +// textDelta prints a chunk on the open stream line, opening one if needed, and closes the line when +// the model's response is done. The done frame is not relied on to close it: a failed model call +// sends none, so the next whole line or the end of the turn closes it instead. +func (o *execOutput) textDelta(d *v1.Delta) { if chunk := d.GetChunk(); chunk != "" { if !o.streaming { - _, _ = io.WriteString(o.w, "stream: ") + o.write("stream: ") o.streaming = true } - _, _ = io.WriteString(o.w, escapeText(chunk)) + o.write(escapeText(chunk)) } if d.GetDone() { o.endStream() @@ -403,7 +467,7 @@ func (o *execOutput) delta(d *v1.Delta) { func (o *execOutput) endStream() { if o.streaming { - _, _ = fmt.Fprintln(o.w) + o.write("\n") o.streaming = false } } diff --git a/cmd/agentctl/main_test.go b/cmd/agentctl/main_test.go index 24dc6b16..ecb33d53 100644 --- a/cmd/agentctl/main_test.go +++ b/cmd/agentctl/main_test.go @@ -4,6 +4,7 @@ import ( "bytes" "context" "encoding/json" + "errors" "fmt" "net" "net/http" @@ -22,6 +23,8 @@ import ( "google.golang.org/grpc" "google.golang.org/grpc/codes" "google.golang.org/grpc/status" + "google.golang.org/protobuf/encoding/protojson" + "google.golang.org/protobuf/proto" "github.com/agent-primitives/sessions/api" v1 "github.com/agent-primitives/sessions/api/genpb" @@ -657,10 +660,12 @@ func TestExecStreamedTextEscaped(t *testing.T) { } } -// execStreamer answers Exec with fixed updates, as the daemon streams them. +// execStreamer answers Exec with fixed updates, as the daemon streams them, then ends the stream with +// err. type execStreamer struct { v1.UnimplementedSessionsServer updates []*v1.ExecUpdate + err error } func (s *execStreamer) Exec(_ *v1.ExecRequest, stream v1.Sessions_ExecServer) error { @@ -669,5 +674,128 @@ func (s *execStreamer) Exec(_ *v1.ExecRequest, stream v1.Sessions_ExecServer) er return err } } - return nil + return s.err +} + +// serveExec serves srv on a loopback port for the test and returns its address. +func serveExec(t *testing.T, srv v1.SessionsServer) string { + t.Helper() + lis, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + s := grpc.NewServer() + v1.RegisterSessionsServer(s, srv) + go func() { _ = s.Serve(lis) }() + t.Cleanup(s.Stop) + return lis.Addr().String() +} + +// exec --json prints every session frame and committed record as one protobuf ExecUpdate per line, +// with or without --session. Streamed deltas are left out, model text that could act on a terminal +// stays escaped, and the final session frame carries an approval pause. If the stream fails, the +// lines already written stay and the error is returned. +func TestExecJSON(t *testing.T) { + sessionUpdate := func(s *v1.Session) *v1.ExecUpdate { + return &v1.ExecUpdate{Update: &v1.ExecUpdate_Session{Session: s}} + } + first := sessionUpdate(&v1.Session{Metadata: &v1.ResourceMetadata{Uid: "sess-json"}}) + output := &v1.ExecUpdate{Update: &v1.ExecUpdate_Record{Record: &v1.LogRecord{Seq: 2, Event: &v1.Event{ + Kind: v1.EventKind_EVENT_OUTPUT, + Body: &v1.Event_Message{Message: wire.MessageToProto(api.TextMessage("assistant", "hi\x1b[8m\u202e\u009b"))}, + }}}} + delta := &v1.ExecUpdate{Update: &v1.ExecUpdate_Delta{Delta: &v1.Delta{Chunk: "hi\x1b"}}} + parked := sessionUpdate(&v1.Session{Metadata: &v1.ResourceMetadata{Uid: "sess-json"}, LastSeq: 2, + PendingApproval: &v1.ApprovalRef{ExecutionId: "exec-1", ToolCallId: "call_1", RequestSeq: 2}}) + for _, tt := range []struct { + name string + args []string + updates []*v1.ExecUpdate + err error + want []*v1.ExecUpdate + }{{ + name: "new session", + updates: []*v1.ExecUpdate{first, delta, output, parked}, + want: []*v1.ExecUpdate{first, output, parked}, + }, { + name: "existing session", + args: []string{"--session", "sess-json"}, + updates: []*v1.ExecUpdate{first, delta, output, parked}, + want: []*v1.ExecUpdate{first, output, parked}, + }, { + name: "stream error", + updates: []*v1.ExecUpdate{first, output}, + err: status.Error(codes.Unavailable, "connection reset"), + want: []*v1.ExecUpdate{first, output}, + }} { + t.Run(tt.name, func(t *testing.T) { + addr := serveExec(t, &execStreamer{updates: tt.updates, err: tt.err}) + var out bytes.Buffer + err := runExec(append([]string{"--server", addr, "--input", "hello", "--json"}, tt.args...), &out) + if status.Code(err) != status.Code(tt.err) { + t.Fatalf("exec error = %v, want code %v", err, status.Code(tt.err)) + } + if !strings.HasSuffix(out.String(), "\n") { + t.Fatalf("output %q does not end its last line", out.String()) + } + lines := strings.Split(strings.TrimSuffix(out.String(), "\n"), "\n") + if len(lines) != len(tt.want) { + t.Fatalf("got %d lines, want %d: %q", len(lines), len(tt.want), lines) + } + for i, line := range lines { + assertOneSafeLine(t, line) + var got v1.ExecUpdate + if err := protojson.Unmarshal([]byte(line), &got); err != nil || !proto.Equal(&got, tt.want[i]) { + t.Fatalf("line %d = %s (%v), want %v", i, line, err, tt.want[i]) + } + } + }) + } +} + +// A failed stdout write ends exec with an error instead of a successful exit, in both output modes, +// and nothing more is written after it. The error names the session to replay, and a stream error +// that follows is reported with it rather than in place of it. +func TestExecWriteError(t *testing.T) { + record := &v1.ExecUpdate{Update: &v1.ExecUpdate_Record{Record: &v1.LogRecord{Seq: 1, + Event: &v1.Event{Kind: v1.EventKind_EVENT_END}}}} + updates := []*v1.ExecUpdate{ + {Update: &v1.ExecUpdate_Session{Session: &v1.Session{Metadata: &v1.ResourceMetadata{Uid: "sess-write"}}}}, + {Update: &v1.ExecUpdate_Delta{Delta: &v1.Delta{Chunk: "hi"}}}, + record, + } + for _, streamErr := range []error{nil, status.Error(codes.Unavailable, "connection reset")} { + for _, args := range [][]string{nil, {"--json"}} { + t.Run(fmt.Sprint(status.Code(streamErr), args), func(t *testing.T) { + addr := serveExec(t, &execStreamer{updates: updates, err: streamErr}) + w := &failingWriter{err: errors.New("disk full")} + err := runExec(append([]string{"--server", addr, "--input", "hello"}, args...), w) + if !errors.Is(err, w.err) || streamErr != nil && status.Code(err) != status.Code(streamErr) { + t.Fatalf("exec error = %v, want the write error and code %v", err, status.Code(streamErr)) + } + if !strings.Contains(err.Error(), "agentctl replay --session sess-write and the same --server or --journal") { + t.Fatalf("exec error = %v, want a hint naming the session and its store", err) + } + if streamErr == nil && !strings.Contains(err.Error(), "records are committed") { + t.Fatalf("exec error = %v, want it to say the records are committed", err) + } + if streamErr != nil && strings.Contains(err.Error(), "records are committed") { + t.Fatalf("exec error = %v claims the turn finished although the stream failed", err) + } + if w.calls != 1 { + t.Fatalf("got %d writes, want none after the failed one", w.calls) + } + }) + } + } +} + +type failingWriter struct { + err error + calls int +} + +func (w *failingWriter) Write([]byte) (int, error) { + w.calls++ + return 0, w.err } diff --git a/cmd/agentctl/output.go b/cmd/agentctl/output.go index 3dcbe757..be8c0ab9 100644 --- a/cmd/agentctl/output.go +++ b/cmd/agentctl/output.go @@ -16,7 +16,7 @@ import ( func sessionFlags(fs *flag.FlagSet) *config { cfg := commonFlags(fs) - fs.BoolVar(&cfg.json, "json", false, "print protobuf JSON (replay: one LogRecord per line)") + fs.BoolVar(&cfg.json, "json", false, "print protobuf JSON (exec: one ExecUpdate per line; replay: one LogRecord per line)") return cfg } @@ -32,11 +32,20 @@ func writeOutput(text string) error { } func writeJSON(message proto.Message) error { - data, err := (protojson.MarshalOptions{UseProtoNames: true}).Marshal(message) + text, err := protoJSON(message) if err != nil { return fmt.Errorf("encode protobuf JSON response (successful operations remain committed): %w", err) } - return writeOutput(escapeFormatRunes(string(data)) + "\n") + return writeOutput(text + "\n") +} + +// protoJSON is message as the CLI's protobuf JSON, on one line without its newline. +func protoJSON(message proto.Message) (string, error) { + data, err := (protojson.MarshalOptions{UseProtoNames: true}).Marshal(message) + if err != nil { + return "", err + } + return escapeFormatRunes(string(data)), nil } func sessionDetails(s *v1.Session) string { diff --git a/cmd/agentsessionsd/lifecycle_e2e_test.go b/cmd/agentsessionsd/lifecycle_e2e_test.go index cdc5e0d9..02c5e26c 100644 --- a/cmd/agentsessionsd/lifecycle_e2e_test.go +++ b/cmd/agentsessionsd/lifecycle_e2e_test.go @@ -1,12 +1,19 @@ package main import ( + "maps" "os/exec" "path/filepath" "regexp" + "slices" "strings" "testing" "time" + + "google.golang.org/protobuf/encoding/protojson" + "google.golang.org/protobuf/proto" + + v1 "github.com/agent-primitives/sessions/api/genpb" ) // TestSessionLifecycleRealBinaries is the smoke test for the quickstart path: agentsessionsd on the @@ -55,32 +62,108 @@ func TestSessionLifecycleRealBinaries(t *testing.T) { } } + // exec, fork and replay are read through --json: their human views can change. Lines that are not + // JSON are diagnostics on stderr, which ctl merges into its output. + jsonLines := func(out string, decode func([]byte) error) { + t.Helper() + for _, line := range strings.Split(out, "\n") { + if strings.HasPrefix(line, "{") { + if err := decode([]byte(line)); err != nil { + t.Fatalf("decode %s: %v", line, err) + } + } + } + } + execRecords := func(args ...string) []*v1.LogRecord { + t.Helper() + var recs []*v1.LogRecord + jsonLines(ctl(append([]string{"exec", "--json"}, args...)...), func(b []byte) error { + var u v1.ExecUpdate + if err := protojson.Unmarshal(b, &u); err != nil { + return err + } + if r := u.GetRecord(); r != nil { + recs = append(recs, r) + } + return nil + }) + return recs + } + replayRecords := func(sess string) []*v1.LogRecord { + t.Helper() + var recs []*v1.LogRecord + jsonLines(ctl("replay", "--json", "--session", sess), func(b []byte) error { + var r v1.LogRecord + if err := protojson.Unmarshal(b, &r); err != nil { + return err + } + recs = append(recs, &r) + return nil + }) + return recs + } + // outputs is the text of each OUTPUT record, by seq. + outputs := func(recs []*v1.LogRecord) map[int64]string { + texts := map[int64]string{} + for _, r := range recs { + if r.GetEvent().GetKind() == v1.EventKind_EVENT_OUTPUT { + var text strings.Builder + for _, p := range r.GetEvent().GetMessage().GetParts() { + text.WriteString(p.GetText().GetText()) + } + texts[r.GetSeq()] = text.String() + } + } + return texts + } + expectOutput := func(recs []*v1.LogRecord, seq int64, text string) { + t.Helper() + if got, ok := outputs(recs)[seq]; !ok || got != text { + t.Fatalf("OUTPUT at seq %d = %q (present %v), want %q; records:\n%v", seq, got, ok, text, recs) + } + } + uid := strings.TrimSpace(ctl("create", "--name", "smoke-parent")) if !regexp.MustCompile(`^sess-[0-9a-f]+$`).MatchString(uid) { t.Fatalf("create printed %q, want a session UID", uid) } expectGet(uid, "smoke-parent", "0", "NONE", "PENDING", "ACTIVE", "unset") - out := ctl("exec", "--session", uid, "--input", "hello") - expect(out, `^seq=4 +EVENT_OUTPUT assistant: echo:hello$`) - expect(out, `^seq=5 +EVENT_END$`) + recs := execRecords("--session", uid, "--input", "hello") + expectOutput(recs, 4, "echo:hello") + if last := recs[len(recs)-1]; last.GetSeq() != 5 || last.GetEvent().GetEnd().GetState() != "COMPLETED" { + t.Fatalf("turn ended with %v, want END COMPLETED at seq 5", last) + } expect(ctl("suspend", "--session", uid), `^session `+uid+` suspend execution=COMPLETED compute=COLD last_seq=6$`) expectGet(uid, "smoke-parent", "6", "COLD", "COMPLETED", "ACTIVE", "unset") expect(ctl("resume", "--session", uid), `^session `+uid+` resume execution=COMPLETED compute=LIVE last_seq=7$`) - out = ctl("exec", "--session", uid, "--input", "again") - expect(out, `^seq=11 +EVENT_OUTPUT assistant: echo:again$`) + expectOutput(execRecords("--session", uid, "--input", "again"), 11, "echo:again") - child := expect(ctl("fork", "--session", uid, "--at", "5", "--names", "smoke-child"), - `^child (sess-[0-9a-f]+) parent=`+uid+` fork_seq=5 name=smoke-child$`)[1] + var forked v1.ForkResponse + jsonLines(ctl("fork", "--json", "--session", uid, "--at", "5", "--names", "smoke-child"), func(b []byte) error { + return protojson.Unmarshal(b, &forked) + }) + if len(forked.GetChildren()) != 1 || forked.GetChildren()[0].GetParentUid() != uid || forked.GetChildren()[0].GetForkSeq() != 5 || + forked.GetChildren()[0].GetMetadata().GetName() != "smoke-child" || !regexp.MustCompile(`^sess-[0-9a-f]+$`).MatchString(forked.GetChildren()[0].GetMetadata().GetUid()) { + t.Fatalf("fork = %v, want one child smoke-child of %s at seq 5", &forked, uid) + } + child := forked.GetChildren()[0].GetMetadata().GetUid() // The child shares the parent's history up to seq 5, so its turn sees "hello", not "again". - out = ctl("exec", "--session", child, "--input", "from child") - expect(out, `^seq=\d+ +EVENT_OUTPUT assistant: echo:from child$`) - replay := ctl("replay", "--session", child) - if got := regexp.MustCompile(`(?m)^seq=\d+ +EVENT_OUTPUT assistant: (.*)$`).FindAllStringSubmatch(replay, -1); len(got) != 2 || - got[0][1] != "echo:hello" || got[1][1] != "echo:from child" { - t.Fatalf("child replay outputs = %v, want echo:hello then echo:from child:\n%s", got, replay) + recs = execRecords("--session", child, "--input", "from child") + if got := outputs(recs); len(got) != 1 || !slices.Contains(slices.Collect(maps.Values(got)), "echo:from child") { + t.Fatalf("child turn outputs = %v, want echo:from child", got) + } + replay := replayRecords(child) + var got []string + for _, r := range replay { + if text, ok := outputs([]*v1.LogRecord{r})[r.GetSeq()]; ok { + got = append(got, text) + } + } + if len(got) != 2 || got[0] != "echo:hello" || got[1] != "echo:from child" { + t.Fatalf("child replay outputs = %q, want echo:hello then echo:from child", got) } list := ctl("list") @@ -99,11 +182,16 @@ func TestSessionLifecycleRealBinaries(t *testing.T) { expect(ctl("delete", "--session", child), `^session `+child+tombstone) expectGet(child, "smoke-child", `\d+`, `\w+`, "COMPLETED", "PENDING", regexp.QuoteMeta(requested)) before := replay - replay = ctl("replay", "--session", child) - if !strings.HasPrefix(replay, before) { - t.Fatalf("child replay lost records on delete:\nbefore\n%s\nafter\n%s", before, replay) + replay = replayRecords(child) + if len(replay) != len(before)+1 { + t.Fatalf("child replay has %d records after delete, want the %d before plus one", len(replay), len(before)) + } + if !slices.EqualFunc(before, replay[:len(before)], func(a, b *v1.LogRecord) bool { return proto.Equal(a, b) }) { + t.Fatalf("child replay changed on delete:\nbefore\n%v\nafter\n%v", before, replay) + } + if last := replay[len(replay)-1]; last.GetEvent().GetLifecycle().GetKind() != v1.Lifecycle_LIFECYCLE_DELETE { + t.Fatalf("child replay ends with %v, want the DELETE lifecycle record", last) } - expect(strings.TrimPrefix(replay, before), `\Aseq=\d+ +EVENT_LIFECYCLE\n\z`) if strings.Contains(ctl("list"), child) { t.Fatalf("list shows deleted session %s", child) } @@ -116,11 +204,11 @@ func TestSessionLifecycleRealBinaries(t *testing.T) { startServer(t, bin, addr, "-journal", journalPath) expectGet(uid, "smoke-parent", "12", `\w+`, "COMPLETED", "ACTIVE", "unset") expectGet(child, "smoke-child", `\d+`, `\w+`, "COMPLETED", "PENDING", regexp.QuoteMeta(requested)) - if again := ctl("replay", "--session", child); again != replay { - t.Fatalf("child replay changed across a restart:\nbefore\n%s\nafter\n%s", replay, again) + if again := replayRecords(child); !slices.EqualFunc(again, replay, func(a, b *v1.LogRecord) bool { return proto.Equal(a, b) }) { + t.Fatalf("child replay changed across a restart:\nbefore\n%v\nafter\n%v", replay, again) } if strings.Contains(ctl("list"), child) { t.Fatalf("list shows deleted session %s after a restart", child) } - expect(ctl("exec", "--session", uid, "--input", "after restart"), `^seq=16 +EVENT_OUTPUT assistant: echo:after restart$`) + expectOutput(execRecords("--session", uid, "--input", "after restart"), 16, "echo:after restart") } diff --git a/docs/approval-gated-tool.md b/docs/approval-gated-tool.md index 392cc96b..740a665b 100644 --- a/docs/approval-gated-tool.md +++ b/docs/approval-gated-tool.md @@ -112,6 +112,18 @@ control, format and other non-printing characters as escapes such as `\n`, `\x1b model's text cannot add a line that looks like a call, or use terminal escapes to hide part of the call. +A script can run the same turn with `-json` and detect the pause: the command exits successfully, +and its last line is a `session` update, a snapshot of the session as the stream closes. It holds +the session UID that `approve` and `deny` take, and its `pending_approval` holds the execution ID, +call ID and request sequence, unless a concurrent approval has already resolved the call; only a +recorded `EVENT_END` shows that the turn completed: + +```bash +set -o pipefail # a failed exec fails the pipeline, not just jq +bin/agentctl exec -server 127.0.0.1:8080 -harness publisher -input 'Publish the text: hello' -json | + jq -c 'select(.session.pending_approval) | {session: .session.metadata.uid, pending_approval: .session.pending_approval}' +``` + Stop the daemon and the harness (Ctrl-C) and start them again with the same commands. Nothing has run, and the request is still pending; `replay` shows the exact call you are deciding on: diff --git a/docs/quickstart.md b/docs/quickstart.md index 9cf800f1..67feefb0 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -34,7 +34,8 @@ go build -o agentsessionsd ./cmd/agentsessionsd ``` Release archives and container images are published only for tagged releases. The release pinned -below, v0.4.0, runs every section as shown. +below, v0.4.0, runs every section as shown except `exec --json`, which needs a build from `main` +until the next release. ```bash # Release archive: both binaries, for linux/darwin on amd64/arm64. @@ -276,7 +277,8 @@ replace `--journal ...` on the client commands with `--server 127.0.0.1:8080`. ### CLI output and server defaults -This subsection needs `agentctl` v0.4.0 or later (see [Install](#install)). v0.3.0 ignores +This subsection needs `agentctl` v0.4.0 or later (see [Install](#install)); `exec --json` needs a +build from `main` until the next release. v0.3.0 ignores `AGENTSESSIONS_SERVER` and silently uses a local `agentsessions.db`; with that release, pass `--server 127.0.0.1:8080` on each command of the example below instead. @@ -332,7 +334,9 @@ subsequent columns without expanding the other rows. Table alignment assumes single-width characters; wide characters and combining marks can shift columns. Use `--json` when character widths matter to a consumer. -For agents and scripts, use `--json` rather than parsing the human views: +For agents and scripts, use `--json` rather than parsing the human views. The human output of +`exec`, `replay` and `fork` is for people and can change between releases; the JSON is the format +to parse: | Commands | JSON response | |---|---| @@ -340,6 +344,7 @@ For agents and scripts, use `--json` rather than parsing the human views: | `list` | One `ListSessionsResponse`, combining all pages with no next-page token | | `fork` | One `ForkResponse` containing `children` | | `approve`, `deny` | One `ApproveResponse` containing the original committed decision and resumed session | +| `exec` | JSON Lines: one protobuf `ExecUpdate` per line as the turn runs, each a `session` or a committed `record` | | `replay` | JSON Lines: one complete protobuf `LogRecord` per line, in sequence order | All CLI JSON uses protobuf's snake_case field names, full enum names (for example, @@ -350,11 +355,69 @@ matches CHAIN-1, but CLI JSON is not the RFC 8785 canonical byte representation Harness commands retain their existing JSON format. ```bash +set -o pipefail # a failed agentctl fails the pipeline, not just jq agentctl get --server= --journal /tmp/qs.db --session "$SID" --json | jq '.compute_state' agentctl list --server= --journal /tmp/qs.db --json | jq -r '.sessions[]? | .metadata.uid' agentctl replay --server= --journal /tmp/qs.db --session "$SID" --json > records.jsonl +agentctl exec --server= --journal /tmp/qs.db --session "$SID" --input "hello again" --json | + jq -r 'select(.record.event.kind == "EVENT_OUTPUT") | [.record.event.message.parts[]?.text.text // empty] | join("")' +``` + +For example, a turn on a new session with the default `echo` harness, `agentctl exec --server= +--journal /tmp/qs.db --input hello --json`, prints six lines: the session, then records 1 to 5 +(`EXECUTION_START`, `INPUT`, `MODEL_CALL`, `OUTPUT`, `END`). Its first line and its `EVENT_OUTPUT` +line, pretty-printed with `jq .`: + +```json +{ + "session": { + "metadata": { + "project": "default", + "uid": "sess-c8ee5796a843c2e1ab52574f", + "create_time": "2026-11-18T17:50:06.868696886Z", + "update_time": "2026-11-18T17:50:06.868696886Z" + }, + "harness": "echo", + "exec_state": "EXEC_PENDING", + "compute_state": "COMPUTE_NONE", + "deletion_state": "DELETION_ACTIVE" + } +} +{ + "record": { + "seq": "4", + "prev_hash": "04e48225040b1b85ad920f6c637463c324016f1c58e97f20b3caf9b3958a691a", + "content_hash": "7ba925d93b4dd7f231058a713916ba9d4e75fc2f4e5edece4d01177b41d81577", + "fence": "1", + "event": { + "execution_id": "f5e321cc1d47a8cb", + "kind": "EVENT_OUTPUT", + "message": { + "role": "assistant", + "parts": [ + { + "text": { + "text": "echo:hello" + } + } + ] + } + } + } +} ``` +Exec JSON starts with a `session` update, so a script learns the UID of a session that `exec` +created, then prints each record as it is committed. An `exec` record line holds the same +`LogRecord` a `replay` line does, under `record`. The model's streamed chunks are left out: they are +not committed, and a model call that completes records its whole response in `EVENT_OUTPUT`. A turn +that pauses for approval exits successfully and ends with a `session` update, a snapshot of the +session as the stream closes, whose `pending_approval` names the call unless a concurrent approval +has already resolved it. Only a recorded `EVENT_END` shows that a turn completed. Ignore update +kinds you do not expect, since later releases may add some. If the stream fails, the lines already +written stay and the command exits with an error; it does not retry the turn. Read the stream to its +end: on Unix, closing the pipe early ends `exec` with SIGPIPE, which can cut an embedded turn short. + Replay JSON retains full hashes, sequence numbers and protobuf field presence; `--json` takes precedence over `-v`. It only reads recorded events, never calls a model, and does not itself verify the chain; use `agentctl verify` for verification. An empty replay writes no lines. Treat output @@ -364,7 +427,9 @@ Human output is uncolored; color support is deferred. Diagnostics and the deleti go to stderr, including in JSON mode, so stdout remains parseable. On Unix, unary response commands report broken stdout pipes as output errors on stderr rather than exiting via SIGPIPE, noting that successful mutations remain committed. `exec` retains its -existing streaming signal behavior. +existing streaming signal behavior. Other stdout write errors no longer go unnoticed: `exec` stops +writing, reads the turn to its end so it is not cut short, then exits with an error noting that the +turn's records are committed. **Migration:** `get` no longer emits a single key/value line; `list` now has aligned columns and headings, even when empty. Lifecycle and approval summaries use short state values and include @@ -373,8 +438,8 @@ for example, `decision.contentHash` becomes `decision.content_hash`, and `sessio `session.last_seq`. `create` still prints only the UID by default; `fork` retains its existing default summary. Deletion still warns that PENDING is durable intent, not resource cleanup. Approval still reports a committed decision if Resume fails; JSON -does not turn that failure into a successful response. `exec` output is unchanged and has no -`--json` flag. +does not turn that failure into a successful response. `exec` human output is unchanged; scripts +that parse it should switch to `exec --json`. ## 7. Verify the provenance chain with a non-Go verifier diff --git a/examples/agentsuite-substrate/demo.sh b/examples/agentsuite-substrate/demo.sh index 7952367a..e7d1b027 100755 --- a/examples/agentsuite-substrate/demo.sh +++ b/examples/agentsuite-substrate/demo.sh @@ -59,17 +59,32 @@ print("generation %s %s %s" % (s["generation"], s["fidelity"], s["durableSnapsho actor_state() { "${ATE[@]}" get actor "$1" -a "${ATESPACE}" -o json | python3 -c 'import json,sys; print(json.load(sys.stdin)["status"]["state"])'; } actor_uid() { "${ATE[@]}" get actor "$1" -a "${ATESPACE}" -o json | python3 -c 'import json,sys; print(json.load(sys.stdin)["metadata"].get("uid", ""))'; } agentctl() { "${WORK}/bin/agentctl" "$1" --server "${SERVER}" "${@:2}"; } +# The checks below read agentctl's --json output, not its human views, which can change. +# texts KIND ROLE: from agentctl JSON Lines on stdin (replay's LogRecords or exec's ExecUpdates), +# the text of each KIND record whose message has ROLE, one per line. Newlines print as \n and other +# control and format characters as \xNN or \uNNNN, as agentctl's human output prints them, so a +# reply quoted in a failure message cannot act on the terminal. +texts() { + jq -r --arg kind "$1" --arg role "$2" '(.record // .) | .event // empty + | select(.kind == $kind and .message.role == $role) + | [.message.parts[]?.text.text // empty] | join("") | gsub("\n"; "\\n")' | + python3 -c 'import sys, unicodedata +for line in sys.stdin: + print("".join(c if unicodedata.category(c)[0] != "C" else ("\\x%02x" if ord(c) < 128 else "\\u%04x") % ord(c) + for c in line.rstrip("\n")))' +} inputs() { # session -> the user inputs its journal holds, in order, joined by '|' - agentctl replay --session "$1" | sed -n 's/^seq=[0-9]* *EVENT_INPUT user: //p' | paste -sd '|' - + agentctl replay --session "$1" --json | texts EVENT_INPUT user | paste -sd '|' - } records() { # session kind -> how many records of that kind its journal holds - agentctl replay --session "$1" | awk -v k="$2" '$2 == k { n++ } END { print n + 0 }' + agentctl replay --session "$1" --json | jq -s --arg kind "$2" 'map(select(.event.kind == $kind)) | length' } say() { # session input -> prints the turn, sets REPLY to the assistant text - local out - out="$(agentctl exec --session "$1" --input "$2")" - echo "${out}" - REPLY="$(sed -n 's/^seq=[0-9]* *EVENT_OUTPUT assistant: //p' <<<"${out}" | tail -1)" + local out from + out="$(agentctl exec --session "$1" --input "$2" --json)" + from="$(jq -rs 'map(select(.record))[0].record.seq // empty' <<<"${out}")" + agentctl replay --session "$1" --from "${from}" + REPLY="$(texts EVENT_OUTPUT assistant <<<"${out}" | tail -1)" } (cd "${ROOT}" && go build -o "${WORK}/bin/agentctl" ./cmd/agentctl) @@ -159,13 +174,14 @@ else fi step "7. Fork at the end of turn 1 and diverge" -FORK_SEQ="$(agentctl replay --session "${SID}" | awk '/EVENT_END/ { sub("seq=", "", $1); print $1; exit }')" -CHILD="$(agentctl fork --session "${SID}" --at "${FORK_SEQ}" --names after-turn-1 | awk '{ print $2 }')" +# jq reads all of replay's output (-s): stopping at the first match could end replay with SIGPIPE. +FORK_SEQ="$(agentctl replay --session "${SID}" --json | jq -rs 'map(select(.event.kind == "EVENT_END"))[0].seq // empty')" +CHILD="$(agentctl fork --session "${SID}" --at "${FORK_SEQ}" --names after-turn-1 --json | jq -r '.children[0].metadata.uid')" echo "child ${CHILD} forked at seq ${FORK_SEQ}" say "${CHILD}" "actually, the printer is on fire" [[ -n "${REAL}" || "${REPLY}" == *"1) my laptop will not boot; 2) actually, the printer is on fire | next"* ]] || fail "child did not diverge from turn 1: ${REPLY}" "${ATE[@]}" get actor "${CHILD}" -a "${ATESPACE}" -PARENT_LAST="$(agentctl replay --session "${SID}" | sed -n 's/^seq=[0-9]* *EVENT_OUTPUT assistant: //p' | tail -1)" +PARENT_LAST="$(agentctl replay --session "${SID}" --json | texts EVENT_OUTPUT assistant | tail -1)" [[ -n "${REAL}" || "${PARENT_LAST}" == *"4) also, my password expired"* ]] || fail "parent changed" [[ "$(inputs "${CHILD}")" == "my laptop will not boot|actually, the printer is on fire" ]] || fail "child journal inputs are not turn 1 plus its own: $(inputs "${CHILD}")" diff --git a/examples/agentsuite-substrate/demo/driver.sh b/examples/agentsuite-substrate/demo/driver.sh index 8a4f55e9..84b72eca 100755 --- a/examples/agentsuite-substrate/demo/driver.sh +++ b/examples/agentsuite-substrate/demo/driver.sh @@ -114,7 +114,7 @@ cleanup() { rm -rf "${LOGS}/trace" && cp -r "${TRACE_DIR}" "${LOGS}/trace" 2>/dev/null || true fi for p in "${PIDS[@]}"; do kill "${p}" 2>/dev/null || true; done - rm -f "${TOKEN_FILE}" + rm -f "${TOKEN_FILE}" "${PRIVATE:-}" # A failed setup deletes the cluster only if this invocation created it, so a run on a shared host # leaves nothing behind; a cluster it reused (a rerun of setup on an installed cluster, say) keeps # its daemons and their session journals, as up.sh does, and a failed show keeps it too, so either @@ -383,8 +383,8 @@ reset() { # Every command on screen is the literal command line that runs: run prints it, evaluates it in this # shell (so $COPY, $IMAGE and the rest are this shell's variables, set by an earlier command on # screen or, for $IMAGE, $TEMPLATE, $MEMTEMPLATE, $API, $API_MEM and $ROUTER, from setup's state -# before the title card; show.log records their values; $CHILD is read from the line agentctl fork -# prints on screen, and the chapter's log records it), writes its complete output to the +# before the title card; show.log records their values; $CHILD is the fork's child in agentctl +# list --json, and the chapter's log records it), writes its complete output to the # chapter's log, and shows that output. A command must exit 0 (run -x: must fail) and write nothing # to stderr, which the screen would not show. A screen shows at most MAX_LINES output rows (run -n # raises it for the trace); a file screen (run -f) shows its output whole, in pages if it is taller @@ -468,6 +468,10 @@ show_file() { # show_file); the command sees LINES and COLUMNS set to the rows and columns left for its output. # -n MAX: this screen may show up to MAX output rows. RAW="${WORK}/run.out" RAW_ERR="${WORK}/run.err" +# PRIVATE (show only) holds agentctl JSON the logs must not carry: whole journals (with provider data +# such as opaque reasoning bytes) and the session list (with every session's metadata). show creates +# it with mktemp, readable by this user only; cleanup removes it. +PRIVATE="" run() { local what="" done="" expect_fail=false file=false max="${MAX_LINES}" while (($#)); do @@ -541,11 +545,53 @@ offscreen() { log "(exit ${rc})" return "${rc}" } -# journal SERVER SESSION: the session's journal (agentctl replay) in RAW and the log. -journal() { offscreen "the journal of $2" "${WORK}/bin/agentctl" replay --server "$1" --session "$2" || fail "agentctl replay $2 failed"; } -# last_seq KIND: the seq of the last record of KIND in RAW's journal. -last_seq() { python3 -c 'import re, sys; s = [int(m.group(1)) for m in re.finditer(r"^seq=(\d+) +" + sys.argv[1] + r"\b", open(sys.argv[2]).read(), re.M)]; print(s[-1] if s else "")' "$1" "${RAW}"; } -count() { python3 -c 'import re, sys; print(len(re.findall(r"^seq=\d+ +" + sys.argv[1] + r"\b", open(sys.argv[2]).read(), re.M)))' "$1" "${RAW}"; } +# journal SERVER SESSION: the session's journal (agentctl replay --json) in PRIVATE. The checks read it +# as JSON, not as agentctl's human view, which can change. The log gets one "seq kind" line per record +# instead of the JSON, which holds provider data (opaque reasoning bytes, for one) that redact cannot +# inspect; anything else agentctl printed, such as an error, is logged as it is. +journal() { + local rc=0 + log "(off screen, the journal of $2: agentctl replay --json --server $1 --session $2)" + "${WORK}/bin/agentctl" replay --json --server "$1" --session "$2" >"${PRIVATE}" 2>&1 || rc=$? + python3 -c 'import json, sys +for line in open(sys.argv[1]): + if line.startswith("{"): + r = json.loads(line) + print(r["seq"], r["event"]["kind"]) + else: + print(line, end="")' "${PRIVATE}" | redact >>"${STEP_LOG}" + log "(exit ${rc})" + ((rc == 0)) || fail "agentctl replay $2 failed" +} +# seqs [KIND]: the seqs of the journal's records of KIND, or of every record, in order. +seqs() { + python3 -c 'import json, sys +for line in open(sys.argv[2]): + if line.startswith("{"): + r = json.loads(line) + if sys.argv[1] in ("", r["event"]["kind"]): + print(r["seq"])' "${1:-}" "${PRIVATE}" +} +# last_seq [KIND]: the seq of the last record of KIND, or of the last record, in the journal. +last_seq() { seqs "${1:-}" | tail -1; } +count() { seqs "$1" | wc -l | tr -d ' '; } +# journal_check EXPR [ARG...]: exits 0 when the Python expression EXPR holds of the journal, given +# as rs (its records, decoded JSON, in order), text(r) (a message's text) and args (the ARGs). +journal_check() { + python3 -c 'import json, sys +rs = [json.loads(l) for l in open(sys.argv[1]) if l.startswith("{")] +args = sys.argv[3:] +def text(r): + return "".join(p.get("text", {}).get("text", "") for p in r["event"].get("message", {}).get("parts", [])) +sys.exit(0 if eval("(" + sys.argv[2] + ")") else 1)' "${PRIVATE}" "$@" +} +# hashes SEQ: the content hashes of the journal's records 1 to SEQ, one per line. +hashes() { + python3 -c 'import json, sys +for line in open(sys.argv[1]): + if line.startswith("{") and int(json.loads(line)["seq"]) <= int(sys.argv[2]): + print(json.loads(line).get("content_hash", ""))' "${PRIVATE}" "$1" +} actor_json() { # session: its actor's record in RAW and the log offscreen "the actor of $1" "${ATE[@]}" get actor "$1" -a "${ATESPACE}" -o json || fail "no actor for $1" } @@ -585,6 +631,7 @@ diagram() { show() { [[ -x "${WORK}/bin/agentctl" && -x "${WORK}/bin/replay" && -x "${WORK}/bin/emit" && -x "${WORK}/bin/harness" && -s "${EXPIRY_FILE}" ]] || fail "run driver.sh setup first" + PRIVATE="$(mktemp)" rm -f "${LOGS}"/ch-*.log "${LOGS}/timeline.tsv" # Exactly the paths the on-screen commands below write, never a glob: on a host /tmp is shared. rm -rf "${LOGS}/trace" /tmp/render /tmp/render-memory /tmp/render-arm64 /tmp/tampered "${TRACE_DIR}" @@ -837,11 +884,16 @@ EOF # --------------------------------------------------------------------------------------------- chapter 6 "The journal" "Every input, model call, answer and token count is a record that carries the previous record's hash" + journal "${SERVER}" "${COPY}" seq="$(last_seq EVENT_USAGE)" run < parent=... fork_seq=... name=..."). - CHILD="$(python3 -c 'import sys; w = sys.argv[1].split(); print(w[1] if len(w) > 1 and w[0] == "child" else "")' "${SHOWN}")" - [[ "${CHILD}" =~ ^sess-[0-9a-f]+$ ]] || fail "fork printed no child" - log "(CHILD=${CHILD}, read off screen from the line agentctl fork printed)" + # The child's UID, from the session list (agentctl list --json): its child of $COPY named + # haiku-branch, which must be the only one. Only the UID is logged, not the list, which holds + # every session on the server. + "${WORK}/bin/agentctl" list --json --server "${SERVER}" >"${PRIVATE}" 2>"${RAW_ERR}" || + fail "agentctl list failed: $(redact <"${RAW_ERR}")" + CHILD="$(python3 -c 'import json, sys +s = [x for x in json.load(open(sys.argv[1])).get("sessions", []) + if x.get("parent_uid") == sys.argv[2] and x.get("metadata", {}).get("name") == "haiku-branch"] +print(s[0]["metadata"]["uid"] if len(s) == 1 else "")' "${PRIVATE}" "${COPY}")" + [[ "${CHILD}" =~ ^sess-[0-9a-f]+$ ]] || fail "fork made no child named haiku-branch" + log "(CHILD=${CHILD}, the fork's child in the session list)" run -w "asking ${model} in the child" "answered" <<'EOF' agentctl exec --server $API --session $CHILD --input "Instead, rewrite the blurb as a haiku." >/tmp/child.txt EOF offscreen "the child's turn 2" cat /tmp/child.txt - grep -q '^seq=[0-9]* *EVENT_OUTPUT assistant: .' /tmp/child.txt || fail "the child's turn produced no answer" + journal "${SERVER}" "${CHILD}" + journal_check 'any(r["event"]["kind"] == "EVENT_OUTPUT" and int(r["seq"]) > int(args[0]) and text(r) for r in rs)' "${seq}" || + fail "the child's turn produced no answer" page "Both journals: the first turn they share (highlighted), then each one's own second turn" run <<'EOF' agentctl replay --server $API --session $COPY >/tmp/parent.txt && agentctl replay --server $API --session $CHILD >/tmp/child.txt @@ -930,15 +992,21 @@ EOF run -f < int(args[0]) + and text(r) == "Instead, rewrite the blurb as a haiku." for r in rs)' "${seq}" || fail "the child's second turn is not its own" # --------------------------------------------------------------------------------------------- chapter 10 "Guarding memory" "If a session's micro-VM is swapped behind AgentSessions' back, its next turn is refused" journal "${MEMSERVER}" "${MEM}" turns_before="$(count EVENT_END)" - seq="$(python3 -c 'import re, sys; print(re.findall(r"^seq=(\d+)", open(sys.argv[1]).read(), re.M)[-1])' "${RAW}")" + seq="$(last_seq)" run -w "deleting the session's micro-VM out of band" "deleted" <<'EOF' kubectl ate delete actor $MEM -a agentsuite-demo --any-state EOF @@ -968,7 +1036,7 @@ EOF agentctl replay --server \$API_MEM --session \$MEM --from ${seq} EOF journal "${MEMSERVER}" "${MEM}" - [[ "$(count EVENT_END)" == "${turns_before}" && "$(python3 -c 'import re, sys; print(re.findall(r"^seq=(\d+)", open(sys.argv[1]).read(), re.M)[-1])' "${RAW}")" == "${seq}" ]] || + [[ "$(count EVENT_END)" == "${turns_before}" && "$(last_seq)" == "${seq}" ]] || fail "the refused turn journaled something" # --------------------------------------------------------------------------------------------- diff --git a/examples/agentsuite-substrate/demo/record.sh b/examples/agentsuite-substrate/demo/record.sh index 2e5f41af..2aba8a85 100755 --- a/examples/agentsuite-substrate/demo/record.sh +++ b/examples/agentsuite-substrate/demo/record.sh @@ -333,7 +333,7 @@ collect() { echo " logs/ch-N.log. Files are printed by bat with scripts/bat.conf (colors, line numbers, wrapping at" echo " the terminal's width); split screens are scripts/split-view.py. \$IMAGE, \$TEMPLATE, \$MEMTEMPLATE," echo " \$API, \$API_MEM and \$ROUTER are set from setup's state before the title card (show.log has their" - echo " values); \$CHILD is read from the line \`agentctl fork\` prints on screen (ch-9.log has it); the" + echo " values); \$CHILD is the fork's child in \`agentctl list --json\` (ch-9.log has it); the" echo " other variables are set by a command on screen." echo "- The diagrams (build.mmd, run.mmd) are rendered with ${MERMAID_CLI} and spliced over the blocks" echo " chapters 2 and 4 draw for them (splice.py): $(awk -F'\t' '{ printf "%sthe %s diagram %s-%s s", (NR > 1 ? ", " : ""), ($1 == "magenta" ? "build" : $1 == "green" ? "run" : $1), $2, $3 }' "${OUT}/splice.tsv")." diff --git a/examples/agentsuite-substrate/demo/trace-turn.sh b/examples/agentsuite-substrate/demo/trace-turn.sh index 7dac9443..83784247 100755 --- a/examples/agentsuite-substrate/demo/trace-turn.sh +++ b/examples/agentsuite-substrate/demo/trace-turn.sh @@ -44,6 +44,17 @@ done kubectl ate logs actor "${session}" -a "${atespace}" --source lifecycle >"${dir}/actor-lifecycle.log" kubectl ate logs actor "${session}" -a "${atespace}" --source containers >"${dir}/harness.log" agentctl replay -v --server "${API:?}" --session "${session}" >"${dir}/journal.log" +# The model call hop reads the journal as JSON, since the human view can change: only its MODEL_CALL +# records, picked by their decoded kind (a regex could match a kind inside another record's data). +# That copy stays out of DIR: the journal holds provider data, such as opaque reasoning bytes, that +# the saved logs should not. +journal="$(mktemp)" +trap 'rm -f "${journal}"' EXIT +agentctl replay --json --server "${API:?}" --session "${session}" | + python3 -c 'import json, sys +for line in sys.stdin: + if line.startswith("{") and json.loads(line)["event"]["kind"] == "EVENT_MODEL_CALL": + print(line, end="")' >"${journal}" exec 2>&3 3>&- hop() { python3 "${here}/trace-hop.py" "$@"; } @@ -54,4 +65,4 @@ hop worker "\"method\":\"/ateworker\\.Worker/(RestoreWorkload|RunWorkload)\".*\" hop micro-VM '"Actor (started|restored)' "" "${dir}/actor-lifecycle.log" hop atenet-router "Route ok.*${session}" actor.name,targetAddr "${dir}"/ate-system.atenet-router*.log hop harness 'harness: model .* used [0-9]+ input' "" "${dir}/harness.log" -hop "model call" '^seq=[0-9]+ +EVENT_MODEL_CALL ' seq,model,input_hash "${dir}/journal.log" +hop "model call" '^\{' seq,model=event.model.model,input_hash=event.model.input_hash "${journal}" diff --git a/examples/agentsuite-substrate/scripts_test.go b/examples/agentsuite-substrate/scripts_test.go index 084a2dce..f67f6b26 100644 --- a/examples/agentsuite-substrate/scripts_test.go +++ b/examples/agentsuite-substrate/scripts_test.go @@ -1648,32 +1648,59 @@ func TestUpRendersTheDaemon(t *testing.T) { } // demoStubs prepares s for demo.sh in real-provider mode: an agentctl that keeps each session's -// journal in $STUB_DIR/j- and prints records the way agentctl does, a kubectl-ate that -// reports the actor states agentctl left and the actor's UID, a replay that counts the completed -// turns in the journal, and the template name up.sh would have rendered. STUB_FAULT makes agentctl -// or replay misbehave in one way (new-actor-on-resume: the resumed actor has another UID), so a -// test can show demo.sh's checks catch it. +// journal in $STUB_DIR/j- and prints records the way agentctl does, as text or, with +// --json, as JSON Lines, a kubectl-ate that reports the actor states agentctl left and the actor's +// UID, a replay that counts the completed turns in the journal, and the template name up.sh would +// have rendered. STUB_FAULT makes agentctl or replay misbehave in one way (new-actor-on-resume: the +// resumed actor has another UID), so a test can show demo.sh's checks catch it. func demoStubs(t *testing.T, s *stubs) { t.Helper() bin := filepath.Join(s.work, "bin") + // demo.sh reads agentctl's JSON with jq. PATH holds only the stubs (s.dir/bin) and the system + // directories, so expose the test's jq, which may be installed elsewhere (Homebrew's + // /opt/homebrew/bin). + jq, err := exec.LookPath("jq") + if err != nil { + t.Skip("jq not found") + } + if err := os.Symlink(jq, filepath.Join(s.dir, "bin", "jq")); err != nil { + t.Fatal(err) + } log := `echo "$(basename "$0") $*" >>"$STUB_DIR/calls"` + "\n" stub(t, bin, "agentctl", log+` cmd=$1 shift -sess= input= at= +sess= input= at= from=1 json= while [ $# -gt 0 ]; do case "$1" in --session) sess=$2; shift ;; --input) input=$2; shift ;; --at) at=$2; shift ;; + --from) from=$2; shift ;; + --json) json=1 ;; esac shift done -j="$STUB_DIR/j-$sess" -rec() { +j="$STUB_DIR/j-$sess" # one record per line: seq|kind|role|text +line() { # seq kind role text: one record as replay prints it + if [ -n "$json" ] && [ -n "$3" ]; then + printf '{"seq":"%s","event":{"kind":"%s","message":{"role":"%s","parts":[{"text":{"text":"%s"}}]}}}\n' "$1" "$2" "$3" "$4" + elif [ -n "$json" ]; then + printf '{"seq":"%s","event":{"kind":"%s"}}\n' "$1" "$2" + elif [ -n "$3" ]; then + printf 'seq=%-3d %s %s: %s\n' "$1" "$2" "$3" "$4" + else + printf 'seq=%-3d %s\n' "$1" "$2" + fi +} +rec() { # kind [role text]: append a record and print it as exec does n=$(($(wc -l <"$j") + 1)) - printf 'seq=%-3d %s\n' "$n" "$*" >>"$j" - printf 'seq=%-3d %s\n' "$n" "$*" + printf '%s|%s|%s|%s\n' "$n" "$1" "${2:-}" "${3:-}" >>"$j" + if [ -n "$json" ]; then + printf '{"record":%s}\n' "$(line "$n" "$1" "${2:-}" "${3:-}")" + else + line "$n" "$1" "${2:-}" "${3:-}" + fi } case "$cmd" in list) ;; @@ -1683,35 +1710,44 @@ create) ;; get) echo "session $sess" ;; exec) + [ -z "$json" ] || printf '{"session":{"metadata":{"uid":"%s"}}}\n' "$sess" turn=$(($(grep -c EVENT_END "$j") + 1)) - [ "$STUB_FAULT $turn" = "lost-input 2" ] || rec "EVENT_INPUT user: $input" + [ "$STUB_FAULT $turn" = "lost-input 2" ] || rec EVENT_INPUT user "$input" [ "$STUB_FAULT $turn" = "no-model-call 2" ] || [ "$STUB_FAULT $turn" = "no-model-call-4 4" ] || - [ "$STUB_FAULT $sess" = "no-child-model-call child-1" ] || rec "EVENT_MODEL_CALL" - rec "EVENT_OUTPUT assistant: a real reply $turn" - rec "EVENT_END" + [ "$STUB_FAULT $sess" = "no-child-model-call child-1" ] || rec EVENT_MODEL_CALL + rec EVENT_OUTPUT assistant "a real reply $turn" + rec EVENT_END echo ACTOR_STATE_RUNNING >"$STUB_DIR/state-$sess" ;; suspend) - [ "$STUB_FAULT" = no-lifecycle ] || rec "EVENT_LIFECYCLE" + [ "$STUB_FAULT" = no-lifecycle ] || rec EVENT_LIFECYCLE echo ACTOR_STATE_SUSPENDED >"$STUB_DIR/state-$sess" : >"$STUB_DIR/snap-$sess" ;; resume) - rec "EVENT_LIFECYCLE" + rec EVENT_LIFECYCLE echo ACTOR_STATE_RUNNING >"$STUB_DIR/state-$sess" [ "$STUB_FAULT" != new-actor-on-resume ] || echo "uid-$sess-2" >"$STUB_DIR/uid-$sess" ;; -replay) cat "$j" ;; +replay) + while IFS='|' read -r n kind role text; do + [ "$n" -lt "$from" ] || line "$n" "$kind" "$role" "$text" + done <"$j" + ;; fork) if [ "$STUB_FAULT" = whole-parent-fork ]; then cp "$j" "$STUB_DIR/j-child-1" else - awk -v at="$at" '{ s = $1; sub("seq=", "", s); if (s + 0 <= at + 0) print }' "$j" >"$STUB_DIR/j-child-1" + awk -F'|' -v at="$at" '$1 + 0 <= at + 0' "$j" >"$STUB_DIR/j-child-1" fi if [ "$STUB_FAULT" = fork-writes-parent ]; then - printf 'seq=%-3d %s\n' 99 "EVENT_INPUT user: stray" >>"$j" + echo '99|EVENT_INPUT|user|stray' >>"$j" + fi + if [ -n "$json" ]; then + printf '{"children":[{"metadata":{"uid":"child-1","name":"after-turn-1"},"parent_uid":"%s","fork_seq":"%s"}]}\n' "$sess" "$at" + else + echo "child child-1 parent=$sess fork_seq=$at name=after-turn-1" fi - echo "child child-1 parent=$sess fork_seq=$at name=after-turn-1" ;; *) exit 2 ;; esac diff --git a/hack/demos/kubernetes-tour.sh b/hack/demos/kubernetes-tour.sh index 5699d518..a12338f4 100755 --- a/hack/demos/kubernetes-tour.sh +++ b/hack/demos/kubernetes-tour.sh @@ -5,7 +5,7 @@ # call, fork into independent children, suspend and resume, listing, and finally pod death with # the session surviving it. # -# Requires: a cluster, kubectl, agentctl on PATH, and deploy/kubernetes/agentsessionsd.yaml applied. +# Requires: a cluster, kubectl, agentctl and jq on PATH, and deploy/kubernetes/agentsessionsd.yaml applied. set -euo pipefail NS=agentsessions @@ -61,14 +61,10 @@ say "agentsessionsd on a plain Kubernetes Deployment. One pod, one PersistentVol run 'kubectl -n $NS get deploy,pvc,pod -l app=agentsessionsd -o name' note "SERVER=$SERVER, forwarded from svc/agentsessionsd:8080" -say "1. Run a turn." -OUT=$(agentctl exec --server "$SERVER" --input "plan a trip to Tokyo" 2>/dev/null) -printf '%s$%s agentctl exec --input "plan a trip to Tokyo"\n' "$c_cmd" "$c_off" -sleep 0.7 -echo "$OUT" -SID=$(echo "$OUT" | head -1 | cut -d' ' -f2) -note "four typed records: the input, the host-mediated model call, the output, the end" -sleep 1.2 +say "1. Create a session and run a turn." +run 'SID=$(agentctl create --server $SERVER) && echo $SID' +run 'agentctl exec --server $SERVER --session $SID --input "plan a trip to Tokyo"' +note "five typed records: the start, the input, the host-mediated model call, the output, the end" say "2. Keep talking. The sequence keeps climbing in one log." run 'agentctl exec --server $SERVER --session $SID --input "make it a week"' @@ -82,8 +78,12 @@ FORKED=$(agentctl fork --server "$SERVER" --session "$SID" --at 4 --count 2 --na printf '%s$%s agentctl fork --session %s --at 4 --count 2 --names "budget,luxury"\n' "$c_cmd" "$c_off" "${SID:0:18}" sleep 0.7 echo "$FORKED" -# Reuse the first named child rather than forking a third one nobody saw being created. -CHILD=$(echo "$FORKED" | head -1 | cut -d' ' -f2) +# Reuse the child named "budget" rather than forking a third one nobody saw being created. Its UID +# comes from the session list as JSON, not from the fork output above, which is for people. +CHILD=$(agentctl list --server "$SERVER" --json | jq -r --arg p "$SID" \ + '[.sessions[]? | select(.parent_uid == $p and .metadata.name == "budget")] | if length == 1 then .[0].metadata.uid else empty end') +# stderr is discarded above, so the failure is reported on stdout. +[ -n "$CHILD" ] || { echo "fork made no single child named budget"; exit 1; } sleep 1.3 say "5. A child inherits the prefix, then diverges on its own." diff --git a/spec.md b/spec.md index b0900796..4fcd043c 100644 --- a/spec.md +++ b/spec.md @@ -88,9 +88,21 @@ an RPC, encoding or output failure is not converted into a success. Approval rec still reports that the decision committed. JSON serialization does not change canonical bytes, the hash chain or the journal format. -Without `--json`, `create` retains its bare UID output. `exec` streaming and harness JSON content -are unchanged. Approval JSON changes from lowerCamelCase to snake_case field names. Non-JSON -diagnostics, including the deletion PENDING warning, go to stderr even in JSON mode. +`exec --json` emits JSON Lines, one protobuf `ExecUpdate` per line in the order the stream delivers +them: `session` frames and committed `record`s, each record the same `LogRecord` `replay --json` +prints. The first line is the session frame `Exec` sends before the turn runs. A turn that pauses +for approval exits successfully and ends with a `session` frame: a snapshot of the session when the +stream closes, which carries `pending_approval` unless a concurrent decision has already resolved +it. Only a recorded `END` shows that a turn completed. Streamed `delta` chunks are not committed and +are omitted; readers ignore update kinds they do not expect. A stream error leaves the lines already +written and exits unsuccessfully, without retrying the turn. A failed stdout write ends the command +unsuccessfully after the stream is read to its end, except that on Unix a closed pipe still ends +`exec` with SIGPIPE, which can cut an embedded turn short; readers consume the whole stream. + +Without `--json`, `create` retains its bare UID output, and the human output of `exec`, `replay` and +`fork` is not a stable contract; scripts use `--json`. Harness JSON content is unchanged. Approval +JSON changes from lowerCamelCase to snake_case field names. Non-JSON diagnostics, including the +deletion PENDING warning, go to stderr even in JSON mode. Session commands default their endpoint from `AGENTSESSIONS_SERVER`; explicit `--server` wins, including an empty value to select embedded mode. An environment-selected target is announced on stderr before making requests; failure to write