@stigmer/runner 3.0.1

package/src/activities/execute-deep-agent/__tests__/subagent-wiring.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { buildSubAgentMiddleware } from "../subagent-wiring.js";
+import { createCostCapMiddleware } from "../../../middleware/cost-cap.js";
+
+describe("buildSubAgentMiddleware", () => {
+  it("returns the correct middleware order without cost cap", () => {
+    const stack = buildSubAgentMiddleware();
+
+    expect(stack).toHaveLength(3);
+    expect(stack[0].name).toBe("LoopDetectionMiddleware");
+    expect(stack[1].name).toBe("ExecutionBudgetMiddleware");
+    expect(stack[2].name).toBe("ToolTruncationMiddleware");
+  });
+
+  it("includes cost cap view when parent cost cap is provided", () => {
+    const parentCostCap = createCostCapMiddleware({
+      maxCostUsd: 10,
+      inputPricePerMillion: 3,
+      outputPricePerMillion: 15,
+      cacheReadPricePerMillion: 0.3,
+      warningPct: 80,
+    });
+
+    const stack = buildSubAgentMiddleware({ costCap: parentCostCap });
+
+    expect(stack).toHaveLength(4);
+    expect(stack[3].name).toBe("CostCapSubAgentView");
+  });
+
+  it("sub-agent cost cap view shares parent state", () => {
+    const parentCostCap = createCostCapMiddleware({
+      maxCostUsd: 1,
+      inputPricePerMillion: 3,
+      outputPricePerMillion: 15,
+      cacheReadPricePerMillion: 0.3,
+      warningPct: 80,
+    });
+
+    const stack = buildSubAgentMiddleware({ costCap: parentCostCap });
+
+    expect(parentCostCap.runningCost).toBe(0);
+
+    const subView = stack[3];
+    expect(subView.afterModel).toBeDefined();
+    expect(subView.wrapToolCall).toBeDefined();
+    expect(subView.beforeAgent).toBeUndefined();
+  });
+
+  it("execution budget uses periodic mode (interval=30, max=4)", () => {
+    const stack = buildSubAgentMiddleware();
+    const budgetMiddleware = stack[1];
+
+    expect(budgetMiddleware.name).toBe("ExecutionBudgetMiddleware");
+    expect(budgetMiddleware.wrapModelCall).toBeDefined();
+  });
+
+  it("loop detection is independent per sub-agent call", () => {
+    const stack1 = buildSubAgentMiddleware();
+    const stack2 = buildSubAgentMiddleware();
+
+    expect(stack1[0]).not.toBe(stack2[0]);
+  });
+
+  it("accepts custom tool truncation config", () => {
+    const stack = buildSubAgentMiddleware({
+      toolTruncation: { maxChars: 5000 },
+    });
+
+    expect(stack[2].name).toBe("ToolTruncationMiddleware");
+  });
+});

