@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/src/activities/execute-deep-agent/__test-utils__/gateway-substrate.ts

@@ -0,0 +1,180 @@
+/**
+ * Deep-agent adapter for the HITL gateway Contract Test Kit.
+ *
+ * Drives the REAL in-process gateway: a `createDeepAgent` graph carrying the
+ * production {@link createApprovalGateMiddleware}, a `MemorySaver` checkpointer,
+ * and a scripted model that proposes the action under test. `authorize` runs the
+ * graph to its first pause and, for an approving/non-approving decision, resumes
+ * via `Command(resume=…)` — exactly the production pause/resume cycle proven in
+ * `__tests__/subagent-approval-propagation.test.ts`. There is no mocked
+ * `interrupt()`: the gate's own `interrupt()` fires, so the contract exercises the
+ * gateway end-to-end.
+ *
+ * Capabilities: this substrate IS the side effect, so it observes (and counts)
+ * execution; resource-exact leasing is not a property of this gate (sameness comes
+ * from checkpoint replay), so `enforcesExactResource` is false and
+ * `authorizeAfterGrant` is intentionally not implemented.
+ */
+
+import { HumanMessage } from "@langchain/core/messages";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { Command, MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent, StateBackend } from "deepagents";
+
+import { createApprovalGateMiddleware } from "../../../middleware/approval-gate.js";
+import { deriveLeaseScope } from "../../../shared/approval-policy.js";
+import type { ToolApprovalCategory } from "../../../shared/tool-kind.js";
+import { ScriptedModel, readPendingInterrupts } from "./scripted-model.js";
+import type {
+  GatewayDecision,
+  GatewayOutcome,
+  GatewaySubstrate,
+  ProposedAction,
+} from "../../../__test-utils__/approval-contract/types.js";
+
+/**
+ * Translate an abstract action into a deep-agent tool name + args + MCP server.
+ * The names are deliberately ALIASES, not deepagents built-ins, so we can attach
+ * a counting handler without shadowing an injected built-in, while still hitting
+ * the right approval category via the shared classifier:
+ *  - write  → `overwrite_file` (FILE_WRITE), delete → `remove_file` (FILE_DELETE),
+ *    shell → `execute_command` (SHELL): each gated fail-closed by category.
+ *  - read   → an unknown, non-mutating name: auto-approved (fail-open), no gate.
+ *  - mcp    → the MCP tool name mapped to its server: governed by policy, absent
+ *    policy ⇒ auto-approved.
+ */
+function toDeepAgentTool(action: ProposedAction): {
+  name: string;
+  args: Record<string, unknown>;
+  serverSlug: string;
+} {
+  switch (action.kind) {
+    case "write":
+      return { name: "overwrite_file", args: { path: action.resource, content: "x" }, serverSlug: "" };
+    case "shell":
+      return { name: "execute_command", args: { command: action.resource }, serverSlug: "" };
+    case "delete":
+      return { name: "remove_file", args: { path: action.resource }, serverSlug: "" };
+    case "read":
+      return { name: "inspect_resource", args: { path: action.resource }, serverSlug: "" };
+    case "mcp":
+      return { name: action.mcpToolName ?? "mcp_tool", args: {}, serverSlug: action.mcpServerSlug ?? "srv" };
+  }
+}
+
+/** Map a contract decision to the gate's resume verdict (anything unrecognized = unknown). */
+function toResumeAction(decision: GatewayDecision): string {
+  switch (decision) {
+    case "approve":
+      return "approve";
+    case "skip":
+      return "skip";
+    case "reject":
+      return "reject";
+    default:
+      return "unrecognized-verdict";
+  }
+}
+
+let threadSeq = 0;
+
+/**
+ * Drive one probe action through a freshly built gate and report the outcome.
+ * `leasedCategories` pre-arms a run-lifetime class lease (empty for the plain
+ * authorize path); `decision` resumes a pause for the non-lease drives.
+ */
+async function runProbe(
+  action: ProposedAction,
+  decision: GatewayDecision,
+  leasedCategories: ReadonlySet<ToolApprovalCategory>,
+): Promise<GatewayOutcome> {
+  const { name, args, serverSlug } = toDeepAgentTool(action);
+
+  let executionCount = 0;
+  const countingTool = tool(
+    async () => {
+      executionCount += 1;
+      return "ok";
+    },
+    {
+      name,
+      description: `contract probe tool ${name}`,
+      schema: z.object({}).passthrough(),
+    },
+  );
+
+  const toolServerMap = serverSlug ? new Map([[name, serverSlug]]) : new Map<string, string>();
+  const gate = createApprovalGateMiddleware({
+    policies: new Map(),
+    toolServerMap,
+    leasedCategories,
+  });
+
+  const agent = await createDeepAgent({
+    model: new ScriptedModel(() => ({
+      toolCalls: [{ name, args, id: "call_1" }],
+      done: "done",
+    })),
+    checkpointer: new MemorySaver() as never,
+    backend: new StateBackend(),
+    tools: [countingTool],
+    middleware: [gate],
+  } as unknown as Parameters<typeof createDeepAgent>[0]);
+
+  const config = { configurable: { thread_id: `contract-${threadSeq++}` }, recursionLimit: 50 };
+
+  // Run to the first pause. A gated tool interrupts before its handler runs.
+  await agent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+  const pending = readPendingInterrupts((await agent.getState(config)) as never);
+  const gated = pending.length > 0;
+  // The gate stamps the authorization provenance on every interrupt it raises;
+  // surface it so the contract can assert no side effect is gated without one.
+  const policySource = gated ? pending[0].policySource : "";
+
+  // `none` is the "no decision yet" probe: leave the action withheld.
+  if (gated && decision !== "none") {
+    const resume: Record<string, { action: string }> = {};
+    for (const p of pending) resume[p.interruptId] = { action: toResumeAction(decision) };
+    await agent.invoke(new Command({ resume }), config);
+  }
+
+  return { executed: executionCount > 0, gated, executionCount, policySource };
+}
+
+const NO_LEASED_CATEGORIES: ReadonlySet<ToolApprovalCategory> = new Set();
+
+export function createDeepAgentSubstrate(): GatewaySubstrate {
+  return {
+    name: "deep-agent",
+    available: true,
+    capabilities: {
+      observesExecution: true,
+      enforcesExactResource: false,
+      // The deep-agent gate re-checks every distinct call and relies on
+      // checkpoint replay for sameness; content isolation is not a property of
+      // the gate itself, so the content-exact invariant does not apply here.
+      enforcesExactContent: false,
+      appliesRunLifetimeLease: true,
+      surfacesGatePolicySource: true,
+    },
+
+    async authorize(action: ProposedAction, decision: GatewayDecision): Promise<GatewayOutcome> {
+      return runProbe(action, decision, NO_LEASED_CATEGORIES);
+    },
+
+    async authorizeUnderClassLease(
+      leased: ProposedAction,
+      probe: ProposedAction,
+    ): Promise<GatewayOutcome> {
+      // Reduce the leased action to its class exactly as the runner does, then
+      // arm the gate with that category lease and run the probe with no fresh
+      // decision — so only the lease can clear it.
+      const leasedTool = toDeepAgentTool(leased);
+      const scope = deriveLeaseScope(leasedTool.name, leasedTool.serverSlug);
+      const leasedCategories =
+        scope?.kind === "category" ? new Set([scope.category]) : NO_LEASED_CATEGORIES;
+      return runProbe(probe, "none", leasedCategories);
+    },
+  };
+}

