@stigmer/cli 3.0.8

package/src/resources/stream/diff.ts

@@ -0,0 +1,254 @@
+// The snapshot→event differ: the headless analog of Go's streamToEvents
+// (run_stream_events.go:203-468).
+//
+// Go's version owns a gRPC loop and blocks on an approval channel. This is a
+// pure, stateful transformer instead: feed it each AgentExecution snapshot and
+// it returns the discrete events for that snapshot, holding all cross-snapshot
+// state (message cursor, tool/sub-agent/todo trackers, prompted-approval dedup).
+// Approval *submission* is the renderer's job — the differ only emits
+// ApprovalNeededEvent. The step numbering and ordering below mirror the Go body
+// exactly, because the resulting event sequence is a wire-parity contract.
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  buildApprovalNeeded,
+  buildPendingApprovalFromToolCall,
+  findAllUnpromptedApprovals,
+  hasUsableApproval,
+} from "./approval-detect.js";
+import {
+  collectToolCallsFromMessages,
+  convertToolCalls,
+  findToolCallById,
+  isApprovalNoiseMessage,
+  isTerminalAgentPhase,
+  mapPhaseToString,
+  mapSummarizationSource,
+  sanitizeSystemContent,
+} from "./convert.js";
+import type { StreamEvent } from "./events.js";
+import { SubAgentTracking } from "./subagent.js";
+import { TodoDiffer } from "./todo.js";
+import { buildToolEventMap, toolEventId, ToolStateTracker } from "./tool-state.js";
+
+/**
+ * Stateful differ. Construct one per execution stream, then call {@link next}
+ * for every snapshot in arrival order. Once a terminal `done` is emitted, later
+ * calls return nothing.
+ */
+export class SnapshotDiffer {
+  private displayedCount = 0;
+  private inStream = false;
+  private humanMessageEmitted = false;
+  private lastPhase: ExecutionPhase = ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+  private seenSummarizationCount = 0;
+  private finished = false;
+  private readonly promptedIds = new Set<string>();
+  private readonly topTools = new ToolStateTracker();
+  private readonly subAgentTracking = new SubAgentTracking();
+  private readonly todos = new TodoDiffer();
+
+  /** Project one snapshot into its events, advancing all internal state. */
+  next(execution: AgentExecution): StreamEvent[] {
+    if (this.finished) return [];
+    const out: StreamEvent[] = [];
+    const status = execution.status;
+    const messages = status?.messages ?? [];
+    const subAgents = status?.subAgentExecutions ?? [];
+    const phase = status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+
+    this.emitHumanMessage(out, execution);
+
+    // Step 1: track tool transitions, then interleave message + tool events.
+    const rootToolCalls = collectToolCallsFromMessages(messages);
+    const toolEvents = this.topTools.track(rootToolCalls, "");
+    const pendingTools = buildToolEventMap(toolEvents);
+    this.emitMessageEvents(out, messages, pendingTools);
+
+    // Step 1c: orphan tool events (no matching MESSAGE_TOOL this snapshot).
+    for (const ev of toolEvents) {
+      if (pendingTools.has(toolEventId(ev))) out.push(ev);
+    }
+
+    // Step 1d–1f: sub-agents, todos, context compaction.
+    if (subAgents.length > 0) out.push(...this.subAgentTracking.emit(subAgents));
+    const todos = status?.todos ?? {};
+    if (Object.keys(todos).length > 0 || this.todos.hasPrev) {
+      out.push(...this.todos.diff(todos));
+    }
+    this.emitContextCompaction(out, execution);
+
+    // Step 2: phase change (with approval cycle-reset) before approval handling.
+    this.emitPhaseChange(out, phase);
+
+    // Step 3 + 3b: approval detection (pending_approvals, then status scan).
+    this.emitApprovals(out, status?.pendingApprovals ?? [], rootToolCalls, subAgents, phase);
+
+    // Step 5: terminal → done.
+    if (isTerminalAgentPhase(phase)) {
+      this.finished = true;
+      out.push({ kind: "done", phase: mapPhaseToString(phase), error: status?.error ?? "" });
+    }
+
+    return out;
+  }
+
+  // Step 0: emit the user's input message once, suppressing the "execute"
+  // placeholder. Mirrors streamToEvents Step 0.
+  private emitHumanMessage(out: StreamEvent[], execution: AgentExecution): void {
+    if (this.humanMessageEmitted) return;
+    const msg = execution.spec?.message ?? "";
+    if (msg !== "" && msg !== "execute") {
+      out.push({ kind: "humanMessage", content: msg });
+      this.humanMessageEmitted = true;
+    }
+  }
+
+  // Steps 1b: convert new messages to events, interleaving matched tool events
+  // at their chronological position. Mirrors Go's emitMessageEvents.
+  private emitMessageEvents(out: StreamEvent[], messages: readonly AgentMessage[], pending: Map<string, StreamEvent>): void {
+    // Phase 1: an in-progress streaming AI message.
+    if (this.inStream && this.displayedCount < messages.length) {
+      const msg = messages[this.displayedCount];
+      if (msg.isStreaming) {
+        out.push({ kind: "aiStreamDelta", content: msg.content, subAgentId: "" });
+        return;
+      }
+      out.push({ kind: "aiStreamEnd", content: msg.content, toolCalls: convertToolCalls(msg.toolCalls), subAgentId: "" });
+      this.displayedCount++;
+      this.inStream = false;
+    }
+
+    // Phase 2: complete messages, detecting a new streaming start.
+    while (this.displayedCount < messages.length) {
+      const msg = messages[this.displayedCount];
+      if (msg.isStreaming && msg.type === MessageType.MESSAGE_AI) {
+        out.push({ kind: "aiStreamStart", content: msg.content, subAgentId: "" });
+        this.inStream = true;
+        return;
+      }
+      if (msg.type === MessageType.MESSAGE_HUMAN) {
+        this.displayedCount++;
+        continue;
+      }
+      if (this.isTrackedToolMessage(msg)) {
+        emitMatchedToolEvents(out, msg, pending);
+        this.displayedCount++;
+        continue;
+      }
+      this.emitCompleteMessage(out, msg);
+      this.displayedCount++;
+    }
+  }
+
+  // Emit one complete (non-streaming) message by type. Mirrors Go's emitCompleteMessage.
+  private emitCompleteMessage(out: StreamEvent[], msg: AgentMessage): void {
+    switch (msg.type) {
+      case MessageType.MESSAGE_HUMAN:
+        out.push({ kind: "humanMessage", content: msg.content });
+        return;
+      case MessageType.MESSAGE_AI:
+        out.push({ kind: "aiMessage", content: msg.content, toolCalls: convertToolCalls(msg.toolCalls), subAgentId: "" });
+        return;
+      case MessageType.MESSAGE_TOOL:
+        out.push({ kind: "toolResult", content: msg.content, toolCalls: convertToolCalls(msg.toolCalls) });
+        return;
+      case MessageType.MESSAGE_SYSTEM:
+        if (isApprovalNoiseMessage(msg.content)) return;
+        out.push({ kind: "systemMessage", content: sanitizeSystemContent(msg.content) });
+        return;
+      default:
+        out.push({ kind: "systemMessage", content: `Unknown message: ${msg.content}` });
+    }
+  }
+
+  // True for a MESSAGE_TOOL whose tool call the top-level tracker already owns.
+  // Mirrors Go's isTrackedToolMessage.
+  private isTrackedToolMessage(msg: AgentMessage): boolean {
+    if (msg.type !== MessageType.MESSAGE_TOOL) return false;
+    return msg.toolCalls.some((tc) => tc.id !== "" && this.topTools.has(tc.id));
+  }
+
+  // Step 1f: emit a ContextCompactedEvent per new summarization event. Mirrors
+  // the count-based tracking in streamToEvents.
+  private emitContextCompaction(out: StreamEvent[], execution: AgentExecution): void {
+    const events = execution.status?.contextInfo?.summarizationEvents ?? [];
+    for (let i = this.seenSummarizationCount; i < events.length; i++) {
+      const se = events[i];
+      out.push({
+        kind: "contextCompacted",
+        source: mapSummarizationSource(se.source),
+        tokensBefore: se.tokensBefore,
+        tokensAfter: se.tokensAfter,
+        compressionRatio: se.compressionRatio,
+        durationMs: se.durationMs,
+        messagesBefore: se.messagesBefore,
+        messagesAfter: se.messagesAfter,
+      });
+    }
+    this.seenSummarizationCount = events.length;
+  }
+
+  // Step 2: phase change, resetting the prompted set on an approval cycle
+  // (IN_PROGRESS→WAITING_FOR_APPROVAL) so a re-entered gate re-prompts instead
+  // of deadlocking. Mirrors streamToEvents Step 2.
+  private emitPhaseChange(out: StreamEvent[], phase: ExecutionPhase): void {
+    if (phase === this.lastPhase) return;
+    if (
+      phase === ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL &&
+      this.lastPhase === ExecutionPhase.EXECUTION_IN_PROGRESS
+    ) {
+      this.promptedIds.clear();
+    }
+    out.push({ kind: "phaseChange", phase: mapPhaseToString(phase), previous: mapPhaseToString(this.lastPhase) });
+    this.lastPhase = phase;
+  }
+
+  // Steps 3 + 3b: emit ApprovalNeededEvent for each unprompted pending approval,
+  // then fall back to a tool-status scan when pending_approvals is degraded.
+  private emitApprovals(
+    out: StreamEvent[],
+    pendingApprovals: readonly PendingApproval[],
+    rootToolCalls: readonly ToolCall[],
+    subAgents: readonly SubAgentExecution[],
+    phase: ExecutionPhase,
+  ): void {
+    for (const pa of pendingApprovals) {
+      const key = pa.toolCallId;
+      if (key === "" || this.promptedIds.has(key)) continue;
+      const tc = findToolCallById(rootToolCalls, subAgents, pa.toolCallId);
+      out.push(buildApprovalNeeded(tc, pa));
+      this.promptedIds.add(key);
+    }
+
+    if (
+      !hasUsableApproval(pendingApprovals, this.promptedIds) &&
+      phase === ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL
+    ) {
+      for (const u of findAllUnpromptedApprovals(rootToolCalls, subAgents, this.promptedIds)) {
+        const pa = buildPendingApprovalFromToolCall(u.toolCall);
+        pa.fromSubAgent = u.fromSubAgent;
+        pa.subAgentName = u.subAgentName;
+        out.push(buildApprovalNeeded(u.toolCall, pa));
+        this.promptedIds.add(pa.toolCallId);
+      }
+    }
+  }
+}
+
+// Emit tool events whose IDs match the MESSAGE_TOOL's embedded tool calls at the
+// current position, consuming them from `pending`. Mirrors Go's emitMatchedToolEvents.
+function emitMatchedToolEvents(out: StreamEvent[], msg: AgentMessage, pending: Map<string, StreamEvent>): void {
+  for (const tc of msg.toolCalls) {
+    if (tc.id === "") continue;
+    const ev = pending.get(tc.id);
+    if (ev !== undefined) {
+      out.push(ev);
+      pending.delete(tc.id);
+    }
+  }
+}

