debugger: add events stream; rename listen → wait-for-reply, history → chat-history

`events` prints the session as a flat, timestamped, one-line-per-event stream
(messages, tool calls, handoffs, config changes, errors, agent state
transitions), replaying the most recent events by default and streaming new
ones with --follow; --logs adds agent log lines and --json emits NDJSON so
another program can consume the stream live. It observes through a separate
tap, so it never affects what `say` and `wait-for-reply` see.

Events now carry a `time` field (arrival time for live events, the SDK's
created_at for chat-history items), and agent state transitions are reported
on the stream as `state` events.

`listen` is renamed `wait-for-reply` and `history` is renamed `chat-history`
(the `transcript` alias stays).

Author: bcherry

README.md

@@ -491,8 +491,9 @@ A typical session, run from the agent project directory (`lk agent dbg` is short
 lk agent debugger start                       # starts the agent, prints its opening message if it has one
 lk agent debugger say "Hi, what can you do?"  # prints tool calls (with arguments and results), handoffs, and the reply
 lk agent debugger say "Book a table for two tonight"
-lk agent debugger listen --timeout 15s        # wait for the agent to speak unprompted (a timer, a follow-up after silence)
-lk agent debugger history                     # the whole conversation so far
+lk agent debugger wait-for-reply --timeout 15s   # wait for the agent to speak unprompted (a timer, a follow-up after silence)
+lk agent debugger chat-history                # the whole conversation so far
+lk agent debugger events --follow             # live, one-line-per-event stream of everything the session does
 lk agent debugger logs --last 40              # the agent process's logs (tracebacks, warnings)
 lk agent debugger status                      # active agent, its tools, state, log file
 lk agent debugger stop --transcript           # closing summary, plus the whole conversation
@@ -504,10 +505,11 @@ Useful options:
 
 -   `say --logs` shows the agent's log lines beneath the step they belong to, so a tool's traceback appears right under the sanitized error the user would hear.
 -   `say --timeout 30s` bounds how long to wait for the reply (default 2 minutes); the exit code is non-zero if the turn failed or timed out.
--   `--json` on any command prints machine-readable output. Each turn is a document with `text`, `reply`, `duration_ms`, and an `events` list of `message`, `tool_call`, `handoff`, `config`, `error`, and `log` entries.
+-   `--json` on any command prints machine-readable output. Each turn is a document with `text`, `reply`, `duration_ms`, and an `events` list of `message`, `tool_call`, `handoff`, `config`, `error`, `log`, and (on the events stream) `state` entries, each with a `time`.
 -   `--metrics` adds per-turn latency metrics (time to first token, end-to-end).
 -   `restart` relaunches the agent with a fresh conversation after the code changes.
--   `listen --timeout 15s` waits for the agent to speak unprompted, for example after a tool set a timer, and prints whatever it says.
+-   `wait-for-reply --timeout 15s` waits for the agent to speak unprompted, for example after a tool set a timer, and prints whatever it says.
+-   `events` prints the session as a flat, timestamped event stream (messages, tool calls, handoffs, state changes); `--follow` keeps streaming, `--logs` adds agent log lines, and `--json` emits NDJSON for piping into other tools.
 -   `--port` runs several sessions side by side (one agent per port).
 -   A session stops itself after 30 minutes without commands so a forgotten one doesn't linger; `start --idle-timeout` changes that (0 disables it).
 

autocomplete/fish_autocomplete

@@ -117,9 +117,10 @@ Typical flow, run from the agent project directory:
    lk agent debugger start                  # starts the agent, prints its greeting (if any)
    lk agent debugger say "Hi, what can you do?"
    lk agent debugger say "Book me a table for two tonight"
-   lk agent debugger listen --timeout 15s   # wait for the agent to speak unprompted (timers, follow-ups)
+   lk agent debugger wait-for-reply --timeout 15s   # wait for unprompted speech (timers, follow-ups)
    lk agent debugger logs --last 40         # agent process logs (tracebacks, warnings)
-   lk agent debugger history                # full transcript so far
+   lk agent debugger chat-history           # full transcript so far
+   lk agent debugger events --follow        # live one-line stream of every session event
    lk agent debugger stop --transcript      # closing summary, plus the conversation
 
 The agent is found the same way as for "lk agent console": the project in the
@@ -192,7 +193,7 @@ be piped on stdin:
 			Action: runSessionSay,
 		},
 		{
-			Name:  "listen",
+			Name:  "wait-for-reply",
 			Usage: "Wait for the agent to say something on its own (a greeting, timer, or follow-up) without sending a turn",
 			Description: `Prints agent output that no turn asked for. Anything already waiting is printed
 immediately; otherwise it waits up to --timeout for the agent to start
@@ -214,7 +215,7 @@ did not.`,
 			Action: runSessionListen,
 		},
 		{
-			Name:    "history",
+			Name:    "chat-history",
 			Aliases: []string{"transcript"},
 			Usage:   "Print the conversation so far, as the agent recorded it",
 			Description: `Fetches the agent's own chat history, so it reflects exactly what the LLM has
@@ -223,6 +224,28 @@ instruction/tool changes. Works while a turn is in progress.`,
 			Flags:  []cli.Flag{sessionPortFlag, jsonFlag, sessionMetricsFlag},
 			Action: runSessionHistory,
 		},
