@stigmer/cli 3.0.8

package/src/resources/stream/snapshot.ts

@@ -0,0 +1,191 @@
+// Historical replay: stored executions → the same StreamEvent sequence the live
+// differ produces. The headless analog of Go's snapshotToEvents
+// (run_stream_snapshot.go). Resume's completed-session path feeds these events
+// to the NDJSON/plaintext renderers so noise suppression, tool lifecycle badges,
+// and interleaving all apply identically to a live run.
+//
+// Unlike the live differ, there is no cross-snapshot state: each execution's
+// final state is a complete picture, so we walk messages once and emit a single
+// todo snapshot. Only the last execution emits `done` (so the Ink composer
+// activates for follow-ups; headless renderers ignore intermediate dones).
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  collectToolCallsFromMessages,
+  convertProtoTodos,
+  convertToolCall,
+  isApprovalNoiseMessage,
+  isTerminalToolStatus,
+  mapPhaseToString,
+  mapToolCallStatus,
+  sanitizeSystemContent,
+} from "./convert.js";
+import type { StreamEvent } from "./events.js";
+import { SubAgentTracking } from "./subagent.js";
+
+/**
+ * Convert stored executions (chronological, oldest first) into a flat event
+ * sequence. Only the final execution emits a `done` event.
+ */
+export function snapshotToEvents(executions: readonly AgentExecution[]): StreamEvent[] {
+  const out: StreamEvent[] = [];
+  executions.forEach((exec, i) => {
+    emitSnapshotEvents(out, exec, i === executions.length - 1);
+  });
+  return out;
+}
+
+// Project one stored execution's final state into events. Mirrors Go's
+// emitSnapshotEvents: spec message → interleaved messages + tools → trailing
+// non-message tools → sub-agents → todos → (optional) done.
+function emitSnapshotEvents(out: StreamEvent[], exec: AgentExecution, emitDone: boolean): void {
+  const status = exec.status;
+  const messages = status?.messages ?? [];
+
+  const allToolCalls = collectToolCallsFromMessages(messages);
+  const toolCallById = new Map<string, ToolCall>();
+  for (const tc of allToolCalls) {
+    if (tc.id !== "") toolCallById.set(tc.id, tc);
+  }
+
+  const messageToolIds = collectMessageToolIds(messages);
+  const nonMsgToolCalls = sortByStartedAt(allToolCalls.filter((tc) => tc.id !== "" && !messageToolIds.has(tc.id)));
+
+  // The user's prompt for this execution (the "execute" placeholder is hidden).
+  const specMessage = exec.spec?.message ?? "";
+  if (specMessage !== "" && specMessage !== "execute") {
+    out.push({ kind: "humanMessage", content: specMessage });
+  }
+
+  const emitted = new Set<string>();
+  let cursor = 0;
+
+  for (const msg of messages) {
+    cursor = emitInterleaved(out, nonMsgToolCalls, cursor, msg.timestamp, emitted);
+
+    switch (msg.type) {
+      case MessageType.MESSAGE_HUMAN:
+        break; // already emitted via spec.message
+      case MessageType.MESSAGE_TOOL:
+        emitToolMessage(out, msg, toolCallById, emitted);
+        break;
+      case MessageType.MESSAGE_AI:
+        out.push({ kind: "aiMessage", content: msg.content, toolCalls: [], subAgentId: "" });
+        break;
+      default:
+        emitOtherMessage(out, msg);
+    }
+  }
+
+  // Non-message tools that started after every message (or had no timestamp).
+  for (; cursor < nonMsgToolCalls.length; cursor++) {
+    const tc = nonMsgToolCalls[cursor];
+    if (!emitted.has(tc.id)) {
+      emitToolByStatus(out, tc);
+      emitted.add(tc.id);
+    }
+  }
+
+  const subAgents = status?.subAgentExecutions ?? [];
+  if (subAgents.length > 0) out.push(...new SubAgentTracking().emit(subAgents));
+
+  const todos = convertProtoTodos(status?.todos ?? {});
+  if (todos.length > 0) out.push({ kind: "todoUpdate", todos });
+
+  if (emitDone) {
+    out.push({ kind: "done", phase: mapPhaseToString(status?.phase ?? 0), error: status?.error ?? "" });
+  }
+}
+
+// Emit non-message tool calls whose started_at is at/before the message's
+// timestamp, advancing the cursor. Mirrors Go's emitInterleaved.
+function emitInterleaved(
+  out: StreamEvent[],
+  toolCalls: readonly ToolCall[],
+  cursor: number,
+  msgTimestamp: string,
+  emitted: Set<string>,
+): number {
+  let i = cursor;
+  while (i < toolCalls.length) {
+    const tc = toolCalls[i];
+    if (tc.startedAt === "") break; // no timestamp — defer to the end
+    if (msgTimestamp === "" || tc.startedAt > msgTimestamp) break;
+    if (!emitted.has(tc.id)) {
+      emitToolByStatus(out, tc);
+      emitted.add(tc.id);
+    }
+    i++;
+  }
+  return i;
+}
+
+// Promote a MESSAGE_TOOL into stateful tool events using the full tool-call
+// data. Mirrors Go's emitToolMessageAsStateful (falls back to other-message
+// handling when the message carries no tool refs).
+function emitToolMessage(
+  out: StreamEvent[],
+  msg: AgentMessage,
+  toolCallById: Map<string, ToolCall>,
+  emitted: Set<string>,
+): void {
+  if (msg.toolCalls.length === 0) {
+    emitOtherMessage(out, msg);
+    return;
+  }
+  for (const ref of msg.toolCalls) {
+    if (ref.id === "" || emitted.has(ref.id)) continue;
+    const full = toolCallById.get(ref.id) ?? ref;
+    emitToolByStatus(out, full);
+    emitted.add(full.id);
+  }
+}
+
+// SYSTEM (with noise suppression + sanitize) and any unexpected type. Mirrors
+// the SYSTEM/default arms of Go's emitCompleteMessage.
+function emitOtherMessage(out: StreamEvent[], msg: AgentMessage): void {
+  if (msg.type === MessageType.MESSAGE_SYSTEM) {
+    if (isApprovalNoiseMessage(msg.content)) return;
+    out.push({ kind: "systemMessage", content: sanitizeSystemContent(msg.content) });
+    return;
+  }
+  out.push({ kind: "systemMessage", content: `Unknown message: ${msg.content}` });
+}
+
+// Emit the right tool event for a tool call's final status. Mirrors Go's
+// emitToolEventByStatus.
+function emitToolByStatus(out: StreamEvent[], tc: ToolCall): void {
+  const status = mapToolCallStatus(tc.status);
+  const toolCall = convertToolCall(tc);
+  if (isTerminalToolStatus(status)) {
+    out.push({ kind: "toolCompleted", toolCallId: tc.id, toolCall, subAgentId: "" });
+  } else if (status === "waiting_approval") {
+    out.push({ kind: "toolWaitingApproval", toolCallId: tc.id, toolCall, subAgentId: "" });
+  } else {
+    out.push({ kind: "toolRunning", toolCallId: tc.id, toolCall, subAgentId: "" });
+  }
+}
+
+// Tool-call IDs referenced by MESSAGE_TOOL entries (Go's collectMessageToolIDs).
+function collectMessageToolIds(messages: readonly AgentMessage[]): Set<string> {
+  const ids = new Set<string>();
+  for (const msg of messages) {
+    if (msg.type !== MessageType.MESSAGE_TOOL) continue;
+    for (const tc of msg.toolCalls) {
+      if (tc.id !== "") ids.add(tc.id);
+    }
+  }
+  return ids;
+}
+
+// Sort by started_at ascending; empty timestamps sort to the end. Mirrors the
+// sort.Slice predicate in emitSnapshotEvents.
+function sortByStartedAt(toolCalls: ToolCall[]): ToolCall[] {
+  return [...toolCalls].sort((a, b) => {
+    if (a.startedAt === "") return 1;
+    if (b.startedAt === "") return -1;
+    return a.startedAt < b.startedAt ? -1 : a.startedAt > b.startedAt ? 1 : 0;
+  });
+}

