@stigmer/runner 3.0.1

package/src/middleware/__tests__/graceful-stop.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, vi } from "vitest";
+import { ToolMessage } from "@langchain/core/messages";
+import { createGracefulStopMiddleware } from "../graceful-stop.js";
+import type { ToolCallRequest } from "../types.js";
+
+function makeRequest(name = "read"): ToolCallRequest {
+  return {
+    toolCall: { id: "tc_1", name, args: {} },
+    tool: undefined,
+    state: { messages: [] },
+    runtime: {},
+  };
+}
+
+describe("GracefulStopMiddleware", () => {
+  it("starts inert — passes through tool calls", async () => {
+    const mw = createGracefulStopMiddleware();
+    const msg = new ToolMessage({ content: "ok", tool_call_id: "tc_1", name: "read" });
+    const handler = vi.fn().mockResolvedValue(msg);
+
+    expect(mw.activated).toBe(false);
+    const result = await mw.wrapToolCall!(makeRequest(), handler);
+    expect(handler).toHaveBeenCalled();
+    expect(result).toBe(msg);
+  });
+
+  it("does not inject message when not activated", () => {
+    const mw = createGracefulStopMiddleware();
+    const result = mw.afterModel!({}, {});
+    expect(result).toBeUndefined();
+  });
+
+  it("blocks tool calls after activation", async () => {
+    const mw = createGracefulStopMiddleware();
+    mw.activate("user requested stop");
+
+    expect(mw.activated).toBe(true);
+
+    const handler = vi.fn();
+    const result = await mw.wrapToolCall!(makeRequest("execute"), handler);
+
+    expect(handler).not.toHaveBeenCalled();
+    expect(result).toBeInstanceOf(ToolMessage);
+    expect((result as ToolMessage).content).toContain("stopped by platform");
+  });
+
+  it("injects stop message once after activation", () => {
+    const mw = createGracefulStopMiddleware();
+    mw.activate();
+
+    const result1 = mw.afterModel!({}, {});
+    expect(result1).toBeDefined();
+    const messages = (result1 as { messages: unknown[] }).messages;
+    expect(messages).toHaveLength(1);
+
+    const result2 = mw.afterModel!({}, {});
+    expect(result2).toBeUndefined();
+  });
+
+  it("uses custom reason as stop message", () => {
+    const mw = createGracefulStopMiddleware();
+    mw.activate("Cost limit reached — wrap up");
+
+    const result = mw.afterModel!({}, {});
+    const messages = (result as { messages: Array<{ content: string }> }).messages;
+    expect(messages[0].content).toBe("Cost limit reached — wrap up");
+  });
+
+  it("ignores duplicate activate calls", () => {
+    const mw = createGracefulStopMiddleware();
+    mw.activate("first");
+    mw.activate("second");
+    expect(mw.activated).toBe(true);
+
+    const result = mw.afterModel!({}, {});
+    const messages = (result as { messages: Array<{ content: string }> }).messages;
+    expect(messages[0].content).toBe("first");
+  });
+
+  describe("forSubAgent", () => {
+    it("delegates afterModel to parent", () => {
+      const parent = createGracefulStopMiddleware();
+      const child = parent.forSubAgent();
+
+      parent.activate("stopping");
+
+      const result = child.afterModel!({}, {});
+      expect(result).toBeDefined();
+      const messages = (result as { messages: unknown[] }).messages;
+      expect(messages).toHaveLength(1);
+    });
+
+    it("delegates wrapToolCall to parent", async () => {
+      const parent = createGracefulStopMiddleware();
+      const child = parent.forSubAgent();
+
+      parent.activate();
+
+      const handler = vi.fn();
+      const result = await child.wrapToolCall!(makeRequest(), handler);
+      expect(handler).not.toHaveBeenCalled();
+      expect(result).toBeInstanceOf(ToolMessage);
+    });
+  });
+});

