@stigmer/cli 3.0.8

package/src/resources/stream/ink.tsx

@@ -0,0 +1,56 @@
+// In-process Ink renderer for the interactive (TTY) stream path.
+//
+// Go spawns a separate `stigmer-ink` subprocess (sdk/ink/src/cli/stigmer-ink.tsx)
+// and pipes session config to it. Here the CLI *is* a TS process, so we render
+// Ink in-process and — crucially — reuse the CLI's already-authenticated client
+// via InkStigmerProvider rather than letting SessionApp build its own. SessionView
+// (from @stigmer/ink) owns the live conversation: history, streaming, approvals,
+// and a follow-up composer.
+//
+// This module is only ever reached through a dynamic import() in the command
+// action (DD-001), so React/Ink load lazily — non-streaming commands never pay
+// for them. Within this already-lazy module, ordinary JSX/imports are fine.
+
+import React from "react";
+import { render } from "ink";
+import { InkStigmerProvider, SessionView, type InteractionMode } from "@stigmer/ink";
+import type { DeploymentMode, Stigmer } from "@stigmer/sdk";
+
+export interface InkSessionOptions {
+  /** The CLI's configured, refreshing-token client (backend.stigmer). */
+  readonly client: Stigmer;
+  readonly sessionId: string;
+  /** Org slug, for follow-up executions created from the composer. */
+  readonly org: string;
+  /** Initial interaction mode; the user can toggle with Ctrl+T. */
+  readonly mode: InteractionMode;
+  /** Feature-gating mode; "cloud" unless the CLI targets a local backend. */
+  readonly deploymentMode?: DeploymentMode;
+}
+
+/**
+ * Render a live session in the terminal and resolve when the user exits (Ctrl+C
+ * unmounts the app). This NEVER calls process.exit — the caller still runs its
+ * epilogue (final Get + usage). Termination signals unmount the Ink tree so the
+ * terminal is restored cleanly, but control returns here rather than killing
+ * the host process.
+ */
+export async function runInkSession(opts: InkSessionOptions): Promise<void> {
+  const instance = render(
+    <InkStigmerProvider client={opts.client} deploymentMode={opts.deploymentMode ?? "cloud"}>
+      <SessionView sessionId={opts.sessionId} org={opts.org} mode={opts.mode} />
+    </InkStigmerProvider>,
+    { exitOnCtrlC: true },
+  );
+
+  const onSignal = (): void => instance.unmount();
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+
+  try {
+    await instance.waitUntilExit();
+  } finally {
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+  }
+}

package/src/resources/stream/lazy-import.test.ts

@@ -0,0 +1,63 @@
+// DD-001 boundary guard: React/Ink must load lazily so non-streaming commands
+// and `--help` never pay for them. This codifies the boundary structurally so a
+// regression (a stray static import) fails CI instead of silently slowing every
+// command. The one allowed static importer is ink.tsx, which is itself only ever
+// reached through a dynamic import().
+
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const SRC_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+// The only modules allowed to statically import react/ink/@stigmer/ink. Each is
+// itself reached exclusively through a dynamic import() in a command action, so
+// the heavy graph stays out of every non-interactive path (DD-001).
+const INK_MODULES = [
+  join(SRC_ROOT, "resources/stream/ink.tsx"),
+  join(SRC_ROOT, "resources/picker/ink.tsx"),
+];
+const STATIC_HEAVY_IMPORT = /^\s*import\s+[^;]*?from\s+["'](?:react|ink|@stigmer\/ink)["']/m;
+
+function walk(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk(path));
+    else if (/\.(ts|tsx)$/.test(entry.name)) out.push(path);
+  }
+  return out;
+}
+
+describe("lazy-import boundary (DD-001)", () => {
+  it("only the lazy Ink entrypoints statically import react/ink/@stigmer/ink", () => {
+    const offenders = walk(SRC_ROOT)
+      .filter((path) => !INK_MODULES.includes(path))
+      .filter((path) => STATIC_HEAVY_IMPORT.test(readFileSync(path, "utf8")));
+    expect(offenders).toEqual([]);
+  });
+
+  it("the Ink entrypoints are reached only through dynamic import()", () => {
+    const staticImporters = walk(SRC_ROOT).filter((path) => {
+      if (INK_MODULES.includes(path)) return false;
+      const src = readFileSync(path, "utf8");
+      return /^\s*import\s+[^;]*?from\s+["'][^"']*(?:stream|picker)\/ink(?:\.js)?["']/m.test(src);
+    });
+    expect(staticImporters).toEqual([]);
+  });
+
+  // The workflow run stream renders over a CLI-local plaintext/NDJSON renderer
+  // (no Ink WorkflowView this round), so it must stay out of the React/Ink graph.
+  it("workflow-stream.ts has no static react/ink imports", () => {
+    const src = readFileSync(join(SRC_ROOT, "resources/run/workflow-stream.ts"), "utf8");
+    expect(STATIC_HEAVY_IMPORT.test(src)).toBe(false);
+  });
+
+  // `connect` renders plaintext only; its command + resources stay Ink-free.
+  it("connect command and resources have no static react/ink imports", () => {
+    for (const rel of ["commands/connect.ts", "resources/connect/connect.ts", "resources/connect/display.ts"]) {
+      const src = readFileSync(join(SRC_ROOT, rel), "utf8");
+      expect(STATIC_HEAVY_IMPORT.test(src)).toBe(false);
+    }
+  });
+});