package/src/activities/execute-deep-agent/__test-utils__/scripted-model.ts

@@ -0,0 +1,134 @@
+/**
+ * Scripted deep-agent test harness: a deterministic chat model plus the
+ * parent-checkpoint interrupt reader.
+ *
+ * These two helpers are what every "drive a real deepagents/LangGraph graph
+ * through the approval gate" test needs, and they were previously copy-pasted
+ * inline. They are shared by:
+ * - `__tests__/subagent-approval-propagation.test.ts` (sub-agent interrupt
+ *   propagation against the real runtime), and
+ * - `__test-utils__/gateway-substrate.ts` (the deep-agent adapter for the
+ *   gateway Contract Test Kit).
+ *
+ * Keeping one copy means a change to how the runner reads pending interrupts (or
+ * how a scripted run is driven) updates every consumer at once.
+ */
+
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { AIMessage, ToolMessage, type BaseMessage } from "@langchain/core/messages";
+import type { ChatResult } from "@langchain/core/outputs";
+
+/** A single tool call the scripted model proposes on a non-terminal turn. */
+export interface ScriptedToolCall {
+  name: string;
+  args: Record<string, unknown>;
+  id: string;
+}
+
+/**
+ * What the scripted model does for a given role: propose `toolCalls` while no
+ * tool result is pending, then emit the `done` text once a tool result returns.
+ */
+export interface ScriptStep {
+  toolCalls: ScriptedToolCall[];
+  done: string;
+}
+
+/**
+ * Picks the {@link ScriptStep} for the currently-bound tool set. A single-agent
+ * test ignores the argument; a parent/sub-agent test keys the role on a tool
+ * unique to one role (e.g. the sub-agent's gated tool), because `createDeepAgent`
+ * injects the `task` tool into both the parent and its sub-agents.
+ */
+export type ScriptSelector = (boundToolNames: string[]) => ScriptStep;
+
+/**
+ * A deterministic two-turn chat model: on the first turn it proposes the
+ * selected role's tool calls; once a tool result comes back it returns the
+ * role's terminating text. No LLM, no network — the role is keyed on the bound
+ * tool names so the same model instance drives a parent and its sub-agents.
+ */
+export class ScriptedModel extends BaseChatModel {
+  toolNames: string[] = [];
+  private readonly select: ScriptSelector;
+
+  constructor(select: ScriptSelector) {
+    super({});
+    this.select = select;
+  }
+
+  _llmType(): string {
+    return "scripted";
+  }
+
+  bindTools(tools: unknown[]): this {
+    const next = new ScriptedModel(this.select);
+    next.toolNames = (tools as Array<{ name?: string }>).map((t) => t?.name ?? "");
+    return next as unknown as this;
+  }
+
+  async _generate(messages: BaseMessage[]): Promise<ChatResult> {
+    const step = this.select(this.toolNames);
+    const lastIsToolResult = messages[messages.length - 1] instanceof ToolMessage;
+
+    const message = lastIsToolResult
+      ? new AIMessage({ content: step.done })
+      : new AIMessage({
+          content: "",
+          tool_calls: step.toolCalls.map((tc) => ({ ...tc, type: "tool_call" as const })),
+        });
+
+    const text = typeof message.content === "string" ? message.content : "";
+    return { generations: [{ message, text }] };
+  }
+}
+
+/** A pending approval interrupt surfaced at the parent checkpoint. */
+export interface PendingInterrupt {
+  taskId: string;
+  interruptId: string;
+  toolCallId: string;
+  toolName: string;
+  message: string;
+  /**
+   * Authorization provenance the gate attached to the interrupt
+   * (approval-gate.ts `policy_source`) — the PolicySource union string, or "" for
+   * legacy. Lets the gateway contract assert every gated side effect is
+   * provenance-tagged.
+   */
+  policySource: string;
+}
+
+/**
+ * Read the pending approval interrupts from a graph state, exactly as the
+ * production resume path does (`hitl.ts` / `index.ts`): scan the parent's
+ * top-level `tasks[].interrupts`, skipping any already carrying a resume value.
+ *
+ * Crucially `interruptId` is the interrupt's OWN id (`interrupts[].id`), not the
+ * owning `task.id` — for a nested sub-agent interrupt the two differ, and only
+ * the interrupt id routes a `Command(resume=...)` value back into the nested
+ * `interrupt()`.
+ */
+export function readPendingInterrupts(state: {
+  tasks?: ReadonlyArray<{
+    id: string;
+    interrupts?: ReadonlyArray<{ id?: string; value?: unknown; resumeValue?: unknown }>;
+  }>;
+}): PendingInterrupt[] {
+  const out: PendingInterrupt[] = [];
+  for (const task of state.tasks ?? []) {
+    for (const intr of task.interrupts ?? []) {
+      if (intr.resumeValue !== undefined) continue;
+      const v = (intr.value ?? {}) as Record<string, unknown>;
+      out.push({
+        taskId: task.id,
+        interruptId: (intr.id as string) ?? task.id,
+        toolCallId: (v.tool_call_id as string) ?? "",
+        toolName: (v.tool_name as string) ?? "",
+        message: (v.message as string) ?? "",
+        policySource: (v.policy_source as string) ?? "",
+      });
+    }
+  }
+  return out;
+}

