@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/harness/transcript/events.ts

@@ -0,0 +1,281 @@
+/**
+ * TranscriptEvent — the canonical event the transcript builder folds: what
+ * every harness's translator emits and `TranscriptBuilder` consumes to build
+ * the transcript half of the RunStatus proto.
+ *
+ * A runner-internal contract (not persisted, not exposed to clients). It was
+ * born in the native adapter as `StigmerRunEvent`, the normalized form of
+ * LangGraph's v3 protocol, and promoted here on 2026-09-14 (#1097) because
+ * its own header already called it the thing that isolates the builder from
+ * the engine — the same move #1070 and #1096 made for the turn runtime. #1097
+ * cut it engine-neutral one rule at a time:
+ *
+ *   - Every member the builder never folded left — `usage`, `lifecycle`,
+ *     `provider`, and the `seq`/`node`/`messageId`/`reason` fields no handler
+ *     read. Usage is a LOOP concern: the native loop reads it off the wire
+ *     (`usageOf`) and prices it into `TurnSink.reportUsage`; the Cursor loop
+ *     reads its own from the SDK's `turn-ended` delta. A transcript fact is
+ *     what a row or a message carries; usage is neither.
+ *   - `tool_finished` carries `result: string`; the engine's output
+ *     envelope is the translator's to render.
+ *   - `tool_started` carries the attribution (`mcpServerSlug`) and the
+ *     provenance, which the translator resolves from the harness's policy
+ *     state. It never says whether the call is held: a started call is
+ *     running, and a held one reaches the transcript as `approval_proposed`
+ *     on both harnesses, the one writer of a row's approval fields (#1117).
+ *     The builder writes what it is told and decides nothing about approval.
+ *   - Scope is `subAgentId?` — the only scope either harness has is
+ *     "the root, or one sub-agent by the id its row carries" — and the
+ *     translator says when a sub-agent opens and closes
+ *     (`sub_agent_started/finished/failed`). LangGraph's namespace grammar
+ *     (`tools:<uuid>|model_request:<uuid>`), the `task` tool's name and its
+ *     depth rule are the native translator's alone now.
+ *   - `approval_proposed`, the one post-stream fact both harnesses
+ *     produce, and `system_note`, a harness's line in its own voice. The
+ *     union is complete: a Cursor translator emits it and writes
+ *     nothing else.
+ *   - `tool_policy`, the provenance of a call an agent's hook decided. A
+ *     hook is a process, not policy state a translator can re-derive, so the
+ *     gate that ran it says what it decided, and the builder stamps the row
+ *     whether it opens before or after.
+ *
+ * The rule the union keeps: a member carries an identity and the
+ * fact the builder cannot read elsewhere, nothing else. Every engine fact
+ * reaches the builder as a translator's output.
+ *
+ * ID conventions:
+ *   - `runId`  — the identity of ONE streamed assistant message (LangGraph's
+ *     LLM-call run id on native; a translator-minted segment id on Cursor);
+ *     shared across that message's events
+ *   - `callId` — provider tool call ID (e.g. `toolu_...`); keys ToolCall records
+ *   - `subAgentId` — the sub-agent row's id, which on both harnesses is the
+ *     `task` tool call's id
+ */
+
+import type { PolicySource } from "../../shared/approval-policy.js";
+
+// ── Scope ─────────────────────────────────────────────────────────
+
+/**
+ * Which transcript a fact belongs to: the root's, or a sub-agent's by the id
+ * its row carries. Absent = root. The builder keeps one set of handlers and
+ * looks the scope's transcript up by this id; how a harness knows which
+ * sub-agent an event belongs to (LangGraph's namespace prefix, Cursor's
+ * `conversationSteps`) is the translator's knowledge.
+ */
+interface Scoped {
+  readonly subAgentId?: string;
+}
+
+// ── Message Events ────────────────────────────────────────────────
+
+export interface MessageStartEvent extends Scoped {
+  readonly kind: "message_start";
+  readonly runId: string;
+}
+
+export interface TextDeltaEvent extends Scoped {
+  readonly kind: "text_delta";
+  readonly runId: string;
+  readonly text: string;
+}
+
+export interface ReasoningDeltaEvent extends Scoped {
+  readonly kind: "reasoning_delta";
+  readonly runId: string;
+  readonly text: string;
+}
+
+export interface MessageFinishEvent extends Scoped {
+  readonly kind: "message_finish";
+  readonly runId: string;
+}
+
+// ── Tool Events ───────────────────────────────────────────────────
+
+/**
+ * A tool call has started. It carries no approval fact, on either harness
+ * (#1117): whether a call is HELD for a person's decision is known only after
+ * the engine's own gate has run, and it reaches the transcript as
+ * `approval_proposed` — native's post-stream seed after LangGraph's
+ * `interrupt()` (which fires before the tool handler, so a held call never
+ * starts), Cursor's deny-and-retry boundary after the preToolUse hook denied
+ * it. A call that runs under a lease, a bypass or capture mode is therefore
+ * never marked as requiring approval. A `gate` member carried the policy's
+ * category verdict here until #1117; it had one producer (Cursor), which made
+ * the field mean different things per harness, and it was dropped, as a
+ * `parked: true` arm with no producer was before it.
+ */
+export interface ToolStartedEvent extends Scoped {
+  readonly kind: "tool_started";
+  readonly callId: string;
+  readonly name: string;
+  readonly input: Record<string, unknown>;
+  /** The MCP server this tool belongs to, `""` for a built-in — resolved by the translator (attribution is engine knowledge). */
+  readonly mcpServerSlug: string;
+  /**
+   * Which policy layer governs this call, for the row's authorization
+   * provenance; absent where the harness cannot attribute it (sub-agent rows
+   * on both harnesses today, #1133) or no layer governs it.
+   */
+  readonly provenance?: PolicySource;
+  /** The plugin whose hook the provenance names (`""` for the agent's own hooks block); absent when no hook did. */
+  readonly policyHook?: string;
+}
+
+/**
+ * Which hook decided a call that runs, as the gate that ran it reports it
+ * (a hook's answer cannot be re-derived from static policy state). The
+ * builder stamps it on the call's row and lets it outrank the provenance its
+ * `tool_started` carried, in whichever order the two arrive: they travel on
+ * different engine streams, and nothing orders one against the other.
+ */
+export interface ToolPolicyEvent extends Scoped {
+  readonly kind: "tool_policy";
+  readonly callId: string;
+  readonly provenance: PolicySource;
+  /** The deciding plugin's slug; `""` for the agent's own hooks block. */
+  readonly policyHook: string;
+}
+
+export interface ToolArgDeltaEvent extends Scoped {
+  readonly kind: "tool_arg_delta";
+  readonly callId: string;
+  readonly argsChunk: string;
+}
+
+export interface ToolOutputDeltaEvent extends Scoped {
+  readonly kind: "tool_output_delta";
+  readonly callId: string;
+  readonly delta: string;
+}
+
+/**
+ * A fact the harness observed at one instant and delivers at another. The
+ * builder is the transcript's one clock — every row stamp is `utcTimestamp()`
+ * at apply, read once per observation when the loop folds a raw event's
+ * facts together (`TranscriptBuilder.applyObservation`) — except here: a
+ * Cursor completion arrives first on the SDK's
+ * delta channel, and the translator must QUEUE it for the loop to apply after
+ * the current stream event (a delta applied mid-persist would land on a row
+ * the offload is replacing). Without the observed
+ * instant the row's `completedAt` would be the fold's moment, one stream
+ * event late — seconds late while the model narrates — and the tool's
+ * duration in the console would lie (fixed 2026-09-15, #1097). Absent
+ * means the fold's instant: native, and every fact a translator emits as it
+ * sees it, never set it.
+ */
+interface Observed {
+  readonly observedAt?: string;
+}
+
+export interface ToolFinishedEvent extends Scoped, Observed {
+  readonly kind: "tool_finished";
+  readonly callId: string;
+  /**
+   * The result as the row carries it — already a string. Rendering the
+   * engine's output (LangChain's ToolMessage envelope, Cursor's result
+   * object) is the translator's; the builder stores what it is handed and
+   * the persist chokepoint bounds it.
+   */
+  readonly result: string;
+}
+
+export interface ToolErrorEvent extends Scoped, Observed {
+  readonly kind: "tool_error";
+  readonly callId: string;
+  readonly message: string;
+}
+
+// ── Sub-Agent Events ──────────────────────────────────────────────
+
+/**
+ * A sub-agent opens: the builder creates its row (keyed by `subAgentId`) and
+ * a transcript of its own that later events scoped to it fold into. Emitted
+ * by the translator BEFORE the delegating tool's own `tool_started`, so the
+ * row exists when the parent's `task` row is created. For a sub-agent the
+ * builder already knows (a seeded row re-announced by a replayed engine)
+ * this is a no-op — the row is never duplicated.
+ */
+export interface SubAgentStartedEvent {
+  readonly kind: "sub_agent_started";
+  readonly subAgentId: string;
+  /** The sub-agent's declared name (deepagents' `subagent_type`; Cursor's `task` name). */
+  readonly name: string;
+  /** What it was asked to do, as the card's title and as its input. */
+  readonly subject: string;
+  readonly input: string;
+}
+
+export interface SubAgentFinishedEvent {
+  readonly kind: "sub_agent_finished";
+  readonly subAgentId: string;
+  /** The sub-agent's final output as the row carries it — the same string the delegating tool's `tool_finished` carries. */
+  readonly output?: string;
+}
+
+export interface SubAgentFailedEvent {
+  readonly kind: "sub_agent_failed";
+  readonly subAgentId: string;
+  readonly error: string;
+}
+
+// ── Post-Stream Facts ─────────────────────────────────────────────
+
+/**
+ * A call the harness's boundary parked for approval AFTER the stream — the
+ * one post-stream fact both harnesses produce: native's
+ * `seedPendingInterrupts` reads the graph checkpoint's un-resumed interrupts
+ * (a held call never streamed a `tool_started`, so no row exists yet);
+ * Cursor's denial overlay re-proposes a call the hook denied (a row exists,
+ * `error`ed). An UPSERT: a known `callId` REOPENS its row — WAITING, the
+ * outcome fields cleared, `approvalRequestedAt` stamped once; an unknown one
+ * gets a WAITING row on the scope's current AI message, the text that
+ * proposed it (the message-boundary rule). Either way the builder reports
+ * {@link awaitingApproval}. The one place a row is ever WAITING.
+ */
+export interface ApprovalProposedEvent extends Scoped {
+  readonly kind: "approval_proposed";
+  readonly callId: string;
+  readonly name: string;
+  readonly mcpServerSlug: string;
+  /** The proposed arguments, redacted by the harness — the card renders the change from them; absent when the harness could not correlate them. */
+  readonly args?: Record<string, unknown>;
+  /** The approval card's message, placeholders already resolved. */
+  readonly message: string;
+  readonly provenance?: PolicySource;
+  /** The plugin whose hook asked (`""` for the agent's own hooks block); absent when no hook asked. */
+  readonly policyHook?: string;
+  /** Cursor's content identity for a same-identity re-proposal (`approvalContentDigest`); native has none. */
+  readonly contentDigest?: string;
+}
+
+/**
+ * A line the harness adds to the transcript in its own voice — Cursor's
+ * `task` SDK event (a status line about the run), the boundary's
+ * unresolved-disclosure row. A SYSTEM message in the scope, never
+ * an AI one, so it neither hosts tool rows nor moves the message boundary.
+ */
+export interface SystemNoteEvent extends Scoped {
+  readonly kind: "system_note";
+  readonly text: string;
+}
+
+// ── Union ─────────────────────────────────────────────────────────
+
+export type TranscriptEvent =
+  | MessageStartEvent
+  | TextDeltaEvent
+  | ReasoningDeltaEvent
+  | MessageFinishEvent
+  | ToolStartedEvent
+  | ToolPolicyEvent
+  | ToolArgDeltaEvent
+  | ToolOutputDeltaEvent
+  | ToolFinishedEvent
+  | ToolErrorEvent
+  | SubAgentStartedEvent
+  | SubAgentFinishedEvent
+  | SubAgentFailedEvent
+  | ApprovalProposedEvent
+  | SystemNoteEvent;