package/src/resources/stream/render-ndjson.test.ts

@@ -0,0 +1,116 @@
+// Golden-line tests for the NDJSON renderer: event type strings, payload shape,
+// and Go-parity payload cleaning (empty strings dropped, false/0 kept).
+
+import { describe, expect, it } from "vitest";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { StreamEvent, ToolCallInfo } from "./events.js";
+import { NdjsonRenderer } from "./render-ndjson.js";
+
+const FIXED_TS = "2026-01-01T00:00:00.000Z";
+
+function buffer(): {
+  writer: { write(s: string): void };
+  raw: () => string;
+  lines: () => Array<Record<string, unknown>>;
+} {
+  let raw = "";
+  return {
+    writer: { write: (s: string) => void (raw += s) },
+    raw: () => raw,
+    lines: () =>
+      raw
+        .split("\n")
+        .filter((l) => l !== "")
+        .map((l) => JSON.parse(l) as Record<string, unknown>),
+  };
+}
+
+function renderer(defaultAction = ApprovalAction.SKIP) {
+  const data = buffer();
+  const status = buffer();
+  const r = new NdjsonRenderer({ data: data.writer, status: status.writer, defaultAction, now: () => FIXED_TS });
+  return { r, data, status };
+}
+
+function toolInfo(overrides: Partial<ToolCallInfo> = {}): ToolCallInfo {
+  return { id: "", name: "read", status: "running", args: undefined, result: "", error: "", durationMs: 0, ...overrides };
+}
+
+function render(events: StreamEvent[], defaultAction = ApprovalAction.SKIP) {
+  const ctx = renderer(defaultAction);
+  for (const e of events) ctx.r.render(e);
+  return ctx;
+}
+
+describe("envelope", () => {
+  it("wraps each event as {type, ts, payload} and strips empty payload fields", () => {
+    const { data } = render([{ kind: "aiStreamDelta", content: "", subAgentId: "" }]);
+    const [line] = data.lines();
+    expect(line.type).toBe("ai_stream_delta");
+    expect(line.ts).toBe(FIXED_TS);
+    expect(line.payload).toEqual({});
+  });
+
+  it("keeps boolean false and present strings", () => {
+    const { data } = render([
+      { kind: "approvalNeeded", toolCallId: "t1", toolName: "delete", argsPreview: "", message: "ok", fromSubAgent: false, subAgentName: "" },
+    ]);
+    const [line] = data.lines();
+    expect(line.type).toBe("approval_needed");
+    expect(line.payload).toEqual({ tool_call_id: "t1", tool_name: "delete", message: "ok", from_sub_agent: false });
+  });
+});
+
+describe("tool events", () => {
+  it("emits tool_running with only the meaningful fields", () => {
+    const { data } = render([
+      { kind: "toolRunning", toolCallId: "t1", subAgentId: "", toolCall: toolInfo({ id: "t1", result: "out", durationMs: 42 }) },
+    ]);
+    expect(data.lines()[0]).toMatchObject({
+      type: "tool_running",
+      payload: { tool_call_id: "t1", tool_name: "read", status: "running", result: "out", duration_ms: 42 },
+    });
+  });
+
+  it("includes tool_calls in ai_stream_end, omits when empty", () => {
+    const { data } = render([
+      { kind: "aiStreamEnd", content: "done", subAgentId: "", toolCalls: [toolInfo({ id: "t1", status: "completed" })] },
+      { kind: "aiMessage", content: "x", subAgentId: "", toolCalls: [] },
+    ]);
+    const [end, msg] = data.lines();
+    expect((end.payload as Record<string, unknown>).tool_calls).toEqual([{ name: "read", status: "completed", id: "t1" }]);
+    expect((msg.payload as Record<string, unknown>).tool_calls).toBeUndefined();
+  });
+});
+
+describe("done", () => {
+  it("drops an empty error but keeps a present one", () => {
+    const { data } = render([
+      { kind: "done", phase: "completed", error: "" },
+      { kind: "done", phase: "failed", error: "boom" },
+    ]);
+    const [ok, fail] = data.lines();
+    expect(ok.payload).toEqual({ phase: "completed" });
+    expect(fail.payload).toEqual({ phase: "failed", error: "boom" });
+  });
+});
+
+describe("approval policy", () => {
+  it("honors the configured default action without warning", () => {
+    const { r, status } = renderer(ApprovalAction.APPROVE);
+    const action = r.resolveApproval({
+      kind: "approvalNeeded", toolCallId: "t1", toolName: "delete", argsPreview: "", message: "", fromSubAgent: false, subAgentName: "",
+    });
+    expect(action).toBe(ApprovalAction.APPROVE);
+    expect(status.lines()).toHaveLength(0);
+  });
+
+  it("auto-skips with a stderr warning when no default is set", () => {
+    const { r, status } = renderer(ApprovalAction.UNSPECIFIED);
+    const action = r.resolveApproval({
+      kind: "approvalNeeded", toolCallId: "t1", toolName: "delete", argsPreview: "", message: "", fromSubAgent: false, subAgentName: "",
+    });
+    expect(action).toBe(ApprovalAction.SKIP);
+    expect(status.raw()).toContain("auto-skipping approval for delete");
+  });
+});