package/src/activities/execute-deep-agent/__tests__/approval-file-change.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import {
+  findAiMessageToolCallArgs,
+  captureApprovalArtifacts,
+} from "../approval-file-change.js";
+
+/** An AI message shaped like LangChain's, carrying tool calls with args. */
+function aiMessage(toolCalls: Array<{ id: string; name: string; args: unknown }>) {
+  return { _getType: () => "ai", tool_calls: toolCalls };
+}
+
+describe("findAiMessageToolCallArgs", () => {
+  it("returns the args of the tool call matching the id", () => {
+    const messages = [
+      { _getType: () => "human", content: "do it" },
+      aiMessage([
+        { id: "call-a", name: "write_file", args: { file_path: "a.txt", content: "A" } },
+        { id: "call-b", name: "edit_file", args: { file_path: "b.txt", old_string: "x", new_string: "y" } },
+      ]),
+    ];
+    expect(findAiMessageToolCallArgs(messages, "call-b")).toEqual({
+      file_path: "b.txt",
+      old_string: "x",
+      new_string: "y",
+    });
+  });
+
+  it("finds the call across multiple AI messages", () => {
+    const messages = [
+      aiMessage([{ id: "call-1", name: "write_file", args: { file_path: "1", content: "" } }]),
+      aiMessage([{ id: "call-2", name: "write_file", args: { file_path: "2", content: "" } }]),
+    ];
+    expect(findAiMessageToolCallArgs(messages, "call-2")).toEqual({ file_path: "2", content: "" });
+  });
+
+  it("ignores ToolMessages (singular tool_call_id, no tool_calls array)", () => {
+    const messages = [
+      { _getType: () => "tool", tool_call_id: "call-x", content: "result" },
+    ];
+    expect(findAiMessageToolCallArgs(messages, "call-x")).toBeUndefined();
+  });
+
+  it("returns undefined when no message emitted the id (sub-agent-nested miss)", () => {
+    const messages = [aiMessage([{ id: "other", name: "write_file", args: {} }])];
+    expect(findAiMessageToolCallArgs(messages, "call-missing")).toBeUndefined();
+  });
+
+  it("returns an empty object when the matched call carries no args", () => {
+    const messages = [aiMessage([{ id: "call-1", name: "write_file", args: undefined }])];
+    expect(findAiMessageToolCallArgs(messages, "call-1")).toEqual({});
+  });
+});
+
+describe("captureApprovalArtifacts", () => {
+  it("returns a sanitized args preview for a correlated tool call", () => {
+    const messages = [
+      aiMessage([
+        { id: "call-1", name: "write_file", args: { file_path: "a.txt", content: "hi", token: "sk-secret" } },
+      ]),
+    ];
+    const { argsPreview } = captureApprovalArtifacts({ toolCallId: "call-1", messages });
+
+    expect(argsPreview).toBeDefined();
+    expect(argsPreview).toContain("a.txt");
+    expect(argsPreview).toContain("[REDACTED]");
+    expect(argsPreview).not.toContain("sk-secret");
+  });
+
+  it("returns nothing when the interrupt cannot be correlated", () => {
+    const result = captureApprovalArtifacts({
+      toolCallId: "missing",
+      messages: [aiMessage([{ id: "other", name: "write_file", args: { file_path: "a", content: "" } }])],
+    });
+    expect(result).toEqual({});
+  });
+
+  it("returns a preview for a correlated non-file tool", () => {
+    const messages = [
+      aiMessage([{ id: "call-1", name: "search", args: { query: "needle" } }]),
+    ];
+    const { argsPreview } = captureApprovalArtifacts({ toolCallId: "call-1", messages });
+    expect(argsPreview).toContain("needle");
+  });
+});

