@stigmer/runner 3.15.1 → 3.15.2-dev.20260913223433

package/src/activities/execute-deep-agent/__tests__/v3-status-builder.test.ts

@@ -1,10 +1,14 @@
 import { describe, it, expect, beforeEach } from "vitest";
 import { create } from "@bufbuild/protobuf";
 import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import { ExecutionPhase, MessageType, ToolCallStatus, ToolKind, TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApprovalAction, ExecutionPhase, MessageType, ToolCallStatus, ToolKind, TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { WorkspaceWriteBackSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
 import { V3StatusBuilder } from "../v3-status-builder.js";
 import { normalize } from "../v3-protocol-normalizer.js";
-import type { ApprovalPolicyProvider } from "../status-builder.js";
+import type { ApprovalPolicyProvider } from "../status-builder-shared.js";
+import type { MergedToolPolicy } from "../../../shared/approval-policy.js";
 import {
   resetSeq,
   makeMessageStart,
@@ -20,8 +24,38 @@ import {
 } from "../__test-utils__/v3-event-fixtures.js";
 import type { V3ProtocolEvent } from "../v3-event-recorder.js";
 
+/**
+ * What the builder REPORTED through `onUsage`, summed by the test the way an
+ * accountant would (the builder itself sums nothing and writes no
+ * `streamingUsage`; the runtime does, priced, through the sink).
+ */
+interface ReportedUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  turnCount: number;
+}
+
+const reportedByBuilder = new WeakMap<V3StatusBuilder, ReportedUsage>();
+
 function makeBuilder(): V3StatusBuilder {
-  return new V3StatusBuilder("exec-test", create(AgentExecutionStatusSchema, {}));
+  const reported: ReportedUsage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, turnCount: 0 };
+  const sb = new V3StatusBuilder("exec-test", create(AgentExecutionStatusSchema, {}), {
+    onUsage: (usage) => {
+      reported.inputTokens += usage.input_tokens ?? 0;
+      reported.outputTokens += usage.output_tokens ?? 0;
+      reported.cacheReadTokens += usage.input_token_details?.cache_read ?? 0;
+      reported.cacheWriteTokens += usage.input_token_details?.cache_creation ?? 0;
+      reported.turnCount += 1;
+    },
+  });
+  reportedByBuilder.set(sb, reported);
+  return sb;
+}
+
+function reportedUsage(sb: V3StatusBuilder): ReportedUsage {
+  return reportedByBuilder.get(sb)!;
 }
 
 function feedAll(sb: V3StatusBuilder, events: V3ProtocolEvent[]): void {
@@ -39,14 +73,11 @@ describe("V3StatusBuilder", () => {
   // ── Initialization ───────────────────────────────────────────────
 
   describe("initialization", () => {
-    it("sets phase to IN_PROGRESS on construction", () => {
+    it("writes neither phase nor startedAt (the turn runtime owns both; S3 M2a, Q-M2a-7)", () => {
       const sb = makeBuilder();
-      expect(sb.currentStatus.phase).toBe(ExecutionPhase.EXECUTION_IN_PROGRESS);
-    });
-
-    it("sets startedAt on construction", () => {
-      const sb = makeBuilder();
-      expect(sb.currentStatus.startedAt).toBeTruthy();
+      expect(sb.currentStatus.phase).toBe(ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED);
+      expect(sb.currentStatus.startedAt).toBe("");
+      expect(sb.awaitingApproval).toBe(false);
     });
 
     it("starts with forceNextUpdate = false", () => {
@@ -95,13 +126,11 @@ describe("V3StatusBuilder", () => {
         expect(status.messages[1].content).toBe("Here is more detail.");
         expect(status.messages[1].isStreaming).toBe(false);
 
-        const usage = status.streamingUsage!;
-        expect(usage.inputTokens).toBe(130n);
-        expect(usage.outputTokens).toBe(20n);
+        const usage = reportedUsage(sb);
+        expect(usage.inputTokens).toBe(130);
+        expect(usage.outputTokens).toBe(20);
         expect(usage.turnCount).toBe(2);
-        expect(usage.totalTokens).toBe(150n);
-
-        expect(status.phase).toBe(ExecutionPhase.EXECUTION_IN_PROGRESS);
+        expect(status.streamingUsage, "the runtime owns streamingUsage; the builder reports").toBeUndefined();
       });
     });
 
@@ -144,12 +173,11 @@ describe("V3StatusBuilder", () => {
         expect(status.messages[2].content).toBe("Let me elaborate.");
         expect(status.messages[2].isStreaming).toBe(false);
 
-        const usage = status.streamingUsage!;
-        expect(usage.inputTokens).toBe(500n);
-        expect(usage.outputTokens).toBe(120n);
-        expect(usage.cacheReadTokens).toBe(50n);
+        const usage = reportedUsage(sb);
+        expect(usage.inputTokens).toBe(500);
+        expect(usage.outputTokens).toBe(120);
+        expect(usage.cacheReadTokens).toBe(50);
         expect(usage.turnCount).toBe(2);
-        expect(usage.totalTokens).toBe(670n);
       });
     });
 
@@ -197,9 +225,9 @@ describe("V3StatusBuilder", () => {
         expect(secondMsg.content).toBe("The file contains a main function that logs 'hello'.");
         expect(secondMsg.toolCalls).toHaveLength(0);
 
-        const usage = status.streamingUsage!;
-        expect(usage.inputTokens).toBe(300n);
-        expect(usage.outputTokens).toBe(35n);
+        const usage = reportedUsage(sb);
+        expect(usage.inputTokens).toBe(300);
+        expect(usage.outputTokens).toBe(35);
         expect(usage.turnCount).toBe(2);
       });
     });
@@ -293,7 +321,8 @@ describe("V3StatusBuilder", () => {
         ]);
 
         const status = sb.currentStatus;
-        expect(status.phase).toBe(ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL);
+        expect(sb.awaitingApproval, "a fact for the caller, never a phase write").toBe(true);
+        expect(status.phase).toBe(ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED);
 
         const tc = status.messages[0].toolCalls[0];
         expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
@@ -338,14 +367,12 @@ describe("V3StatusBuilder", () => {
           }),
         ]);
 
-        const usage = sb.currentStatus.streamingUsage!;
-        expect(usage.inputTokens).toBe(600n);
-        expect(usage.outputTokens).toBe(60n);
-        expect(usage.cacheWriteTokens).toBe(80n);
-        expect(usage.cacheReadTokens).toBe(150n);
+        const usage = reportedUsage(sb);
+        expect(usage.inputTokens).toBe(600);
+        expect(usage.outputTokens).toBe(60);
+        expect(usage.cacheWriteTokens).toBe(80);
+        expect(usage.cacheReadTokens).toBe(150);
         expect(usage.turnCount).toBe(3);
-        expect(usage.totalTokens).toBe(890n);
-        expect(usage.observedAt).toBeTruthy();
       });
     });
 