package/src/resources/stream/render-ndjson.ts

@@ -0,0 +1,176 @@
+// NDJSON headless renderer: StreamEvent → Go's run --json wire taxonomy.
+//
+// Mirrors run_stream_json.go's handleJSONEvent one case at a time — the event
+// `type` strings and payload keys are a parity contract (DD-005). The envelope
+// + payload cleaning live in output/ndjson.ts; this module only maps events to
+// `{type, payload}` and applies the headless approval policy.
+
+import { ndjsonEnvelope, writeNdjson } from "../../output/ndjson.js";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCallInfo, ApprovalNeededEvent, StreamEvent } from "./events.js";
+import type { HeadlessRenderer } from "./headless.js";
+
+/** A minimal output sink (process.stdout/stderr or a test buffer). */
+export interface LineWriter {
+  write(chunk: string): unknown;
+}
+
+export interface NdjsonRendererOptions {
+  /** NDJSON event lines (stdout). */
+  readonly data: LineWriter;
+  /** Fatal/auto-skip diagnostics (stderr). */
+  readonly status: LineWriter;
+  /** Approval default; UNSPECIFIED means auto-skip with a warning. */
+  readonly defaultAction: ApprovalAction;
+  /** Injectable clock for deterministic tests. */
+  readonly now?: () => string;
+}
+
+/** Writes one `{type, ts, payload}` line per event; auto-resolves approvals. */
+export class NdjsonRenderer implements HeadlessRenderer {
+  constructor(private readonly opts: NdjsonRendererOptions) {}
+
+  render(event: StreamEvent): void {
+    const mapped = mapToNdjson(event);
+    if (mapped !== undefined) {
+      writeNdjson(this.opts.data, ndjsonEnvelope(mapped.type, mapped.payload, this.opts.now));
+    }
+  }
+
+  // JSON mode has no interactive prompt: honor --approve-default, else skip with
+  // a warning to stderr. Mirrors run_stream_json.go's resolveJSONApproval.
+  resolveApproval(event: ApprovalNeededEvent): ApprovalAction {
+    if (this.opts.defaultAction === ApprovalAction.UNSPECIFIED) {
+      this.opts.status.write(`⚠ No --approve-default set; auto-skipping approval for ${event.toolName}\n`);
+      return ApprovalAction.SKIP;
+    }
+    return this.opts.defaultAction;
+  }
+}
+
+interface MappedEvent {
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+}
+
+// Map one event to its NDJSON type + raw payload (cleaned later). The arms are
+// 1:1 with handleJSONEvent so the wire output stays byte-faithful.
+function mapToNdjson(event: StreamEvent): MappedEvent | undefined {
+  switch (event.kind) {
+    case "aiStreamStart":
+      return { type: "ai_stream_start", payload: { content: event.content, sub_agent_id: event.subAgentId } };
+    case "aiStreamDelta":
+      return { type: "ai_stream_delta", payload: { content: event.content, sub_agent_id: event.subAgentId } };
+    case "aiStreamEnd":
+      return {
+        type: "ai_stream_end",
+        payload: { content: event.content, tool_calls: toolCallsToJson(event.toolCalls), sub_agent_id: event.subAgentId },
+      };
+    case "aiMessage":
+      return {
+        type: "ai_message",
+        payload: { content: event.content, tool_calls: toolCallsToJson(event.toolCalls), sub_agent_id: event.subAgentId },
+      };
+    case "humanMessage":
+      return { type: "human_message", payload: { content: event.content } };
+    case "toolRunning":
+      return { type: "tool_running", payload: toolEventPayload(event.toolCallId, event.toolCall, event.subAgentId) };
+    case "toolCompleted":
+      return { type: "tool_completed", payload: toolEventPayload(event.toolCallId, event.toolCall, event.subAgentId) };
+    case "toolWaitingApproval":
+      return {
+        type: "tool_waiting_approval",
+        payload: toolEventPayload(event.toolCallId, event.toolCall, event.subAgentId),
+      };
+    case "toolStreamDelta":
+      return {
+        type: "tool_stream_delta",
+        payload: {
+          tool_call_id: event.toolCallId,
+          tool_name: event.toolCall.name,
+          content: event.content,
+          sub_agent_id: event.subAgentId,
+        },
+      };
+    case "systemMessage":
+      return { type: "system_message", payload: { content: event.content } };
+    case "phaseChange":
+      return { type: "phase_change", payload: { phase: event.phase, previous: event.previous } };
+    case "approvalNeeded":
+      return {
+        type: "approval_needed",
+        payload: {
+          tool_call_id: event.toolCallId,
+          tool_name: event.toolName,
+          args_preview: event.argsPreview,
+          message: event.message,
+          from_sub_agent: event.fromSubAgent,
+          sub_agent_name: event.subAgentName,
+        },
+      };
+    case "todoUpdate":
+      return {
+        type: "todo_update",
+        payload: { todos: event.todos.map((t) => ({ id: t.id, content: t.content, status: t.status })) },
+      };
+    case "contextCompacted":
+      return {
+        type: "context_compacted",
+        payload: {
+          source: event.source,
+          tokens_before: event.tokensBefore,
+          tokens_after: event.tokensAfter,
+          compression_ratio: event.compressionRatio,
+          duration_ms: event.durationMs,
+          messages_before: event.messagesBefore,
+          messages_after: event.messagesAfter,
+        },
+      };
+    case "subAgentStarted":
+      return {
+        type: "sub_agent_started",
+        payload: { id: event.id, name: event.name, description: event.description },
+      };
+    case "subAgentCompleted":
+      return {
+        type: "sub_agent_completed",
+        payload: { id: event.id, status: event.status, tool_count: event.toolCount, output: event.output },
+      };
+    case "done":
+      return { type: "done", payload: { phase: event.phase, error: event.error } };
+    case "streamError":
+      return { type: "stream_error", payload: { error: event.error } };
+  }
+}
+
+// The shared payload for tool-lifecycle events. Mirrors Go's toolEventPayload:
+// args/result/error/duration are only present when meaningful. Empty strings are
+// stripped later by cleanNdjsonPayload.
+function toolEventPayload(toolCallId: string, tc: ToolCallInfo, subAgentId: string): Record<string, unknown> {
+  return {
+    tool_call_id: toolCallId,
+    tool_name: tc.name,
+    status: tc.status,
+    sub_agent_id: subAgentId,
+    args: tc.args,
+    result: tc.result,
+    error: tc.error,
+    duration_ms: tc.durationMs > 0 ? tc.durationMs : undefined,
+  };
+}
+
+// Convert a tool-call list to JSON maps, returning undefined for an empty list
+// (so the field is dropped). Inner maps keep name+status; the rest are omitted
+// when empty. Mirrors Go's toolCallsToJSON.
+function toolCallsToJson(tcs: readonly ToolCallInfo[]): Array<Record<string, unknown>> | undefined {
+  if (tcs.length === 0) return undefined;
+  return tcs.map((tc) => {
+    const m: Record<string, unknown> = { name: tc.name, status: tc.status };
+    if (tc.id !== "") m.id = tc.id;
+    if (tc.args !== undefined) m.args = tc.args;
+    if (tc.result !== "") m.result = tc.result;
+    if (tc.error !== "") m.error = tc.error;
+    if (tc.durationMs > 0) m.duration_ms = tc.durationMs;
+    return m;
+  });
+}