package/src/resources/stream/subagent.ts

@@ -0,0 +1,104 @@
+// Sub-agent activity tracking for the snapshot differ.
+//
+// Ports the Go CLI's run_stream_subagent.go. Each sub-agent execution has its
+// own message cursor and tool-state tracker (its data arrays grow independently
+// of the top-level status), so this module keeps a per-sub-agent tracker keyed
+// by sub-agent ID and emits started/message/tool/completed events with the
+// sub-agent ID set for nested rendering.
+
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  collectToolCallsFromMessages,
+  isTerminalSubAgentStatus,
+  subAgentStatusName,
+} from "./convert.js";
+import type { StreamEvent } from "./events.js";
+import { ToolStateTracker } from "./tool-state.js";
+
+// Per-sub-agent cursor state. Mirrors Go's subAgentTracker.
+interface SubAgentCursor {
+  displayedMsgCount: number;
+  inStream: boolean;
+  readonly tools: ToolStateTracker;
+  completed: boolean;
+}
+
+/**
+ * Tracks every sub-agent across snapshots, emitting started/message/tool/
+ * completed events. Holds one cursor per sub-agent ID, persisting across calls.
+ */
+export class SubAgentTracking {
+  private readonly cursors = new Map<string, SubAgentCursor>();
+
+  /** Process all sub-agent executions in a snapshot. Mirrors Go's emitSubAgentEvents. */
+  emit(subAgents: readonly SubAgentExecution[]): StreamEvent[] {
+    const out: StreamEvent[] = [];
+
+    for (const sa of subAgents) {
+      if (sa.id === "") continue;
+
+      let cursor = this.cursors.get(sa.id);
+      if (cursor === undefined) {
+        cursor = { displayedMsgCount: 0, inStream: false, tools: new ToolStateTracker(), completed: false };
+        this.cursors.set(sa.id, cursor);
+        out.push({ kind: "subAgentStarted", id: sa.id, name: sa.name, description: sa.subject, input: sa.input });
+      }
+
+      const toolEvents = cursor.tools.track(collectToolCallsFromMessages(sa.messages), sa.id);
+      emitSubAgentMessages(out, sa.id, sa.messages, cursor);
+      out.push(...toolEvents);
+
+      if (!cursor.completed && isTerminalSubAgentStatus(sa.status)) {
+        cursor.completed = true;
+        out.push({
+          kind: "subAgentCompleted",
+          id: sa.id,
+          status: subAgentStatusName(sa.status),
+          toolCount: collectToolCallsFromMessages(sa.messages).length,
+          output: sa.output,
+        });
+      }
+    }
+
+    return out;
+  }
+}
+
+// Emit new sub-agent messages, streaming AI messages incrementally. Tool results
+// are owned by the tool-state tracker, so MESSAGE_TOOL entries are skipped, and
+// AI tool-call lists are omitted to avoid duplicating the stateful tool blocks.
+// Mirrors Go's emitSubAgentMessageEvents.
+function emitSubAgentMessages(
+  out: StreamEvent[],
+  subAgentId: string,
+  messages: readonly AgentMessage[],
+  cursor: SubAgentCursor,
+): void {
+  // Phase 1: an in-progress streaming AI message.
+  if (cursor.inStream && cursor.displayedMsgCount < messages.length) {
+    const msg = messages[cursor.displayedMsgCount];
+    if (msg.isStreaming) {
+      out.push({ kind: "aiStreamDelta", content: msg.content, subAgentId });
+      return;
+    }
+    out.push({ kind: "aiStreamEnd", content: msg.content, toolCalls: [], subAgentId });
+    cursor.displayedMsgCount++;
+    cursor.inStream = false;
+  }
+
+  // Phase 2: complete messages, detecting a new streaming start.
+  while (cursor.displayedMsgCount < messages.length) {
+    const msg = messages[cursor.displayedMsgCount];
+    if (msg.isStreaming && msg.type === MessageType.MESSAGE_AI) {
+      out.push({ kind: "aiStreamStart", content: msg.content, subAgentId });
+      cursor.inStream = true;
+      return;
+    }
+    if (msg.type === MessageType.MESSAGE_AI && msg.content !== "") {
+      out.push({ kind: "aiMessage", content: msg.content, toolCalls: [], subAgentId });
+    }
+    cursor.displayedMsgCount++;
+  }
+}

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