package/src/resources/stream/events.ts

@@ -0,0 +1,193 @@
+// The sealed event model for the headless snapshot differ.
+//
+// Mirrors Go's pkg/executiontui.Event family (events.go). The differ projects
+// each AgentExecution snapshot into a sequence of these discrete events; the
+// NDJSON and plaintext renderers consume them. The Ink TTY path does NOT use
+// this model — it renders from full snapshots via @stigmer/react.
+//
+// `kind` is the discriminant. The NDJSON renderer maps each kind to Go's exact
+// wire taxonomy (run_stream_json.go), so kinds are deliberately 1:1 with the Go
+// event types rather than the wire strings.
+
+import type { JsonObject } from "@bufbuild/protobuf";
+
+/** A tool call projected for rendering. Mirrors toolrender.ToolCallInfo. */
+export interface ToolCallInfo {
+  readonly id: string;
+  readonly name: string;
+  /** Mapped status: pending|running|completed|failed|waiting_approval|skipped|unknown. */
+  readonly status: string;
+  readonly args?: JsonObject;
+  readonly result: string;
+  readonly error: string;
+  /** Elapsed time in ms from started_at→completed_at, or 0 when unknown. */
+  readonly durationMs: number;
+}
+
+/** A todo item projected for rendering. Mirrors executiontui.TodoItem. */
+export interface TodoItemView {
+  readonly id: string;
+  readonly content: string;
+  /** Mapped status: pending|in_progress|completed|cancelled. */
+  readonly status: string;
+}
+
+// --- The event union. Each variant carries exactly what its renderers need. ---
+
+export interface AIMessageEvent {
+  readonly kind: "aiMessage";
+  readonly content: string;
+  readonly toolCalls: readonly ToolCallInfo[];
+  readonly subAgentId: string;
+}
+
+export interface AIStreamStartEvent {
+  readonly kind: "aiStreamStart";
+  readonly content: string;
+  readonly subAgentId: string;
+}
+
+export interface AIStreamDeltaEvent {
+  readonly kind: "aiStreamDelta";
+  readonly content: string;
+  readonly subAgentId: string;
+}
+
+export interface AIStreamEndEvent {
+  readonly kind: "aiStreamEnd";
+  readonly content: string;
+  readonly toolCalls: readonly ToolCallInfo[];
+  readonly subAgentId: string;
+}
+
+export interface HumanMessageEvent {
+  readonly kind: "humanMessage";
+  readonly content: string;
+}
+
+export interface ToolResultEvent {
+  readonly kind: "toolResult";
+  readonly content: string;
+  readonly toolCalls: readonly ToolCallInfo[];
+}
+
+export interface ToolRunningEvent {
+  readonly kind: "toolRunning";
+  readonly toolCallId: string;
+  readonly toolCall: ToolCallInfo;
+  readonly subAgentId: string;
+}
+
+export interface ToolCompletedEvent {
+  readonly kind: "toolCompleted";
+  readonly toolCallId: string;
+  readonly toolCall: ToolCallInfo;
+  readonly subAgentId: string;
+}
+
+export interface ToolWaitingApprovalEvent {
+  readonly kind: "toolWaitingApproval";
+  readonly toolCallId: string;
+  readonly toolCall: ToolCallInfo;
+  readonly subAgentId: string;
+}
+
+export interface ToolStreamDeltaEvent {
+  readonly kind: "toolStreamDelta";
+  readonly toolCallId: string;
+  readonly toolCall: ToolCallInfo;
+  readonly content: string;
+  readonly subAgentId: string;
+}
+
+export interface SystemMessageEvent {
+  readonly kind: "systemMessage";
+  readonly content: string;
+}
+
+export interface PhaseChangeEvent {
+  readonly kind: "phaseChange";
+  readonly phase: string;
+  readonly previous: string;
+}
+
+export interface ApprovalNeededEvent {
+  readonly kind: "approvalNeeded";
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly argsPreview: string;
+  readonly message: string;
+  readonly fromSubAgent: boolean;
+  readonly subAgentName: string;
+}
+
+export interface TodoUpdateEvent {
+  readonly kind: "todoUpdate";
+  readonly todos: readonly TodoItemView[];
+}
+
+export interface ContextCompactedEvent {
+  readonly kind: "contextCompacted";
+  readonly source: string;
+  readonly tokensBefore: number;
+  readonly tokensAfter: number;
+  readonly compressionRatio: number;
+  readonly durationMs: number;
+  readonly messagesBefore: number;
+  readonly messagesAfter: number;
+}
+
+export interface SubAgentStartedEvent {
+  readonly kind: "subAgentStarted";
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly input: string;
+}
+
+export interface SubAgentCompletedEvent {
+  readonly kind: "subAgentCompleted";
+  readonly id: string;
+  /** Protojson enum string for the sub-agent's terminal status. */
+  readonly status: string;
+  readonly toolCount: number;
+  readonly output: string;
+}
+
+export interface DoneEvent {
+  readonly kind: "done";
+  readonly phase: string;
+  readonly error: string;
+}
+
+export interface StreamErrorEvent {
+  readonly kind: "streamError";
+  readonly error: string;
+}
+
+/** The sealed union of every differ event. */
+export type StreamEvent =
+  | AIMessageEvent
+  | AIStreamStartEvent
+  | AIStreamDeltaEvent
+  | AIStreamEndEvent
+  | HumanMessageEvent
+  | ToolResultEvent
+  | ToolRunningEvent
+  | ToolCompletedEvent
+  | ToolWaitingApprovalEvent
+  | ToolStreamDeltaEvent
+  | SystemMessageEvent
+  | PhaseChangeEvent
+  | ApprovalNeededEvent
+  | TodoUpdateEvent
+  | ContextCompactedEvent
+  | SubAgentStartedEvent
+  | SubAgentCompletedEvent
+  | DoneEvent
+  | StreamErrorEvent;
+
+/** True for the two events that end a stream. */
+export function isTerminalEvent(event: StreamEvent): boolean {
+  return event.kind === "done" || event.kind === "streamError";
+}