@@ -406,9 +433,9 @@ describe("V3StatusBuilder", () => {
         expect(status.messages[3].type).toBe(MessageType.MESSAGE_AI);
         expect(status.messages[3].content).toBe("The research is complete.");
 
-        const usage = status.streamingUsage!;
-        expect(usage.inputTokens).toBe(650n);
-        expect(usage.outputTokens).toBe(50n);
+        const usage = reportedUsage(sb);
+        expect(usage.inputTokens).toBe(650);
+        expect(usage.outputTokens).toBe(50);
         expect(usage.turnCount).toBe(3);
       });
     });
@@ -442,9 +469,9 @@ describe("V3StatusBuilder", () => {
         }),
       ]);
 
-      const usage = sb.currentStatus.streamingUsage!;
-      expect(usage.inputTokens).toBe(50n);
-      expect(usage.outputTokens).toBe(10n);
+      const usage = reportedUsage(sb);
+      expect(usage.inputTokens).toBe(50);
+      expect(usage.outputTokens).toBe(10);
       expect(usage.turnCount).toBe(1);
     });
 
@@ -586,6 +613,26 @@ describe("V3StatusBuilder", () => {
       expect(todos["todo-0"].status).toBe(TodoStatus.TODO_COMPLETED);
     });
 
+    it("reports a sub-agent's usage through the same hook as the parent's (S3 M2b, Q-M2b-1)", () => {
+      const sb = makeBuilder();
+      const subNs = ["tools:task-1", "model_request:sub-run"];
+      feedAll(sb, [
+        ...[makeMessageStart("parent-1"), makeTextDelta("parent-1", "Delegating."), makeMessageFinish("parent-1", { usage: { input_tokens: 1_000, output_tokens: 10 } })],
+        makeToolStarted("task-1", "task", { subagent_type: "worker", description: "delegate" }),
+        makeMessageStart("sub-run", { namespace: subNs }),
+        makeTextDelta("sub-run", "Working on it.", { namespace: subNs }),
+        makeMessageFinish("sub-run", { namespace: subNs, usage: { input_tokens: 600, output_tokens: 12 } }),
+      ]);
+
+      const usage = reportedUsage(sb);
+      expect(usage.inputTokens, "the parent's 1,000 and the sub-agent's 600").toBe(1_600);
+      expect(usage.outputTokens).toBe(22);
+      expect(usage.turnCount).toBe(2);
+      // The transcript still routes the sub-agent's message to its own row, never the parent's.
+      expect(sb.currentStatus.messages.map((m) => m.content)).toEqual(["Delegating."]);
+      expect(sb.currentStatus.subAgentExecutions).toHaveLength(1);
+    });
+
     it("does not project a sub-agent's write_todos into parent status.todos", () => {
       const sb = makeBuilder();
       const subNs = ["tools:task-1", "tools:sub-todo"];
@@ -608,4 +655,262 @@ describe("V3StatusBuilder", () => {
       expect(Object.keys(sb.currentStatus.todos)).toHaveLength(0);
     });
   });
