@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/src/activities/execute-deep-agent/translator.ts

@@ -0,0 +1,463 @@
+/**
+ * DeepAgentTranslator — the native harness's translator: LangGraph's v3
+ * protocol events in, the canonical `TranscriptEvent` union out
+ * (`harness/transcript/events.ts`).
+ *
+ * The one module that knows LangGraph's wire shape:
+ * the shared builder folds what comes out of here and nothing of the engine
+ * reaches it otherwise. Every engine fact the builder used to read is
+ * answered on this side now (since #1097):
+ *
+ *   - the tool's result, rendered to the string the row carries — the
+ *     LangChain ToolMessage envelope and the LangGraph Command unwrapped;
+ *   - the tool's attribution (`mcpServerSlug`) and authorization provenance,
+ *     from the gate's posture (`resolveApprovalProvenance`, the gate's
+ *     read-side twin);
+ *   - the SCOPE of every event — the root's transcript or one sub-agent's —
+ *     from LangGraph's namespace grammar, and the sub-agent's own lifecycle
+ *     (`sub_agent_started/finished/failed`) from deepagents' `task` tool
+ *     Until #1097 the builder read the namespace and the
+ *     tool's name itself, and kept a second copy of every handler for the
+ *     sub-agents' transcripts.
+ *
+ * What this translator deliberately does NOT answer: whether the gate holds
+ * a call. On native it never has to. LangGraph's `interrupt()` runs inside
+ * the gate middleware BEFORE the tool handler, so a held call emits no
+ * `tool-started` at all; the `tool-started` that does arrive is the engine's
+ * own word that the call was authorized — capture mode let the file write
+ * flow, a lease or the policy chain cleared it, or the user approved it on a
+ * resume. The gate's decision has arms this side cannot evaluate (capture
+ * mode asks the workspace's git state, asynchronously;
+ * `middleware/approval-gate.ts`), and duplicating them would be a second copy
+ * of the decision — exactly the drift one writer per fact exists to end. So
+ * native emits no `tool_started.gate`; the held call reaches the transcript
+ * as `approval_proposed` from the post-stream seed. Until #1097 the builder
+ * carried a copy of the decision that gated MCP tools only, a path
+ * production never took.
+ *
+ * Attribution and provenance are answered for ROOT-scope calls only: a
+ * sub-agent's rows carry none on either harness today (#1133), and one
+ * handler set would otherwise stamp them as a side effect.
+ *
+ * The scope, in LangGraph 1.3.2's grammar (mirrors deepagents'
+ * `createSubagentTransformer`): the root's model events arrive under
+ * `["model_request:<uuid>"]` and its tool events under `["tools:<uuid>"]`
+ * (one segment); a `task` tool start at that depth opens a sub-agent, and
+ * the segment it arrived under is the prefix every event of that sub-agent's
+ * graph carries first (`["tools:<uuid>", "model_request:<inner>"]`, two or
+ * more segments). An event with a REGISTERED first segment and two or more
+ * segments is the sub-agent's; everything else is the root's — including a
+ * nested namespace whose prefix nobody registered, which folds into the
+ * root as it always did (a sub-agent resumed inside its own gate
+ * with no re-emitted `task` start is the production case). A `task` inside
+ * a sub-agent is an ordinary row of that sub-agent's transcript: one level
+ * of delegation is tracked, as before.
+ *
+ * Beside the transcript, {@link usageOf} answers the loop's one
+ * non-transcript question about the wire — the usage a
+ * `message-finish` carries — so the loop never parses a raw event itself.
+ * What the wire carries that the transcript does not: `lifecycle` and
+ * `provider` events, the standalone `usage` event, each event's `seq` and
+ * `node`. None of it was ever folded; the recorder keeps the raw event for
+ * a replay.
+ *
+ * The file was `v3-protocol-normalizer.ts` (a stateless `normalize`) until
+ * #1097 made it stateful — the same word as `execute-cursor/translator.ts`,
+ * so a third harness's author finds one shape in both.
+ *
+ * Defensive parsing: handles both snake_case and camelCase field names
+ * for tool IDs/names (protocol spec uses camelCase but recordings show
+ * snake_case). Uses `data.event` as canonical discriminator, with
+ * `data.type` as fallback (CP04 finding).
+ */
+
+import type { V3ProtocolEvent } from "./v3-event-recorder.js";
+import type { ToolStartedEvent, TranscriptEvent } from "../../harness/transcript/events.js";
+import { resolveApprovalProvenance, type PolicySource } from "../../shared/approval-policy.js";
+import type { DeepAgentGateState } from "./turn-setup.js";
+
+const loggedUnknowns = new Set<string>();
+
+/** deepagents' delegation tool: the one tool name this translator knows, because its start opens a sub-agent. */
+const TASK_TOOL = "task";
+
+// ── The translator ────────────────────────────────────────────────
+
+export class DeepAgentTranslator {
+  /** First namespace segment → the sub-agent (its `task` call id) whose graph runs under it. */
+  private readonly subAgentByPrefix = new Map<string, string>();
+  /** The `task` call ids whose completion closes a sub-agent. */
+  private readonly taskCalls = new Set<string>();
+
+  /**
+   * @param gate the turn's gate posture, for attribution and provenance;
+   *   `null` where a turn runs with none (the unit arms that drive the
+   *   builder bare), and then every call is unattributed.
+   */
+  constructor(private readonly gate: DeepAgentGateState | null) {}
+
+  /** One raw event to its canonical events — `translate(raw)` is the one signature every harness's translator shares. */
+  translate(raw: V3ProtocolEvent): TranscriptEvent[] {
+    const namespace = raw.params.namespace;
+    const subAgentId = this.scopeOf(namespace);
+    const out: TranscriptEvent[] = [];
+    for (const event of normalize(raw)) {
+      if (subAgentId !== undefined) {
+        out.push({ ...event, subAgentId });
+        continue;
+      }
+      switch (event.kind) {
+        case "tool_started":
+          if (event.name === TASK_TOOL && namespace.length <= 1) {
+            out.push(this.openSubAgent(event, namespace));
+          }
+          out.push(this.attribute(event));
+          break;
+        case "tool_finished":
+          out.push(event);
+          if (this.taskCalls.has(event.callId)) {
+            out.push({ kind: "sub_agent_finished", subAgentId: event.callId, output: event.result });
+          }
+          break;
+        case "tool_error":
+          out.push(event);
+          if (this.taskCalls.has(event.callId)) {
+            out.push({ kind: "sub_agent_failed", subAgentId: event.callId, error: event.message });
+          }
+          break;
+        default:
+          out.push(event);
+      }
+    }
+    return out;
+  }
+
+  /** The sub-agent an event belongs to, or `undefined` for the root (see the header for the grammar). */
+  private scopeOf(namespace: readonly string[]): string | undefined {
+    if (namespace.length < 2) return undefined;
+    return this.subAgentByPrefix.get(namespace[0]);
+  }
+
+  /**
+   * A `task` start at the root opens a sub-agent keyed by the call id, with
+   * the segment it arrived under as the routing prefix (a depth-0 start —
+   * tests — gets a synthetic one so its children can still name it).
+   */
+  private openSubAgent(event: ToolStartedEvent, namespace: readonly string[]): TranscriptEvent {
+    const prefix = namespace[0] ?? `tools:${event.callId}`;
+    this.subAgentByPrefix.set(prefix, event.callId);
+    this.taskCalls.add(event.callId);
+    const description = stringArg(event.input, "description");
+    return {
+      kind: "sub_agent_started",
+      subAgentId: event.callId,
+      name: stringArg(event.input, "subagent_type") || TASK_TOOL,
+      subject: description,
+      input: description,
+    };
+  }
+
+  /** The attribution and provenance for one root-scope tool start. */
+  private attribute(event: ToolStartedEvent): ToolStartedEvent {
+    const gate = this.gate;
+    if (!gate) return event;
+    const mcpServerSlug = gate.toolServerMap.get(event.name) ?? "";
+    const provenance: PolicySource | undefined = resolveApprovalProvenance(
+      event.name,
+      mcpServerSlug,
+      gate.policies,
+      gate.leasedCategories,
+      gate.globalBypass,
+    );
+    return {
+      ...event,
+      mcpServerSlug,
+      ...(provenance !== undefined ? { provenance } : {}),
+    };
+  }
+}
+
+function stringArg(input: Record<string, unknown>, key: string): string {
+  const value = input[key];
+  return typeof value === "string" ? value : "";
+}
+
+// ── The wire, event by event ──────────────────────────────────────
+
+/**
+ * The stateless core: one raw event to its canonical events, root-scoped
+ * (no `subAgentId`) and unattributed (`mcpServerSlug: ""`, no provenance, no
+ * gate). The translator layers scope and the gate's answers on top; the arms
+ * that pin the wire's shape read this directly.
+ */
+export function normalize(event: V3ProtocolEvent): TranscriptEvent[] {
+  const method = event.method;
+
+  switch (method) {
+    case "messages": return normalizeMessage(event);
+    case "tools": return normalizeTool(event);
+    default:
+      return [];
+  }
+}
+
+// ── Usage ─────────────────────────────────────────────────────────
+
+/**
+ * The token usage as LangChain's v3 protocol delivers it on a
+ * `message-finish`. `input_tokens` already INCLUDES the cache buckets (the
+ * Anthropic adapter folds them in); the loop prices over the disjoint parts.
+ */
+export interface V3UsagePayload {
+  readonly input_tokens?: number;
+  readonly output_tokens?: number;
+  readonly total_tokens?: number;
+  readonly input_token_details?: {
+    readonly cache_creation?: number;
+    readonly cache_read?: number;
+  };
+}
+
+/**
+ * The usage one raw event carries, or `undefined`. Read from `message-finish`
+ * ONLY — v3 also emits a standalone `usage` event for the same turn, and
+ * reading both would double-count. Every namespace's finish counts: a
+ * sub-agent's spend is the execution's spend (since #1096), and the cost
+ * cap the runtime enforces reads the whole execution.
+ *
+ * A loop concern, deliberately NOT a `TranscriptEvent`:
+ * usage is neither a row nor a message, and `translate`'s return type stays
+ * the one signature every harness's translator shares. The Cursor loop reads
+ * its usage from the SDK's `turn-ended` delta — the same division.
+ */
+export function usageOf(event: V3ProtocolEvent): V3UsagePayload | undefined {
+  if (event.method !== "messages") return undefined;
+  const data = event.params.data as Record<string, unknown> | undefined;
+  if (!data || readEventType(data) !== "message-finish") return undefined;
+  return normalizeUsagePayload(data.usage as Record<string, unknown> | undefined);
+}
+
+// ── Messages Channel ──────────────────────────────────────────────
+
+function normalizeMessage(event: V3ProtocolEvent): TranscriptEvent[] {
+  const data = event.params.data as Record<string, unknown> | undefined;
+  if (!data) return [];
+
+  const eventType = readEventType(data);
+  const runId = (data.run_id ?? "") as string;
+
+  switch (eventType) {
+    case "message-start":
+      return [{ kind: "message_start" as const, runId }];
+
+    case "content-block-delta":
+      return normalizeContentBlockDelta(data, runId);
+
+    case "message-finish":
+      return [{ kind: "message_finish" as const, runId }];
+
+    // Carried by the wire, not by the transcript (see the header).
+    case "usage":
+    case "provider":
+    case "content-block-start":
+    case "content-block-finish":
+      return [];
+
+    default:
+      logUnknown("messages", eventType);
+      return [];
+  }
+}
+
+function normalizeContentBlockDelta(
+  data: Record<string, unknown>,
+  runId: string,
+): TranscriptEvent[] {
+  const delta = data.delta as Record<string, unknown> | undefined;
+  if (!delta) return [];
+
+  const deltaType = delta.type as string | undefined;
+
+  if (deltaType === "text-delta") {
+    const text = (delta.text ?? "") as string;
+    if (!text) return [];
+    return [{ kind: "text_delta" as const, runId, text }];
+  }
+
+  if (deltaType === "reasoning-delta") {
+    const text = (delta.reasoning ?? "") as string;
+    if (!text) return [];
+    return [{ kind: "reasoning_delta" as const, runId, text }];
+  }
+
+  if (deltaType === "block-delta") {
+    const fields = delta.fields as Record<string, unknown> | undefined;
+    if (!fields) return [];
+    if (fields.type === "tool_call_chunk") {
+      const callId = (fields.id ?? "") as string;
+      const argsChunk = (fields.args ?? "") as string;
+      if (!argsChunk && !callId) return [];
+      return [{ kind: "tool_arg_delta" as const, callId, argsChunk }];
+    }
+  }
+
+  return [];
+}
+
+// ── Tools Channel ─────────────────────────────────────────────────
+
+function normalizeTool(event: V3ProtocolEvent): TranscriptEvent[] {
+  const data = event.params.data as Record<string, unknown> | undefined;
+  if (!data) return [];
+
+  const eventType = readEventType(data);
+
+  switch (eventType) {
+    case "tool-started": {
+      const callId = readToolCallId(data);
+      const name = readToolName(data);
+      const input = parseToolInput(data.input);
+      return [{ kind: "tool_started" as const, callId, name, input, mcpServerSlug: "" }];
+    }
+
+    case "tool-finished": {
+      const callId = readToolCallId(data);
+      return [{ kind: "tool_finished" as const, callId, result: extractToolResult(data.output) }];
+    }
+
+    case "tool-error": {
+      const callId = readToolCallId(data);
+      const message = (data.message ?? data.error ?? "") as string;
+      return [{ kind: "tool_error" as const, callId, message }];
+    }
+
+    case "tool-output-delta": {
+      const callId = readToolCallId(data);
+      const delta = (data.delta ?? "") as string;
+      return [{ kind: "tool_output_delta" as const, callId, delta: String(delta) }];
+    }
+
+    default:
+      logUnknown("tools", eventType);
+      return [];
+  }
+}
+
+// ── Tool Result ───────────────────────────────────────────────────
+
+/**
+ * Serialize a LangChain message `content` field into the canonical tool-result
+ * string.
+ *
+ * Text-only content is a plain string and passes through unchanged. Multimodal
+ * content (image, or mixed text+image — e.g. a computer-use screenshot) is an
+ * array of content blocks; we serialize the blocks array ITSELF, not the
+ * surrounding message envelope, so the result lands in the exact top-level-array
+ * shape the persist-time offload (`detectImagePayload`/`contentBlocks` in
+ * status-offload.ts) consumes to lift the image out into a renderable
+ * `ToolCallOutputRef`. Serializing the envelope instead would bury the base64
+ * one level deeper and defeat that detection.
+ *
+ * Returns undefined when `content` is neither a string nor an array, letting the
+ * caller fall back to serializing whatever else it holds.
+ */
+function serializeToolContent(content: unknown): string | undefined {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return JSON.stringify(content);
+  return undefined;
+}
+
+/**
+ * The `result: string` a `tool_finished` carries, from the v3 `tool-finished`
+ * output — engine knowledge that stays on this side of the union (it was
+ * `extractToolResultV3` in `harness/transcript/tool-result.ts` for a few
+ * commits of #1097). v3 wraps a LangChain `ToolMessage` in a constructor
+ * envelope, `{ lc, type, id, kwargs: { content, status, ... } }`; the content
+ * is what the row shows. Anything else is serialized as it came.
+ *
+ * A state-mutating tool returns a LangGraph `Command` instead —
+ * `{ lg_name: "Command", update: { ..., messages: [ToolMessage] }, goto }` —
+ * with its ToolMessage nested in the update (deepagents' `write_todos` and
+ * `task` both do). The row shows that ToolMessage's content, not the whole
+ * Command (since #1097; until then the row carried the serialized
+ * Command, the todos array twice over).
+ */
+function extractToolResult(output: unknown): string {
+  if (typeof output === "string") return output;
+  if (typeof output === "object" && output !== null) {
+    const obj = output as Record<string, unknown>;
+    const commandMessage = toolMessageOfCommand(obj);
+    if (commandMessage !== undefined) return extractToolResult(commandMessage);
+    const kwargs = obj.kwargs as Record<string, unknown> | undefined;
+    if (kwargs) {
+      const fromKwargs = serializeToolContent(kwargs.content);
+      if (fromKwargs !== undefined) return fromKwargs;
+    }
+    const fromContent = serializeToolContent(obj.content);
+    if (fromContent !== undefined) return fromContent;
+  }
+  try {
+    return JSON.stringify(output);
+  } catch {
+    return "[serialization error]";
+  }
+}
+
+/**
+ * The ToolMessage a LangGraph `Command` carries in `update.messages`, or
+ * `undefined` when the object is not a Command or carries none. The LAST
+ * message is the tool's own reply (a Command may prepend others); a Command
+ * with no message falls through to plain serialization, so nothing is lost.
+ */
+function toolMessageOfCommand(obj: Record<string, unknown>): unknown {
+  if (obj.lg_name !== "Command") return undefined;
+  const update = obj.update as Record<string, unknown> | undefined;
+  const messages = update?.messages;
+  if (!Array.isArray(messages) || messages.length === 0) return undefined;
+  return messages[messages.length - 1];
+}
+
+// ── Defensive Field Parsers ───────────────────────────────────────
+
+function readEventType(data: Record<string, unknown>): string {
+  return ((data.event ?? data.type) as string) ?? "";
+}
+
+function readToolCallId(data: Record<string, unknown>): string {
+  return ((data.tool_call_id ?? data.toolCallId) as string) ?? "";
+}
+
+function readToolName(data: Record<string, unknown>): string {
+  return ((data.tool_name ?? data.toolName ?? data.name) as string) ?? "unknown_tool";
+}
+
+function parseToolInput(raw: unknown): Record<string, unknown> {
+  if (raw === undefined || raw === null) return {};
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw as Record<string, unknown>;
+  if (typeof raw === "string") {
+    try { return JSON.parse(raw) as Record<string, unknown>; }
+    catch { return {}; }
+  }
+  return {};
+}
+
+function normalizeUsagePayload(raw: Record<string, unknown> | undefined): V3UsagePayload | undefined {
+  if (!raw) return undefined;
+  const details = raw.input_token_details as Record<string, unknown> | undefined;
+  return {
+    input_tokens: raw.input_tokens as number | undefined,
+    output_tokens: raw.output_tokens as number | undefined,
+    total_tokens: raw.total_tokens as number | undefined,
+    input_token_details: details ? {
+      cache_creation: details.cache_creation as number | undefined,
+      cache_read: details.cache_read as number | undefined,
+    } : undefined,
+  };
+}
+
+function logUnknown(method: string, eventType: string): void {
+  const key = `${method}:${eventType}`;
+  if (loggedUnknowns.has(key)) return;
+  loggedUnknowns.add(key);
+  console.debug(`[DeepAgentTranslator] Unknown event: method=${method} event=${eventType}`);
+}

