@stigmer/runner 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/harness/transcript/events.ts

@@ -0,0 +1,262 @@
+/**
+ * TranscriptEvent — the canonical event the transcript builder folds: what
+ * every harness's translator emits and `TranscriptBuilder` consumes to build
+ * the transcript half of the AgentExecutionStatus 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`), the
+ *     provenance and — where the harness runs a gated call before its
+ *     boundary parks it — the gate's word. The translator resolves them from
+ *     the harness's policy state; 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.
+ *
+ * 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 ───────────────────────────────────────────────────
+
+/**
+ * The translator's word that a call is GATED — the fields the row carries,
+ * never a decision the builder makes (#1097, 2026-09-14). A gated call that
+ * has STARTED is running until the
+ * harness's boundary parks it through `approval_proposed`: that is Cursor's
+ * shape (the SDK runs the tool; the deny-and-retry boundary parks it after
+ * the stream). Native never emits this member — LangGraph's `interrupt()`
+ * fires before the tool handler runs, so a held call never produces a
+ * `tool_started` at all, and the arrival of one IS the engine's word that
+ * the call was authorized (capture mode let it flow, a lease or policy
+ * cleared it, or the user approved it). Native's gate fact reaches the
+ * transcript through `approval_proposed` from the post-stream seed. So a
+ * row is never WAITING at creation on either harness; the plan's `parked:
+ * true` arm had no producer and was dropped.
+ */
+export interface GateAnswer {
+  /** The approval card's message, placeholders already resolved. */
+  readonly message: string;
+}
+
+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;
+  readonly gate?: GateAnswer;
+}
+
+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 — 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 "now": 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;
+  /** 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
+  | ToolArgDeltaEvent
+  | ToolOutputDeltaEvent
+  | ToolFinishedEvent
+  | ToolErrorEvent
+  | SubAgentStartedEvent
+  | SubAgentFinishedEvent
+  | SubAgentFailedEvent
+  | ApprovalProposedEvent
+  | SystemNoteEvent;

package/src/harness/transcript/state.ts

@@ -0,0 +1,167 @@
+/**
+ * TranscriptState — the AgentExecutionStatus proto `TranscriptBuilder` is
+ * building into, held as one {@link Transcript} per scope: the root's over
+ * `status.messages`, and one per sub-agent over its row's `messages`.
+ *
+ * Indexes, not copies: every map value is the live proto object (a ToolCall
+ * inside a message's repeated field, an AgentMessage inside a `messages`
+ * array), so a mutation through the index IS the mutation of the proto, and
+ * nothing here can drift from what is persisted. The arrays themselves are
+ * the status's own, pushed into and never replaced, so every wrapper of the
+ * status (the runtime's persist chokepoint, the settle modules that amend
+ * rows by identity) keeps seeing every row. A reinvocation's prior rows
+ * arrive through {@link TranscriptState.seed} — the turn runtime's
+ * `seedFromPersistedStatus` hands them here — so they are indexed by the
+ * same routine that indexes a status handed to the constructor.
+ *
+ * One shape for every scope (since #1097): until then the root's indexes
+ * lived here keyed by LangGraph namespace and the
+ * sub-agents' in a second module with its own copies of the same maps and
+ * handlers (`subagent-tracker.ts`, deleted in #1097). Scope is `subAgentId?`
+ * now and the namespace key collapsed — the tracker already resolved every
+ * local namespace to `""` — so a transcript's "current AI message" and
+ * "last run" are single values.
+ *
+ * The name says what it holds — the transcript's bookkeeping, not the
+ * execution's state, which is the turn runtime's (`harness/turn-context.ts`);
+ * it was `ExecutionState` in the native adapter (renamed in #1097).
+ */
+
+import type { AgentExecutionStatus } 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 type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+
+/**
+ * One scope's transcript: the `messages[]` it folds into (by reference) and
+ * the live indexes over it. Seeded rows are indexed at construction so a
+ * re-emitted event reconciles onto the existing row instead of duplicating
+ * it (the durable-checkpoint resume; the memory-checkpointer replay).
+ */
+export class Transcript {
+  /** tool_call_id → the live ToolCall inside one of this transcript's messages. */
+  readonly toolCalls = new Map<string, ToolCall>();
+
+  /**
+   * runId → the AgentMessage that run streams into (a THINKING row under
+   * its own key), so two runs' tokens never interleave.
+   */
+  readonly messagesByRun = new Map<string, AgentMessage>();
+
+  /**
+   * The AI message a tool row attaches to — the latest message with text in
+   * this scope. Over a seeded transcript it starts as the seed's
+   * last AI message: the message that proposed a call is still the
+   * one that proposed it across a turn boundary, which is also Cursor's
+   * shape (`findOrCreateLastAiMessage`).
+   */
+  currentAiMessage: AgentMessage | undefined;
+
+  /** The latest LLM run in this scope, for closing the previous message's streaming flag when a new run starts. */
+  lastRunId: string | undefined;
+
+  /** Progressive tool-call argument JSON, accumulated per callId until it parses. */
+  readonly argBuffers = new Map<string, string>();
+
+  constructor(readonly messages: AgentMessage[]) {
+    for (const message of messages) this.index(message);
+  }
+
+  /**
+   * Take a message that is already on (or is being appended to) this
+   * transcript into the indexes: every row by id, and the message as the
+   * current AI message when it is one — the seed's last AI message is the
+   * one a resumed turn's first row joins. The one routine behind
+   * both ways rows arrive before the stream — the status as handed to the
+   * constructor, and the runtime's seed of a reinvocation's prior rows
+   * ({@link TranscriptState.seed}) — so neither can index differently.
+   */
+  index(message: AgentMessage): void {
+    for (const tc of message.toolCalls) {
+      if (tc.id) this.toolCalls.set(tc.id, tc);
+    }
+    if (message.type === MessageType.MESSAGE_AI) this.currentAiMessage = message;
+  }
+}
+
+/** The transcript half of a persisted status: what a reinvocation seeds through the builder. */
+export type TranscriptSeed = Pick<AgentExecutionStatus, "messages" | "subAgentExecutions" | "artifacts" | "workspaceWriteBacks" | "todos">;
+
+/** A sub-agent's row and the transcript folded into it. */
+export interface SubAgentScope {
+  readonly row: SubAgentExecution;
+  readonly transcript: Transcript;
+}
+
+export class TranscriptState {
+  /** The protobuf projection being built. */
+  readonly proto: AgentExecutionStatus;
+
+  /** The root transcript, over `proto.messages`. */
+  readonly root: Transcript;
+
+  private readonly subAgentsById = new Map<string, SubAgentScope>();
+
+  /**
+   * Indexes the status as handed: the root's messages and every seeded
+   * sub-agent row (a reinvocation's seed carries prior turns' rows, whose
+   * events may be re-driven).
+   */
+  constructor(proto: AgentExecutionStatus) {
+    this.proto = proto;
+    this.root = new Transcript(proto.messages);
+    for (const row of proto.subAgentExecutions) {
+      this.subAgentsById.set(row.id, { row, transcript: new Transcript(row.messages) });
+    }
+  }
+
+  /** The transcript an event folds into: the root's for no `subAgentId`, a sub-agent's for a known one, `undefined` for an unknown one. */
+  scope(subAgentId: string | undefined): Transcript | undefined {
+    if (subAgentId === undefined) return this.root;
+    return this.subAgentsById.get(subAgentId)?.transcript;
+  }
+
+  subAgent(subAgentId: string): SubAgentScope | undefined {
+    return this.subAgentsById.get(subAgentId);
+  }
+
+  /** Push a new sub-agent row onto the status and open its transcript. The caller checks the id is new. */
+  openSubAgent(row: SubAgentExecution): SubAgentScope {
+    this.proto.subAgentExecutions.push(row);
+    const scope = { row, transcript: new Transcript(row.messages) };
+    this.subAgentsById.set(row.id, scope);
+    return scope;
+  }
+
+  /**
+   * Append a persisted transcript's rows to the status AND index them — the
+   * runtime's seed of a reinvocation (`harness/turn-context.ts`
+   * `seedFromPersistedStatus` says why every collection is seeded: the
+   * server replaces each list wholesale, so a resumed turn's write must be a
+   * superset). Every collection is pushed into, never reassigned, so the
+   * status's arrays stay the ones every wrapper of the status holds. A
+   * sub-agent row already known by id is skipped (a seed is applied once).
+   * The rows arrive through the same {@link Transcript.index} the
+   * constructor uses, so a builder that seeds after it is born indexes
+   * exactly as one born over the seeded status would.
+   */
+  seed(persisted: TranscriptSeed): void {
+    for (const message of persisted.messages) {
+      this.proto.messages.push(message);
+      this.root.index(message);
+    }
+    for (const row of persisted.subAgentExecutions) {
+      if (this.subAgentsById.has(row.id)) continue;
+      this.openSubAgent(row);
+    }
+    this.proto.artifacts.push(...persisted.artifacts);
+    this.proto.workspaceWriteBacks.push(...persisted.workspaceWriteBacks);
+    for (const [id, todo] of Object.entries(persisted.todos)) this.proto.todos[id] = todo;
+  }
+
+  /** Every transcript, the root's first — for the rules that sweep them all (`finalize`). */
+  *transcripts(): IterableIterator<Transcript> {
+    yield this.root;
+    for (const { transcript } of this.subAgentsById.values()) yield transcript;
+  }
+}