@@ -0,0 +1,77 @@
+// Tests for approval-submit resilience: retry classification, backoff loop,
+// and stream-error message parity with Go.
+
+import { describe, expect, it } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { classifyStreamError, isRetryableSubmitError, retryWithBackoff } from "./submit.js";
+
+const never = new AbortController().signal;
+
+describe("isRetryableSubmitError", () => {
+  it("retries transient gRPC codes", () => {
+    for (const code of [Code.Unavailable, Code.DeadlineExceeded, Code.ResourceExhausted, Code.Aborted, Code.Internal, Code.Unknown]) {
+      expect(isRetryableSubmitError(new ConnectError("x", code))).toBe(true);
+    }
+  });
+
+  it("retries FailedPrecondition only for 'no pending approvals'", () => {
+    expect(isRetryableSubmitError(new ConnectError("no pending approvals yet", Code.FailedPrecondition))).toBe(true);
+    expect(isRetryableSubmitError(new ConnectError("something else", Code.FailedPrecondition))).toBe(false);
+  });
+
+  it("does not retry permanent codes, but retries non-RPC errors", () => {
+    expect(isRetryableSubmitError(new ConnectError("nope", Code.NotFound))).toBe(false);
+    expect(isRetryableSubmitError(new ConnectError("nope", Code.InvalidArgument))).toBe(false);
+    expect(isRetryableSubmitError(new Error("socket hang up"))).toBe(true);
+  });
+});
+
+describe("retryWithBackoff", () => {
+  it("retries a retryable failure then succeeds", async () => {
+    let calls = 0;
+    await retryWithBackoff(never, 3, 1, async () => {
+      calls++;
+      if (calls < 3) throw new ConnectError("lost", Code.Unavailable);
+    });
+    expect(calls).toBe(3);
+  });
+
+  it("stops immediately on a non-retryable failure", async () => {
+    let calls = 0;
+    await expect(
+      retryWithBackoff(never, 3, 1, async () => {
+        calls++;
+        throw new ConnectError("bad", Code.InvalidArgument);
+      }),
+    ).rejects.toBeInstanceOf(ConnectError);
+    expect(calls).toBe(1);
+  });
+
+  it("gives up after maxAttempts and throws the last error", async () => {
+    let calls = 0;
+    await expect(
+      retryWithBackoff(never, 2, 1, async () => {
+        calls++;
+        throw new ConnectError("still down", Code.Unavailable);
+      }),
+    ).rejects.toBeInstanceOf(ConnectError);
+    expect(calls).toBe(2);
+  });
+});
+
+describe("classifyStreamError", () => {
+  it("maps known codes and appends a resume hint", () => {
+    const msg = classifyStreamError(new ConnectError("x", Code.Unavailable), "ses_1");
+    expect(msg).toContain("Connection to server lost.");
+    expect(msg).toContain("stigmer resume ses_1");
+  });
+
+  it("omits the resume hint when there is no session", () => {
+    const msg = classifyStreamError(new ConnectError("x", Code.DeadlineExceeded), "");
+    expect(msg).toBe("Server response timed out.");
+  });
+
+  it("falls back for non-RPC errors", () => {
+    expect(classifyStreamError(new Error("boom"), "")).toBe("Unexpected stream error: boom");
+  });
+});