package/src/resources/stream/headless.test.ts

@@ -0,0 +1,119 @@
+// Tests for the headless stream driver: terminal result propagation, approval
+// auto-resolution + submission, submit-failure → stream_error, clean abort.
+
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import {
+  ApprovalAction,
+  ExecutionPhase,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ApprovalNeededEvent, StreamEvent } from "./events.js";
+import { type HeadlessRenderer, runHeadlessStream } from "./headless.js";
+
+function snapshot(phase: ExecutionPhase, opts: { waiting?: boolean } = {}): AgentExecution {
+  const toolCalls = opts.waiting
+    ? [create(ToolCallSchema, { id: "t1", name: "delete", status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL })]
+    : [];
+  return create(AgentExecutionSchema, {
+    status: create(AgentExecutionStatusSchema, {
+      phase,
+      messages: [create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content: "hi", toolCalls })],
+      pendingApprovals: opts.waiting ? [create(PendingApprovalSchema, { toolCallId: "t1", toolName: "delete" })] : [],
+    }),
+  });
+}
+
+function source(snapshots: AgentExecution[]): (signal: AbortSignal) => AsyncIterable<AgentExecution> {
+  return async function* (signal: AbortSignal) {
+    for (const s of snapshots) {
+      if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+      yield s;
+    }
+  };
+}
+
+class RecordingRenderer implements HeadlessRenderer {
+  readonly kinds: string[] = [];
+  constructor(private readonly action: ApprovalAction = ApprovalAction.SKIP) {}
+  render(event: StreamEvent): void {
+    this.kinds.push(event.kind);
+  }
+  resolveApproval(_event: ApprovalNeededEvent): ApprovalAction {
+    return this.action;
+  }
+}
+
+describe("runHeadlessStream", () => {
+  it("drives to a terminal done and returns the phase", async () => {
+    const renderer = new RecordingRenderer();
+    const result = await runHeadlessStream({
+      subscribe: source([snapshot(ExecutionPhase.EXECUTION_IN_PROGRESS), snapshot(ExecutionPhase.EXECUTION_COMPLETED)]),
+      submitApproval: async () => {},
+      renderer,
+      sessionId: "ses_1",
+      signal: new AbortController().signal,
+    });
+    expect(result).toEqual({ phase: "completed", error: "" });
+    expect(renderer.kinds).toContain("done");
+  });
+
+  it("resolves and submits an approval, then completes", async () => {
+    const renderer = new RecordingRenderer(ApprovalAction.SKIP);
+    const submitted: Array<{ id: string; action: ApprovalAction }> = [];
+    const result = await runHeadlessStream({
+      subscribe: source([
+        snapshot(ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL, { waiting: true }),
+        snapshot(ExecutionPhase.EXECUTION_COMPLETED),
+      ]),
+      submitApproval: async (id, action) => void submitted.push({ id, action }),
+      renderer,
+      sessionId: "ses_1",
+      signal: new AbortController().signal,
+    });
+    expect(submitted).toEqual([{ id: "t1", action: ApprovalAction.SKIP }]);
+    expect(renderer.kinds).toContain("approvalNeeded");
+    expect(result.phase).toBe("completed");
+  });
+
+  it("renders a stream_error and stops when submission fails permanently", async () => {
+    const renderer = new RecordingRenderer();
+    const result = await runHeadlessStream({
+      subscribe: source([
+        snapshot(ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL, { waiting: true }),
+        snapshot(ExecutionPhase.EXECUTION_COMPLETED),
+      ]),
+      submitApproval: async () => {
+        throw new ConnectError("nope", Code.InvalidArgument);
+      },
+      renderer,
+      sessionId: "ses_9",
+      signal: new AbortController().signal,
+    });
+    expect(renderer.kinds).toContain("streamError");
+    expect(result.error).toContain("Failed to submit approval");
+    expect(result.error).toContain("stigmer resume ses_9");
+  });
+
+  it("exits cleanly when aborted", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const result = await runHeadlessStream({
+      subscribe: source([snapshot(ExecutionPhase.EXECUTION_IN_PROGRESS)]),
+      submitApproval: async () => {},
+      renderer: new RecordingRenderer(),
+      sessionId: "",
+      signal: controller.signal,
+    });
+    expect(result).toEqual({ phase: "", error: "" });
+  });
+});