package/src/resources/stream/render-plaintext.test.ts

@@ -0,0 +1,68 @@
+// Tests for the plaintext renderer: AI text to data, terse status lines to
+// status, approvals auto-skipped, untracked event kinds silent.
+
+import { describe, expect, it } from "vitest";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { StreamEvent, ToolCallInfo } from "./events.js";
+import { PlaintextRenderer } from "./render-plaintext.js";
+
+function toolInfo(overrides: Partial<ToolCallInfo> = {}): ToolCallInfo {
+  return { id: "t1", name: "read", status: "completed", result: "", error: "", durationMs: 0, ...overrides };
+}
+
+function render(events: StreamEvent[]): { data: string; status: string } {
+  let data = "";
+  let status = "";
+  const r = new PlaintextRenderer({ data: { write: (s) => void (data += s) }, status: { write: (s) => void (status += s) } });
+  for (const e of events) r.render(e);
+  return { data, status };
+}
+
+describe("PlaintextRenderer", () => {
+  it("streams AI text to data and finalizes on stream end", () => {
+    const { data } = render([
+      { kind: "aiStreamDelta", content: "Hello", subAgentId: "" },
+      { kind: "aiStreamDelta", content: " world", subAgentId: "" },
+      { kind: "aiStreamEnd", content: "Hello world", subAgentId: "", toolCalls: [] },
+    ]);
+    expect(data).toBe("Hello world\n");
+  });
+
+  it("writes tool success and failure lines to status", () => {
+    const { status } = render([
+      { kind: "toolRunning", toolCallId: "t1", subAgentId: "", toolCall: toolInfo({ status: "running" }) },
+      { kind: "toolCompleted", toolCallId: "t1", subAgentId: "", toolCall: toolInfo() },
+      { kind: "toolCompleted", toolCallId: "t2", subAgentId: "", toolCall: toolInfo({ name: "shell", error: "exploded" }) },
+    ]);
+    expect(status).toContain("⠋ read");
+    expect(status).toContain("✓ read");
+    expect(status).toContain("✗ shell: exploded");
+  });
+
+  it("notes the auto-skip for approvals and resolves to SKIP", () => {
+    const r = new PlaintextRenderer({ data: { write: () => {} }, status: { write: () => {} } });
+    const action = r.resolveApproval({
+      kind: "approvalNeeded", toolCallId: "t1", toolName: "delete", argsPreview: "", message: "", fromSubAgent: false, subAgentName: "",
+    });
+    expect(action).toBe(ApprovalAction.SKIP);
+
+    const { status } = render([
+      { kind: "approvalNeeded", toolCallId: "t1", toolName: "delete", argsPreview: "", message: "", fromSubAgent: false, subAgentName: "" },
+    ]);
+    expect(status).toContain("Approval needed: delete (auto-skipped in non-TTY mode)");
+  });
+
+  it("renders sub-agent and context-compaction lines, stays silent on phase/done", () => {
+    const { data, status } = render([
+      { kind: "subAgentStarted", id: "s1", name: "researcher", description: "Explore code", input: "" },
+      { kind: "subAgentCompleted", id: "s1", status: "SUB_AGENT_COMPLETED", toolCount: 2, output: "" },
+      { kind: "contextCompacted", source: "graph_start", tokensBefore: 12000, tokensAfter: 6000, compressionRatio: 0.5, durationMs: 10, messagesBefore: 8, messagesAfter: 3 },
+      { kind: "phaseChange", phase: "in_progress", previous: "pending" },
+      { kind: "done", phase: "completed", error: "" },
+    ]);
+    expect(status).toContain("↳ Sub-agent: Explore code");
+    expect(status).toContain("✓ Sub-agent completed: s1");
+    expect(status).toContain("Context compacted (12K → 6K tokens)");
+    expect(data).toBe("");
+  });
+});