package/src/resources/stream/submit.ts

@@ -0,0 +1,137 @@
+// Approval-submission resilience for the headless stream driver.
+//
+// Ports the retry/backoff machinery from Go's run_stream_events.go:21-191:
+// approval submits race a transient DB-consistency window ("no pending
+// approvals") and ordinary network blips, so they retry with exponential
+// backoff. Also ports classifyStreamError (:53-82) — the user-facing message
+// for a dropped Subscribe stream, with a resume hint.
+
+import { Code, ConnectError } from "@connectrpc/connect";
+import { StigmerError } from "@stigmer/sdk";
+
+export const APPROVAL_RETRY_MAX_ATTEMPTS = 3;
+export const APPROVAL_RETRY_BASE_DELAY_MS = 1000;
+
+const MAX_CHAIN_DEPTH = 20;
+
+/**
+ * Retry `fn` up to `maxAttempts` times with doubling backoff, stopping early on
+ * success, a non-retryable error, or abort. Mirrors Go's retryWithBackoff. The
+ * delay between attempts is abort-aware. Rejects with the last error on failure.
+ */
+export async function retryWithBackoff(
+  signal: AbortSignal,
+  maxAttempts: number,
+  baseDelayMs: number,
+  fn: () => Promise<void>,
+): Promise<void> {
+  let lastErr: unknown;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+
+    try {
+      await fn();
+      return;
+    } catch (err) {
+      lastErr = err;
+      if (!isRetryableSubmitError(err)) throw err;
+      if (attempt < maxAttempts - 1) {
+        await abortableDelay(baseDelayMs * 2 ** attempt, signal);
+      }
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * True when an approval-submit error is transient and worth retrying. Mirrors
+ * Go's isRetryableSubmitError, including the "no pending approvals" special
+ * case. Non-RPC errors default to retryable (typically transient I/O).
+ */
+export function isRetryableSubmitError(err: unknown): boolean {
+  const coded = extractCoded(err);
+  if (coded === undefined) return true;
+
+  switch (coded.code) {
+    case Code.Unavailable:
+    case Code.DeadlineExceeded:
+    case Code.ResourceExhausted:
+    case Code.Aborted:
+    case Code.Internal:
+    case Code.Unknown:
+      return true;
+    case Code.FailedPrecondition:
+      return coded.message.includes("no pending approvals");
+    default:
+      return false;
+  }
+}
+
+/**
+ * Translate a dropped Subscribe stream error into a user-facing message with a
+ * resume hint. Mirrors Go's classifyStreamError.
+ */
+export function classifyStreamError(err: unknown, sessionId: string): string {
+  let message: string;
+  const coded = extractCoded(err);
+  if (coded === undefined) {
+    message = `Unexpected stream error: ${messageOf(err)}`;
+  } else {
+    switch (coded.code) {
+      case Code.Unavailable:
+        message = "Connection to server lost.";
+        break;
+      case Code.Canceled:
+        message = "Server cancelled the stream.";
+        break;
+      case Code.DeadlineExceeded:
+        message = "Server response timed out.";
+        break;
+      default:
+        message = `Stream error (${Code[coded.code] ?? "Unknown"}): ${coded.message}`;
+    }
+  }
+
+  if (sessionId !== "") message += `\nRe-attach to this session: stigmer resume ${sessionId}`;
+  return message;
+}
+
+interface CodedError {
+  readonly code: number;
+  readonly message: string;
+}
+
+// Walk the cause chain for the first SDK/Connect coded error. Mirrors the
+// Unwrap walk in errors/classify.ts.
+function extractCoded(err: unknown): CodedError | undefined {
+  let depth = 0;
+  for (let current: unknown = err; current != null && depth < MAX_CHAIN_DEPTH; current = causeOf(current), depth++) {
+    if (current instanceof StigmerError) return { code: current.connectCode, message: current.message };
+    if (current instanceof ConnectError) return { code: current.code, message: current.rawMessage };
+  }
+  return undefined;
+}
+
+function causeOf(value: unknown): unknown {
+  return value !== null && typeof value === "object" ? (value as { cause?: unknown }).cause : undefined;
+}
+
+function messageOf(value: unknown): string {
+  if (value instanceof Error) return value.message;
+  if (typeof value === "string") return value;
+  return String(value);
+}
+
+function abortableDelay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/resources/stream/todo.ts

@@ -0,0 +1,53 @@
+// Todo-list change detection for the snapshot differ.
+//
+// Ports the Go CLI's emitTodoEvents + fingerprint helpers
+// (run_stream_events.go:786-847). Each snapshot carries the full todo map; this
+// differ compares a lightweight {content,status} fingerprint per item and emits
+// a single TodoUpdateEvent (with the full list) whenever anything is added,
+// removed, or changed.
+
+import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
+import { convertProtoTodos, mapTodoStatus } from "./convert.js";
+import type { StreamEvent } from "./events.js";
+
+interface Fingerprint {
+  readonly content: string;
+  readonly status: string;
+}
+
+/** Stateful todo differ: holds the last fingerprint snapshot across calls. */
+export class TodoDiffer {
+  private prev = new Map<string, Fingerprint>();
+
+  /** True once any todo has been recorded, until the list is emptied. Mirrors Go's `len(prevTodos) > 0` guard. */
+  get hasPrev(): boolean {
+    return this.prev.size > 0;
+  }
+
+  /** Diff the current todo map and return a TodoUpdateEvent when it changed. */
+  diff(todos: Record<string, TodoItem>): StreamEvent[] {
+    const current = buildFingerprints(todos);
+    if (!changed(this.prev, current)) return [];
+    this.prev = current;
+    return [{ kind: "todoUpdate", todos: convertProtoTodos(todos) }];
+  }
+}
+
+function buildFingerprints(todos: Record<string, TodoItem>): Map<string, Fingerprint> {
+  const fp = new Map<string, Fingerprint>();
+  for (const [id, item] of Object.entries(todos)) {
+    fp.set(id, { content: item.content, status: mapTodoStatus(item.status) });
+  }
+  return fp;
+}
+
+// True if the maps differ in size or any key's value. Detects add/remove/edit.
+// Mirrors Go's todoFingerprintsChanged.
+function changed(prev: Map<string, Fingerprint>, current: Map<string, Fingerprint>): boolean {
+  if (prev.size !== current.size) return true;
+  for (const [k, v] of current) {
+    const p = prev.get(k);
+    if (p === undefined || p.content !== v.content || p.status !== v.status) return true;
+  }
+  return false;
+}