package/src/activities/execute-deep-agent/turn-settle.ts

@@ -8,37 +8,38 @@
  * the runtime's stop, mark in-flight sub-agent rows through the shared act
  * and settle `interrupted` with nothing further; the graph's
  * `structuredResponse` folded onto the status; the interrupts a completed
- * stream left pending seeded as WAITING rows; and the outcome.
+ * stream left pending proposed through the builder as WAITING rows; and the
+ * outcome.
  *
  * What this module never does: write a phase, a terminal copy or
  * `completedAt` — those are the runtime's (`harness/run-turn.ts`,
- * `terminal-table.ts`); settle SKIP and REJECT rows — the runtime's
+ * `terminal-table.ts`); close the transcript's streaming flags — the
+ * runtime's, once `runTurn` returns, on every path (since #1097; until then this
+ * settle finalized the builder itself, and a turn that threw before
+ * reaching it left its last message streaming); settle SKIP and REJECT rows — the runtime's
  * (`harness/approval-decisions.ts`, after every outcome); withhold secret
  * content — the runtime's chokepoint does it on every write; finalize the
  * write-back — the runtime's epilogue; capture the turn's file changes or
  * decide whether a review is pending — the runtime's (`harness/capture.ts`,
  * once, over whatever the whole turn left on the tree, after this settle