package/src/activities/execute-deep-agent/__tests__/summarization-verification.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Summarization middleware verification tests.
+ *
+ * Verifies that the DeepAgents JS built-in SummarizationMiddleware
+ * integrates correctly with the Stigmer runner infrastructure:
+ *
+ * 1. Default thresholds are model-profile-aware and reasonable
+ * 2. Summarization state survives checkpoint serialization roundtrips
+ * 3. Middleware ordering places summarization before Stigmer custom middleware
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  computeSummarizationDefaults,
+  createSummarizationMiddleware,
+  createDeepAgent,
+  StateBackend,
+} from "deepagents";
+import { HumanMessage } from "@langchain/core/messages";
+import { HttpCheckpointSaver } from "../../../shared/checkpointer/http-saver.js";
+
+// ── 1. Default Threshold Verification ───────────────────────────────
+
+describe("computeSummarizationDefaults", () => {
+  it("returns fraction-based defaults when model has maxInputTokens profile", () => {
+    const mockModel = {
+      profile: { maxInputTokens: 200_000 },
+    } as any;
+
+    const defaults = computeSummarizationDefaults(mockModel);
+
+    expect(defaults.trigger).toEqual({ type: "fraction", value: 0.85 });
+    expect(defaults.keep).toEqual({ type: "fraction", value: 0.1 });
+    expect(defaults.truncateArgsSettings.trigger).toEqual({
+      type: "fraction",
+      value: 0.85,
+    });
+    expect(defaults.truncateArgsSettings.keep).toEqual({
+      type: "fraction",
+      value: 0.1,
+    });
+  });
+
+  it("returns token/message-based fallbacks when model has no profile", () => {
+    const mockModel = {} as any;
+
+    const defaults = computeSummarizationDefaults(mockModel);
+
+    expect(defaults.trigger).toEqual({ type: "tokens", value: 170_000 });
+    expect(defaults.keep).toEqual({ type: "messages", value: 6 });
+    expect(defaults.truncateArgsSettings.trigger).toEqual({
+      type: "messages",
+      value: 20,
+    });
+    expect(defaults.truncateArgsSettings.keep).toEqual({
+      type: "messages",
+      value: 20,
+    });
+  });
+
+  it("returns token/message-based fallbacks when profile lacks maxInputTokens", () => {
+    const mockModel = {
+      profile: { someOtherField: 42 },
+    } as any;
+
+    const defaults = computeSummarizationDefaults(mockModel);
+
+    expect(defaults.trigger.type).toBe("tokens");
+    expect(defaults.keep.type).toBe("messages");
+  });
+
+  it("produces reasonable thresholds for Claude Sonnet 4 (200K context)", () => {
+    const sonnet4Profile = { profile: { maxInputTokens: 200_000 } } as any;
+    const defaults = computeSummarizationDefaults(sonnet4Profile);
+
+    // Trigger at 85% of 200K = 170K tokens
+    expect(defaults.trigger.type).toBe("fraction");
+    expect(defaults.trigger.value).toBe(0.85);
+    const effectiveTrigger = Math.floor(200_000 * defaults.trigger.value);
+    expect(effectiveTrigger).toBe(170_000);
+
+    // Keep 10% of 200K = 20K tokens worth of recent messages
+    expect(defaults.keep.type).toBe("fraction");
+    expect(defaults.keep.value).toBe(0.1);
+    const effectiveKeep = Math.floor(200_000 * defaults.keep.value);
+    expect(effectiveKeep).toBe(20_000);
+  });
+
+  it("produces reasonable thresholds for Claude Opus 4 (200K context)", () => {
+    const opus4Profile = { profile: { maxInputTokens: 200_000 } } as any;
+    const defaults = computeSummarizationDefaults(opus4Profile);
+
+    // Same profile shape → same defaults
+    expect(defaults.trigger).toEqual({ type: "fraction", value: 0.85 });
+    expect(defaults.keep).toEqual({ type: "fraction", value: 0.1 });
+  });
+
+  it("adapts to smaller context windows", () => {
+    const smallModel = { profile: { maxInputTokens: 32_000 } } as any;
+    const defaults = computeSummarizationDefaults(smallModel);
+
+    // Still fraction-based (profile present)
+    expect(defaults.trigger.type).toBe("fraction");
+    const effectiveTrigger = Math.floor(32_000 * defaults.trigger.value);
+    expect(effectiveTrigger).toBe(27_200);
+
+    const effectiveKeep = Math.floor(32_000 * defaults.keep.value);
+    expect(effectiveKeep).toBe(3_200);
+  });
+});
+
+// ── 2. Checkpoint Serialization Roundtrip ───────────────────────────
+
+describe("summarization state checkpoint serialization", () => {
+  const saver = new HttpCheckpointSaver("https://proxy.test", "test-token");
+
+  it("serializes and deserializes _summarizationEvent through JsonPlusSerializer", async () => {
+    const summarizationEvent = {
+      cutoffIndex: 15,
+      summaryMessage: new HumanMessage({
+        content: "Summary of prior conversation: The user asked about deployment.",
+        additional_kwargs: { lc_source: "summarization" },
+      }),
+      filePath: "/conversation_history/session_abc12345.md",
+    };
+
+    const [typeTag, payload] = await saver.serde.dumpsTyped(summarizationEvent);
+    expect(typeTag).toBeDefined();
+    expect(payload).toBeInstanceOf(Uint8Array);
+    expect(payload.length).toBeGreaterThan(0);
+
+    const restored = await saver.serde.loadsTyped(typeTag, payload) as typeof summarizationEvent;
+
+    expect(restored.cutoffIndex).toBe(15);
+    expect(restored.filePath).toBe("/conversation_history/session_abc12345.md");
+    expect(restored.summaryMessage).toBeDefined();
+    expect(restored.summaryMessage.content).toContain(
+      "Summary of prior conversation",
+    );
+  });
+
+  it("serializes _summarizationSessionId as a plain string", async () => {
+    const sessionId = "session_abc12345";
+
+    const [typeTag, payload] = await saver.serde.dumpsTyped(sessionId);
+    const restored = await saver.serde.loadsTyped(typeTag, payload);
+
+    expect(restored).toBe(sessionId);
+  });
+
+  it("roundtrips a full checkpoint-shaped channel_values containing summarization state", async () => {
+    const channelValues = {
+      messages: [
+        new HumanMessage({
+          content: "Summary: user discussed deployment configs.",
+          additional_kwargs: { lc_source: "summarization" },
+        }),
+        new HumanMessage({ content: "Now let's configure the database." }),
+      ],
+      _summarizationEvent: {
+        cutoffIndex: 8,
+        summaryMessage: new HumanMessage({
+          content: "Summary: user discussed deployment configs.",
+          additional_kwargs: { lc_source: "summarization" },
+        }),
+        filePath: "/conversation_history/session_def67890.md",
+      },
+      _summarizationSessionId: "session_def67890",
+    };
+
+    const [typeTag, payload] = await saver.serde.dumpsTyped(channelValues);
+    const restored = await saver.serde.loadsTyped(typeTag, payload) as typeof channelValues;
+
+    expect(restored._summarizationSessionId).toBe("session_def67890");
+    expect(restored._summarizationEvent.cutoffIndex).toBe(8);
+    expect(restored._summarizationEvent.filePath).toBe(
+      "/conversation_history/session_def67890.md",
+    );
+    expect(restored.messages).toHaveLength(2);
+  });
+
+  it("handles null filePath in _summarizationEvent (backend offload failure)", async () => {
+    const event = {
+      cutoffIndex: 5,
+      summaryMessage: new HumanMessage({ content: "Summary of conversation." }),
+      filePath: null,
+    };
+
+    const [typeTag, payload] = await saver.serde.dumpsTyped(event);
+    const restored = await saver.serde.loadsTyped(typeTag, payload) as typeof event;
+
+    expect(restored.filePath).toBeNull();
+    expect(restored.cutoffIndex).toBe(5);
+  });
+});
+
+// ── 3. Middleware Stack Ordering ─────────────────────────────────────
+
+describe("middleware stack ordering in createDeepAgent", () => {
+  it("includes SummarizationMiddleware in the default stack", () => {
+    const agent = createDeepAgent({
+      model: "anthropic:claude-sonnet-4-6",
+      backend: new StateBackend(),
+      tools: [],
+    });
+
+    // The compiled graph's middleware is not directly exposed, but we
+    // can verify the agent was created successfully with the built-in
+    // summarization by checking it's a valid agent.
+    expect(agent).toBeDefined();
+    expect(typeof agent.streamEvents).toBe("function");
+    expect(typeof agent.invoke).toBe("function");
+  });
+
+  it("does not throw when Stigmer custom middleware is appended alongside defaults", () => {
+    const stigmerMiddleware = {
+      name: "StigmerCostCap",
+      wrapModelCall: async (request: any, handler: any) => handler(request),
+    };
+
+    const agent = createDeepAgent({
+      model: "anthropic:claude-sonnet-4-6",
+      backend: new StateBackend(),
+      tools: [],
+      middleware: [stigmerMiddleware] as any,
+    });
+
+    expect(agent).toBeDefined();
+  });
+
+  it("places SummarizationMiddleware before custom middleware", () => {
+    /**
+     * Verified by reading createDeepAgent source (index.js lines 8165-8173):
+     *
+     *   const middleware = [
+     *     todoMiddleware,
+     *     ...skillsMiddleware,
+     *     fsMiddleware,
+     *     subagentMiddleware,
+     *     summarizationMiddleware,   // <-- position 4 (0-indexed)
+     *     patchToolCallsMiddleware,
+     *     ...asyncSubAgents,
+     *     ...customMiddleware,       // <-- Stigmer's stack goes here
+     *     ...cacheMiddleware,
+     *     ...memory,
+     *     ...interruptOn,
+     *   ];
+     *
+     * This means summarization's wrapModelCall runs before Stigmer's
+     * cost-cap wrapModelCall, so:
+     * - Summarization modifies messages first (compresses history)
+     * - Cost-cap then sees only the reduced message set
+     * - This is correct: cost-cap should count tokens that actually
+     *   get sent to the model, not the full unsummarized history.
+     */
+
+    let middlewareNames: string[] = [];
+
+    const recordingMiddleware = {
+      name: "StigmerRecorder",
+      wrapModelCall: async (request: any, handler: any) => {
+        const state = request.state ?? {};
+        const existingNames = (state._middlewareOrder as string[] | undefined) ?? [];
+        middlewareNames = [...existingNames, "StigmerRecorder"];
+        return handler(request);
+      },
+    };
+
+    // Construction succeeds with custom middleware after defaults
+    const agent = createDeepAgent({
+      model: "anthropic:claude-sonnet-4-6",
+      backend: new StateBackend(),
+      tools: [],
+      middleware: [recordingMiddleware] as any,
+    });
+
+    expect(agent).toBeDefined();
+  });
+
+  it("creates SummarizationMiddleware with the same backend passed to createDeepAgent", () => {
+    /**
+     * Verified from source (index.js line 8162):
+     *   createSummarizationMiddleware({ backend })
+     *
+     * The `backend` variable is the same one received in createDeepAgent params.
+     * This means summarization uses the same StateBackend instance, so
+     * offloaded conversation history is stored in LangGraph state which
+     * the HttpCheckpointSaver persists to MongoDB via the proxy.
+     */
+    const backend = new StateBackend();
+
+    const agent = createDeepAgent({
+      model: "anthropic:claude-sonnet-4-6",
+      backend,
+      tools: [],
+    });
+
+    expect(agent).toBeDefined();
+  });
+
+  it("resolves summarization model from the agent model (no explicit model option)", () => {
+    /**
+     * Verified from source (index.js lines 4067, 8114):
+     *
+     *   createSummarizationMiddleware({ backend })
+     *   // No `model` option passed
+     *
+     *   // Inside wrapModelCall:
+     *   const resolvedModel = request.model ?? await getChatModel();
+     *
+     * Since no model option is provided, the middleware uses request.model
+     * which is the same ChatAnthropic instance from setup.ts with the
+     * proxy baseURL. All summarization LLM calls route through the proxy.
+     */
+
+    const summarizationMw = createSummarizationMiddleware({
+      backend: new StateBackend(),
+    });
+
+    expect(summarizationMw).toBeDefined();
+    expect(summarizationMw.name).toBe("SummarizationMiddleware");
+  });
+});