+		{
+			Name:  "events",
+			Usage: "Print the session's event stream, one line per event; --follow keeps streaming",
+			Description: `Shows what happened in the session as a flat, timestamped stream: user and
+agent messages, tool calls with arguments and results, handoffs, config
+changes, errors, and agent state transitions, one line each. It observes
+without taking part, so it works alongside "say" from another shell, a person
+on "lk agent console", or a script driving the session.
+
+By default the most recent events are printed and the command exits. With
+--follow it keeps printing new events until interrupted, and --logs adds the
+agent's log lines. --json emits one JSON object per line (NDJSON), suitable
+for piping into jq or another program in real time.`,
+			Flags: []cli.Flag{
+				sessionPortFlag,
+				jsonFlag,
+				&cli.IntFlag{Name: "last", Aliases: []string{"n"}, Value: 50, Usage: "How many recent events to print first (0 for all kept, up to 500)"},
+				&cli.BoolFlag{Name: "follow", Aliases: []string{"f"}, Usage: "Keep streaming new events until interrupted"},
+				&cli.BoolFlag{Name: "logs", Usage: "Include the agent's log lines in the stream"},
+			},
+			Action: runSessionEvents,
+		},
 		{
 			Name:  "status",
 			Usage: "Show whether a session is running, which agent is active, and its tools",
@@ -559,7 +582,7 @@ func runSessionSay(ctx context.Context, cmd *cli.Command) error {
 	return nil
 }
 
-// listenJSON is the --json document `listen` prints.
+// listenJSON is the --json document `wait-for-reply` prints.
 type listenJSON struct {
 	Events     []turnEvent `json:"events"`
 	Reply      string      `json:"reply"`
@@ -582,7 +605,7 @@ func runSessionListen(ctx context.Context, cmd *cli.Command) error {
 		conn.Close() // ctrl-C stops waiting cleanly
 	}()
 
-	if err := writeControlFrame(conn, controlRequest{Cmd: "listen", TimeoutMs: timeout.Milliseconds()}); err != nil {
+	if err := writeControlFrame(conn, controlRequest{Cmd: "wait", TimeoutMs: timeout.Milliseconds()}); err != nil {
 		return err
 	}
 
@@ -594,7 +617,7 @@ func runSessionListen(ctx context.Context, cmd *cli.Command) error {
 			return
 		}
 		e := *r.Event
-		e.Earlier = false // everything listen reports is, by definition, unprompted
+		e.Earlier = false // everything wait-for-reply reports is, by definition, unprompted
 		if asJSON {
 			doc.Events = append(doc.Events, e)
 			return
@@ -624,8 +647,50 @@ func runSessionListen(ctx context.Context, cmd *cli.Command) error {
 	return nil
 }
 
+func runSessionEvents(ctx context.Context, cmd *cli.Command) error {
+	conn, err := dialControl(int(cmd.Int("port")))
+	if err != nil {
+		return err
+	}
+	defer conn.Close()
+	follow := cmd.Bool("follow")
+	if !follow {
+		_ = conn.SetReadDeadline(time.Now().Add(15 * time.Second))
+	} else {
+		go func() {
+			<-ctx.Done()
+			conn.Close() // ctrl-C stops streaming cleanly
+		}()
+	}
+	last := int(cmd.Int("last"))
+	if last == 0 {
+		last = -1 // explicit 0: everything the daemon kept
+	}
+	if err := writeControlFrame(conn, controlRequest{Cmd: "events", Lines: last, Follow: follow, Logs: cmd.Bool("logs")}); err != nil {
+		return err
+	}
+	asJSON := cmd.Bool("json")
+	enc := json.NewEncoder(out.ResultWriter())
+	_, err = streamControlReplies(conn, func(r controlReply) {
+		if r.Event == nil {
+			return
+		}
+		if asJSON {
+			_ = enc.Encode(r.Event)
+			return
+		}
+		if line := renderEventLine(*r.Event); line != "" {
+			out.Result(line)
+		}
+	})
+	if err != nil && ctx.Err() != nil {
+		return nil
+	}
+	return err
+}
+
 func runSessionHistory(ctx context.Context, cmd *cli.Command) error {
-	reply, err := controlRoundTrip(int(cmd.Int("port")), controlRequest{Cmd: "history"}, 30*time.Second)
+	reply, err := controlRoundTrip(int(cmd.Int("port")), controlRequest{Cmd: "chat-history"}, 30*time.Second)
 	if err != nil {
 		return err
 	}
@@ -699,7 +764,7 @@ func runSessionStatus(ctx context.Context, cmd *cli.Command) error {
 	}
 	turns := strconv.Itoa(st.Turns)
 	if st.UnseenEvents > 0 {
-		turns += util.Dimmed(fmt.Sprintf(" (+%d agent event(s) not yet shown; run `lk agent debugger listen` to see them)", st.UnseenEvents))
+		turns += util.Dimmed(fmt.Sprintf(" (+%d agent event(s) not yet shown; run `lk agent debugger wait-for-reply` to see them)", st.UnseenEvents))
 	}
 	out.Resultf("%s%s\n", label("Turns:"), turns)
 	if st.IdleTimeoutSeconds > 0 {

cmd/lk/debugger.go

@@ -38,8 +38,12 @@ import (
 // emits them verbatim, so the schema doubles as the machine-readable contract
 // for coding agents driving the CLI.
 type turnEvent struct {
-	// Type is one of: message, tool_call, handoff, config, error, log.
+	// Type is one of: message, tool_call, handoff, config, error, log, state.
+	// "state" (agent state transitions, From → To) is only reported by the
+	// events stream, never inside a turn.
 	Type string `json:"type"`
+	// Time is when the event happened (RFC 3339 with milliseconds), when known.
+	Time string `json:"time,omitempty"`
 	// Role is "user" or "assistant" for message events.
 	Role string `json:"role,omitempty"`
 	// Text is the message text, error message, or log line.
@@ -88,6 +92,8 @@ type textSession struct {
 	mu          sync.Mutex
 	pending     map[string]chan *agent.SessionResponse
 	subs        map[*eventSub]struct{}
+	observers   map[*eventSub]struct{} // `events --follow` taps; never affect buffering
+	recent      []turnEvent            // ring of the latest events for `events`
 	undelivered []turnEvent
 	agentState  agent.AgentState
 	activity    chan struct{}
@@ -112,13 +118,14 @@ func newTextSession(conn net.Conn, reader io.Reader) *textSession {
 		reader = conn
 	}
 	s := &textSession{
-		conn:     conn,
-		reader:   reader,
-		pending:  make(map[string]chan *agent.SessionResponse),
-		subs:     make(map[*eventSub]struct{}),
-		activity: make(chan struct{}, 1),
-		turnSem:  make(chan struct{}, 1),
-		done:     make(chan struct{}),
+		conn:      conn,
+		reader:    reader,
+		pending:   make(map[string]chan *agent.SessionResponse),
+		subs:      make(map[*eventSub]struct{}),
+		observers: make(map[*eventSub]struct{}),
+		activity:  make(chan struct{}, 1),
+		turnSem:   make(chan struct{}, 1),
+		done:      make(chan struct{}),
 	}
 	go s.readLoop()
 	return s
@@ -196,13 +203,26 @@ func (s *textSession) notifyActivity() {
 	}
 }
 
+// recentEventsMax bounds the ring of events kept for `events`.
+const recentEventsMax = 500
+
+func eventTimestamp(t time.Time) string { return t.UTC().Format("2006-01-02T15:04:05.000Z07:00") }
+
 func (s *textSession) handleEvent(ev *agent.AgentSessionEvent) {
 	if ev == nil {
 		return
 	}
+	now := eventTimestamp(time.Now())
 	if sc, ok := ev.Event.(*agent.AgentSessionEvent_AgentStateChanged_); ok && sc.AgentStateChanged != nil {
 		s.mu.Lock()
+		old := s.agentState
 		s.agentState = sc.AgentStateChanged.NewState
+		// State transitions are noise inside a turn but useful on the event
+		// stream, so they go to observers (and the ring) only.
+		s.publishLocked([]turnEvent{{
+			Type: "state", Time: now,
+			From: agentStateName(old), To: agentStateName(sc.AgentStateChanged.NewState),
+		}}, false)
 		s.mu.Unlock()
 		s.notifyActivity()
 		return
@@ -211,21 +231,81 @@ func (s *textSession) handleEvent(ev *agent.AgentSessionEvent) {
 	if len(events) == 0 {
 		return
 	}
+	// Live events are stamped on arrival so the stream reads in order; the
+	// SDK's own created_at (kept for chat-history items) can predate the state
+	// transitions that surround it.
+	for i := range events {
+		events[i].Time = now
+	}
 	s.mu.Lock()
+	s.publishLocked(events, true)
+	s.mu.Unlock()
+	s.notifyActivity()
+}
+
+// publishLocked records events in the ring and hands them to observers; when
+// toTurns is set they also go to turn subscribers, or to the undelivered
+// buffer if nobody is listening. Caller holds s.mu.
+func (s *textSession) publishLocked(events []turnEvent, toTurns bool) {
+	s.recent = append(s.recent, events...)
+	if over := len(s.recent) - recentEventsMax; over > 0 {
+		s.recent = append([]turnEvent(nil), s.recent[over:]...)
+	}
+	for obs := range s.observers {
+		for _, e := range events {
+			select {
+			case obs.ch <- e:
+			default:
+			}
+		}
+	}
+	if !toTurns {
+		return
+	}
 	if len(s.subs) == 0 {
 		s.undelivered = append(s.undelivered, events...)
-	} else {
-		for sub := range s.subs {
-			for _, e := range events {
-				select {
-				case sub.ch <- e:
-				default:
-				}
+		return
+	}
+	for sub := range s.subs {
+		for _, e := range events {
+			select {
+			case sub.ch <- e:
+			default:
 			}
 		}
 	}
+}
+
+// observe taps the live event stream without affecting what turns see. It
+// returns the subscription and the most recent `last` events (all if last <= 0).
+func (s *textSession) observe(last int) (*eventSub, []turnEvent) {
+	obs := &eventSub{ch: make(chan turnEvent, 1024)}
+	s.mu.Lock()
+	recent := s.recent
+	if last > 0 && last < len(recent) {
+		recent = recent[len(recent)-last:]
+	}
+	snapshot := append([]turnEvent(nil), recent...)
+	s.observers[obs] = struct{}{}
+	s.mu.Unlock()
+	return obs, snapshot
+}
+
+func (s *textSession) unobserve(obs *eventSub) {
+	s.mu.Lock()
+	delete(s.observers, obs)
 	s.mu.Unlock()
-	s.notifyActivity()
+}
+
+// RecentEvents returns the most recent `last` events (all if last <= 0).
+func (s *textSession) RecentEvents(last int) []turnEvent {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	recent := s.recent
+	if last > 0 && last < len(recent) {
+		recent = recent[len(recent)-last:]
+	}
+	return append([]turnEvent(nil), recent...)
 }
 
 // subscribe starts receiving live events and, atomically with that, returns
@@ -629,7 +709,11 @@ func chatItemsToTurnEvents(items []*agent.ChatContext_ChatItem) []turnEvent {
 		case *agent.ChatContext_ChatItem_FunctionCall:
 			fc := i.FunctionCall
 			callIndex[fc.GetCallId()] = len(events)
-			events = append(events, turnEvent{Type: "tool_call", Name: fc.GetName(), Arguments: fc.GetArguments()})
+			e := turnEvent{Type: "tool_call", Name: fc.GetName(), Arguments: fc.GetArguments()}
+			if ts := fc.GetCreatedAt(); ts != nil {
+				e.Time = eventTimestamp(ts.AsTime())
+			}
+			events = append(events, e)
 		case *agent.ChatContext_ChatItem_FunctionCallOutput:
 			fco := i.FunctionCallOutput
 			if idx, ok := callIndex[fco.GetCallId()]; ok {
@@ -689,6 +773,9 @@ func messageToTurnEvent(msg *agent.ChatMessage) (turnEvent, bool) {
 		return turnEvent{}, false
 	}
 	e := turnEvent{Type: "message", Role: role, Text: text, Interrupted: msg.GetInterrupted()}
+	if ts := msg.GetCreatedAt(); ts != nil {
+		e.Time = eventTimestamp(ts.AsTime())
+	}
 	if m := msg.GetMetrics(); m != nil {
 		metrics := map[string]float64{}
 		if m.LlmNodeTtft != nil {