Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions changelog/unreleased/exec-json-compat.md
Original file line number Diff line number Diff line change
@@ -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.
10 changes: 10 additions & 0 deletions changelog/unreleased/exec-json.md
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 7 additions & 0 deletions changelog/unreleased/exec-output-errors.md
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 2 additions & 2 deletions client/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}

Expand Down
12 changes: 6 additions & 6 deletions cmd/agentctl/delete_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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") {
Expand All @@ -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")
Expand Down
118 changes: 91 additions & 27 deletions cmd/agentctl/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ import (
"bytes"
"context"
"encoding/json"
"errors"
"flag"
"fmt"
"io"
Expand Down Expand Up @@ -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")
Expand All @@ -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()
Expand All @@ -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
}
}
Expand Down
132 changes: 130 additions & 2 deletions cmd/agentctl/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"net"
"net/http"
Expand All @@ -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"
Expand Down Expand Up @@ -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 {
Expand All @@ -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{

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: the stream has OUTPUT but no INPUT, so a mutation that drops only INPUT passes both the agentctl and agentsessionsd tests. An INPUT frame in the supplied and expected stream would pin "every committed record". Separately, nothing covers text-mode exec with --session: setting newSession: true at main.go:356 passes every test. A row asserting no session line would cover it.

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
}
Loading
Loading