@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/harness/transcript/builder.js

@@ -0,0 +1,842 @@
+/**
+ * TranscriptBuilder — folds `TranscriptEvent`s into the turn's rows it is
+ * handed (`TurnRows`, the runner's own proto: messages, tool-call rows and
+ * their approval status, sub-agent rows, todos), and registers the turn's
+ * artifacts and write-backs on the run's status it is handed beside them.
+ *
+ * The one transcript builder, for every harness (#1097). It
+ * was the native harness's `V3StatusBuilder` (the one builder there since
+ * #1096 retired the v2 `StatusBuilder`), promoted here on 2026-09-14
+ * unchanged and then cut engine-neutral one rule per commit:
+ * it reads no engine envelope, decides nothing about approval,
+ * and knows no engine's tool names or namespace grammar — every engine
+ * fact reaches it as a translator's output, on one union. The Cursor
+ * harness feeds it through a translator; the runtime constructs it once
+ * per turn and hands it to every adapter as `TurnSink.transcript`, so
+ * a transcript row has exactly one way into the rows — a source-walking
+ * fence, `harness/__tests__/transcript-writers.test.ts`, refuses a second.
+ *
+ * ONE set of handlers over ONE scope shape: every handler takes
+ * the scope's {@link Transcript} — the root's over `rows.messages`, or a
+ * sub-agent's over its row's — from `TranscriptState`, so a sub-agent's
+ * transcript is folded by exactly the rules the root's is. Until #1097 the
+ * sub-agents' half was a second module (`SubAgentTracker`) with its own copy
+ * of every handler, differing only in which array it pushed into — the
+ * memo's third copy of the folding rule, and the one whose namespace filter
+ * differed from the root's by one segment (found in #1096: the root
+ * filed text under `model_request:<uuid>` and looked the tool's parent up
+ * under `""`, so every native tool row sat on an empty message after its
+ * text). With scope a single value per transcript, that class of miss
+ * cannot exist.
+ *
+ * The rules this builder owns, each with an arm in
+ * `harness/transcript/__tests__/builder.test.ts` and the harness whose rule
+ * it generalises in parentheses:
+ *
+ *   - A row per `callId`, indexed over the rows as handed and over what
+ *     {@link seed} appends (a reinvocation's asks, indexed by the same
+ *     routine, so a builder born before the seed is no different from one
+ *     born after it), reconciled in place on a re-emitted start — an UNSETTLED row becomes
+ *     RUNNING (a WAITING row on native's durable-checkpoint resume; an
+ *     INTERRUPTED row on a recovery replay, the enum's supersede rule) and
+ *     takes the args and preview it lacked — never duplicated. Every row
+ *     with args carries them with secret-keyed values redacted
+ *     (stigmer#1119), and an `argsPreview` elided and redacted, salient
+ *     fields verbatim. A finish or an error is an upsert: status
+ *     monotonic, `completedAt` once, a non-empty result or message
+ *     overwrites, an empty one never clears; a re-emit that
+ *     changes nothing forces no persist; a fact the harness
+ *     observed earlier and delivers later stamps its own instant
+ *     (`observedAt`); an output chunk for a settled row is stale
+ *     and dropped — the completion's result is the whole output.
+ *   - One observation, one instant: the facts a translator made of one
+ *     raw engine event, folded through {@link applyObservation}, share
+ *     one clock read for every stamp they make (a Cursor completion with
+ *     no running before it starts and finishes at the same instant,
+ *     stigmer#1390); {@link apply} alone reads the clock per fact.
+ *   - The AI-message boundary (native's own rule, made correct by
+ *     scoping): a tool row attaches to the scope's current AI message — the
+ *     latest with text, the seed's last AI message over a seeded transcript
+ *     — and to a new empty one only when the scope has none.
+ *   - A THINKING row per `runId`, a text message per `runId`; a
+ *     new run closes the previous message's streaming flag, and a run's
+ *     finish closes both its text and its thinking.
+ *   - A sub-agent row per `subAgentId`, opened by `sub_agent_started`,
+ *     closed COMPLETED/FAILED by `sub_agent_finished/failed` with its
+ *     transcript's streaming flags cleared; a known id is never re-opened.
+ *     CANCELLED is not this builder's: `shared/subagent-rows.ts`
+ *     `cancelInProgressSubAgentProtos` is the one home of that transition.
+ *   - `approval_proposed` is the one place a row is ever WAITING: a known
+ *     row REOPENS — WAITING, the outcome fields cleared,
+ *     `approvalRequestedAt` stamped once, the proposal's args and preview
+ *     taken when carried (Cursor's `markWaitingApproval` + `applyGateInput`);
+ *     an unknown call gets a WAITING row on the scope's current AI message,
+ *     the text that proposed it (native's post-stream seed, before #1097 a new
+ *     empty message of its own). Either way {@link awaitingApproval} is set.
+ *   - `system_note` is a SYSTEM message in the scope, in the harness's
+ *     voice; it hosts no rows and moves no boundary.
+ *   - A completed `ToolKind.TODO` call in the ROOT scope is projected into
+ *     `rows.todos` through the shared `applyTodoUpdate`, a full replace
+ *     unless the call's args say `merge: true` (the row stays — the
+ *     clients filter it); a sub-agent's is not.
+ *   - `finalize()` clears every streaming flag in every scope.
+ *   - Artifacts upsert by `sandboxPath`/`contentHash`, write-backs by
+ *     `workspaceEntryName`: the inline publisher and the write-back
+ *     coordinator register theirs here, each through the one-method view it
+ *     declares for itself (`ArtifactSink`, `WriteBackSink`), which this class
+ *     satisfies by shape.
+ *   - {@link dirty} is set by every discrete change above and by nothing a
+ *     token delta does; the adapter's loop reads it and clears it with
+ *     {@link markPersisted} as it requests the persist.
+ *
+ * The runtime may hand the constructor an OBSERVER of the fold: a callback
+ * that sees every event `apply` folded, in order, after the fold, and creates
+ * nothing (the runtime's turn timeline, `harness/turn-timeline.ts`, is the
+ * one observer today). A callback at construction, not a subscribe method,
+ * because that is how the runtime tells its collaborators what to do
+ * everywhere else (`PersistChokepoint`'s options, the stall watchdog's
+ * `onStall`): one observer, fixed at the one constructor call, nothing to
+ * add or remove mid-turn. The observer runs in its own try/catch, so it can
+ * neither block a fold nor break a harness; `seed()` does not notify it,
+ * because a seeded row is last turn's fact. When the adapter runs in the agent
+ * host, the events are folded by the host's builder and this one only relays
+ * them to its observer ({@link relayObserved}), with the instant of the
+ * host's fold.
+ *
+ * What this builder deliberately does NOT write, and who does (the adapter
+ * contract's field ownership, `harness/types.ts` `TurnSink`): the phase,
+ * `startedAt`, `streamingUsage` and the epilogue's plan artifact are the
+ * turn runtime's (the plan artifact supersedes by its own name rule, which
+ * is the plan's knowledge, not the transcript's). A row left
+ * WAITING_APPROVAL is reported as the {@link awaitingApproval} fact and the
+ * caller decides what that means for the turn — a fact only
+ * `approval_proposed` produces, because a call that has
+ * STARTED is never parked at creation. Usage never passes
+ * through here: the native loop reads it off the wire (`usageOf`) and
+ * prices it into the sink, the Cursor loop reads its own from the SDK.
+ */
+import { create } from "@bufbuild/protobuf";
+import { POLICY_ENGINE_VERSION, toProtoPolicySource } from "../../shared/approval-policy.js";
+import { SALIENT_ARG_FIELDS, buildElidedArgsPreview, redactSensitiveArgs } from "../../shared/args-preview.js";
+import { classifyTool } from "../../shared/tool-kind.js";
+import { applyTodoUpdate } from "../../shared/todos.js";
+import { utcTimestamp } from "../../shared/status.js";
+import { TranscriptState } from "./state.js";
+import { AgentMessageSchema, ToolCallSchema, SubAgentRunSchema, } from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { ApprovalAction, MessageType, SubAgentStatus, ToolCallStatus, ToolCallStreamingSource, ToolKind, } from "../../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+export class TranscriptBuilder {
+    executionId;
+    state;
+    observer;
+    _dirty = false;
+    _awaitingApproval = false;
+    /** The one instant of the observation being folded, while {@link applyObservation} runs; absent otherwise. */
+    observationInstant;
+    /** Hook provenance that arrived before its call's row, by call id; stamped when the row opens. */
+    pendingPolicies = new Map();
+    /**
+     * Builds INTO `rows`, by reference: its `messages`, `subAgentRuns` and
+     * every sub-agent row's `messages` are the arrays indexed and pushed
+     * into, never replaced, so a caller that holds the same rows (the
+     * runtime's chokepoint, a settle amending rows by identity) keeps seeing
+     * every row. Rows already there are indexed here; the asks a reinvocation
+     * resumes onto arrive later through {@link seed}, indexed by the same
+     * routine, so a re-driven event reconciles onto them either way. The
+     * turn's artifacts and write-backs are registered on `status`.
+     *
+     * The builder hands nothing back. A reader holds the rows it built the
+     * builder over — `TurnSink.rows` in production, the test's own in a
+     * test — so the transcript has one read handle and one write handle, and
+     * no second spelling of either.
+     *
+     * `observer`, when given, is told every event after it is folded (the
+     * header's rule). The runtime passes its turn timeline; the contract kit
+     * and the test doubles pass nothing.
+     */
+    constructor(executionId, rows, status, observer) {
+        this.executionId = executionId;
+        this.state = new TranscriptState(rows, status);
+        this.observer = observer;
+    }
+    /**
+     * Append a reinvocation's asks — the asked calls its engine resumes onto,
+     * read from the session's log, and the sub-agent rows that hold them —
+     * and index them, so a re-issued call reconciles onto its seeded row
+     * instead of duplicating it. The runtime calls this once, in its
+     * reinvocation phase, before any harness runs (`harness/transcript/resume-seed.ts`
+     * says what is seeded and why nothing else is). Seeded rows are an earlier
+     * invocation's facts: this sets neither {@link dirty} nor
+     * {@link awaitingApproval}.
+     */
+    seed(seeded) {
+        this.state.seed(seeded);
+    }
+    /**
+     * True once a row this turn was left WAITING_APPROVAL: the engine has
+     * interrupted (or the harness's boundary parked the call) and the turn
+     * should end awaiting a decision. A fact about the transcript, not a phase
+     * — the caller owns the phase. No `tool_started` sets it (a started call
+     * is running); `approval_proposed` does.
+     */
+    get awaitingApproval() {
+        return this._awaitingApproval;
+    }
+    /**
+     * True once a discrete, user-visible change has landed since the last
+     * persist — a row started or settled, a sub-agent opened or closed, an
+     * artifact or write-back registered, a note appended; never a token
+     * delta, which rides the streaming cadence. The one fact the adapter's
+     * persist decision reads (`shared/persist-decision.ts`); the adapter
+     * clears it with {@link markPersisted} as it requests the write, so a
+     * change that lands after the write started dirties the next one.
+     */
+    get dirty() {
+        return this._dirty;
+    }
+    markPersisted() {
+        this._dirty = false;
+    }
+    /**
+     * Fold one canonical event into the transcript, then tell the observer.
+     * Never throws: a handler's error is logged and the stream goes on, and so
+     * is an observer's — each in its own catch, so a failing observer still
+     * sees a folded transcript and a failing handler still reaches the observer.
+     */
+    apply(event) {
+        this.fold(event);
+        if (!this.observer)
+            return;
+        try {
+            this.observer(event, undefined, this.placeOf(event));
+        }
+        catch (err) {
+            console.error(`[TranscriptBuilder] Observer error: execution=${this.executionId} kind=${event.kind}: ${err}`);
+        }
+    }
+    /**
+     * Tell the observer about an event the agent host's builder folded
+     * (`agent-host/remote-adapter.ts`): the host's builder is the adapter's,
+     * this one is the runtime's, and the runtime's timeline observes through
+     * this one. Nothing is folded here; the host's rows reach these rows
+     * with its next persist. `atMs` is the host's fold instant on this
+     * process's `performance.now()` scale, `place` where the host's fold left
+     * a delta's row (the host's rows are these, row for row). Never
+     * throws.
+     */
+    relayObserved(event, atMs, place) {
+        if (!this.observer)
+            return;
+        try {
+            this.observer(event, atMs, place);
+        }
+        catch (err) {
+            console.error(`[TranscriptBuilder] Observer error: execution=${this.executionId} kind=${event.kind}: ${err}`);
+        }
+    }
+    /**
+     * Fold the facts ONE harness observation yields — the events a translator
+     * made of one raw engine event — at one instant: the clock is read once,
+     * and every stamp the facts make (a row's start and finish, a sub-agent's
+     * open and close, a message's timestamp) is that instant. A Cursor
+     * completion the stream reports with no running before it is a start and a
+     * finish in one event, and it must carry one instant, not two reads a
+     * millisecond apart (stigmer#1390). A fact that carries its own
+     * `observedAt` keeps it. Each fact is applied exactly as {@link apply}
+     * applies it, observer included.
+     */
+    applyObservation(facts) {
+        const outer = this.observationInstant;
+        this.observationInstant = outer ?? utcTimestamp();
+        try {
+            for (const fact of facts)
+                this.apply(fact);
+        }
+        finally {
+            this.observationInstant = outer;
+        }
+    }
+    /** Where the fold left a text or reasoning delta's row; absent for every other fact. */
+    placeOf(event) {
+        if (event.kind !== "text_delta" && event.kind !== "reasoning_delta")
+            return undefined;
+        const scope = this.state.scope(event.subAgentId);
+        const row = scope?.messagesByRun.get(event.kind === "text_delta" ? event.runId : thinkingKeyOf(event.runId));
+        if (scope === undefined || row === undefined)
+            return undefined;
+        const messageIndex = scope.messages.lastIndexOf(row);
+        return messageIndex < 0 ? undefined : { messageIndex };
+    }
+    /** The instant a stamp records: the observation's, while one is being folded, else now. */
+    instant() {
+        return this.observationInstant ?? utcTimestamp();
+    }
+    fold(event) {
+        try {
+            switch (event.kind) {
+                case "sub_agent_started":
+                    this.openSubAgent(event);
+                    return;
+                case "sub_agent_finished":
+                    this.closeSubAgent(event);
+                    return;
+                case "sub_agent_failed":
+                    this.failSubAgent(event);
+                    return;
+                default:
+                    break;
+            }
+            const scope = this.state.scope(event.subAgentId);
+            if (!scope) {
+                throw new Error(`event for unknown sub-agent ${event.subAgentId}`);
+            }
+            switch (event.kind) {
+                case "message_start":
+                    this.handleMessageStart(scope, event.runId);
+                    break;
+                case "text_delta":
+                    this.appendTextContent(scope, event.runId, event.text);
+                    break;
+                case "reasoning_delta":
+                    this.appendThinkingContent(scope, event.runId, event.text);
+                    break;
+                case "message_finish":
+                    this.handleMessageFinish(scope, event.runId);
+                    break;
+                case "tool_started":
+                    this.handleToolStarted(scope, event);
+                    break;
+                case "tool_policy":
+                    this.handleToolPolicy(scope, event);
+                    break;
+                case "tool_arg_delta":
+                    this.handleToolArgDelta(scope, event.callId, event.argsChunk);
+                    break;
+                case "tool_output_delta":
+                    this.handleToolOutputDelta(scope, event.callId, event.delta);
+                    break;
+                case "tool_finished":
+                    this.handleToolFinished(scope, event.callId, event.result, event.observedAt);
+                    break;
+                case "tool_error":
+                    this.handleToolError(scope, event.callId, event.message, event.observedAt);
+                    break;
+                case "approval_proposed":
+                    this.handleApprovalProposed(scope, event);
+                    break;
+                case "system_note":
+                    this.appendSystemNote(scope, event.text);
+                    break;
+                default: {
+                    const exhaustive = event;
+                    throw new Error(`unknown transcript event ${String(exhaustive.kind)}`);
+                }
+            }
+        }
+        catch (err) {
+            console.error(`[TranscriptBuilder] Event handler error: execution=${this.executionId} kind=${event.kind}: ${err}`);
+        }
+    }
+    /**
+     * Every streaming flag off, in every scope — messages and rows. What a
+     * turn owes the transcript when its stream ends, however it ended: a
+     * stopped turn's in-flight message must not persist as still streaming.
+     * The sub-agent rows' own CANCELLED transition is the caller's, through
+     * the shared `cancelInProgressSubAgentProtos`.
+     */
+    finalize() {
+        for (const transcript of this.state.transcripts())
+            finalizeStreaming(transcript);
+    }
+    // ── Artifact & WriteBack ───────────────────────────────────────────
+    addArtifact(artifact) {
+        const artifacts = this.state.status.artifacts;
+        const idx = artifacts.findIndex(a => a.sandboxPath === artifact.sandboxPath);
+        if (idx >= 0) {
+            if (artifacts[idx].contentHash !== artifact.contentHash) {
+                artifacts[idx] = artifact;
+                this._dirty = true;
+            }
+            return;
+        }
+        artifacts.push(artifact);
+        this._dirty = true;
+    }
+    addWriteBack(wb) {
+        const backs = this.state.status.workspaceWriteBacks;
+        const idx = backs.findIndex(b => b.workspaceEntryName === wb.workspaceEntryName);
+        if (idx >= 0) {
+            backs[idx] = wb;
+        }
+        else {
+            backs.push(wb);
+        }
+        this._dirty = true;
+    }
+    // ── Sub-Agent Rows ─────────────────────────────────────────────────
+    openSubAgent(event) {
+        // A seeded row re-announced by a replayed engine (the memory-checkpointer
+        // re-drives the whole graph): the row and its transcript already exist.
+        if (this.state.subAgent(event.subAgentId))
+            return;
+        const row = create(SubAgentRunSchema, {
+            id: event.subAgentId,
+            name: event.name,
+            subject: event.subject,
+            input: event.input,
+            status: SubAgentStatus.SUB_AGENT_IN_PROGRESS,
+            startedAt: this.instant(),
+        });
+        this.state.openSubAgent(row);
+        this._dirty = true;
+    }
+    closeSubAgent(event) {
+        const scope = this.state.subAgent(event.subAgentId);
+        if (!scope)
+            return;
+        scope.row.status = SubAgentStatus.SUB_AGENT_COMPLETED;
+        scope.row.completedAt = this.instant();
+        if (event.output !== undefined)
+            scope.row.output = event.output;
+        finalizeStreaming(scope.transcript);
+        this._dirty = true;
+    }
+    failSubAgent(event) {
+        const scope = this.state.subAgent(event.subAgentId);
+        if (!scope)
+            return;
+        scope.row.status = SubAgentStatus.SUB_AGENT_FAILED;
+        scope.row.completedAt = this.instant();
+        scope.row.error = event.error;
+        finalizeStreaming(scope.transcript);
+        this._dirty = true;
+    }
+    // ── Message Handlers ───────────────────────────────────────────────
+    handleMessageStart(scope, runId) {
+        // Record the run for the message boundary but do NOT create the AI
+        // message yet: it is created lazily on the first text_delta, so a
+        // THINKING row that streams first sits before the text it precedes.
+        if (scope.lastRunId && scope.lastRunId !== runId && scope.currentAiMessage) {
+            scope.currentAiMessage.isStreaming = false;
+        }
+        scope.lastRunId = runId;
+    }
+    handleMessageFinish(scope, runId) {
+        // A finished run's text AND its thinking are finished (Cursor closes
+        // both when a tool call ends the segment). Before #1097 only the
+        // text closed here and the THINKING row spun until `finalize()` — a live
+        // spinner on a block the model had left, on both harnesses.
+        const msg = scope.messagesByRun.get(runId);
+        if (msg) {
+            msg.isStreaming = false;
+        }
+        const thinking = scope.messagesByRun.get(thinkingKeyOf(runId));
+        if (thinking) {
+            thinking.isStreaming = false;
+        }
+    }
+    appendTextContent(scope, runId, text) {
+        const msg = this.ensureAiMessage(scope, runId);
+        msg.content += text;
+        msg.isStreaming = true;
+    }
+    appendThinkingContent(scope, runId, text) {
+        // One THINKING row per run, keyed apart from the run's text so
+        // the two never share a message.
+        const thinkingKey = thinkingKeyOf(runId);
+        const existingMsg = scope.messagesByRun.get(thinkingKey);
+        if (existingMsg && existingMsg.type === MessageType.MESSAGE_THINKING) {
+            existingMsg.content += text;
+            existingMsg.isStreaming = true;
+            return;
+        }
+        const msg = create(AgentMessageSchema, {
+            type: MessageType.MESSAGE_THINKING,
+            content: text,
+            timestamp: this.instant(),
+            isStreaming: true,
+        });
+        scope.messages.push(msg);
+        scope.messagesByRun.set(thinkingKey, msg);
+    }
+    // ── Tool Handlers ──────────────────────────────────────────────────
+    handleToolStarted(scope, event) {
+        const { callId, name, input } = event;
+        // A re-emitted start reconciles onto the existing row — never a duplicate,
+        // never a second gate. Keyed by the provider's tool_call_id, so this is an
+        // exact match (no name heuristics). Two shapes reach here: the durable
+        // checkpoint re-emitting a seeded WAITING call now that approval is granted
+        // (native's resume; the runtime's seed from the log, `transcript/resume-seed.ts`), and a
+        // recovery replaying a call the server had marked INTERRUPTED when the
+        // execution terminalized with it in flight (the enum's supersede rule; the
+        // Cursor accumulator's merge). Either way an UNSETTLED row becomes RUNNING
+        // (before #1097 only WAITING flipped); a settled one keeps
+        // its outcome. Args it lacked are filled and previewed, once.
+        const existing = scope.toolCalls.get(callId);
+        if (existing) {
+            if (!isSettled(existing.status)) {
+                existing.status = ToolCallStatus.TOOL_CALL_RUNNING;
+            }
+            if (Object.keys(input).length > 0) {
+                if (!existing.args)
+                    existing.args = rowArgs(input);
+                if (!existing.argsPreview)
+                    stampArgsPreview(existing, input);
+            }
+            this._dirty = true;
+            return;
+        }
+        // The message boundary: the row joins the message whose text
+        // proposed it — the scope's current AI message — and gets an empty one
+        // only when the scope has no message yet.
+        const parentMsg = scope.currentAiMessage ?? this.ensureAiMessageForToolCall(scope);
+        // A started call is RUNNING and carries no approval fact: whether it is
+        // held is known only after the engine's gate has run, and a held call
+        // reaches the transcript as `approval_proposed` (Cursor's boundary after
+        // the hook denied it; native's post-stream seed, where a held call never
+        // starts at all). The builder decides nothing about approval.
+        const tc = create(ToolCallSchema, {
+            id: callId,
+            name,
+            status: ToolCallStatus.TOOL_CALL_RUNNING,
+            startedAt: this.instant(),
+        });
+        if (Object.keys(input).length > 0) {
+            tc.args = rowArgs(input);
+            stampArgsPreview(tc, input);
+        }
+        if (event.mcpServerSlug) {
+            tc.mcpServerSlug = event.mcpServerSlug;
+        }
+        // Classify after mcpServerSlug is set so MCP tools resolve correctly.
+        tc.toolKind = classifyTool(tc.name, tc.mcpServerSlug);
+        // Authorization provenance — which policy layer governs the call — stamped
+        // in the same spot as tool_kind, for every observed call the translator
+        // could attribute (gated or auto-approved), so the persisted record is
+        // auditable and the UI can explain the gate. Absent provenance leaves the
+        // field at UNSPECIFIED, like an unclassified tool_kind. A gated call is
+        // re-seeded on reinvocation (the runtime's wide seed) with the same source
+        // carried through the interrupt.
+        if (event.provenance !== undefined) {
+            stampProvenance(tc, event.provenance, event.policyHook);
+        }
+        const pending = this.pendingPolicies.get(callId);
+        if (pending !== undefined) {
+            this.pendingPolicies.delete(callId);
+            stampProvenance(tc, pending.provenance, pending.policyHook);
+        }
+        parentMsg.toolCalls.push(tc);
+        scope.toolCalls.set(callId, tc);
+        this._dirty = true;
+    }
+    /**
+     * A hook's provenance for a call that runs (`ToolPolicyEvent`): stamped on
+     * the row now, or held until the row opens, so it outranks whatever its
+     * `tool_started` said in either order. A row a person already decided (its
+     * answer, copied from the session's log onto the row at the seed) keeps
+     * the provenance that asked them, as a re-emitted start does: on
+     * resume the hook runs again and an "approve all" it just leased answers
+     * it, and re-stamping that as the lease would make the next turn read the
+     * row as the tool's whole category or server instead of the hook.
+     */
+    handleToolPolicy(scope, event) {
+        const existing = scope.toolCalls.get(event.callId);
+        if (existing === undefined) {
+            this.pendingPolicies.set(event.callId, event);
+            return;
+        }
+        if (existing.approvalAction !== ApprovalAction.UNSPECIFIED)
+            return;
+        stampProvenance(existing, event.provenance, event.policyHook);
+        this._dirty = true;
+    }
+    handleToolFinished(scope, callId, result, observedAt) {
+        const tc = scope.toolCalls.get(callId);
+        if (!tc)
+            return;
+        // An UPSERT, not an overwrite (Cursor's `mergeToolCallEvent`):
+        // the status advances monotonically — a settled row never regresses;
+        // `completedAt` is stamped once; only a non-empty result overwrites, so a
+        // completion that carries none never wipes the output an earlier one
+        // did. Two completions per call is the Cursor shape after stigmer#1053
+        // (the SDK's timing delta precedes the stream's completion); on native
+        // there is one, and the rules read as the plain write they replace.
+        //
+        // Store the faithful result; bounding the gRPC payload is owned solely by
+        // the persist chokepoint (offload + enforce in status.ts/status-offload.ts).
+        // Truncating here would corrupt binary content (e.g. a screenshot's base64)
+        // before offload can lift it into a renderable ToolCallOutputRef.
+        //
+        // A completion that changes nothing — a settled row re-completed with no
+        // new result — forces no persist (Cursor's "a redundant
+        // terminal re-emit is noise, not a state change"). On Cursor every call
+        // completes twice (the delta, then the stream), and the second carries the
+        // result, so the flush the UI needs still happens exactly once.
+        const wasSettled = isSettled(tc.status);
+        const resultChanged = !!result && result !== tc.result;
+        if (!wasSettled)
+            tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
+        // The instant the harness OBSERVED the completion when it delivers it
+        // later (Cursor's queued delta); otherwise the fold's instant.
+        if (!tc.completedAt)
+            tc.completedAt = observedAt ?? this.instant();
+        if (resultChanged)
+            tc.result = result;
+        stopStreaming(tc);
+        scope.argBuffers.delete(callId);
+        if (wasSettled && !resultChanged)
+            return;
+        // Project a completed to-do write into rows.todos. deepagents' write_todos
+        // runs its state-mutating Command when the tool node COMPLETES, so we mirror
+        // it here (not at tool-start) — a call cancelled before finishing correctly
+        // projects nothing. Keyed on the harness-agnostic ToolKind.TODO (stamped at
+        // tool-start) and fed by the same shared mapper every harness uses; the
+        // call's own `merge` flag decides replace-or-merge (Cursor's `updateTodos`
+        // sets it; deepagents never does, so native stays a full replace);
+        // a sub-agent's list is its own, never the execution's. The tool
+        // call itself stays in messages (the client filters ToolKind.TODO from the
+        // thread).
+        if (scope === this.state.root && tc.toolKind === ToolKind.TODO) {
+            applyTodoUpdate(this.state.rows.todos, tc.args?.todos, { merge: tc.args?.merge === true });
+        }
+        this._dirty = true;
+    }
+    handleToolError(scope, callId, message, observedAt) {
+        const tc = scope.toolCalls.get(callId);
+        if (!tc)
+            return;
+        // The same upsert as a finish. A call the Cursor hook denied also reports
+        // `error` here; it is an ordinary failure until the boundary parks it
+        // through `approval_proposed`, which stamps the approval fields.
+        const wasSettled = isSettled(tc.status);
+        const messageChanged = !!message && message !== tc.error;
+        const at = observedAt ?? this.instant();
+        if (!wasSettled)
+            tc.status = ToolCallStatus.TOOL_CALL_FAILED;
+        if (!tc.completedAt)
+            tc.completedAt = at;
+        if (messageChanged)
+            tc.error = message;
+        stopStreaming(tc);
+        scope.argBuffers.delete(callId);
+        // The same no-change rule as a finish.
+        if (wasSettled && !messageChanged)
+            return;
+        this._dirty = true;
+    }
+    handleToolArgDelta(scope, callId, argsChunk) {
+        const tc = scope.toolCalls.get(callId);
+        if (!tc)
+            return;
+        const buffer = (scope.argBuffers.get(callId) ?? "") + argsChunk;
+        scope.argBuffers.set(callId, buffer);
+        let parsed;
+        try {
+            parsed = JSON.parse(buffer);
+        }
+        catch {
+            // Partial JSON — will parse on next chunk or tool-finished
+            return;
+        }
+        // A tool's arguments are an object (a proto Struct); anything else is not args.
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            tc.args = rowArgs(parsed);
+        }
+    }
+    handleToolOutputDelta(scope, callId, delta) {
+        const tc = scope.toolCalls.get(callId);
+        if (!tc)
+            return;
+        // A chunk for a row that has already settled is stale: the completion's
+        // result IS the whole output, and appending would double it (Cursor's
+        // delta channel and stream can deliver the output's
+        // chunks and the completion in one loop window, completion first).
+        if (isSettled(tc.status))
+            return;
+        // Output arriving live: the row streams its OUTPUT (Cursor's
+        // enricher), so the client can show the partial result as it grows;
+        // the finish, or `finalize()`, closes it.
+        tc.result = (tc.result ?? "") + delta;
+        tc.isStreaming = true;
+        tc.streamingSource = ToolCallStreamingSource.OUTPUT;
+    }
+    // ── Post-Stream Facts ──────────────────────────────────────────────
+    handleApprovalProposed(scope, event) {
+        const now = this.instant();
+        const existing = scope.toolCalls.get(event.callId);
+        if (existing) {
+            // Reopen (Cursor's `markWaitingApproval`): the boundary is re-proposing
+            // a call the stream already showed — an errored built-in the hook
+            // denied — so the outcome the stream wrote is not the outcome.
+            existing.status = ToolCallStatus.TOOL_CALL_WAITING_APPROVAL;
+            existing.requiresApproval = true;
+            existing.approvalMessage = event.message;
+            if (!existing.approvalRequestedAt)
+                existing.approvalRequestedAt = now;
+            existing.completedAt = "";
+            existing.error = "";
+            existing.result = "";
+            // The proposal's args are the authoritative proposed change when the
+            // harness carries them (Cursor's `applyGateInput`: the hook's captured
+            // input outranks what the stream carried before the first-denial cancel),
+            // and they re-derive the preview. Absent, the row
+            // keeps what it had.
+            if (event.args && Object.keys(event.args).length > 0) {
+                existing.args = rowArgs(event.args);
+                stampArgsPreview(existing, event.args);
+            }
+            if (event.contentDigest)
+                existing.approvalContentDigest = event.contentDigest;
+            stopStreaming(existing);
+            this._awaitingApproval = true;
+            this._dirty = true;
+            return;
+        }
+        // A call the stream never showed (native: the engine interrupted before
+        // the tool started). Its row lands on the text that proposed it, like
+        // any other row (before #1097 the seed pushed a new empty message).
+        const parentMsg = scope.currentAiMessage ?? this.ensureAiMessageForToolCall(scope);
+        const tc = create(ToolCallSchema, {
+            id: event.callId,
+            name: event.name,
+            status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+            requiresApproval: true,
+            approvalMessage: event.message,
+            approvalRequestedAt: now,
+            startedAt: now,
+        });
+        if (event.mcpServerSlug)
+            tc.mcpServerSlug = event.mcpServerSlug;
+        tc.toolKind = classifyTool(tc.name, tc.mcpServerSlug);
+        if (event.provenance !== undefined) {
+            stampProvenance(tc, event.provenance, event.policyHook);
+        }
+        if (event.args && Object.keys(event.args).length > 0) {
+            tc.args = rowArgs(event.args);
+            stampArgsPreview(tc, event.args);
+        }
+        if (event.contentDigest)
+            tc.approvalContentDigest = event.contentDigest;
+        parentMsg.toolCalls.push(tc);
+        scope.toolCalls.set(event.callId, tc);
+        this._awaitingApproval = true;
+        this._dirty = true;
+    }
+    appendSystemNote(scope, text) {
+        scope.messages.push(create(AgentMessageSchema, {
+            type: MessageType.MESSAGE_SYSTEM,
+            content: text,
+            timestamp: this.instant(),
+        }));
+        this._dirty = true;
+    }
+    // ── Content Helpers ───────────────────────────────────────────────
+    /** The AI message a run's text streams into, created on its first token; a new run closes the previous message's flag. */
+    ensureAiMessage(scope, runId) {
+        const existingByRun = scope.messagesByRun.get(runId);
+        if (existingByRun)
+            return existingByRun;
+        if (scope.lastRunId && scope.lastRunId !== runId && scope.currentAiMessage) {
+            scope.currentAiMessage.isStreaming = false;
+        }
+        const msg = create(AgentMessageSchema, {
+            type: MessageType.MESSAGE_AI,
+            content: "",
+            timestamp: this.instant(),
+            isStreaming: true,
+        });
+        scope.messages.push(msg);
+        scope.messagesByRun.set(runId, msg);
+        scope.currentAiMessage = msg;
+        scope.lastRunId = runId;
+        return msg;
+    }
+    /** The message a tool row lands on when the scope has no AI message yet: the latest run's, else a new empty one. */
+    ensureAiMessageForToolCall(scope) {
+        if (scope.lastRunId) {
+            const existing = scope.messagesByRun.get(scope.lastRunId);
+            if (existing) {
+                scope.currentAiMessage = existing;
+                return existing;
+            }
+        }
+        const msg = create(AgentMessageSchema, {
+            type: MessageType.MESSAGE_AI,
+            content: "",
+            timestamp: this.instant(),
+            isStreaming: false,
+        });
+        scope.messages.push(msg);
+        scope.currentAiMessage = msg;
+        return msg;
+    }
+}
+/** The `messagesByRun` key of a run's THINKING row — apart from the run's text, so the two never share a message. */
+function thinkingKeyOf(runId) {
+    return `thinking:${runId}`;
+}
+/** Every streaming flag off in one transcript — messages and rows. */
+function finalizeStreaming(transcript) {
+    for (const message of transcript.messages) {
+        message.isStreaming = false;
+        for (const tc of message.toolCalls)
+            stopStreaming(tc);
+    }
+}
+/**
+ * The row's `args`, on every row with args: the call's arguments with every
+ * secret-keyed value redacted (`redactSensitiveArgs`, the preview's own
+ * first step). Until stigmer#1119 the row stored them raw and only the
+ * preview was redacted, so a settled row's detail view showed a token the
+ * waiting row had hidden. Nothing that reads a row's args back needs a
+ * secret: exact-apply, the approval identity and the content digest read
+ * path, content, edit and command fields, which
+ * `shared/__tests__/args-preview.test.ts` pins disjoint from the secret keys.
+ */
+function rowArgs(args) {
+    return redactSensitiveArgs(args);
+}
+/**
+ * A row's authorization provenance: the source, the engine version that
+ * decided it, and the deciding hook when a hook's answer is what the source
+ * records (empty otherwise, so a later stamp never leaves a stale hook).
+ */
+function stampProvenance(tc, source, policyHook) {
+    tc.approvalPolicySource = toProtoPolicySource(source);
+    tc.policyEngineVersion = POLICY_ENGINE_VERSION;
+    tc.approvalPolicyHook = policyHook ?? "";
+}
+/**
+ * The row's `args_preview`, on EVERY row with args (since #1097):
+ * `message.proto` promises it sanitized, redacted, at creation, for inline
+ * visibility, and the one builder that keeps it small and always valid JSON
+ * is `buildElidedArgsPreview` over the platform's salient fields. Until then
+ * native stamped a whole-string-truncating preview on gated rows only and
+ * Cursor stamped `JSON.stringify(args)` unredacted. An empty preview (a
+ * cycle in the args) leaves the field unset rather than failing the row.
+ */
+function stampArgsPreview(tc, args) {
+    const preview = buildElidedArgsPreview(args, SALIENT_ARG_FIELDS);
+    if (preview)
+        tc.argsPreview = preview;
+}
+/** A row no longer streaming: the flag off and the source cleared, so a stale OUTPUT marker never outlives the stream. */
+function stopStreaming(tc) {
+    if (!tc.isStreaming)
+        return;
+    tc.isStreaming = false;
+    tc.streamingSource = ToolCallStreamingSource.UNSPECIFIED;
+}
+/**
+ * A row that has finished, however it finished — the statuses a later event
+ * must not move backwards (Cursor's `isTerminalToolStatus`). INTERRUPTED is
+ * deliberately NOT here: it is server-authored when an execution
+ * terminalized with the call in flight, and a recovery-replayed event must
+ * be able to advance the row to its true outcome (the enum's recovery
+ * supersede rule; `shared/tool-row.ts` explains the two sets).
+ */
+function isSettled(status) {
+    return (status === ToolCallStatus.TOOL_CALL_COMPLETED ||
+        status === ToolCallStatus.TOOL_CALL_FAILED ||
+        status === ToolCallStatus.TOOL_CALL_SKIPPED);
+}
+//# sourceMappingURL=builder.js.map