package/src/resources/stream/render-plaintext.ts

@@ -0,0 +1,86 @@
+// Plaintext headless renderer for non-TTY output (piped stdout).
+//
+// Mirrors Go's streamAgentPlainText (run_stream_plaintext.go): clean AI text to
+// the data sink (stdout), terse tool/status lines to the status sink (stderr).
+// No ANSI, no frames. Approvals are auto-skipped — there is no keyboard here;
+// use --json for a machine-readable non-TTY stream. Phase/done/stream-error are
+// not rendered: the driver returns the outcome and the command surfaces it.
+
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ApprovalNeededEvent, StreamEvent } from "./events.js";
+import type { HeadlessRenderer } from "./headless.js";
+import type { LineWriter } from "./render-ndjson.js";
+
+export interface PlaintextRendererOptions {
+  /** AI text output (stdout). */
+  readonly data: LineWriter;
+  /** Tool/status/diagnostic lines (stderr). */
+  readonly status: LineWriter;
+}
+
+const MAX_ERROR_LEN = 100;
+
+/** Renders a terse, ANSI-free transcript; auto-skips every approval. */
+export class PlaintextRenderer implements HeadlessRenderer {
+  constructor(private readonly opts: PlaintextRendererOptions) {}
+
+  render(event: StreamEvent): void {
+    const { data, status } = this.opts;
+    switch (event.kind) {
+      case "aiStreamDelta":
+        data.write(event.content);
+        return;
+      case "aiStreamEnd":
+        data.write("\n");
+        return;
+      case "aiMessage":
+        if (event.content !== "") data.write(`${event.content}\n`);
+        return;
+      case "humanMessage":
+        status.write(`\n> ${event.content}\n\n`);
+        return;
+      case "toolRunning":
+        status.write(`  ⠋ ${event.toolCall.name}\n`);
+        return;
+      case "toolCompleted":
+        status.write(
+          event.toolCall.error !== ""
+            ? `  ✗ ${event.toolCall.name}: ${truncate(event.toolCall.error, MAX_ERROR_LEN)}\n`
+            : `  ✓ ${event.toolCall.name}\n`,
+        );
+        return;
+      case "approvalNeeded":
+        status.write(`  ⚠ Approval needed: ${event.toolName} (auto-skipped in non-TTY mode)\n`);
+        return;
+      case "subAgentStarted":
+        status.write(`  ↳ Sub-agent: ${event.description !== "" ? event.description : event.name}\n`);
+        return;
+      case "subAgentCompleted":
+        status.write(`  ✓ Sub-agent completed: ${event.id}\n`);
+        return;
+      case "contextCompacted":
+        status.write(
+          `  … Context compacted (${Math.floor(event.tokensBefore / 1000)}K → ${Math.floor(event.tokensAfter / 1000)}K tokens)\n`,
+        );
+        return;
+      case "systemMessage":
+        status.write(`[system] ${event.content}\n`);
+        return;
+      default:
+        // phaseChange, toolWaitingApproval, toolStreamDelta, todoUpdate, done,
+        // streamError: not surfaced in plaintext (parity with Go).
+        return;
+    }
+  }
+
+  // Non-TTY has no prompt — always skip (the render() line already noted it).
+  resolveApproval(_event: ApprovalNeededEvent): ApprovalAction {
+    return ApprovalAction.SKIP;
+  }
+}
+
+// Trim and ellipsize. Mirrors Go's truncate.
+function truncate(value: string, maxLen: number): string {
+  const trimmed = value.trim();
+  return trimmed.length <= maxLen ? trimmed : `${trimmed.slice(0, maxLen)}…`;
+}

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

