@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/src/activities/execute-deep-agent/__tests__/hermetic/structured-output.test.ts

@@ -0,0 +1,236 @@
+/**
+ * Hermetic goldens: STRUCTURED OUTPUT — an execution whose config carries a
+ * JSON schema, through the three paths a native turn has:
+ *
+ *  1. The engine's `structuredResponse`. langchain 1.4.1 turns a bare schema
+ *     into `toolStrategy` when the model's profile does not declare native
+ *     structured output (`agents/responses.js`): a synthetic function tool is
+ *     bound (named `extract-N` from a per-module counter — deepagents passes
+ *     no name and the schema's `title` is not consulted, so the script selects
+ *     it by pattern rather than by name), the model calls it with the answer
+ *     as arguments, and the graph's `run.output.structuredResponse` holds the
+ *     parsed object. The adapter folds it onto the status (`turn-settle.ts`).
+ *  2. The text fallback (the runtime's tier 1): the model answers in prose
+ *     with a fenced JSON block and `shared/extract-json.ts` recovers the
+ *     object from the final text (`run-turn.ts` `extractStructuredOutputFromText`).
+ *  3. The LLM fallback (the runtime's tier 2, Q-S3-7): the final text carries
+ *     no JSON at all, so the runtime asks a second model — the registry's
+ *     economy tier for the primary's provider — to extract it through
+ *     `withStructuredOutput` (`shared/extract-structured-output.ts`). Native
+ *     gained this arm at S3 M2a, when the turn runtime took the epilogue
+ *     over; it is pinned here since M2b (F-M2b-14), where every other ruled
+ *     alignment is. Two facts the golden records: the extraction call is a
+ *     SECOND model build (`maxTokens: 4096`, on the primary — the fixture
+ *     registry declares no economy row, `getEconomyModel`'s last resort),
+ *     and its tool call never reaches the transcript (it is not a graph
+ *     step). The arm runs in the OSS direct-credential posture
+ *     (`ANTHROPIC_API_KEY` stubbed for the arm only): without a proxy the
+ *     runtime refuses tier 2 when no credential path exists, and that
+ *     refusal is a log line, never a lost run.
+ *
+ * Whatever each path yields is recorded as found: `status.structuredOutput`
+ * and the slim's `structured`.
+ *
+ * The `extract-N` name is deterministic per test FILE (vitest isolates each
+ * file's module graph, so the counter starts at 1), and only the tool-strategy
+ * arm compiles a graph with a schema tool in this file, so its row — if one
+ * is persisted — is `extract-1`. Tier 2's tool is `@langchain/core`'s default
+ * `extract` (`withStructuredOutput` with no name), bound on the extraction
+ * model alone, which is how the script tells the two calls apart.
+ *
+ * Since S3 M2a the activity is the turn runtime over the native adapter, and
+ * `streamingUsage` carries the runtime accountant's fields — `model`,
+ * `estimatedCostUsd` priced at the registry's rates, the requested tier and
+ * thinking mode (Q-M2a-2: one writer of the summary, the runtime). Nothing
+ * else in this golden moved with the flip.
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-deep-agent/__tests__/hermetic -u
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+import { recordedModelBuilds } from "../../__test-utils__/scripted-model-module.js";
+import { FIXTURE_NATIVE_MODEL } from "../../../../__test-utils__/model-registry-fixture.js";
+
+const SCHEMA = {
+  type: "object",
+  properties: { answer: { type: "string" }, score: { type: "number" } },
+  required: ["answer", "score"],
+};
+const ANSWER = { answer: "forty-two", score: 42 };
+const SCHEMA_TOOL_PATTERN = /^extract-\d+$/;
+
+describe("ExecuteDeepAgent hermetic — structured output", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("tool strategy: the model calls the bound schema tool", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    clock.reset();
+    const record = deepAgentExecutionRecord({ message: "Give me the answer.", structuredOutputSchema: SCHEMA });
+    const boundSchemaTools: string[] = [];
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: (tools) => {
+        const schemaTool = tools.find((t) => SCHEMA_TOOL_PATTERN.test(t));
+        if (schemaTool) boundSchemaTools.push(schemaTool);
+        return {
+          turns: [
+            {
+              text: "Here is the structured answer.",
+              toolCalls: schemaTool ? [{ id: "call-hermetic-extract-0001", name: schemaTool, args: ANSWER }] : [],
+              usage: { inputTokens: 1_300, outputTokens: 40 },
+            },
+            { text: "Recorded.", usage: { inputTokens: 1_500, outputTokens: 10 } },
+          ],
+        };
+      },
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runDeepAgentTurn(scenario);
+
+    // ── Assert ───────────────────────────────────────────────────────────────
+    expect(invocation.outcome.kind).toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_COMPLETED");
+    expect(boundSchemaTools[0], "langchain bound the toolStrategy schema tool").toBe("extract-1");
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+    const final = record.lastFullStatus!;
+    expect(final.structuredOutput, "the engine's structuredResponse reaches the status").toEqual(ANSWER);
+    expect(slim.structured).toEqual(ANSWER);
+
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/structured-output.tool-strategy.status.json");
+  });
+
+  it("text fallback: a fenced JSON block in the final text", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    clock.reset();
+    const record = deepAgentExecutionRecord({ message: "Give me the answer.", structuredOutputSchema: SCHEMA });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: () => ({
+        turns: [
+          {
+            text: "Here you go:\n```json\n" + JSON.stringify(ANSWER) + "\n```",
+            usage: { inputTokens: 1_300, outputTokens: 40 },
+          },
+        ],
+      }),
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runDeepAgentTurn(scenario);
+
+    // ── Assert ───────────────────────────────────────────────────────────────
+    expect(invocation.outcome.kind).toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_COMPLETED");
+    const final = record.lastFullStatus!;
+    expect(final.structuredOutput, "extracted from the final text").toEqual(ANSWER);
+    expect(slim.structured).toEqual(ANSWER);
+    expect(record.toolCalls(), "no tool was involved").toHaveLength(0);
+
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/structured-output.text-fallback.status.json");
+  });
+
+  it("LLM fallback (tier 2): prose with no JSON is extracted by a second model call the transcript never sees (Q-S3-7)", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    clock.reset();
+    // The OSS direct-credential posture, for this arm only: with no proxy the
+    // runtime refuses tier 2 unless a credential path exists.
+    vi.stubEnv("ANTHROPIC_API_KEY", "hermetic-tier2-credential");
+    const PROSE = "The answer is forty-two, and I would score it a perfect forty-two out of the same.";
+    const record = deepAgentExecutionRecord({ message: "Give me the answer.", structuredOutputSchema: SCHEMA });
+    const extractionCalls: string[][] = [];
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: (tools) => {
+        // The extraction model binds exactly one tool, core's default `extract`;
+        // the agent's graph never binds a tool of that name.
+        if (tools.length === 1 && tools[0] === "extract") {
+          extractionCalls.push([...tools]);
+          return { turns: [{ text: "", toolCalls: [{ id: "call-hermetic-tier2-0001", name: "extract", args: ANSWER }] }] };
+        }
+        return { turns: [{ text: PROSE, usage: { inputTokens: 1_300, outputTokens: 40 } }] };
+      },
+    });
+
+    try {
+      // ── Act ────────────────────────────────────────────────────────────────
+      const invocation = await runDeepAgentTurn(scenario);
+
+      // ── Assert ─────────────────────────────────────────────────────────────
+      expect(invocation.outcome.kind).toBe("returned");
+      const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+      expect(slim.phase).toBe("EXECUTION_COMPLETED");
+      const final = record.lastFullStatus!;
+      expect(final.structuredOutput, "extracted by the second model").toEqual(ANSWER);
+      expect(slim.structured).toEqual(ANSWER);
+      expect(record.toolCalls(), "the extraction tool call is not a graph step and never reaches the transcript").toHaveLength(0);
+      expect(extractionCalls, "the extractor was asked exactly once").toHaveLength(1);
+
+      // The agent's build, the sub-agent factory's builds (every registered
+      // profile sub-agent is compiled, invoked or not), then — last, after the
+      // graph has ended — the extractor's: the one build that caps its output
+      // (`maxTokens: 4096`) and carries no execution header scope.
+      const builds = recordedModelBuilds();
+      const extractorBuilds = builds.filter((b) => b.maxTokens === 4096);
+      expect(extractorBuilds, "exactly one extraction build").toHaveLength(1);
+      expect(builds.at(-1), "the extractor is built after the graph's run, never before").toBe(extractorBuilds[0]);
+      expect(extractorBuilds[0]!.headerScope).toBeUndefined();
+      // The fixture registry declares no economy row, so `getEconomyModel`
+      // falls back to the primary (its last resort).
+      expect(extractorBuilds[0]!.modelName).toBe(FIXTURE_NATIVE_MODEL);
+
+      const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+      await expect(json).toMatchFileSnapshot("./goldens/structured-output.tier2.status.json");
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/sub-agent-delegation.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Hermetic golden: SUB-AGENT DELEGATION — the root agent hands a task to a
+ * declared sub-agent through deepagents' `task` tool, and the sub-agent's
+ * own turn is tracked as a `SubAgentExecution`.
+ *
+ * Invariant pinned: `transformAndCompileSubagents` compiles the agent's
+ * declared sub-agent (plus deepagents' built-in `general-purpose` and the
+ * runner's `shell`) on the SAME model double through `modelFactory`; the root
+ * proposes `task({ subagent_type, description })`; the tools node runs the
+ * sub-agent graph under a nested namespace (`tools:<uuid>|...`); the
+ * `SubAgentTracker` opens a `SubAgentExecution` keyed by the `task` call id
+ * (not by the namespace uuid, which never reaches the status), routes the
+ * nested model events into its own transcript, and closes it COMPLETED when
+ * the `task` tool finishes; the root's transcript carries the `task` row and
+ * its closing text. The golden (`goldens/sub-agent-delegation.status.json`)
+ * pins the nested transcript shape S4 must reproduce.
+ *
+ * Role selection: `createDeepAgent` gives the sub-agent the same tool set as
+ * its parent (`task` included), so the script tells the roles apart by the
+ * system prompt (`ScriptRoleContext.systemPrompt`), which carries the
+ * sub-agent's own instructions — the one thing that differs.
+ *
+ * Since S3 M2a the activity is the turn runtime over the native adapter, and
+ * `streamingUsage` carries the runtime accountant's fields — `model`,
+ * `estimatedCostUsd` priced at the registry's rates, the requested tier and
+ * thinking mode (Q-M2a-2: one writer of the summary, the runtime). Nothing
+ * else in this golden moved with the flip.
+ *
+ * Since S3 M2b (Q-M2b-1, owner ruling 2026-09-13) the sub-agent's spend is
+ * the execution's spend: the helper's one turn (600 in, 12 out) is reported
+ * through the same hook as the root's, so `streamingUsage` reads 3,900 in /
+ * 102 out / 3 turns where it read 3,300 / 90 / 2, and `estimatedCostUsd`
+ * 0.00441 where it read 0.00375 — the helper's 660 micro-dollars at the
+ * PARENT's rate (per-sub-agent pricing is an S5 item; the in-graph cost cap
+ * this replaces priced sub-agents the same way). The five lines of
+ * `streamingUsage` are the whole diff; the transcript and the sub-agent row
+ * are byte-identical. `max_cost_usd` is now enforced over this total by the
+ * runtime, the one enforcement since the cost middleware became advisory
+ * (Q-S3-3).
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-deep-agent/__tests__/hermetic -u
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { create, toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ExecutionPhase,
+  MessageType,
+  SubAgentStatus,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SubAgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+import { recordedModelBuilds } from "../../__test-utils__/scripted-model-module.js";
+
+const HELPER_INSTRUCTIONS = "You are the hermetic helper. Answer in one line.";
+const TASK_CALL_ID = "call-hermetic-task-0001";
+const TASK_DESCRIPTION = "Look up the fixture value.";
+const HELPER_ANSWER = "The fixture value is forty-two.";
+const ROOT_CLOSING = "The helper reports the fixture value is forty-two.";
+
+describe("ExecuteDeepAgent hermetic — sub-agent delegation", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("tracks the delegated turn as a SubAgentExecution keyed by the task call and completes", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const helper = create(SubAgentSchema, {
+      name: "helper",
+      description: "Looks up fixture values.",
+      instructions: HELPER_INSTRUCTIONS,
+    });
+    const record = deepAgentExecutionRecord({ message: "Ask the helper for the fixture value.", subAgents: [helper] });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: (_tools, context) =>
+        context.systemPrompt.includes(HELPER_INSTRUCTIONS)
+          ? { turns: [{ text: HELPER_ANSWER, usage: { inputTokens: 600, outputTokens: 12 } }] }
+          : {
+              turns: [
+                {
+                  text: "Delegating to the helper.",
+                  toolCalls: [{ id: TASK_CALL_ID, name: "task", args: { description: TASK_DESCRIPTION, subagent_type: "helper" } }],
+                  usage: { inputTokens: 1_500, outputTokens: 60 },
+                },
+                { text: ROOT_CLOSING, usage: { inputTokens: 1_800, outputTokens: 30 } },
+              ],
+            },
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runDeepAgentTurn(scenario);
+
+    // ── Assert: outcome ──────────────────────────────────────────────────────
+    expect(invocation.outcome.kind).toBe("returned");
+    expect((invocation.outcome as { value: Record<string, unknown> }).value.phase).toBe("EXECUTION_COMPLETED");
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+
+    // ── Assert: the root transcript ──────────────────────────────────────────
+    const final = record.lastFullStatus!;
+    const rows = record.toolCalls();
+    expect(rows.map((tc) => [tc.id, tc.name, tc.status])).toEqual([[TASK_CALL_ID, "task", ToolCallStatus.TOOL_CALL_COMPLETED]]);
+    expect(final.messages.filter((m) => m.type === MessageType.MESSAGE_AI).map((m) => m.content)).toEqual([
+      "Delegating to the helper.",
+      "",
+      ROOT_CLOSING,
+    ]);
+
+    // ── Assert: the sub-agent execution ──────────────────────────────────────
+    expect(final.subAgentExecutions).toHaveLength(1);
+    const sub = final.subAgentExecutions[0];
+    expect(sub.id, "keyed by the task call id, never by the namespace uuid").toBe(TASK_CALL_ID);
+    expect(sub.name).toBe("helper");
+    expect(sub.subject).toBe(TASK_DESCRIPTION);
+    expect(sub.status).toBe(SubAgentStatus.SUB_AGENT_COMPLETED);
+    expect(sub.messages.map((m) => [m.type, m.content])).toEqual([[MessageType.MESSAGE_AI, HELPER_ANSWER]]);
+
+    // ── Assert: the model double was built for every compiled role ──────────
+    expect(recordedModelBuilds().length, "the primary plus one per compiled sub-agent").toBeGreaterThanOrEqual(2);
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/sub-agent-delegation.status.json");
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/tool-call.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Hermetic golden: a turn with an UNGATED TOOL CALL through the whole
+ * `ExecuteDeepAgent` activity — the deepagents built-in `read_file` on a
+ * file seeded in the session workspace.
+ *
+ * Invariant pinned: the model's turn ("Let me read it." plus one `read_file`
+ * proposal), the tools node's `tool-started` / `tool-finished` events (status
+ * RUNNING then COMPLETED, `result` from the tool's output, `startedAt` /
+ * `completedAt` on the scripted clock), and the follow-up assistant turn fold
+ * into ONE tool row, and the turn ends COMPLETED. A read-only built-in is never
+ * gated (`shared/tool-kind.ts` FILE_READ), so no approval fields are set. The
+ * mid-stream persist the tool-call boundary forces (`persist-decision.ts`
+ * `contentDirty`) is what the platform-stop arm relies on.
+ *
+ * What the golden shows about TODAY's transcript shape, recorded as found
+ * (S3 M0 finding F-M0-1; a transcript-shape fact for S4): the row does NOT sit on
+ * the AI message that carries the text of the same LLM turn. LangGraph 1.3.2
+ * stamps the model's events with namespace `["model_request:<uuid>"]` and the
+ * tools node's with `["tools:<uuid>"]`; `V3StatusBuilder.ensureAiMessage`
+ * files the text under the raw namespace while `handleToolStarted` looks the
+ * parent up under `resolveAgentNamespace(...)`, which strips only `tools:`
+ * segments and so resolves to `""` — a miss, and `ensureAiMessageForToolCall`
+ * appends an EMPTY AI message for the row. So the transcript is THREE AI
+ * messages: the text, an empty one carrying the row, the closing text. The
+ * hand-authored fixtures in `v3-event-fixtures.ts` use `namespace: []` and
+ * never reached this arm; this golden, on the real graph, does. The golden
+ * (`goldens/tool-call.status.json`) is the shape S4's canonical transcript
+ * builder is measured against, and the shape any fix must change on purpose.
+ *
+ * Since S3 M2a the activity is the turn runtime over the native adapter, and
+ * `streamingUsage` carries the runtime accountant's fields — `model`,
+ * `estimatedCostUsd` priced at the registry's rates, the requested tier and
+ * thinking mode (Q-M2a-2: one writer of the summary, the runtime). Nothing
+ * else in this golden moved with the flip.
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-deep-agent/__tests__/hermetic -u
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+  sessionWorkspaceDir,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+
+const CALL_ID = "call-hermetic-read-0001";
+const USER_MESSAGE = "What is in README.md?";
+const README = "# Hermetic\n\nA fixture readme.\n";
+const ASSISTANT_TEXT = "README.md holds a one-line fixture description.";
+
+describe("ExecuteDeepAgent hermetic — ungated tool call", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("folds the proposal and the tools node's events into one COMPLETED tool row and completes", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const record = deepAgentExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: () => ({
+        turns: [
+          {
+            text: "Let me read it.",
+            toolCalls: [{ id: CALL_ID, name: "read_file", args: { file_path: "/README.md" } }],
+            usage: { inputTokens: 1_500, outputTokens: 60 },
+          },
+          { text: ASSISTANT_TEXT, usage: { inputTokens: 1_700, outputTokens: 30 } },
+        ],
+      }),
+    });
+    // Seeded AFTER the scenario begins: beginning a scenario clears the
+    // session workspace so every scenario starts where a new session starts.
+    const workspace = sessionWorkspaceDir(env);
+    mkdirSync(workspace, { recursive: true });
+    writeFileSync(join(workspace, "README.md"), README, "utf-8");
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runDeepAgentTurn(scenario);
+
+    // ── Assert: outcome and phases ───────────────────────────────────────────
+    expect(invocation.outcome.kind).toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_COMPLETED");
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    ]);
+    expect(record.persisted.length, "the tool-call boundary forces a mid-stream persist").toBeGreaterThan(2);
+
+    // ── Assert: the one tool-call row ────────────────────────────────────────
+    const rows = record.toolCalls();
+    expect(rows, "proposal + started + finished fold into ONE row, never two").toHaveLength(1);
+    const row = rows[0];
+    expect(row.id).toBe(CALL_ID);
+    expect(row.name).toBe("read_file");
+    expect(row.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(row.args).toEqual({ file_path: "/README.md" });
+    expect(row.result, "the built-in's numbered listing of the seeded file").toContain("A fixture readme.");
+    expect(row.requiresApproval, "a read-only built-in is not gated").toBe(false);
+
+    // ── Assert: the transcript, as it is today (F-M0-1 in the header) ────────
+    const final = record.lastFullStatus!;
+    const ai = final.messages.filter((m) => m.type === MessageType.MESSAGE_AI);
+    expect(ai.map((m) => m.content), "text, an EMPTY message carrying the row, closing text").toEqual([
+      "Let me read it.",
+      "",
+      ASSISTANT_TEXT,
+    ]);
+    expect(ai[1].toolCalls.map((tc) => tc.id), "the row sits on the empty message, not beside its text").toEqual([
+      CALL_ID,
+    ]);
+    expect(final.streamingUsage?.turnCount).toBe(2);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/tool-call.status.json");
+  });
+});