package/src/harness/transcript/resume-seed.ts

@@ -0,0 +1,280 @@
+/**
+ * What a resumed invocation seeds from the session's log: the asks its
+ * engine resumes onto, and nothing else of the transcript.
+ *
+ * A run is one turn, and its re-invocations (an approval resume, a pause
+ * and resume, a transient retry) each build their own rows: the run's
+ * status carries no rows, and what earlier invocations did is already in
+ * the log. A resumed engine resumes onto only one thing the runtime must
+ * hold as rows: the calls that asked and are not finished. Cursor re-issues
+ * them under new ids and its translator matches the seeded WAITING rows by
+ * identity token (`execute-cursor/translator.ts`); native re-emits each under
+ * its own id and the builder flips the seeded row (`transcript/builder.ts`).
+ * The runtime's own readers of a seeded row (the answers' copy onto it,
+ * the settle of a denied call, provenance, the exact-apply) read the same
+ * rows.
+ *
+ * So the seed is, per thread (the root, or a sub-agent's), one message with
+ * no text holding:
+ *  - every asked call with no result in the log: an `agent.tool_use` or
+ *    `agent.mcp_tool_use` whose `evaluated_permission` is `ask`, as a
+ *    WAITING_APPROVAL row carrying what its `stigmer.permission.asked` says
+ *    (the message, the preview, the rule and hook that asked, the content
+ *    digest Cursor's identity token reads); the answers and grants are
+ *    copied on afterwards (`approval-answers.ts` `copyAnswersOntoRows`);
+ *  - in the root, the `task` call of every sub-agent thread that holds such
+ *    an ask, RUNNING, so the thread's end and the call's result are written
+ *    when the resumed sub-agent finishes;
+ * and one sub-agent row per such thread, IN_PROGRESS, named and briefed as
+ * its `session.thread_created` and `agent.thread_message_sent` say.
+ *
+ * A seeded row's id is its tool use id's call part (`events/ids.ts`): the
+ * provider's call id as written, or its hashed form for one the id rule
+ * hashed, which derives the same tool use id again, so whatever the turn
+ * writes for the row lands under the id the log already holds. The seeded
+ * messages write nothing (they have no text) and their tool uses are in the
+ * log already, so the emitter numbers the invocation's own messages on from
+ * the log's highest index per scope (`events/emitter.ts`).
+ *
+ * The same read gives two more facts an earlier invocation wrote: the run's
+ * newest root `agent.message` (the run's answer, when this invocation
+ * writes none) and its `stigmer.memory.recalled` (the memory selection a
+ * resumed turn replays rather than re-selects).
+ *
+ * Proven by `transcript/__tests__/resume-seed.test.ts` and both harnesses' hermetic
+ * resume goldens. It lives with the builder because it creates rows: the
+ * seed's rows are built here and enter the turn through `seed()`.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { SessionEvent } from "@stigmer/apis/ai/stigmer/agentic/session/v1/event_pb";
+
+import { POLICY_SOURCE_WORDS } from "../events/emitter.js";
+import type { TranscriptSeed } from "./state.js";
+import { classifyTool } from "../../shared/tool-kind.js";
+import {
+  AgentMessageSchema,
+  RecalledMemoriesReportSchema,
+  SubAgentRunSchema,
+  ToolCallSchema,
+  type AgentMessage,
+  type RecalledMemoriesReport,
+  type SubAgentRun,
+  type ToolCall,
+} from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import {
+  ApprovalPolicySource,
+  MessageType,
+  SubAgentStatus,
+  ToolCallStatus,
+} from "../../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+
+/** The log types the seed reads. */
+export const RESUME_SEED_EVENT_TYPES = [
+  "agent.tool_use",
+  "agent.mcp_tool_use",
+  "agent.tool_result",
+  "agent.mcp_tool_result",
+  "stigmer.permission.asked",
+  "session.thread_created",
+  "agent.thread_message_sent",
+  "agent.message",
+  "stigmer.memory.recalled",
+] as const;
+
+/** What a resumed invocation takes from the log (the module header). */
+export interface ResumeSeed {
+  /** The asks the engine resumes onto, and the threads that hold them. */
+  readonly rows: TranscriptSeed;
+  /** The text of the run's newest root `agent.message`; `undefined` when the log holds none. */
+  readonly answerText: string | undefined;
+  /** The run's memory selection as `stigmer.memory.recalled` states it; `undefined` when it holds none. */
+  readonly recalledMemoriesReport: RecalledMemoriesReport | undefined;
+}
+
+/** Nothing to seed: a fresh turn. */
+export const NO_RESUME_SEED: ResumeSeed = {
+  rows: { messages: [], subAgentRuns: [] },
+  answerText: undefined,
+  recalledMemoriesReport: undefined,
+};
+
+/** One tool use as the log holds it. */
+interface LoggedUse {
+  readonly id: string;
+  readonly name: string;
+  readonly input: ToolCall["args"];
+  readonly mcpServerSlug: string;
+  readonly permission: string;
+  readonly threadId: string;
+}
+
+/** The policy source enum of a logged word; UNSPECIFIED for a word no source has. */
+const POLICY_SOURCE_BY_WORD: ReadonlyMap<string, ApprovalPolicySource> = new Map(
+  (Object.entries(POLICY_SOURCE_WORDS) as [string, string][])
+    .filter(([, word]) => word !== "")
+    .map(([value, word]) => [word, Number(value) as ApprovalPolicySource]),
+);
+
+/** A tool use id's call part: the row id that derives the same tool use id again (the module header). */
+export function rowIdOf(runId: string, toolUseId: string): string {
+  return toolUseId.startsWith(`${runId}.`) ? toolUseId.slice(runId.length + 1) : toolUseId;
+}
+
+/** The text of a content array, its text blocks joined. */
+function textOf(content: readonly { readonly type: string; readonly text: string }[]): string {
+  return content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text)
+    .join("");
+}
+
+/** The seed of a resumed invocation from its run's events, oldest first (the module header). A pure map. */
+export function resumeSeedOf(runId: string, events: readonly SessionEvent[]): ResumeSeed {
+  const uses: LoggedUse[] = [];
+  const usesById = new Map<string, LoggedUse>();
+  const finished = new Set<string>();
+  const asks = new Map<string, Extract<SessionEvent["event"], { case: "stigmerPermissionAsked" }>["value"]>();
+  const threadNames = new Map<string, string>();
+  const threadInputs = new Map<string, string>();
+  let answerText: string | undefined;
+  let recalledMemoriesReport: RecalledMemoriesReport | undefined;
+
+  for (const event of events) {
+    if (event.runId !== "" && event.runId !== runId) continue;
+    switch (event.event.case) {
+      case "agentToolUse":
+      case "agentMcpToolUse": {
+        const value = event.event.value;
+        const use: LoggedUse = {
+          id: value.id,
+          name: value.name,
+          input: value.input,
+          mcpServerSlug: event.event.case === "agentMcpToolUse" ? event.event.value.mcpServerName : "",
+          permission: value.evaluatedPermission,
+          threadId: value.sessionThreadId,
+        };
+        if (!usesById.has(use.id)) {
+          uses.push(use);
+          usesById.set(use.id, use);
+        }
+        break;
+      }
+      case "agentToolResult":
+        finished.add(event.event.value.toolUseId);
+        break;
+      case "agentMcpToolResult":
+        finished.add(event.event.value.mcpToolUseId);
+        break;
+      case "stigmerPermissionAsked":
+        if (!asks.has(event.event.value.toolUseId)) asks.set(event.event.value.toolUseId, event.event.value);
+        break;
+      case "sessionThreadCreated":
+        threadNames.set(event.event.value.sessionThreadId, event.event.value.agentName);
+        break;
+      case "agentThreadMessageSent":
+        threadInputs.set(event.event.value.toSessionThreadId, textOf(event.event.value.content));
+        break;
+      case "agentMessage":
+        if (event.threadId === "") answerText = textOf(event.event.value.content);
+        break;
+      case "stigmerMemoryRecalled": {
+        const { selectionActive, injectedMemoryIds, embeddingModel } = event.event.value;
+        recalledMemoriesReport ??= create(RecalledMemoriesReportSchema, {
+          selectionActive,
+          injectedMemoryIds: [...injectedMemoryIds],
+          embeddingModel,
+        });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const openAsks = uses.filter((use) => use.permission === "ask" && !finished.has(use.id));
+  const rootCalls: ToolCall[] = [];
+  const subAgentRuns: SubAgentRun[] = [];
+  const threadRows = new Map<string, ToolCall[]>();
+  for (const use of openAsks) {
+    if (use.threadId === "") {
+      rootCalls.push(askedRow(runId, use, asks.get(use.id)));
+      continue;
+    }
+    let calls = threadRows.get(use.threadId);
+    if (calls === undefined) {
+      calls = [];
+      threadRows.set(use.threadId, calls);
+    }
+    calls.push(askedRow(runId, use, asks.get(use.id)));
+  }
+  for (const [thread, calls] of threadRows) {
+    const subAgentId = rowIdOf(runId, thread);
+    // The thread's id is its `task` call's tool use id (`events/ids.ts`).
+    const task = usesById.get(thread);
+    if (task !== undefined && !finished.has(task.id)) rootCalls.push(runningRow(runId, task));
+    subAgentRuns.push(
+      create(SubAgentRunSchema, {
+        id: subAgentId,
+        name: threadNames.get(thread) ?? task?.name ?? "",
+        input: threadInputs.get(thread) ?? "",
+        status: SubAgentStatus.SUB_AGENT_IN_PROGRESS,
+        messages: [holder(calls)],
+      }),
+    );
+  }
+  // The root's rows in log order: a thread's `task` call opened before the ask it holds.
+  const order = new Map(uses.map((use, index) => [rowIdOf(runId, use.id), index]));
+  rootCalls.sort((a, b) => (order.get(a.id) ?? 0) - (order.get(b.id) ?? 0));
+
+  return {
+    rows: { messages: rootCalls.length === 0 ? [] : [holder(rootCalls)], subAgentRuns },
+    answerText,
+    recalledMemoriesReport,
+  };
+}
+
+/** A message with no text holding seeded rows: it writes nothing to the log. */
+function holder(calls: ToolCall[]): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content: "", toolCalls: calls });
+}
+
+/** An asked call still waiting, as its tool use and its ask state it. */
+function askedRow(
+  runId: string,
+  use: LoggedUse,
+  ask: { readonly message: string; readonly argsPreview: string; readonly policySource: string; readonly policyHook: string; readonly contentDigest: string; readonly processedAt: string } | undefined,
+): ToolCall {
+  const row = create(ToolCallSchema, {
+    id: rowIdOf(runId, use.id),
+    name: use.name,
+    status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    requiresApproval: true,
+    mcpServerSlug: use.mcpServerSlug,
+  });
+  if (use.input !== undefined) row.args = use.input;
+  row.toolKind = classifyTool(row.name, row.mcpServerSlug);
+  if (ask !== undefined) {
+    row.approvalMessage = ask.message;
+    row.argsPreview = ask.argsPreview;
+    row.approvalPolicySource = POLICY_SOURCE_BY_WORD.get(ask.policySource) ?? ApprovalPolicySource.UNSPECIFIED;
+    row.approvalPolicyHook = ask.policyHook;
+    row.approvalContentDigest = ask.contentDigest;
+    row.approvalRequestedAt = ask.processedAt;
+  }
+  return row;
+}
+
+/** A sub-agent's `task` call, still running while its thread waits on an ask. */
+function runningRow(runId: string, use: LoggedUse): ToolCall {
+  const row = create(ToolCallSchema, {
+    id: rowIdOf(runId, use.id),
+    name: use.name,
+    status: ToolCallStatus.TOOL_CALL_RUNNING,
+    mcpServerSlug: use.mcpServerSlug,
+  });
+  if (use.input !== undefined) row.args = use.input;
+  row.toolKind = classifyTool(row.name, row.mcpServerSlug);
+  return row;
+}
+