package/src/middleware/__tests__/loop-detection.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi } from "vitest";
+import { ToolMessage, AIMessage } from "@langchain/core/messages";
+import { createLoopDetectionMiddleware } from "../loop-detection.js";
+import type { ToolCallRequest } from "../types.js";
+
+function makeRequest(name = "read"): ToolCallRequest {
+  return {
+    toolCall: { id: "tc_1", name, args: {} },
+    tool: undefined,
+    state: { messages: [] },
+    runtime: {},
+  };
+}
+
+function stateWithToolCalls(calls: Array<{ name: string; args?: Record<string, unknown> }>): Record<string, unknown> {
+  const aiMsg = new AIMessage({
+    content: "",
+    tool_calls: calls.map((tc, i) => ({
+      id: `tc_${i}`,
+      name: tc.name,
+      args: tc.args ?? {},
+    })),
+  });
+  return { messages: [aiMsg] };
+}
+
+describe("LoopDetectionMiddleware", () => {
+  it("does nothing when no tool calls are present", () => {
+    const mw = createLoopDetectionMiddleware({ consecutiveThreshold: 2, totalThreshold: 3 });
+    const state = { messages: [new AIMessage({ content: "hello" })] };
+    const result = mw.afterModel!(state, {});
+    expect(result).toBeUndefined();
+  });
+
+  it("detects consecutive repetitions and injects warning", () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 3,
+      totalThreshold: 10,
+      historySize: 20,
+    });
+
+    const state = stateWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+
+    // Call afterModel 3 times with the same tool call
+    mw.afterModel!(state, {});
+    mw.afterModel!(state, {});
+    const result = mw.afterModel!(state, {});
+
+    expect(result).toBeDefined();
+    const messages = (result as { messages: unknown[] }).messages;
+    expect(messages).toHaveLength(1);
+    expect(String((messages[0] as { content: string }).content)).toContain("LOOP WARNING");
+  });
+
+  it("detects total threshold and stops", () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 100,
+      totalThreshold: 3,
+      historySize: 20,
+    });
+
+    const state = stateWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+
+    mw.afterModel!(state, {});
+    mw.afterModel!(state, {});
+    const result = mw.afterModel!(state, {});
+
+    expect(result).toBeDefined();
+    const messages = (result as { messages: unknown[] }).messages;
+    expect(String((messages[0] as { content: string }).content)).toContain("LOOP DETECTED");
+  });
+
+  it("blocks tool execution after total threshold is exceeded", async () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 100,
+      totalThreshold: 2,
+      historySize: 20,
+    });
+
+    const state = stateWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+    mw.afterModel!(state, {});
+    mw.afterModel!(state, {});
+
+    const handler = vi.fn().mockResolvedValue(new ToolMessage({ content: "ok", tool_call_id: "tc_1", name: "read" }));
+    const result = await mw.wrapToolCall!(makeRequest(), handler);
+
+    expect(handler).not.toHaveBeenCalled();
+    expect(result).toBeInstanceOf(ToolMessage);
+    expect((result as ToolMessage).content).toContain("Loop detected");
+  });
+
+  it("passes through tool calls when not stopped", async () => {
+    const mw = createLoopDetectionMiddleware();
+    const msg = new ToolMessage({ content: "result", tool_call_id: "tc_1", name: "read" });
+    const handler = vi.fn().mockResolvedValue(msg);
+
+    const result = await mw.wrapToolCall!(makeRequest(), handler);
+    expect(handler).toHaveBeenCalled();
+    expect(result).toBe(msg);
+  });
+
+  it("resets state on beforeAgent", () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 100,
+      totalThreshold: 2,
+    });
+
+    const state = stateWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+    mw.afterModel!(state, {});
+    mw.afterModel!(state, {});
+
+    mw.beforeAgent!({}, {});
+
+    // After reset, same calls should not trigger
+    mw.afterModel!(state, {});
+    const result = mw.afterModel!(state, {});
+    expect(result).toBeDefined();
+  });
+
+  it("tracks different tool signatures independently", () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 3,
+      totalThreshold: 10,
+    });
+
+    // Alternating tools should not trigger consecutive detection
+    const stateA = stateWithToolCalls([{ name: "read", args: { path: "/a" } }]);
+    const stateB = stateWithToolCalls([{ name: "write", args: { path: "/b" } }]);
+
+    mw.afterModel!(stateA, {});
+    mw.afterModel!(stateB, {});
+    mw.afterModel!(stateA, {});
+    const result = mw.afterModel!(stateB, {});
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/middleware/__tests__/otel-spans.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi } from "vitest";
+import { ToolMessage, AIMessage } from "@langchain/core/messages";
+import { createOtelSpansMiddleware } from "../otel-spans.js";
+import type { ToolCallRequest, ModelCallRequest } from "../types.js";
+
+function makeToolRequest(name = "mcp_tool"): ToolCallRequest {
+  return {
+    toolCall: { id: "tc_1", name, args: {} },
+    tool: undefined,
+    state: { messages: [] },
+    runtime: {},
+  };
+}
+
+function makeModelRequest(): ModelCallRequest {
+  return {
+    model: { model: "claude-sonnet-4-6" },
+    messages: [],
+    state: { messages: [] },
+    runtime: {},
+  };
+}
+
+describe("OtelSpansMiddleware", () => {
+  describe("wrapModelCall", () => {
+    it("passes through to handler and returns response", async () => {
+      const mw = createOtelSpansMiddleware();
+      const aiMsg = new AIMessage({ content: "hello" });
+      const handler = vi.fn().mockResolvedValue(aiMsg);
+
+      const result = await mw.wrapModelCall!(makeModelRequest(), handler);
+      expect(handler).toHaveBeenCalled();
+      expect(result).toBe(aiMsg);
+    });
+
+    it("propagates errors from handler", async () => {
+      const mw = createOtelSpansMiddleware();
+      const handler = vi.fn().mockRejectedValue(new Error("model failed"));
+
+      await expect(mw.wrapModelCall!(makeModelRequest(), handler))
+        .rejects.toThrow("model failed");
+    });
+  });
+
+  describe("wrapToolCall", () => {
+    it("passes through non-MCP tools without span", async () => {
+      const mw = createOtelSpansMiddleware({
+        toolServerMap: new Map([["other_tool", "server-a"]]),
+      });
+      const msg = new ToolMessage({ content: "ok", tool_call_id: "tc_1", name: "read" });
+      const handler = vi.fn().mockResolvedValue(msg);
+
+      const result = await mw.wrapToolCall!(makeToolRequest("read"), handler);
+      expect(handler).toHaveBeenCalled();
+      expect(result).toBe(msg);
+    });
+
+    it("wraps MCP tools that are in the server map", async () => {
+      const mw = createOtelSpansMiddleware({
+        toolServerMap: new Map([["mcp_tool", "my-server"]]),
+      });
+      const msg = new ToolMessage({ content: "ok", tool_call_id: "tc_1", name: "mcp_tool" });
+      const handler = vi.fn().mockResolvedValue(msg);
+
+      const result = await mw.wrapToolCall!(makeToolRequest("mcp_tool"), handler);
+      expect(handler).toHaveBeenCalled();
+      expect(result).toBe(msg);
+    });
+
+    it("propagates errors from MCP tool handler", async () => {
+      const mw = createOtelSpansMiddleware({
+        toolServerMap: new Map([["mcp_tool", "my-server"]]),
+      });
+      const handler = vi.fn().mockRejectedValue(new Error("tool failed"));
+
+      await expect(mw.wrapToolCall!(makeToolRequest("mcp_tool"), handler))
+        .rejects.toThrow("tool failed");
+    });
+  });
+
+  it("works with empty toolServerMap", async () => {
+    const mw = createOtelSpansMiddleware();
+    const msg = new ToolMessage({ content: "ok", tool_call_id: "tc_1", name: "read" });
+    const handler = vi.fn().mockResolvedValue(msg);
+
+    const result = await mw.wrapToolCall!(makeToolRequest("read"), handler);
+    expect(result).toBe(msg);
+  });
+});