package/src/resources/stream/headless.ts

@@ -0,0 +1,112 @@
+// The headless stream driver: subscribe → diff → render → resolve approvals.
+//
+// This is the single-process analog of Go's renderer goroutine + approval
+// channel (run_stream.go / run_stream_events.go). Go runs streamToEvents in one
+// goroutine and the renderer in another, exchanging approvals over channels.
+// Here it's one async loop: each snapshot is diffed, every event is rendered,
+// and an ApprovalNeededEvent is resolved by the renderer's policy and submitted
+// (with retry) before the loop blocks on the next snapshot — which is safe
+// because the backend withholds further updates until the approval lands.
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SnapshotDiffer } from "./diff.js";
+import type { ApprovalNeededEvent, StreamEvent } from "./events.js";
+import {
+  APPROVAL_RETRY_BASE_DELAY_MS,
+  APPROVAL_RETRY_MAX_ATTEMPTS,
+  classifyStreamError,
+  retryWithBackoff,
+} from "./submit.js";
+
+/**
+ * A headless renderer: turns each differ event into output and decides how to
+ * resolve approvals. Both methods are synchronous — submission is the driver's
+ * job. Implemented by NdjsonRenderer and PlaintextRenderer.
+ */
+export interface HeadlessRenderer {
+  /** Render one event to the renderer's sinks. */
+  render(event: StreamEvent): void;
+  /** Choose the approval action for an emitted ApprovalNeededEvent (may warn). */
+  resolveApproval(event: ApprovalNeededEvent): ApprovalAction;
+}
+
+/** The terminal outcome of a headless stream. */
+export interface HeadlessResult {
+  readonly phase: string;
+  readonly error: string;
+}
+
+/** Dependencies for {@link runHeadlessStream}. */
+export interface HeadlessStreamDeps {
+  /** The execution snapshot source (the SDK's agentExecution.subscribe). */
+  readonly subscribe: (signal: AbortSignal) => AsyncIterable<AgentExecution>;
+  /** Submit one approval decision. The caller binds the execution + RPC. */
+  readonly submitApproval: (toolCallId: string, action: ApprovalAction) => Promise<void>;
+  readonly renderer: HeadlessRenderer;
+  readonly sessionId: string;
+  readonly signal: AbortSignal;
+}
+
+/**
+ * Drive the stream to a terminal phase and return the outcome. Aborting (Ctrl-C)
+ * resolves cleanly with an empty result; a dropped stream renders a stream_error
+ * and returns its message.
+ */
+export async function runHeadlessStream(deps: HeadlessStreamDeps): Promise<HeadlessResult> {
+  const differ = new SnapshotDiffer();
+  try {
+    for await (const snapshot of deps.subscribe(deps.signal)) {
+      const terminal = await drainSnapshot(differ.next(snapshot), deps);
+      if (terminal !== undefined) return terminal;
+    }
+    return { phase: "", error: "" };
+  } catch (err) {
+    if (deps.signal.aborted) return { phase: "", error: "" };
+    const message = classifyStreamError(err, deps.sessionId);
+    deps.renderer.render({ kind: "streamError", error: message });
+    return { phase: "", error: message };
+  }
+}
+
+// Render every event for one snapshot, resolving approvals as they appear.
+// Returns the terminal result when a done/stream_error event is reached.
+async function drainSnapshot(events: StreamEvent[], deps: HeadlessStreamDeps): Promise<HeadlessResult | undefined> {
+  for (const event of events) {
+    deps.renderer.render(event);
+
+    if (event.kind === "approvalNeeded") {
+      const failure = await resolveAndSubmit(event, deps);
+      if (failure !== undefined) return failure;
+    }
+    if (event.kind === "done") return { phase: event.phase, error: event.error };
+    if (event.kind === "streamError") return { phase: "", error: event.error };
+  }
+  return undefined;
+}
+
+// Resolve an approval via the renderer's policy and submit it with retry. On
+// terminal submit failure, render a stream_error and return it (mirrors Go's
+// emitAndWaitApproval, which surfaces a StreamErrorEvent the renderer treats as
+// terminal). A successful submit returns undefined to continue the stream.
+async function resolveAndSubmit(
+  event: ApprovalNeededEvent,
+  deps: HeadlessStreamDeps,
+): Promise<HeadlessResult | undefined> {
+  const action = deps.renderer.resolveApproval(event);
+  try {
+    await retryWithBackoff(deps.signal, APPROVAL_RETRY_MAX_ATTEMPTS, APPROVAL_RETRY_BASE_DELAY_MS, () =>
+      deps.submitApproval(event.toolCallId, action),
+    );
+    return undefined;
+  } catch (err) {
+    if (deps.signal.aborted) return { phase: "", error: "" };
+    let message = `Failed to submit approval after ${APPROVAL_RETRY_MAX_ATTEMPTS} attempts`;
+    if (deps.sessionId !== "") message += `. Re-attach to retry: stigmer resume ${deps.sessionId}`;
+    deps.renderer.render({ kind: "streamError", error: message });
+    return { phase: "", error: message };
+  }
+}
+
+/** Re-export so command wiring can reference the enum without a deep import. */
+export { ApprovalAction };