+  // ═══════════════════════════════════════════════════════════════════
+  // Carried from the v2 StatusBuilder's suite when that builder retired
+  // with the v2 stream (S3 M2b, Q-S3-1 / Q-M2b-5): every rule below is the
+  // builder's own — how a policy decides a row's status, what the row
+  // carries, how a seeded row is resolved, how artifacts and write-backs
+  // are upserted — and had no v3 twin. The sanitizer's own rules
+  // (redaction, truncation) are `shared/__tests__/args-preview.test.ts`'s.
+  // ═══════════════════════════════════════════════════════════════════
+
+  function providerWith(overrides: Partial<ApprovalPolicyProvider> = {}): ApprovalPolicyProvider {
+    return { policies: new Map(), toolServerMap: new Map(), globalBypass: false, ...overrides };
+  }
+
+  function policyFor(serverSlug: string, toolName: string, message = "Approve?"): [string, MergedToolPolicy] {
+    return [
+      `${serverSlug}/${toolName}`,
+      { toolName, mcpServerSlug: serverSlug, requiresApproval: true, approvalMessage: message, source: "classifier_default" },
+    ];
+  }
+
+  /** A text turn, then one tool start, on a builder with the given provider. */
+  function firstToolCallUnder(provider: ApprovalPolicyProvider, toolName: string, input: Record<string, unknown> = {}) {
+    const sb = makeBuilder();
+    sb.setApprovalProvider(provider);
+    feedAll(sb, [
+      makeMessageStart("run-1"),
+      makeTextDelta("run-1", "Working."),
+      makeMessageFinish("run-1", { usage: { input_tokens: 10, output_tokens: 5 } }),
+      makeToolStarted("toolu_1", toolName, input),
+    ]);
+    return { sb, tc: sb.currentStatus.messages[0].toolCalls[0] };
+  }
+
+  describe("approval provider: what decides a row's status", () => {
+    it("a policy that requires approval leaves the row WAITING_APPROVAL with its message and server", () => {
+      const [key, policy] = policyFor("github", "create_issue");
+      const { sb, tc } = firstToolCallUnder(
+        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["create_issue", "github"]]) }),
+        "create_issue",
+        { title: "Bug fix" },
+      );
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+      expect(tc.requiresApproval).toBe(true);
+      expect(tc.approvalMessage).toBe("Approve?");
+      expect(tc.mcpServerSlug).toBe("github");
+      expect(tc.approvalRequestedAt, "stamped when approval is required").toContain("T");
+      expect(sb.awaitingApproval).toBe(true);
+    });
+
+    it("the global bypass (spec.auto_approve_all) runs a gated tool without approval", () => {
+      const [key, policy] = policyFor("github", "delete_repo");
+      const { sb, tc } = firstToolCallUnder(
+        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["delete_repo", "github"]]), globalBypass: true }),
+        "delete_repo",
+      );
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+      expect(tc.requiresApproval).toBe(false);
+      expect(sb.awaitingApproval).toBe(false);
+    });
+
+    it("the global bypass still attributes the row to its MCP server", () => {
+      const { tc } = firstToolCallUnder(
+        providerWith({ toolServerMap: new Map([["echo", "test-mcp-server"]]), globalBypass: true }),
+        "echo",
+        { input: "hello" },
+      );
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+      expect(tc.mcpServerSlug).toBe("test-mcp-server");
+    });
+
+    it("a tool with no policy runs, attributed to its server", () => {
+      const { tc } = firstToolCallUnder(providerWith({ toolServerMap: new Map([["read", "filesystem"]]) }), "read");
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+      expect(tc.mcpServerSlug).toBe("filesystem");
+    });
+
+    it("a policy whose tool is not in the server map does not gate (the policy key needs the server)", () => {
+      const [key, policy] = policyFor("github", "create_pr");
+      const { tc } = firstToolCallUnder(providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map() }), "create_pr");
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+    });
+
+    it("resolves {{args.field}} placeholders in the approval message", () => {
+      const [key, policy] = policyFor("github", "create_issue", "Create issue '{{args.title}}' in {{args.repo}}?");
+      const { tc } = firstToolCallUnder(
+        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["create_issue", "github"]]) }),
+        "create_issue",
+        { title: "Fix crash", repo: "stigmer/stigmer" },
+      );
+      expect(tc.approvalMessage).toBe("Create issue 'Fix crash' in stigmer/stigmer?");
+    });
+  });
+
+  describe("args preview: when the builder writes one", () => {
+    it("a gated row carries a sanitized preview; an ungated row carries none", () => {
+      const [key, policy] = policyFor("db", "connect");
+      const gated = firstToolCallUnder(
+        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["connect", "db"]]) }),
+        "connect",
+        { host: "localhost", password: "super-secret" },
+      );
+      const preview = JSON.parse(gated.tc.argsPreview) as Record<string, string>;
+      expect(preview.host).toBe("localhost");
+      expect(preview.password, "the shared sanitizer redacts secret keys").toBe("[REDACTED]");
+
+      const ungated = firstToolCallUnder(providerWith(), "read", { path: "/foo" });
+      expect(ungated.tc.argsPreview).toBe("");
+    });
+
+    it("an unserializable input leaves the preview empty instead of failing the row", () => {
+      const [key, policy] = policyFor("api", "call");
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+      const { tc } = firstToolCallUnder(
+        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["call", "api"]]) }),
+        "call",
+        circular,
+      );
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+      expect(tc.argsPreview).toBe("");
+    });
+  });
+
+  describe("tool rows without a preceding text turn, and interleaving", () => {
+    it("a tool start with no prior text creates the AI message that carries it", () => {
+      const sb = makeBuilder();
+      feedAll(sb, [makeToolStarted("orphan", "read", {})]);
+      expect(sb.currentStatus.messages).toHaveLength(1);
+      expect(sb.currentStatus.messages[0].toolCalls[0].name).toBe("read");
+    });
+
+    it("interleaved start/finish pairs settle each row independently", () => {
+      const sb = makeBuilder();
+      feedAll(sb, [
+        makeMessageStart("run-1"),
+        makeTextDelta("run-1", "working"),
+        makeMessageFinish("run-1", { usage: { input_tokens: 1, output_tokens: 1 } }),
+        makeToolStarted("toolu_a", "read", {}),
+        makeToolFinished("toolu_a", "data 1"),
+        makeToolStarted("toolu_b", "write", {}),
+        makeToolFinished("toolu_b", "done"),
+      ]);
+      const rows = sb.currentStatus.messages.flatMap((m) => m.toolCalls);
+      expect(rows.map((r) => r.status)).toEqual([ToolCallStatus.TOOL_CALL_COMPLETED, ToolCallStatus.TOOL_CALL_COMPLETED]);
+    });
+  });
+
+  describe("a handler that throws", () => {
+    it("is logged with the execution, the event kind and its seq, and never escapes processEvent", () => {
+      const sb = makeBuilder();
+      const errors: string[] = [];
+      const original = console.error;
+      console.error = (msg: unknown) => { errors.push(String(msg)); };
+      try {
+        const poisoned = normalize(makeToolFinished("toolu_x", "ok"))[0]!;
+        // A getter that throws where the handler reads the output.
+        const event = { ...poisoned, get output(): unknown { throw new Error("property access failed"); } };
+        expect(() => sb.processEvent(event as typeof poisoned)).not.toThrow();
+      } finally {
+        console.error = original;
+      }
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toContain("exec-test");
+      expect(errors[0]).toContain("kind=tool_finished");
+      expect(errors[0]).toMatch(/seq=\d+/);
+    });
+  });
+
+  describe("resume reconciliation (a seeded WAITING row on a durable checkpoint)", () => {
+    const GATED_ID = "toolu_seeded_01";
+
+    it("resolves the seeded gated row in place — no duplicate, history kept, no re-gate", () => {
+      const status = create(AgentExecutionStatusSchema, {
+        phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+        messages: [
+          create(AgentMessageSchema, {
+            type: MessageType.MESSAGE_AI,
+            content: "I'll call the gated tool.",
+            toolCalls: [
+              create(ToolCallSchema, {
+                id: GATED_ID,
+                name: "dangerous_tool",
+                status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+                requiresApproval: true,
+                approvalAction: ApprovalAction.APPROVE,
+                mcpServerSlug: "my-server",
+              }),
+            ],
+          }),
+        ],
+      });
+      const sb = new V3StatusBuilder("exec-resume", status);
+      const [key, policy] = policyFor("my-server", "dangerous_tool", "Execute dangerous_tool");
+      sb.setApprovalProvider(providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["dangerous_tool", "my-server"]]) }));
+
+      // The durable checkpoint re-emits the SAME tool_call_id now that approval is granted.
+      feedAll(sb, [
+        makeToolStarted(GATED_ID, "dangerous_tool", { target: "prod" }),
+        makeToolFinished(GATED_ID, "tool executed ok"),
+        makeMessageStart("llm-after"),
+        makeTextDelta("llm-after", "All done."),
+        makeMessageFinish("llm-after", { usage: { input_tokens: 1, output_tokens: 1 } }),
+      ]);
+
+      const gated = sb.currentStatus.messages.flatMap((m) => m.toolCalls).filter((tc) => tc.id === GATED_ID);
+      expect(gated).toHaveLength(1);
+      expect(gated[0].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+      expect(gated[0].result).toContain("tool executed ok");
+      expect(gated[0].args, "the resumed start fills the args the seed lacked").toEqual({ target: "prod" });
+      const allText = sb.currentStatus.messages.map((m) => m.content).join("\n");
+      expect(allText).toContain("I'll call the gated tool.");
+      expect(allText).toContain("All done.");
+      expect(sb.awaitingApproval, "a resumed tool never re-gates").toBe(false);
+    });
+  });
+
+  describe("artifacts and write-backs (the ExecutionStatusWriter face)", () => {
+    const artifact = (sandboxPath: string, contentHash: string) =>
+      create(ExecutionArtifactSchema, { sandboxPath, contentHash, storageKey: `k/${contentHash}` });
+
+    it("appends a new artifact and forces the next persist", () => {
+      const sb = makeBuilder();
+      sb.addArtifact(artifact("out/a.txt", "h1"));
+      expect(sb.currentStatus.artifacts).toHaveLength(1);
+      expect(sb.forceNextUpdate).toBe(true);
+    });
+
+    it("deduplicates by sandboxPath: the same contentHash is a no-op that does not force a persist", () => {
+      const sb = makeBuilder();
+      sb.addArtifact(artifact("out/a.txt", "h1"));
+      sb.clearForceFlag();
+      sb.addArtifact(artifact("out/a.txt", "h1"));
+      expect(sb.currentStatus.artifacts).toHaveLength(1);
+      expect(sb.forceNextUpdate).toBe(false);
+    });
+
+    it("replaces the artifact in place when its contentHash changes", () => {
+      const sb = makeBuilder();
+      sb.addArtifact(artifact("out/a.txt", "h1"));
+      sb.clearForceFlag();
+      sb.addArtifact(artifact("out/a.txt", "h2"));
+      expect(sb.currentStatus.artifacts).toHaveLength(1);
+      expect(sb.currentStatus.artifacts[0].contentHash).toBe("h2");
+      expect(sb.forceNextUpdate).toBe(true);
+    });
+
+    it("upserts write-backs by workspaceEntryName, tracking entries independently", () => {
+      const sb = makeBuilder();
+      sb.addWriteBack(create(WorkspaceWriteBackSchema, { workspaceEntryName: "repo-a", branchName: "stigmer/s1" }));
+      sb.addWriteBack(create(WorkspaceWriteBackSchema, { workspaceEntryName: "repo-b", branchName: "stigmer/s1" }));
+      sb.clearForceFlag();
+      sb.addWriteBack(create(WorkspaceWriteBackSchema, { workspaceEntryName: "repo-a", branchName: "stigmer/s1", pullRequestUrl: "https://example/pr/1" }));
+      const backs = sb.currentStatus.workspaceWriteBacks;
+      expect(backs.map((b) => b.workspaceEntryName)).toEqual(["repo-a", "repo-b"]);
+      expect(backs[0].pullRequestUrl).toBe("https://example/pr/1");
+      expect(sb.forceNextUpdate).toBe(true);
+    });
+  });
 });