package/src/middleware/__tests__/think-tool.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { createThinkTool } from "../think-tool.js";
+
+describe("createThinkTool", () => {
+  it("returns a tool named 'think'", () => {
+    const thinkTool = createThinkTool();
+    expect(thinkTool.name).toBe("think");
+  });
+
+  it("has a description explaining its purpose", () => {
+    const thinkTool = createThinkTool();
+    expect(thinkTool.description).toContain("think through a problem");
+  });
+
+  it("returns 'ok' for any thought input", async () => {
+    const thinkTool = createThinkTool();
+    const result = await thinkTool.invoke({ thought: "Let me consider the options..." });
+    expect(result).toBe("ok");
+  });
+
+  it("accepts an empty thought string", async () => {
+    const thinkTool = createThinkTool();
+    const result = await thinkTool.invoke({ thought: "" });
+    expect(result).toBe("ok");
+  });
+});

package/src/middleware/__tests__/tool-truncation.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, vi } from "vitest";
+import { ToolMessage } from "@langchain/core/messages";
+import { createToolTruncationMiddleware } from "../tool-truncation.js";
+import type { ToolCallRequest } from "../types.js";
+
+function makeRequest(name = "read"): ToolCallRequest {
+  return {
+    toolCall: { id: "tc_1", name, args: {} },
+    tool: undefined,
+    state: { messages: [] },
+    runtime: {},
+  };
+}
+
+function makeToolMessage(content: string, id = "tc_1", name = "read"): ToolMessage {
+  return new ToolMessage({ content, tool_call_id: id, name });
+}
+
+describe("ToolTruncationMiddleware", () => {
+  it("passes through results under the limit", async () => {
+    const mw = createToolTruncationMiddleware({ maxChars: 100 });
+    const handler = vi.fn().mockResolvedValue(makeToolMessage("short"));
+    const result = await mw.wrapToolCall!(makeRequest(), handler);
+    expect(result).toBeInstanceOf(ToolMessage);
+    expect((result as ToolMessage).content).toBe("short");
+    expect(mw.truncationCount).toBe(0);
+  });
+
+  it("truncates results exceeding the limit", async () => {
+    const mw = createToolTruncationMiddleware({ maxChars: 10 });
+    const longContent = "a".repeat(50);
+    const handler = vi.fn().mockResolvedValue(makeToolMessage(longContent));
+
+    const result = await mw.wrapToolCall!(makeRequest(), handler);
+    const content = (result as ToolMessage).content as string;
+
+    expect(content.startsWith("a".repeat(10))).toBe(true);
+    expect(content).toContain("[truncated");
+    expect(content).toContain("50 chars");
+    expect(mw.truncationCount).toBe(1);
+    expect(mw.totalCharsTruncated).toBe(40);
+  });
+
+  it("preserves tool_call_id and name on truncated messages", async () => {
+    const mw = createToolTruncationMiddleware({ maxChars: 5 });
+    const handler = vi.fn().mockResolvedValue(
+      makeToolMessage("a".repeat(100), "tc_42", "execute"),
+    );
+
+    const result = await mw.wrapToolCall!(makeRequest("execute"), handler) as ToolMessage;
+    expect(result.tool_call_id).toBe("tc_1");
+    expect(result.name).toBe("execute");
+  });
+
+  it("skips non-string content", async () => {
+    const mw = createToolTruncationMiddleware({ maxChars: 5 });
+    const msg = new ToolMessage({
+      content: [{ type: "text", text: "a".repeat(100) }],
+      tool_call_id: "tc_1",
+      name: "read",
+    });
+    const handler = vi.fn().mockResolvedValue(msg);
+    const result = await mw.wrapToolCall!(makeRequest(), handler);
+    expect(result).toBe(msg);
+    expect(mw.truncationCount).toBe(0);
+  });
+
+  it("skips results at exactly the limit", async () => {
+    const mw = createToolTruncationMiddleware({ maxChars: 20 });
+    const handler = vi.fn().mockResolvedValue(makeToolMessage("a".repeat(20)));
+    const result = await mw.wrapToolCall!(makeRequest(), handler);
+    expect((result as ToolMessage).content).toBe("a".repeat(20));
+    expect(mw.truncationCount).toBe(0);
+  });
+
+  it("calls onTruncation callback", async () => {
+    const onTruncation = vi.fn();
+    const mw = createToolTruncationMiddleware({ maxChars: 10, onTruncation });
+    const handler = vi.fn().mockResolvedValue(makeToolMessage("a".repeat(50)));
+
+    await mw.wrapToolCall!(makeRequest("glob"), handler);
+    expect(onTruncation).toHaveBeenCalledWith("glob", 40);
+  });
+
+  it("resets counters on beforeAgent", async () => {
+    const mw = createToolTruncationMiddleware({ maxChars: 10 });
+    const handler = vi.fn().mockResolvedValue(makeToolMessage("a".repeat(50)));
+
+    await mw.wrapToolCall!(makeRequest(), handler);
+    expect(mw.truncationCount).toBe(1);
+
+    mw.beforeAgent!({} as any, {});
+    expect(mw.truncationCount).toBe(0);
+    expect(mw.totalCharsTruncated).toBe(0);
+  });
+
+  it("accumulates across multiple truncations", async () => {
+    const mw = createToolTruncationMiddleware({ maxChars: 10 });
+    const handler = vi.fn().mockResolvedValue(makeToolMessage("a".repeat(30)));
+
+    await mw.wrapToolCall!(makeRequest(), handler);
+    await mw.wrapToolCall!(makeRequest(), handler);
+
+    expect(mw.truncationCount).toBe(2);
+    expect(mw.totalCharsTruncated).toBe(40);
+  });
+
+  it("rejects non-positive maxChars", () => {
+    expect(() => createToolTruncationMiddleware({ maxChars: 0 })).toThrow("maxChars must be positive");
+    expect(() => createToolTruncationMiddleware({ maxChars: -5 })).toThrow("maxChars must be positive");
+  });
+});