package/src/activities/execute-deep-agent/__tests__/attachment-injector.test.ts

@@ -14,6 +14,7 @@ import {
   MAX_ZIP_EXTRACTED_SIZE,
 } from "../attachment-injector.js";
 import { mockWorkspaceBackend } from "../../../__test-utils__/mock-workspace.js";
+import { makeInMemoryArtifactStorage } from "../../../__test-utils__/fake-artifact-storage.js";
 
 // ── ZIP Construction Helpers ─────────────────────────────────────────
 
@@ -156,15 +157,11 @@ function makeAttachment(overrides: Partial<{
   } as any;
 }
 
-function makeMockStorage(downloadContent?: Buffer) {
-  const url = "https://storage.example.com/presigned/test";
-  return {
-    upload: vi.fn(),
-    getDownloadUrl: vi.fn().mockResolvedValue(url),
-    exists: vi.fn().mockResolvedValue(true),
-    _content: downloadContent,
-    _url: url,
-  };
+function makeMockStorage() {
+  // The canonical in-memory double; cloud downloads read from what was uploaded,
+  // so tests seed a blob via `storage.upload` and assert on `storage.download`.
+  const { storage } = makeInMemoryArtifactStorage();
+  return storage;
 }
 
 // ═══════════════════════════════════════════════════════════════════════
@@ -359,15 +356,8 @@ describe("injectAttachments", () => {
 
   it("injects single non-ZIP attachment in cloud mode", async () => {
     const content = Buffer.from("cloud data");
-    const storage = makeMockStorage(content);
-
-    const fetchMock = vi.fn().mockResolvedValue({
-      ok: true,
-      arrayBuffer: () => Promise.resolve(content.buffer.slice(
-        content.byteOffset, content.byteOffset + content.byteLength,
-      )),
-    });
-    vi.stubGlobal("fetch", fetchMock);
+    const storage = makeMockStorage();
+    await storage.upload("attachments/xyz/data.csv", content);
 
     const backend = mockWorkspaceBackend();
 
@@ -385,10 +375,7 @@ describe("injectAttachments", () => {
     expect(result[0].filename).toBe("data.csv");
     expect(result[0].path).toBe(".stigmer/inputs/data.csv");
     expect(result[0].sizeBytes).toBe(content.length);
-    expect(storage.getDownloadUrl).toHaveBeenCalledWith("attachments/xyz/data.csv");
-    expect(fetchMock).toHaveBeenCalledWith(storage._url);
-
-    vi.unstubAllGlobals();
+    expect(storage.download).toHaveBeenCalledWith("attachments/xyz/data.csv");
   });
 
   it("extracts ZIP when extract=true", async () => {
@@ -534,7 +521,7 @@ describe("injectAttachments", () => {
 
   it("propagates error when storage download fails", async () => {
     const storage = makeMockStorage();
-    storage.getDownloadUrl.mockRejectedValue(new Error("network timeout"));
+    storage.download.mockRejectedValue(new Error("network timeout"));
 
     const backend = mockWorkspaceBackend();
 
@@ -602,7 +589,7 @@ describe("injectAttachments", () => {
     })).rejects.toThrow(/collides with/);
 
     // Verify no downloads were attempted
-    expect(storage.getDownloadUrl).not.toHaveBeenCalled();
+    expect(storage.download).not.toHaveBeenCalled();
   });
 
   it("derives filename from storageKey when filename is empty", async () => {

package/src/activities/execute-deep-agent/__tests__/cas-capture-backend.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CasCaptureFilesystemBackend } from "../cas-capture-backend.js";
+import { CasCaptureObserver } from "../cas-capture-observer.js";
+
+/**
+ * The backend is a thin adapter: it forwards each mutation point to the shared
+ * {@link CasCaptureObserver} (which owns all capture state and logic) and then
+ * delegates to the base `FilesystemBackend` to apply the write to disk. These
+ * tests assert exactly that delegation contract — the write lands on disk AND the
+ * observer sees the pre-turn bytes. The recording semantics themselves (first
+ * touch, concurrency, memoization) are covered in cas-capture-observer.test.ts.
+ */
+describe("CasCaptureFilesystemBackend (thin CAS adapter)", () => {
+  let root: string;
+
+  const isIgnored = async (relPath: string): Promise<boolean> => relPath.startsWith("ignored/");
+
+  function makeBackend(): { backend: CasCaptureFilesystemBackend; observer: CasCaptureObserver } {
+    const observer = new CasCaptureObserver({ rootDir: root, isIgnored });
+    const backend = new CasCaptureFilesystemBackend({ rootDir: root }, { observer });
+    return { backend, observer };
+  }
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "cas-backend-"));
+    await mkdir(join(root, "ignored"), { recursive: true });
+    await mkdir(join(root, "src"), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("write applies to disk AND records before=null for a new gitignored file", async () => {
+    const { backend, observer } = makeBackend();
+
+    await backend.write("ignored/new.txt", "hello");
+
+    expect(await readFile(join(root, "ignored/new.txt"), "utf8")).toBe("hello");
+    expect(observer.before.get("ignored/new.txt")).toBeNull();
+  });
+
+  it("edit applies to disk AND records the pre-turn bytes for a gitignored file", async () => {
+    await writeFile(join(root, "ignored/cfg.txt"), "v0");
+    const { backend, observer } = makeBackend();
+
+    await backend.edit("ignored/cfg.txt", "v0", "v1");
+
+    expect(await readFile(join(root, "ignored/cfg.txt"), "utf8")).toBe("v1");
+    expect(Buffer.from(observer.before.get("ignored/cfg.txt")!).toString("utf8")).toBe("v0");
+  });
+
+  it("a git-tracked write applies to disk but is NOT observed (the git diff owns it)", async () => {
+    const { backend, observer } = makeBackend();
+
+    await backend.write("src/app.ts", "export const x = 1;");
+
+    expect(await readFile(join(root, "src/app.ts"), "utf8")).toBe("export const x = 1;");
+    expect(observer.before.size).toBe(0);
+  });
+});