package/src/activities/execute-deep-agent/__tests__/vision-input.test.ts

@@ -1,6 +1,6 @@
 /**
  * Proves the T04 vision input path end-to-end through the REAL framework
- * stack: the exact `{ role: "user", content: [...] }` shape that setup.ts
+ * stack: the exact `{ role: "user", content: [...] }` shape that turn-setup.ts
  * builds is driven through `createDeepAgent` (the production graph factory,
  * default middleware included) and the test asserts what the chat model's
  * `_generate` actually received.
@@ -60,9 +60,9 @@ class CapturingModel extends ScriptedModel {
     return next as unknown as this;
   }
 
-  override async _generate(messages: BaseMessage[]): Promise<ChatResult> {
+  override async _generate(messages: BaseMessage[], options: this["ParsedCallOptions"]): Promise<ChatResult> {
     this.captured.push(messages);
-    return super._generate(messages);
+    return super._generate(messages, options);
   }
 }
 
@@ -92,7 +92,7 @@ describe("deep-agent vision input through the real graph", () => {
   });
 
   /**
-   * `content` is exactly what setup.ts puts on the user message: a plain
+   * `content` is exactly what turn-setup.ts puts on the user message: a plain
    * string, or the content-block array built by toLangChainImageBlocks plus
    * the composed text block.
    */