package/src/middleware/approval-gate.ts

@@ -0,0 +1,179 @@
+/**
+ * Approval gate middleware for HITL (human-in-the-loop) tool approval.
+ *
+ * Checks each tool call against the merged approval policy. When a tool
+ * requires approval, calls LangGraph `interrupt()` to pause the graph
+ * at the checkpoint. The Temporal workflow then waits for the user's
+ * decision via the `approvalGateResolved` signal.
+ *
+ * On resume, LangGraph restarts the node from the beginning. The
+ * `interrupt()` call returns the user's decision (approve/skip/reject)
+ * from the `Command(resume=...)` payload.
+ *
+ * Idempotency: Because the node restarts on resume, this middleware
+ * will be invoked again for the same tool call. The `interrupt()` call
+ * is idempotent — on resume it returns the decision value instead of
+ * pausing again.
+ *
+ * Platform tool defaults: DeepAgents JS backend tools (read, write,
+ * edit, execute, etc.) are not covered by MCP policy chains. This
+ * middleware applies sensible defaults: read-only tools are auto-approved,
+ * mutating tools require approval when no explicit policy exists.
+ */
+
+import { ToolMessage } from "@langchain/core/messages";
+import { interrupt } from "@langchain/langgraph";
+import type { StigmerMiddleware, ToolCallRequest } from "./types.js";
+import {
+  type MergedToolPolicy,
+  resolveApprovalMessage,
+} from "../shared/approval-policy.js";
+
+export interface ApprovalGateConfig {
+  readonly policies: ReadonlyMap<string, MergedToolPolicy>;
+  readonly autoApproveAll: boolean;
+  readonly toolServerMap: ReadonlyMap<string, string>;
+}
+
+interface ApprovalDecision {
+  readonly action: string;
+  readonly comment?: string;
+}
+
+const SAFE_PLATFORM_TOOLS = new Set([
+  "read", "read_file",
+  "ls", "list_directory",
+  "glob", "find_files",
+  "grep", "search", "ripgrep",
+  "think",
+]);
+
+const DANGEROUS_PLATFORM_TOOLS = new Map<string, string>([
+  ["write", "Write file: {{args.path}}"],
+  ["write_file", "Write file: {{args.path}}"],
+  ["edit", "Edit file: {{args.path}}"],
+  ["edit_file", "Edit file: {{args.path}}"],
+  ["create", "Create file: {{args.path}}"],
+  ["create_file", "Create file: {{args.path}}"],
+  ["delete", "Delete: {{args.path}}"],
+  ["delete_file", "Delete file: {{args.path}}"],
+  ["execute", "Execute command: {{args.command}}"],
+  ["shell", "Execute shell command: {{args.command}}"],
+  ["str_replace_editor", "Edit file: {{args.path}}"],
+]);
+
+export function createApprovalGateMiddleware(
+  config: ApprovalGateConfig,
+): StigmerMiddleware {
+  const { policies, autoApproveAll, toolServerMap } = config;
+
+  if (autoApproveAll) {
+    return { name: "ApprovalGateMiddleware" };
+  }
+
+  return {
+    name: "ApprovalGateMiddleware",
+
+    async wrapToolCall(request: ToolCallRequest, handler) {
+      const { toolCall } = request;
+      const toolName = toolCall.name;
+      const serverSlug = toolServerMap.get(toolName) ?? "";
+
+      const requirement = resolveToolApproval(
+        toolName,
+        serverSlug,
+        toolCall.args,
+        policies,
+      );
+
+      if (!requirement.requiresApproval) {
+        return await handler(request);
+      }
+
+      const approvalRequest = {
+        tool_call_id: toolCall.id,
+        tool_name: toolName,
+        mcp_server_slug: serverSlug,
+        message: requirement.message,
+      };
+
+      const response = interrupt(approvalRequest) as ApprovalDecision;
+
+      const action = (
+        typeof response === "object" && response !== null
+          ? (response.action ?? "")
+          : ""
+      ).toString().toLowerCase();
+
+      if (action === "approve") {
+        return await handler(request);
+      }
+
+      if (action === "skip") {
+        const comment = response.comment ?? "";
+        const skipMessage = comment
+          ? `Tool '${toolName}' was skipped by user: ${comment}. Please proceed without this operation.`
+          : `Tool '${toolName}' was skipped by user. Please proceed without this operation.`;
+
+        return new ToolMessage({
+          content: skipMessage,
+          tool_call_id: toolCall.id,
+          name: toolName,
+        });
+      }
+
+      if (action === "reject") {
+        const comment = response.comment ?? "rejected by user";
+        return new ToolMessage({
+          content: `Tool '${toolName}' was rejected: ${comment}. Execution will be terminated.`,
+          tool_call_id: toolCall.id,
+          name: toolName,
+        });
+      }
+
+      return new ToolMessage({
+        content: `Tool '${toolName}' approval returned unknown action: '${action}'. Treating as skip.`,
+        tool_call_id: toolCall.id,
+        name: toolName,
+      });
+    },
+  };
+}
+
+interface ApprovalRequirement {
+  readonly requiresApproval: boolean;
+  readonly message: string;
+}
+
+function resolveToolApproval(
+  toolName: string,
+  serverSlug: string,
+  args: Record<string, unknown>,
+  policies: ReadonlyMap<string, MergedToolPolicy>,
+): ApprovalRequirement {
+  if (serverSlug) {
+    const key = `${serverSlug}/${toolName}`;
+    const policy = policies.get(key);
+    if (policy) {
+      return {
+        requiresApproval: policy.requiresApproval,
+        message: resolveApprovalMessage(policy.approvalMessage, toolName, args),
+      };
+    }
+    return { requiresApproval: false, message: "" };
+  }
+
+  if (SAFE_PLATFORM_TOOLS.has(toolName)) {
+    return { requiresApproval: false, message: "" };
+  }
+
+  const dangerousTemplate = DANGEROUS_PLATFORM_TOOLS.get(toolName);
+  if (dangerousTemplate) {
+    return {
+      requiresApproval: true,
+      message: resolveApprovalMessage(dangerousTemplate, toolName, args),
+    };
+  }
+
+  return { requiresApproval: false, message: "" };
+}