- * returns; S3 M4). It does mutate `sink.status`'s transcript rows, which
- * are this harness's to write.
+ * returns; since #1096). Transcript rows it CREATES go through the builder
+ * (`approval_proposed`, since #1097); the one row it AMENDS by identity is the
+ * gate's unattended skip (`reconcileUnattendedSkips`), whose evidence exists
+ * only inside this harness.
  *
  * The structured response is folded BEFORE the outcome is decided, so a turn
  * the runtime then pauses for file review persists it and the pure
  * file-review resume completes with it (the runtime's text fallback runs on
- * the review-pending path too, Q-M4-8).
+ * the review-pending path too).
  *
- * Moved from `index.ts` (post-stream through the terminal arms) at S3 M2a;
- * the capture boundary left for the runtime at M4.
+ * Moved from `index.ts` (post-stream through the terminal arms) in #1096,
+ * where the capture boundary also left for the runtime.
  */
 
-import { create, type JsonObject } from "@bufbuild/protobuf";
-import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import { MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { JsonObject } from "@bufbuild/protobuf";
 
 import type { TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
-import { POLICY_ENGINE_VERSION, toProtoPolicySource } from "../../shared/approval-policy.js";
-import { utcTimestamp } from "../../shared/status.js";
 import { cancelInProgressSubAgentProtos } from "../../shared/subagent-rows.js";
-import { classifyTool } from "../../shared/tool-kind.js";
 import { captureApprovalArtifacts } from "./approval-file-change.js";
 import { autoPublishWrittenFiles } from "./auto-publish.js";
 import { detectPendingInterrupts, reconcileUnattendedSkips, type GraphStateSnapshot } from "./hitl.js";
@@ -82,10 +83,9 @@ export async function settleDeepAgentTurn(deps: DeepAgentSettleDeps): Promise<Tu
   if (stream.reason === "interrupted") {
     // A stopped turn aborted the graph run, so any sub-agent the parent had
     // delegated is no longer executing: CANCELLED through the one shared act
-    // (the runtime marks them itself only on its thrown arms), its messages'
-    // streaming flags cleared. There is no review to open.
+    // (the runtime marks them itself only on its thrown arms). There is no
+    // review to open.
     cancelInProgressSubAgentProtos(status.subAgentExecutions);
-    transcript.builder.finalizeSubAgentStreaming();
     return { kind: "interrupted" };
   }
 
@@ -118,11 +118,17 @@ export async function settleDeepAgentTurn(deps: DeepAgentSettleDeps): Promise<Tu
 }
 
 /**
- * Seed one WAITING_APPROVAL row per interrupt the graph left pending, on one
- * AI message, with the sanitized args preview AND the redacted args read
- * from the AI message in graph state (the single source of truth for the
- * proposed call; issue #754: a placeholder without args rendered a pathless
- * header). Returns whether any was seeded.
+ * Propose, through the builder, one approval per interrupt the graph left
+ * pending — the gate's hold reaching the transcript as `approval_proposed`
+ * (since #1097). LangGraph's `interrupt()` ran before the tool
+ * handler, so the stream showed no row for the call; the builder creates
+ * the WAITING row on the message whose text proposed it, with the redacted
+ * args read from the AI message in graph state (the single source of truth
+ * for the proposed call; issue #754: a placeholder without args rendered a
+ * pathless header). Until #1097 this settle built the message and the rows
+ * itself, on a new empty AI message of its own, with no by-id check against
+ * rows the stream had created (the upsert closes it).
+ * Returns whether any was proposed.
  */
 async function seedPendingInterrupts(deps: DeepAgentSettleDeps): Promise<boolean> {
   const { input, sink, engine } = deps;
@@ -134,31 +140,17 @@ async function seedPendingInterrupts(deps: DeepAgentSettleDeps): Promise<boolean
   const aiMessages = Array.isArray(graphMessages) ? graphMessages : [];
   console.log(`[turn-settle] Detected ${pending.length} pending interrupt(s) for execution ${input.executionId} — awaiting approval`);
 
-  const aiMsg = create(AgentMessageSchema, {
-    type: MessageType.MESSAGE_AI,
-    content: "",
-    timestamp: utcTimestamp(),
-    isStreaming: false,
-  });
   for (const intr of pending) {
-    const toolCall = create(ToolCallSchema, {
-      id: intr.toolCallId,
+    const { args } = captureApprovalArtifacts({ toolCallId: intr.toolCallId, messages: aiMessages });
+    sink.transcript.apply({
+      kind: "approval_proposed",
+      callId: intr.toolCallId,
       name: intr.toolName,
-      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
-      requiresApproval: true,
-      approvalMessage: intr.message,
-      approvalRequestedAt: utcTimestamp(),
       mcpServerSlug: intr.mcpServerSlug,
-      startedAt: utcTimestamp(),
-      toolKind: classifyTool(intr.toolName, intr.mcpServerSlug),
-      approvalPolicySource: toProtoPolicySource(intr.policySource),
-      policyEngineVersion: intr.policySource ? POLICY_ENGINE_VERSION : "",
+      message: intr.message,
+      ...(args ? { args } : {}),
+      ...(intr.policySource ? { provenance: intr.policySource } : {}),
     });
-    const { argsPreview, args } = captureApprovalArtifacts({ toolCallId: intr.toolCallId, messages: aiMessages });
-    if (argsPreview) toolCall.argsPreview = argsPreview;
-    if (args) toolCall.args = args as typeof toolCall.args;
-    aiMsg.toolCalls.push(toolCall);
   }
-  sink.status.messages.push(aiMsg);
-  return true;
+  return sink.transcript.awaitingApproval;
 }

package/src/activities/execute-deep-agent/turn-setup.ts

@@ -25,14 +25,14 @@
  * knows are reported through the sink exactly as the orchestrator reported
  * them (the resolution labels are the runtime's).
  *
- * One root for everything (Q-S3-8): the deepagents backend, the CAS
+ * One root for everything: the deepagents backend, the CAS
  * observer, the gate's path normalization and the publisher are all rooted
  * at `workspace.primaryDir` — the same tree the runtime locks, links and
  * captures. For zero or one workspace entry this is byte-identical to the
  * orchestrator's `workspaceBackend.rootDir`.
  *
  * Moved from `setup.ts` `performSetup` (the LangGraph half; the resolution
- * half is the runtime's twelve phases) at S3 M2a; the step bodies are the
+ * half is the runtime's twelve phases) in #1096; the step bodies are the
  * orchestrator's, verbatim where nothing changed.
  */
 
@@ -81,7 +81,7 @@ import { modelHasNativeThinking, transformAndCompileSubagents } from "./subagent
  * (`execute-cursor/turn-setup.ts` `CursorAdapterConfig` is the idiom): a
  * whole `Config` satisfies it, a test constructs these fields and nothing
  * else. Smaller than the orchestrator's reach — the synthesized attachments'
- * endpoints it read are the runtime's now (S3 M2a, F-M2a-10).
+ * endpoints it read are the runtime's now (since #1096).
  */
 export type DeepAgentAdapterConfig = Pick<
   Config,
@@ -147,8 +147,8 @@ export type DeepAgentGraphInput =
  * spec named none — the one reader of `spec.executionConfig.modelName`, which
  * the Cursor adapter reads too), or the registry's default for `"default"`.
  * The same reading the runtime's attachment phase made for the vision budget,
- * so the model that sees the images is the model that runs. (Until S3 M5 this
- * read the spec field beside the runtime's resolved copy; F-M3-P7.)
+ * so the model that sees the images is the model that runs. (Until #1096 this
+ * read the spec field beside the runtime's resolved copy.)
  */
 export async function resolveModelName(input: TurnInput): Promise<string> {
   return input.model.requested === "default" ? await getDefaultModel() : input.model.requested;
@@ -173,7 +173,7 @@ export async function openCheckpointer(input: TurnInput, sink: TurnSink, config:
 
 /**
  * The workspace as the engine sees it, rooted at the runtime's primary tree
- * (Q-S3-8). The platform dir the shared provision ensured rides along so
+ * (the one root). The platform dir the shared provision ensured rides along so
  * the backend routes `.stigmer/…` reads to it.
  *
  * CAS capture (design docs 08/11/12): the single per-turn observer owns the
@@ -209,7 +209,7 @@ export function buildDeepAgentWorkspace(input: TurnInput): DeepAgentWorkspace {
  * refuses an empty config, which is what the orchestrator's MCP gate
  * (`mcp-gate.ts`) guarded against beside its channel-only reason; the
  * runtime resolves unconditionally, so the one remaining question is
- * "anything to connect?" (S3 M2a, F-M2a-17).
+ * "anything to connect?" (since #1096).
  */
 export async function connectTools(input: TurnInput, sink: TurnSink): Promise<DeepAgentTools> {
   if (input.mcp.servers.length === 0) {
@@ -315,7 +315,7 @@ export function composeSystemPrompt(input: TurnInput, recalledMemories: Recalled
  * stop on the invoke config and the budget middleware's ~80% advisory, so
  * the warning and the enforcement can never disagree.
  *
- * Nothing in the middleware stack stops the run (Q-S3-3, landed at S3 M2b):
+ * Nothing in the middleware stack stops the run (since #1096):
  * the runtime's abort is the platform's one stop, and its TERMINATED arm the
  * one enforcement of `max_cost_usd`; the cost advisory warns the model at
  * ~80% of the cap the way the budget middleware warns at ~80% of the