@@ -111,7 +111,7 @@ describe("deep-agent vision input through the real graph", () => {
       backend,
     } as Parameters<typeof createDeepAgent>[0]);
 
-    // The EXACT input shape setup.ts constructs (plain role/content dict, not
+    // The EXACT input shape turn-setup.ts constructs (plain role/content dict, not
     // a HumanMessage instance — the reducer does the coercion in production).
     await agent.invoke(
       { messages: [{ role: "user", content }] },

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

@@ -0,0 +1,94 @@
+/**
+ * The native deep-agent harness as a `HarnessAdapter` — the worker- and
+ * session-lifetime half of its LangGraph slice, behind the turn runtime's
+ * contract (`harness/types.ts`). One engine turn is `turn.ts`'s
+ * `runDeepAgentTurn`; this module boots and delegates.
+ *
+ * What this adapter owns: the deepagents harness profiles (worker lifetime,
+ * registered once before the first `createDeepAgent`), and one engine turn
+ * (`runTurn`, through `turn.ts`). Everything else about a turn is the
+ * runtime's (`harness/run-turn.ts`).
+ *
+ * THIS MODULE'S STATIC GRAPH IS SDK-FREE, ON PURPOSE. The composition roots
+ * import the harness table (`src/harness-adapters.ts`) BEFORE they boot it,
+ * and that table's static graph must stay connect- and SDK-free (the Cursor
+ * adapter's boot patches `node:http2` before anything dials the control
+ * plane). So `deepagents` and `@langchain/*` — this harness's whole engine —
+ * are loaded with a dynamic import INSIDE `boot`, after the profiles are
+ * registered; a worker that does not serve this harness never pays for
+ * LangChain. `__tests__/adapter-graph-is-sdk-free.test.ts` pins it.
+ *
+ * Nothing is parked per session, and the header says so where the contract
+ * asks: the sqlite saver is opened and closed per turn and the MCP
+ * subprocesses are connected and closed per turn (`turn.ts`), so
+ * `shutdown` and `releaseSession` resolve as no-ops.
+ *
+ * What this adapter never does: throw out of `runTurn` (an engine failure is
+ * `failed` on the `internal` surface; the recursion limit is
+ * `tool_call_limit`; a `CancelledFailure` never exists here), branch on why
+ * `stopSignal` aborted, write a phase or a terminal copy, bind a state id
+ * (the thread id is the runtime's, `deterministic`), or import
+ * `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
+ *
+ * Extracted from `index.ts` `createDeepAgentActivities` at S3 M2a on the
+ * Cursor adapter's layout (`execute-cursor/adapter.ts`).
+ */
+
+import type { Config } from "../../config.js";
+import type { HarnessAdapter, TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
+import { DEEP_AGENT_CAPABILITIES } from "./deep-agent-capabilities.js";
+import type { DeepAgentAdapterConfig } from "./turn-setup.js";
+
+/** The config slice this adapter reads per turn, taken at `boot`; a whole `Config` satisfies it. */
+export function resolveDeepAgentConfig(config: Config): DeepAgentAdapterConfig {
+  return {
+    checkpointerType: config.checkpointerType,
+    checkpointerProxyEndpoint: config.checkpointerProxyEndpoint,
+    stigmerToken: config.stigmerToken,
+    proxyEndpoint: config.proxyEndpoint,
+    mode: config.mode,
+  };
+}
+
+/** What `boot` leaves behind for the turns: the config slice and the engine turn, loaded after the profiles. */
+interface BootedDeepAgentHarness {
+  readonly config: DeepAgentAdapterConfig;
+  readonly runDeepAgentTurn: typeof import("./turn.js").runDeepAgentTurn;
+}
+
+export function createDeepAgentAdapter(): HarnessAdapter {
+  let booted: BootedDeepAgentHarness | undefined;
+
+  return {
+    name: "deep-agent",
+    capabilities: DEEP_AGENT_CAPABILITIES,
+
+    /**
+     * Register the harness profiles (deepagents would otherwise auto-inject
+     * an ungated `general-purpose` sub-agent into every graph), then load
+     * the engine slice. Idempotent: a re-boot re-reads the slice; the
+     * registration is once-guarded.
+     */
+    async boot(bootConfig: Config): Promise<void> {
+      // `deepagents-profiles.ts` imports the SDK to register against it, so
+      // it too is loaded here and not at the top of this module.
+      const { registerStigmerDeepagentsProfiles } = await import("./deepagents-profiles.js");
+      registerStigmerDeepagentsProfiles();
+      const { runDeepAgentTurn } = await import("./turn.js");
+      booted = { config: resolveDeepAgentConfig(bootConfig), runDeepAgentTurn };
+    },
+
+    /** Nothing is held across turns (see the header). */
+    async shutdown(): Promise<void> {},
+
+    /** Nothing is parked per session (see the header); an unknown id is a no-op by construction. */
+    async releaseSession(_sessionId: string): Promise<void> {},
+
+    async runTurn(input: TurnInput, sink: TurnSink): Promise<TurnOutcome> {
+      if (booted === undefined) {
+        throw new Error("deep-agent adapter: runTurn before boot (the registry boots every adapter before the worker polls)");
+      }
+      return booted.runDeepAgentTurn(input, sink, booted.config);
+    },
+  };
+}

package/src/activities/execute-deep-agent/cas-capture-observer.ts

@@ -39,6 +39,7 @@
 
 import { readFile } from "node:fs/promises";
 import { resolveWorkspacePath } from "../../shared/file-change.js";
+import type { CasTouchedSnapshot } from "../../shared/filereview/cas-touched.js";
 
 /**
  * Pre-turn bytes of each first-touched gitignored path, keyed by workspace-root-
@@ -75,6 +76,16 @@ export class CasCaptureObserver {
     return this.blocked;
   }
 
+  /**
+   * An atomic copy of what has been observed so far — the shape the progress
+   * slice and the turn-boundary capture read (`shared/filereview/cas-touched.ts`).
+   * Copied synchronously, so a sub-agent's concurrent `recordBefore` landing
+   * mid-capture cannot mutate a snapshot a reader is walking.
+   */
+  snapshot(): CasTouchedSnapshot {
+    return { before: new Map(this.before), blockedSecretPaths: new Set(this.blocked) };
+  }
+
   /**
    * Record the pre-turn bytes of `rawPath` when it is a first-touched gitignored
    * path. First-touch-wins across ALL backends sharing this observer: the slot is

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

@@ -0,0 +1,43 @@
+/**
+ * The native deep-agent harness's capability flags — the facts about the
+ * LangGraph engine the turn runtime branches on, declared once
+ * (`harness/capabilities.ts` has the matrix and the meaning of each flag).
+ *
+ *  - `interrupt`: the approval gate (`middleware/approval-gate.ts`) calls
+ *    LangGraph's `interrupt()` at a gated tool; the graph checkpoints and
+ *    stops, and the adapter resumes it with a `Command(resume)` carrying
+ *    the decisions (`hitl.ts`). No engine re-run, no exact-apply.
+ *  - `deterministic`: the thread id is the runtime's, minted from the
+ *    session before the first turn (`ensure-thread.ts`), so the adapter
+ *    never binds a state id and the runtime's reinvocation fact is the
+ *    persisted transcript.
+ *  - A system prompt: instructions, skills, input files and standing context
+ *    ride `createDeepAgent`'s `systemPrompt` (`prompt-builder.ts`).
+ *  - Sub-agents as compiled sub-graphs (`subagent-transformer.ts`), each
+ *    with its own mounted skills from the runtime (`TurnSkills.bySubAgent`).
+ *  - Tool restriction by tool list: an MCP server's `enabled_tools` is
+ *    honoured at connect time, so the engine never sees a disabled tool.
+ *  - PNG, JPEG, WebP and GIF inline (`shared/attachment-vision.ts`).
+ *  - File review under the `deep-agent` harness id with nothing excluded:
+ *    this harness writes no transient file into the repo (the `.stigmer`
+ *    link is the runtime's, created before its baseline pin and git-excluded
+ *    at provision). The capture is the runtime's (`harness/capture.ts`, S3
+ *    M4); this harness binds its `CasCaptureObserver`'s snapshot as the
+ *    runtime's CAS observations (`turn.ts`).
+ */
+
+import type { HarnessCapabilities } from "../../harness/capabilities.js";
+import { DEEP_AGENT_VISION_PROFILE } from "../../shared/attachment-vision.js";
+
+/** The harness id stamped on the deep-agent's file-review ledger events. */
+export const DEEP_AGENT_HARNESS_ID = "deep-agent";
+
+export const DEEP_AGENT_CAPABILITIES: HarnessCapabilities = {
+  pausePrimitive: "interrupt",
+  stateIdSource: "deterministic",
+  systemPrompt: true,
+  subAgents: true,
+  toolRestriction: true,
+  visionProfile: DEEP_AGENT_VISION_PROFILE,
+  fileReview: { harnessId: DEEP_AGENT_HARNESS_ID, excludePaths: [] },
+};