package/src/activities/execute-deep-agent/__tests__/v3-event-recorder.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { createV3EventRecorder, type V3ProtocolEvent } from "../v3-event-recorder.js";
+
+function makeProtocolEvent(
+  seq: number,
+  method: string,
+  data: unknown = {},
+  opts?: { namespace?: string[]; node?: string },
+): V3ProtocolEvent {
+  return {
+    type: "event",
+    seq,
+    method,
+    params: {
+      namespace: opts?.namespace ?? [],
+      timestamp: 1716700000000 + seq * 100,
+      node: opts?.node,
+      data,
+    },
+  };
+}
+
+describe("createV3EventRecorder", () => {
+  it("returns undefined when recordDir is undefined", () => {
+    expect(createV3EventRecorder("exec-1", undefined)).toBeUndefined();
+  });
+
+  it("returns undefined when recordDir is empty string", () => {
+    expect(createV3EventRecorder("exec-1", "")).toBeUndefined();
+  });
+
+  it("returns a recorder when recordDir is provided", () => {
+    const recorder = createV3EventRecorder("exec-1", "/tmp/test");
+    expect(recorder).toBeDefined();
+    expect(recorder!.record).toBeInstanceOf(Function);
+    expect(recorder!.flush).toBeInstanceOf(Function);
+  });
+});
+
+describe("V3EventRecorder", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = await mkdtemp(join(tmpdir(), "v3-recorder-test-"));
+  });
+
+  it("flush is a no-op when no events are recorded", async () => {
+    const recorder = createV3EventRecorder("exec-empty", testDir)!;
+    await recorder.flush();
+
+    const { readdir } = await import("node:fs/promises");
+    const files = await readdir(testDir);
+    expect(files).toHaveLength(0);
+  });
+
+  it("writes events to a JSON file named by execution ID", async () => {
+    const recorder = createV3EventRecorder("exec-abc", testDir)!;
+
+    recorder.record(
+      makeProtocolEvent(0, "messages", { event: "message-start", data: { role: "assistant" } }),
+      0,
+    );
+    recorder.record(
+      makeProtocolEvent(1, "messages", { event: "message-finish", data: { usage: { input: 10 } } }),
+      1,
+    );
+
+    await recorder.flush();
+
+    const filePath = join(testDir, "exec-abc.v3-events.json");
+    const content = JSON.parse(await readFile(filePath, "utf-8"));
+
+    expect(content.executionId).toBe("exec-abc");
+    expect(content.eventCount).toBe(2);
+    expect(content.recordedAt).toBeTruthy();
+    expect(content.events).toHaveLength(2);
+
+    expect(content.events[0].seq).toBe(0);
+    expect(content.events[0].method).toBe("messages");
+    expect(content.events[0].type).toBe("event");
+    expect(content.events[0].namespace).toEqual([]);
+    expect(content.events[0].timestamp).toBe(1716700000000);
+    expect(content.events[0].data.event).toBe("message-start");
+    expect(content.events[0].capturedAt).toBeTruthy();
+
+    expect(content.events[1].seq).toBe(1);
+    expect(content.events[1].method).toBe("messages");
+    expect(content.events[1].timestamp).toBe(1716700000100);
+  });
+
+  it("preserves namespace and node fields", async () => {
+    const recorder = createV3EventRecorder("exec-ns", testDir)!;
+
+    recorder.record(
+      makeProtocolEvent(0, "tools", { type: "tool-started" }, {
+        namespace: ["tools:task-1", "agent_node:inner"],
+        node: "model_request",
+      }),
+      0,
+    );
+
+    await recorder.flush();
+
+    const content = JSON.parse(
+      await readFile(join(testDir, "exec-ns.v3-events.json"), "utf-8"),
+    );
+
+    expect(content.events[0].namespace).toEqual(["tools:task-1", "agent_node:inner"]);
+    expect(content.events[0].node).toBe("model_request");
+  });
+
+  it("handles circular references in event data gracefully", async () => {
+    const recorder = createV3EventRecorder("exec-circular", testDir)!;
+
+    const circular: Record<string, unknown> = { a: 1 };
+    circular.self = circular;
+
+    recorder.record(
+      makeProtocolEvent(0, "custom", circular),
+      0,
+    );
+
+    await recorder.flush();
+
+    const content = JSON.parse(
+      await readFile(join(testDir, "exec-circular.v3-events.json"), "utf-8"),
+    );
+
+    expect(content.events[0].data._serializationError).toBe(true);
+    expect(content.events[0].data.keys).toContain("a");
+  });
+
+  it("handles bigint values in event data", async () => {
+    const recorder = createV3EventRecorder("exec-bigint", testDir)!;
+
+    recorder.record(
+      makeProtocolEvent(0, "messages", { tokens: BigInt(12345) }),
+      0,
+    );
+
+    await recorder.flush();
+
+    const content = JSON.parse(
+      await readFile(join(testDir, "exec-bigint.v3-events.json"), "utf-8"),
+    );
+
+    expect(content.events[0].data.tokens).toBe("12345");
+  });
+
+  it("creates output directory if it does not exist", async () => {
+    const nestedDir = join(testDir, "nested", "deep", "dir");
+    const recorder = createV3EventRecorder("exec-mkdir", nestedDir)!;
+
+    recorder.record(makeProtocolEvent(0, "lifecycle", { event: "started" }), 0);
+    await recorder.flush();
+
+    const content = JSON.parse(
+      await readFile(join(nestedDir, "exec-mkdir.v3-events.json"), "utf-8"),
+    );
+    expect(content.eventCount).toBe(1);
+  });
+
+  it("records all protocol channel methods", async () => {
+    const recorder = createV3EventRecorder("exec-channels", testDir)!;
+
+    const channels = ["messages", "tools", "lifecycle", "updates", "values", "input", "custom"];
+    for (let i = 0; i < channels.length; i++) {
+      recorder.record(makeProtocolEvent(i, channels[i], { channel: channels[i] }), i);
+    }
+
+    await recorder.flush();
+
+    const content = JSON.parse(
+      await readFile(join(testDir, "exec-channels.v3-events.json"), "utf-8"),
+    );
+
+    expect(content.eventCount).toBe(7);
+    const methods = content.events.map((e: { method: string }) => e.method);
+    expect(methods).toEqual(channels);
+  });
+});
+