@@ -0,0 +1,97 @@
+// Tests for the historical-replay projection (snapshotToEvents). Stored
+// executions must yield the same event vocabulary as the live differ, with
+// `done` emitted only for the final execution.
+
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+  type AgentMessage,
+  type ToolCall,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ExecutionPhase,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { StreamEvent } from "./events.js";
+import { snapshotToEvents } from "./snapshot.js";
+
+function exec(opts: {
+  message?: string;
+  phase?: ExecutionPhase;
+  messages?: AgentMessage[];
+  error?: string;
+}): AgentExecution {
+  return create(AgentExecutionSchema, {
+    spec: create(AgentExecutionSpecSchema, { message: opts.message ?? "" }),
+    status: create(AgentExecutionStatusSchema, {
+      phase: opts.phase ?? ExecutionPhase.EXECUTION_COMPLETED,
+      messages: opts.messages ?? [],
+      error: opts.error ?? "",
+    }),
+  });
+}
+
+function aiMsg(content: string): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content });
+}
+
+function systemMsg(content: string): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_SYSTEM, content });
+}
+
+function toolMsg(tc: ToolCall): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_TOOL, toolCalls: [tc], timestamp: "t1" });
+}
+
+function tool(id: string, status: ToolCallStatus): ToolCall {
+  return create(ToolCallSchema, { id, name: "read", status, startedAt: "t0" });
+}
+
+const kinds = (events: StreamEvent[]): string[] => events.map((e) => e.kind);
+
+describe("snapshotToEvents", () => {
+  it("emits the human prompt, AI text, and a terminal done for the last execution", () => {
+    const events = snapshotToEvents([exec({ message: "do it", messages: [aiMsg("done")] })]);
+    expect(kinds(events)).toEqual(["humanMessage", "aiMessage", "done"]);
+    expect(events[0]).toMatchObject({ kind: "humanMessage", content: "do it" });
+    expect(events[2]).toMatchObject({ kind: "done", phase: "completed" });
+  });
+
+  it("suppresses the 'execute' placeholder prompt", () => {
+    const events = snapshotToEvents([exec({ message: "execute", messages: [aiMsg("hi")] })]);
+    expect(kinds(events)).toEqual(["aiMessage", "done"]);
+  });
+
+  it("promotes a MESSAGE_TOOL into a stateful tool event by status", () => {
+    const events = snapshotToEvents([
+      exec({ messages: [toolMsg(tool("tc1", ToolCallStatus.TOOL_CALL_COMPLETED))] }),
+    ]);
+    expect(kinds(events)).toEqual(["toolCompleted", "done"]);
+    expect(events[0]).toMatchObject({ kind: "toolCompleted", toolCallId: "tc1" });
+  });
+
+  it("only the final execution emits done", () => {
+    const events = snapshotToEvents([
+      exec({ message: "first", messages: [aiMsg("a")] }),
+      exec({ message: "second", messages: [aiMsg("b")] }),
+    ]);
+    expect(kinds(events)).toEqual(["humanMessage", "aiMessage", "humanMessage", "aiMessage", "done"]);
+  });
+
+  it("carries the failure phase + error into done", () => {
+    const events = snapshotToEvents([
+      exec({ phase: ExecutionPhase.EXECUTION_FAILED, error: "boom", messages: [systemMsg("context")] }),
+    ]);
+    const done = events.at(-1);
+    expect(done).toMatchObject({ kind: "done", phase: "failed", error: "boom" });
+  });
+});