@stigmer/cli 3.0.8

package/src/resources/stream/convert.ts

@@ -0,0 +1,210 @@
+// Proto → domain converters for the snapshot differ.
+//
+// Ports the Go CLI's run_stream_convert.go + run_display_tools.go + the error
+// sanitizer in run_display.go. These are pure mappings from generated proto
+// types to the differ's render-agnostic event payloads (events.ts), keeping the
+// enum/string translation in exactly one place.
+
+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 type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
+import {
+  ExecutionPhase,
+  SubAgentStatus,
+  SummarizationSource,
+  ToolCallStatus,
+  TodoStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCallInfo, TodoItemView } from "./events.js";
+
+/** Mapped tool-call status strings. */
+export type ToolStatus = "pending" | "running" | "completed" | "failed" | "waiting_approval" | "skipped" | "unknown";
+
+/** Convert a proto ToolCall to render info. Mirrors Go's convertToolCall. */
+export function convertToolCall(tc: ToolCall): ToolCallInfo {
+  return {
+    id: tc.id,
+    name: tc.name,
+    status: mapToolCallStatus(tc.status),
+    args: tc.args,
+    result: tc.result,
+    error: tc.error,
+    durationMs: computeDurationMs(tc.startedAt, tc.completedAt),
+  };
+}
+
+/** Convert a slice of proto ToolCalls. Mirrors Go's convertToolCalls. */
+export function convertToolCalls(toolCalls: readonly ToolCall[]): ToolCallInfo[] {
+  return toolCalls.map(convertToolCall);
+}
+
+/** Flatten every tool call embedded in a message list. Mirrors Go's collectToolCallsFromMessages. */
+export function collectToolCallsFromMessages(messages: readonly AgentMessage[]): ToolCall[] {
+  const result: ToolCall[] = [];
+  for (const msg of messages) result.push(...msg.toolCalls);
+  return result;
+}
+
+/** Find a tool call by ID, searching root then sub-agent messages. Mirrors Go's findToolCallByID. */
+export function findToolCallById(
+  toolCalls: readonly ToolCall[],
+  subAgents: readonly SubAgentExecution[],
+  id: string,
+): ToolCall | undefined {
+  for (const tc of toolCalls) {
+    if (tc.id === id) return tc;
+  }
+  for (const sa of subAgents) {
+    for (const msg of sa.messages) {
+      for (const tc of msg.toolCalls) {
+        if (tc.id === id) return tc;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Convert the proto todo map to render items. Mirrors Go's convertProtoTodos. */
+export function convertProtoTodos(todos: Record<string, TodoItem>): TodoItemView[] {
+  return Object.values(todos).map((item) => ({
+    id: item.id,
+    content: item.content,
+    status: mapTodoStatus(item.status),
+  }));
+}
+
+/** Map an ExecutionPhase to its differ string. Mirrors Go's mapPhaseToString. */
+export function mapPhaseToString(phase: ExecutionPhase): string {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_PENDING:
+      return "pending";
+    case ExecutionPhase.EXECUTION_IN_PROGRESS:
+      return "in_progress";
+    case ExecutionPhase.EXECUTION_COMPLETED:
+      return "completed";
+    case ExecutionPhase.EXECUTION_FAILED:
+      return "failed";
+    case ExecutionPhase.EXECUTION_CANCELLED:
+      return "cancelled";
+    case ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL:
+      return "waiting_for_approval";
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      return "terminated";
+    default:
+      return "unknown";
+  }
+}
+
+/** Map a ToolCallStatus to its differ string. Mirrors Go's mapToolCallStatus. */
+export function mapToolCallStatus(status: ToolCallStatus): ToolStatus {
+  switch (status) {
+    case ToolCallStatus.TOOL_CALL_PENDING:
+      return "pending";
+    case ToolCallStatus.TOOL_CALL_RUNNING:
+      return "running";
+    case ToolCallStatus.TOOL_CALL_COMPLETED:
+      return "completed";
+    case ToolCallStatus.TOOL_CALL_FAILED:
+      return "failed";
+    case ToolCallStatus.TOOL_CALL_WAITING_APPROVAL:
+      return "waiting_approval";
+    case ToolCallStatus.TOOL_CALL_SKIPPED:
+      return "skipped";
+    default:
+      return "unknown";
+  }
+}
+
+/** Map a TodoStatus to its differ string (UNSPECIFIED→pending). Mirrors Go's mapTodoStatus. */
+export function mapTodoStatus(status: TodoStatus): string {
+  switch (status) {
+    case TodoStatus.TODO_PENDING:
+      return "pending";
+    case TodoStatus.TODO_IN_PROGRESS:
+      return "in_progress";
+    case TodoStatus.TODO_COMPLETED:
+      return "completed";
+    case TodoStatus.TODO_CANCELLED:
+      return "cancelled";
+    default:
+      return "pending";
+  }
+}
+
+/** Map a SummarizationSource to its differ string. Mirrors Go's mapSummarizationSource. */
+export function mapSummarizationSource(source: SummarizationSource): string {
+  switch (source) {
+    case SummarizationSource.graph_start:
+      return "graph_start";
+    case SummarizationSource.mid_execution:
+      return "mid_execution";
+    default:
+      return "unknown";
+  }
+}
+
+/** The protojson enum name for a sub-agent status (matches Go's status.String()). */
+export function subAgentStatusName(status: SubAgentStatus): string {
+  return SubAgentStatus[status] ?? "SUB_AGENT_STATUS_UNSPECIFIED";
+}
+
+/** True for tool statuses that mean the tool is no longer executing. Mirrors Go's isTerminalToolStatus. */
+export function isTerminalToolStatus(status: string): boolean {
+  return status === "completed" || status === "failed" || status === "skipped";
+}
+
+/** True for terminal agent phases. Mirrors Go's isTerminalAgentPhase. */
+export function isTerminalAgentPhase(phase: ExecutionPhase): boolean {
+  return (
+    phase === ExecutionPhase.EXECUTION_COMPLETED ||
+    phase === ExecutionPhase.EXECUTION_FAILED ||
+    phase === ExecutionPhase.EXECUTION_CANCELLED ||
+    phase === ExecutionPhase.EXECUTION_TERMINATED
+  );
+}
+
+/** True for terminal sub-agent statuses. Mirrors Go's isTerminalSubAgentStatus. */
+export function isTerminalSubAgentStatus(status: SubAgentStatus): boolean {
+  return (
+    status === SubAgentStatus.SUB_AGENT_COMPLETED ||
+    status === SubAgentStatus.SUB_AGENT_FAILED ||
+    status === SubAgentStatus.SUB_AGENT_CANCELLED
+  );
+}
+
+// Raw HTTP/API error response pattern that leaks internals. Mirrors Go's rawAPIErrorPattern.
+const RAW_API_ERROR = /Error code: \d+ - [{'"]/;
+const RAW_EXCEPTION_PATTERNS = ["invalid_request_error", "request_id", "'type': 'error'", '"type": "error"'];
+
+/** Rewrite raw API/exception errors into clean text. Mirrors Go's sanitizeSystemContent. */
+export function sanitizeSystemContent(content: string): string {
+  if (!isRawErrorContent(content)) return content;
+
+  const idx = content.indexOf("Error code:");
+  if (idx > 0) {
+    const prefix = content.slice(0, idx).trim().replace(/[:\-\s]+$/, "");
+    if (prefix !== "") return `${prefix} (internal error — check execution logs for details)`;
+  }
+  return "Agent execution encountered an internal error. Check execution logs for details.";
+}
+
+/** True when the system message looks like an approval-received acknowledgement. Mirrors Go's isApprovalNoiseMessage. */
+export function isApprovalNoiseMessage(content: string): boolean {
+  return content.includes("Approval received");
+}
+
+function isRawErrorContent(content: string): boolean {
+  if (RAW_API_ERROR.test(content)) return true;
+  return RAW_EXCEPTION_PATTERNS.some((p) => content.includes(p));
+}
+
+// Elapsed ms between two RFC3339 timestamps, or 0 when either is missing,
+// unparseable, or negative. Mirrors Go's computeToolCallDuration.
+function computeDurationMs(startedAt: string, completedAt: string): number {
+  if (startedAt === "" || completedAt === "") return 0;
+  const start = Date.parse(startedAt);
+  const end = Date.parse(completedAt);
+  if (Number.isNaN(start) || Number.isNaN(end)) return 0;
+  const d = end - start;
+  return d < 0 ? 0 : d;
+}

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

@@ -0,0 +1,316 @@
+// Scenario tests for the snapshot→event differ. Each test drives a sequence of
+// AgentExecution snapshots through a single SnapshotDiffer and asserts the
+// resulting event sequence — the wire-parity contract with Go's streamToEvents.
+
+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 {
+  SubAgentExecutionSchema,
+  type SubAgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { TodoItemSchema, type TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
+import {
+  PendingApprovalSchema,
+  type PendingApproval,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import {
+  ContextInfoSchema,
+  SummarizationEventSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/context_pb";
+import {
+  ExecutionPhase,
+  MessageType,
+  SubAgentStatus,
+  ToolCallStatus,
+  TodoStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SnapshotDiffer } from "./diff.js";
+import type { StreamEvent } from "./events.js";
+
+// --- Snapshot builders ---------------------------------------------------------
+
+interface SnapshotOpts {
+  message?: string;
+  phase?: ExecutionPhase;
+  messages?: AgentMessage[];
+  subAgents?: SubAgentExecution[];
+  todos?: Record<string, TodoItem>;
+  pendingApprovals?: PendingApproval[];
+  summarizations?: Array<{ source?: number; tokensBefore?: number; tokensAfter?: number }>;
+  error?: string;
+}
+
+function snapshot(opts: SnapshotOpts): AgentExecution {
+  const contextInfo =
+    opts.summarizations !== undefined
+      ? create(ContextInfoSchema, {
+          summarizationEvents: opts.summarizations.map((s) =>
+            create(SummarizationEventSchema, {
+              tokensBefore: s.tokensBefore ?? 0,
+              tokensAfter: s.tokensAfter ?? 0,
+            }),
+          ),
+        })
+      : undefined;
+
+  return create(AgentExecutionSchema, {
+    spec: create(AgentExecutionSpecSchema, { message: opts.message ?? "" }),
+    status: create(AgentExecutionStatusSchema, {
+      phase: opts.phase ?? ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: opts.messages ?? [],
+      subAgentExecutions: opts.subAgents ?? [],
+      todos: opts.todos ?? {},
+      pendingApprovals: opts.pendingApprovals ?? [],
+      contextInfo,
+      error: opts.error ?? "",
+    }),
+  });
+}
+
+function aiMsg(content: string, opts: { streaming?: boolean; toolCalls?: ToolCall[] } = {}): AgentMessage {
+  return create(AgentMessageSchema, {
+    type: MessageType.MESSAGE_AI,
+    content,
+    isStreaming: opts.streaming ?? false,
+    toolCalls: opts.toolCalls ?? [],
+  });
+}
+
+function toolMsg(content: string, toolCalls: ToolCall[]): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_TOOL, content, toolCalls });
+}
+
+function humanMsg(content: string): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_HUMAN, content });
+}
+
+function systemMsg(content: string): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_SYSTEM, content });
+}
+
+function tool(id: string, name: string, status: ToolCallStatus, opts: { result?: string; isStreaming?: boolean } = {}): ToolCall {
+  return create(ToolCallSchema, { id, name, status, result: opts.result ?? "", isStreaming: opts.isStreaming ?? false });
+}
+
+function subAgent(
+  id: string,
+  status: SubAgentStatus,
+  opts: { name?: string; subject?: string; input?: string; output?: string; messages?: AgentMessage[] } = {},
+): SubAgentExecution {
+  return create(SubAgentExecutionSchema, {
+    id,
+    status,
+    name: opts.name ?? "researcher",
+    subject: opts.subject ?? "",
+    input: opts.input ?? "",
+    output: opts.output ?? "",
+    messages: opts.messages ?? [],
+  });
+}
+
+function todo(id: string, content: string, status: TodoStatus): TodoItem {
+  return create(TodoItemSchema, { id, content, status });
+}
+
+function approval(toolCallId: string, toolName: string, message: string): PendingApproval {
+  return create(PendingApprovalSchema, { toolCallId, toolName, message });
+}
+
+// Drive a snapshot sequence through one differ; return flattened event kinds.
+function kindsFor(snapshots: AgentExecution[]): string[] {
+  const differ = new SnapshotDiffer();
+  const out: string[] = [];
+  for (const s of snapshots) out.push(...differ.next(s).map((e) => e.kind));
+  return out;
+}
+
+// Drive a sequence and return the full event objects.
+function eventsFor(snapshots: AgentExecution[]): StreamEvent[] {
+  const differ = new SnapshotDiffer();
+  const out: StreamEvent[] = [];
+  for (const s of snapshots) out.push(...differ.next(s));
+  return out;
+}
+
+// --- Tests ---------------------------------------------------------------------
+
+describe("human message", () => {
+  it("emits once and suppresses the 'execute' placeholder", () => {
+    expect(kindsFor([snapshot({ message: "hi" }), snapshot({ message: "hi" })])).toEqual([
+      "humanMessage",
+      "phaseChange",
+    ]);
+    expect(kindsFor([snapshot({ message: "execute" })])).toEqual(["phaseChange"]);
+  });
+});
+
+describe("AI streaming lifecycle", () => {
+  it("start → delta → end across snapshots", () => {
+    const seq = [
+      snapshot({ messages: [aiMsg("Hel", { streaming: true })] }),
+      snapshot({ messages: [aiMsg("Hello", { streaming: true })] }),
+      snapshot({ messages: [aiMsg("Hello world", { streaming: false })] }),
+    ];
+    expect(kindsFor(seq)).toEqual(["aiStreamStart", "phaseChange", "aiStreamDelta", "aiStreamEnd"]);
+  });
+});
+
+describe("tool call interleaving", () => {
+  it("running tool is an orphan event, completion lands at the tool-message position", () => {
+    const seq = [
+      snapshot({ messages: [aiMsg("calling", { toolCalls: [tool("t1", "read", ToolCallStatus.TOOL_CALL_RUNNING)] })] }),
+      snapshot({
+        messages: [
+          aiMsg("calling", { toolCalls: [tool("t1", "read", ToolCallStatus.TOOL_CALL_COMPLETED, { result: "data" })] }),
+          toolMsg("data", [tool("t1", "read", ToolCallStatus.TOOL_CALL_COMPLETED, { result: "data" })]),
+        ],
+      }),
+    ];
+    expect(kindsFor(seq)).toEqual(["aiMessage", "toolRunning", "phaseChange", "toolCompleted"]);
+  });
+
+  it("first-sight terminal tool synthesizes a completion", () => {
+    const seq = [
+      snapshot({
+        messages: [toolMsg("data", [tool("t1", "read", ToolCallStatus.TOOL_CALL_COMPLETED, { result: "data" })])],
+      }),
+    ];
+    expect(kindsFor(seq)).toContain("toolCompleted");
+  });
+
+  it("emits a streaming delta when a running tool's result grows", () => {
+    const seq = [
+      snapshot({
+        messages: [aiMsg("", { toolCalls: [tool("t1", "shell", ToolCallStatus.TOOL_CALL_RUNNING, { isStreaming: true, result: "a" })] })],
+      }),
+      snapshot({
+        messages: [aiMsg("", { toolCalls: [tool("t1", "shell", ToolCallStatus.TOOL_CALL_RUNNING, { isStreaming: true, result: "ab" })] })],
+      }),
+    ];
+    expect(kindsFor(seq)).toContain("toolStreamDelta");
+  });
+});
+
+describe("system messages", () => {
+  it("sanitizes raw API errors and suppresses approval noise", () => {
+    const events = eventsFor([
+      snapshot({ messages: [systemMsg('Boom: Error code: 500 - {"type": "error"}'), systemMsg("Approval received: ok")] }),
+    ]);
+    const system = events.filter((e) => e.kind === "systemMessage");
+    expect(system).toHaveLength(1);
+    expect(system[0].kind === "systemMessage" && system[0].content).toContain("internal error");
+  });
+});
+
+describe("approval detection", () => {
+  it("emits ApprovalNeeded from pending_approvals once", () => {
+    const snap = snapshot({
+      phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      messages: [aiMsg("", { toolCalls: [tool("t1", "delete", ToolCallStatus.TOOL_CALL_WAITING_APPROVAL)] })],
+      pendingApprovals: [approval("t1", "delete", "Delete repo?")],
+    });
+    // Same snapshot twice — the dedup set prevents a second prompt.
+    const events = eventsFor([snap, snap]);
+    const approvals = events.filter((e) => e.kind === "approvalNeeded");
+    expect(approvals).toHaveLength(1);
+    expect(approvals[0].kind === "approvalNeeded" && approvals[0].toolName).toBe("delete");
+  });
+
+  it("defense-in-depth: detects approval via tool status when pending_approvals is empty", () => {
+    const snap = snapshot({
+      phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      messages: [aiMsg("", { toolCalls: [tool("t1", "delete", ToolCallStatus.TOOL_CALL_WAITING_APPROVAL)] })],
+      pendingApprovals: [],
+    });
+    expect(kindsFor([snap])).toContain("approvalNeeded");
+  });
+
+  it("re-prompts after an approval cycle (IN_PROGRESS → WAITING_FOR_APPROVAL)", () => {
+    const waiting = () =>
+      snapshot({
+        phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+        messages: [aiMsg("", { toolCalls: [tool("t1", "delete", ToolCallStatus.TOOL_CALL_WAITING_APPROVAL)] })],
+        pendingApprovals: [approval("t1", "delete", "Delete?")],
+      });
+    const running = snapshot({
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [aiMsg("", { toolCalls: [tool("t1", "delete", ToolCallStatus.TOOL_CALL_RUNNING)] })],
+    });
+    const events = eventsFor([waiting(), running, waiting()]);
+    expect(events.filter((e) => e.kind === "approvalNeeded")).toHaveLength(2);
+  });
+});
+
+describe("todos", () => {
+  it("emits an update only when the fingerprint changes", () => {
+    const t = todo("a", "do x", TodoStatus.TODO_PENDING);
+    const seq = [
+      snapshot({ todos: { a: t } }),
+      snapshot({ todos: { a: t } }),
+      snapshot({ todos: { a: todo("a", "do x", TodoStatus.TODO_COMPLETED) } }),
+    ];
+    expect(kindsFor(seq).filter((k) => k === "todoUpdate")).toHaveLength(2);
+  });
+});
+
+describe("context compaction", () => {
+  it("emits one event per new summarization entry", () => {
+    const seq = [
+      snapshot({ summarizations: [{ tokensBefore: 100, tokensAfter: 50 }] }),
+      snapshot({ summarizations: [{ tokensBefore: 100, tokensAfter: 50 }, { tokensBefore: 80, tokensAfter: 40 }] }),
+    ];
+    expect(kindsFor(seq).filter((k) => k === "contextCompacted")).toHaveLength(2);
+  });
+});
+
+describe("sub-agents", () => {
+  it("emits started, nested messages, then completed", () => {
+    const seq = [
+      snapshot({
+        subAgents: [subAgent("s1", SubAgentStatus.SUB_AGENT_IN_PROGRESS, { subject: "Explore", messages: [aiMsg("thinking")] })],
+      }),
+      snapshot({
+        subAgents: [
+          subAgent("s1", SubAgentStatus.SUB_AGENT_COMPLETED, {
+            subject: "Explore",
+            output: "done",
+            messages: [aiMsg("thinking"), aiMsg("result")],
+          }),
+        ],
+      }),
+    ];
+    const events = eventsFor(seq);
+    const subKinds = events.filter((e) => ["subAgentStarted", "subAgentCompleted"].includes(e.kind)).map((e) => e.kind);
+    expect(subKinds).toEqual(["subAgentStarted", "subAgentCompleted"]);
+    const nested = events.filter((e) => e.kind === "aiMessage" && e.subAgentId === "s1");
+    expect(nested).toHaveLength(2);
+  });
+});
+
+describe("terminal", () => {
+  it("emits done and ignores all later snapshots", () => {
+    const differ = new SnapshotDiffer();
+    const first = differ.next(snapshot({ phase: ExecutionPhase.EXECUTION_COMPLETED }));
+    expect(first.map((e) => e.kind)).toContain("done");
+    const second = differ.next(snapshot({ phase: ExecutionPhase.EXECUTION_COMPLETED }));
+    expect(second).toEqual([]);
+  });
+
+  it("carries the error message on failure", () => {
+    const events = eventsFor([snapshot({ phase: ExecutionPhase.EXECUTION_FAILED, error: "boom" })]);
+    const done = events.find((e) => e.kind === "done");
+    expect(done?.kind === "done" && done.error).toBe("boom");
+  });
+});