@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

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

@@ -0,0 +1,194 @@
+/**
+ * Loop detection: tracks each model response's tool calls by signature (name
+ * plus a hash of the arguments), warns once at the consecutive threshold,
+ * and at the total threshold intervenes finally and halts every later tool
+ * call with a halt notice.
+ *
+ * How an intervention travels (stigmer/stigmer#1354): it is decided as the
+ * model answers and delivered on the NEXT model call, as a user-role advisory
+ * after that request's last message. It rides that one call, and no hook
+ * writes the graph's state; until #1354 it was a SystemMessage saved between
+ * the model's tool calls and their results, which Anthropic refuses. The
+ * request through the real Anthropic conversion is
+ * `shared/__tests__/advisory-anthropic-payload.test.ts`.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { ToolMessage, AIMessage, HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { createLoopDetectionMiddleware } from "../loop-detection.js";
+import { ADVISORY_LEAD_IN } from "../advisory-message.js";
+import type { ModelCallRequest, StigmerMiddleware, ToolCallRequest } from "../types.js";
+
+const HISTORY = [new HumanMessage("go")];
+const REQUEST: ModelCallRequest = { model: {}, messages: HISTORY, state: { messages: HISTORY }, runtime: {} };
+
+function makeRequest(name = "read"): ToolCallRequest {
+  return {
+    toolCall: { id: "tc_1", name, args: {} },
+    tool: undefined,
+    state: { messages: [] },
+    runtime: {},
+  };
+}
+
+function responseWithToolCalls(calls: Array<{ name: string; args?: Record<string, unknown> }>): AIMessage {
+  return new AIMessage({
+    content: "",
+    tool_calls: calls.map((tc, i) => ({
+      id: `tc_${i}`,
+      name: tc.name,
+      args: tc.args ?? {},
+    })),
+  });
+}
+
+/** One model call through `mw` answered with `response`; returns the request the handler was handed. */
+async function callModel(mw: StigmerMiddleware, response: AIMessage): Promise<ModelCallRequest> {
+  let seen: ModelCallRequest | undefined;
+  await mw.wrapModelCall!(REQUEST, async (request) => {
+    seen = request;
+    return response;
+  });
+  return seen!;
+}
+
+/** The advisory text a request carries after the history, or undefined when it carries none. */
+function advisoryOf(request: ModelCallRequest): string | undefined {
+  const extra = request.messages.slice(HISTORY.length);
+  if (extra.length === 0) return undefined;
+  expect(extra).toHaveLength(1);
+  return String((extra[0] as HumanMessage).content);
+}
+
+/** The intervention the calls so far triggered: what the next model call carries. */
+async function nextAdvisory(mw: StigmerMiddleware): Promise<string | undefined> {
+  return advisoryOf(await callModel(mw, new AIMessage({ content: "next" })));
+}
+
+describe("LoopDetectionMiddleware", () => {
+  it("does nothing when no tool calls are present", async () => {
+    const mw = createLoopDetectionMiddleware({ consecutiveThreshold: 2, totalThreshold: 3 });
+    await callModel(mw, new AIMessage({ content: "hello" }));
+    expect(await nextAdvisory(mw)).toBeUndefined();
+  });
+
+  it("detects consecutive repetitions and injects warning", async () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 3,
+      totalThreshold: 10,
+      historySize: 20,
+    });
+
+    const response = responseWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+
+    // Three model calls with the same tool call, then the call that carries the warning.
+    await callModel(mw, response);
+    await callModel(mw, response);
+    await callModel(mw, response);
+
+    expect(await nextAdvisory(mw)).toContain("LOOP WARNING");
+  });
+
+  it("delivers the warning as a user-role advisory on the next call only, never through the graph's state", async () => {
+    const mw = createLoopDetectionMiddleware({ consecutiveThreshold: 2, totalThreshold: 10 });
+    expect(mw.afterModel, "no hook writes the graph's state").toBeUndefined();
+    const response = responseWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+
+    await callModel(mw, response);
+    expect(await callModel(mw, response), "the call whose response trips it is handed on untouched").toBe(REQUEST);
+
+    const advised = await callModel(mw, new AIMessage({ content: "next" }));
+    const advisory = advised.messages[advised.messages.length - 1];
+    expect(HumanMessage.isInstance(advisory)).toBe(true);
+    expect(SystemMessage.isInstance(advisory)).toBe(false);
+    expect(String((advisory as HumanMessage).content).startsWith(ADVISORY_LEAD_IN)).toBe(true);
+    expect(REQUEST.messages, "the request it was built from is not mutated").toHaveLength(HISTORY.length);
+
+    expect(await callModel(mw, new AIMessage({ content: "later" })), "the advisory rode one call").toBe(REQUEST);
+  });
+
+  it("detects total threshold and stops", async () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 100,
+      totalThreshold: 3,
+      historySize: 20,
+    });
+
+    const response = responseWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+
+    await callModel(mw, response);
+    await callModel(mw, response);
+    await callModel(mw, response);
+
+    expect(await nextAdvisory(mw)).toContain("LOOP DETECTED");
+  });
+
+  it("blocks tool execution after total threshold is exceeded", async () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 100,
+      totalThreshold: 2,
+      historySize: 20,
+    });
+
+    const response = responseWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+    await callModel(mw, response);
+    await callModel(mw, response);
+
+    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", async () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 100,
+      totalThreshold: 2,
+    });
+
+    const response = responseWithToolCalls([{ name: "read", args: { path: "/foo" } }]);
+    await callModel(mw, response);
+    await callModel(mw, response);
+
+    mw.beforeAgent!({}, {});
+
+    // After reset nothing is pending or halted, and the same calls count from zero.
+    expect(await nextAdvisory(mw), "a pending intervention does not survive the reset").toBeUndefined();
+    const handler = vi.fn().mockResolvedValue(new ToolMessage({ content: "ok", tool_call_id: "tc_1", name: "read" }));
+    await mw.wrapToolCall!(makeRequest(), handler);
+    expect(handler, "tools run again after the reset").toHaveBeenCalled();
+    await callModel(mw, response);
+    await callModel(mw, response);
+    expect(await nextAdvisory(mw)).toContain("LOOP DETECTED");
+  });
+
+  it("tracks different tool signatures independently", async () => {
+    const mw = createLoopDetectionMiddleware({
+      consecutiveThreshold: 3,
+      totalThreshold: 10,
+    });
+
+    // Alternating tools should not trigger consecutive detection
+    const responseA = responseWithToolCalls([{ name: "read", args: { path: "/a" } }]);
+    const responseB = responseWithToolCalls([{ name: "write", args: { path: "/b" } }]);
+
+    await callModel(mw, responseA);
+    await callModel(mw, responseB);
+    await callModel(mw, responseA);
+    await callModel(mw, responseB);
+
+    expect(await nextAdvisory(mw)).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,460 @@
+/**
+ * The native engine's spans (`otel-spans.ts`), read back from a real tracer
+ * provider into an in-memory exporter: a `chat {model}` CLIENT span per
+ * model call and an `execute_tool {tool}` INTERNAL span per tool call, in
+ * OpenTelemetry's GenAI conventions, and `withSubAgentSpan`'s
+ * `invoke_agent {name}`.
+ *
+ * Pinned: the names, kinds and parents; the provider and models from the
+ * facts `buildChatModel` records (never a guess from the model's name);
+ * usage with cached tokens; the response id and finish reason; every tool,
+ * built-in or MCP, gets a span; the conversation's text only with content
+ * on, and then never more than the saved conversation shows (a `.env`
+ * write reads `{ path }` with no result, a `token` argument is redacted);
+ * failures mark the span, a LangGraph pause does not. The handlers' results
+ * pass through unchanged.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { AIMessage, HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
+import { Command, GraphInterrupt } from "@langchain/langgraph";
+import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
+import { InMemorySpanExporter, SimpleSpanProcessor, type ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+
+import { createOtelSpansMiddleware, withSubAgentSpan } from "../otel-spans.js";
+import type { ToolCallRequest, ModelCallRequest } from "../types.js";
+import { TELEMETRY_OFF, adoptTelemetrySettings, resetTelemetrySettingsForTests } from "../../otel-export.js";
+import { buildChatModel } from "../../shared/model-client.js";
+import { _resetRegistryCache } from "../../shared/model-registry.js";
+
+const exporter = new InMemorySpanExporter();
+let provider: NodeTracerProvider;
+
+beforeAll(() => {
+  provider = new NodeTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] });
+  provider.register();
+});
+
+afterAll(async () => {
+  await provider.shutdown();
+  trace.disable();
+  context.disable();
+  propagation.disable();
+});
+
+afterEach(() => {
+  exporter.reset();
+  resetTelemetrySettingsForTests();
+  vi.restoreAllMocks();
+});
+
+function contentOn(): void {
+  adoptTelemetrySettings({ ...TELEMETRY_OFF, content: true });
+}
+
+function spans(): ReadableSpan[] {
+  return exporter.getFinishedSpans();
+}
+
+function spanNamed(name: string): ReadableSpan {
+  const found = spans().find((span) => span.name === name);
+  if (!found) throw new Error(`no span named ${name}; have ${spans().map((s) => s.name).join(", ")}`);
+  return found;
+}
+
+function parentOf(span: ReadableSpan): string | undefined {
+  return span.parentSpanContext?.spanId;
+}
+
+function makeToolRequest(name = "mcp_tool", args: Record<string, unknown> = {}): ToolCallRequest {
+  return {
+    toolCall: { id: "tc_1", name, args },
+    tool: undefined,
+    state: { messages: [] },
+    runtime: {},
+  };
+}
+
+function makeModelRequest(overrides: Partial<ModelCallRequest> = {}): ModelCallRequest {
+  return {
+    model: { model: "claude-sonnet-4-6" },
+    messages: [],
+    state: { messages: [] },
+    runtime: {},
+    ...overrides,
+  };
+}
+
+/** A model `buildChatModel` built for real (no network: the registry read is answered here). */
+async function builtModel(): Promise<unknown> {
+  _resetRegistryCache();
+  vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+    new Response(JSON.stringify({ models: [{ id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic" }] }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    }),
+  );
+  vi.stubEnv("ANTHROPIC_API_KEY", "sk-test-not-a-key");
+  const { model } = await buildChatModel({ modelName: "claude-haiku-4.5" });
+  vi.unstubAllEnvs();
+  _resetRegistryCache();
+  return model;
+}
+
+function answer(fields: ConstructorParameters<typeof AIMessage>[0]): AIMessage {
+  return new AIMessage(fields);
+}
+
+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");
+    });
+
+    it("spans the call as `chat <registry id>` with the provider and models buildChatModel recorded", async () => {
+      const model = await builtModel();
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapModelCall!(makeModelRequest({ model }), async () => answer({ content: "hi" }));
+
+      const span = spanNamed("chat claude-haiku-4.5");
+      expect(span.kind).toBe(SpanKind.CLIENT);
+      expect(span.attributes).toMatchObject({
+        "gen_ai.operation.name": "chat",
+        "gen_ai.request.model": "claude-haiku-4.5",
+        "gen_ai.provider.name": "anthropic",
+        "gen_ai.response.model": "claude-haiku-4-5-20251001",
+      });
+    });
+
+    it("names a model it did not build by the model's own name, with no provider guessed", async () => {
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapModelCall!(makeModelRequest(), async () => answer({ content: "hi" }));
+
+      const span = spanNamed("chat claude-sonnet-4-6");
+      expect(span.attributes["gen_ai.provider.name"]).toBeUndefined();
+    });
+
+    it("records usage with cached tokens, the response id and the finish reason", async () => {
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapModelCall!(makeModelRequest(), async () =>
+        answer({
+          content: "hi",
+          id: "msg_123",
+          usage_metadata: {
+            input_tokens: 120,
+            output_tokens: 30,
+            total_tokens: 150,
+            input_token_details: { cache_read: 80, cache_creation: 20 },
+          },
+          response_metadata: { stop_reason: "end_turn" },
+        }),
+      );
+
+      expect(spanNamed("chat claude-sonnet-4-6").attributes).toMatchObject({
+        "gen_ai.usage.input_tokens": 120,
+        "gen_ai.usage.output_tokens": 30,
+        "gen_ai.usage.cache_read.input_tokens": 80,
+        "gen_ai.usage.cache_write.input_tokens": 20,
+        "gen_ai.response.id": "msg_123",
+        "gen_ai.response.finish_reasons": ["end_turn"],
+      });
+    });
+
+    it("reads a streamed answer's finish reason from its additional kwargs", async () => {
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapModelCall!(makeModelRequest(), async () =>
+        answer({ content: "hi", additional_kwargs: { stop_reason: "tool_use" } }),
+      );
+
+      expect(spanNamed("chat claude-sonnet-4-6").attributes["gen_ai.response.finish_reasons"]).toEqual(["tool_use"]);
+    });
+
+    it("carries no text by default", async () => {
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapModelCall!(
+        makeModelRequest({ systemPrompt: "be brief", messages: [new HumanMessage("hello")] }),
+        async () => answer({ content: "hi" }),
+      );
+
+      const attributes = spanNamed("chat claude-sonnet-4-6").attributes;
+      expect(attributes["gen_ai.system_instructions"]).toBeUndefined();
+      expect(attributes["gen_ai.input.messages"]).toBeUndefined();
+      expect(attributes["gen_ai.output.messages"]).toBeUndefined();
+    });
+
+    it("with content on, carries the conversation in the conventions' shape, withholding what the saved conversation withholds", async () => {
+      contentOn();
+      const mw = createOtelSpansMiddleware();
+      const messages = [
+        new HumanMessage("set the key"),
+        new AIMessage({
+          content: "writing it",
+          tool_calls: [
+            { id: "w_env", name: "write_file", args: { file_path: ".env", content: "API_KEY=shh" } },
+            { id: "c_tok", name: "call_api", args: { url: "https://x", token: "s3cr3t" } },
+          ],
+        }),
+        new ToolMessage({ content: "wrote .env", tool_call_id: "w_env" }),
+        new ToolMessage({ content: "200 OK", tool_call_id: "c_tok" }),
+      ];
+      await mw.wrapModelCall!(
+        makeModelRequest({ systemMessage: new SystemMessage("be brief"), messages }),
+        async () => answer({ content: "done", response_metadata: { stop_reason: "end_turn" } }),
+      );
+
+      const attributes = spanNamed("chat claude-sonnet-4-6").attributes;
+      expect(JSON.parse(String(attributes["gen_ai.system_instructions"]))).toEqual([{ type: "text", content: "be brief" }]);
+      const input = JSON.parse(String(attributes["gen_ai.input.messages"])) as unknown;
+      expect(input).toEqual([
+        { role: "user", parts: [{ type: "text", content: "set the key" }] },
+        {
+          role: "assistant",
+          parts: [
+            { type: "text", content: "writing it" },
+            { type: "tool_call", id: "w_env", name: "write_file", arguments: { path: ".env" } },
+            { type: "tool_call", id: "c_tok", name: "call_api", arguments: { url: "https://x", token: "[REDACTED]" } },
+          ],
+        },
+        { role: "tool", parts: [{ type: "tool_call_response", id: "w_env", response: null }] },
+        { role: "tool", parts: [{ type: "tool_call_response", id: "c_tok", response: "200 OK" }] },
+      ]);
+      expect(JSON.stringify(input)).not.toContain("shh");
+      expect(JSON.stringify(input)).not.toContain("s3cr3t");
+      expect(JSON.parse(String(attributes["gen_ai.output.messages"]))).toEqual([
+        { role: "assistant", parts: [{ type: "text", content: "done" }], finish_reason: "end_turn" },
+      ]);
+    });
+
+    it("reads the system prompt from a string, from a message's text blocks, or finds none", async () => {
+      contentOn();
+      const mw = createOtelSpansMiddleware();
+      const reply = async () => answer({ content: "ok" });
+      await mw.wrapModelCall!(makeModelRequest({ systemPrompt: "as a string" }), reply);
+      await mw.wrapModelCall!(
+        makeModelRequest({ systemMessage: new SystemMessage({ content: [{ type: "text", text: "from blocks" }, { type: "image_url", image_url: "x" }] as never }) }),
+        reply,
+      );
+      await mw.wrapModelCall!(makeModelRequest({ systemMessage: new SystemMessage({ content: [{ type: "image_url", image_url: "x" }] as never }) }), reply);
+      await mw.wrapModelCall!(makeModelRequest(), reply);
+      const instructions = spans().map((span) => span.attributes["gen_ai.system_instructions"]);
+      expect(instructions[0]).toContain("as a string");
+      expect(instructions[1]).toContain("from blocks");
+      expect(instructions[2], "no text, no instructions").toBeUndefined();
+      expect(instructions[3], "no system prompt at all").toBeUndefined();
+    });
+
+    it("names a model by its model_name when it carries no model field", async () => {
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapModelCall!(makeModelRequest({ model: { model_name: "gpt-x" } }), async () => answer({ content: "ok" }));
+      expect(spans()[0]!.name).toBe("chat gpt-x");
+    });
+
+    it("marks a failed call and rethrows", async () => {
+      const mw = createOtelSpansMiddleware();
+      class ProviderDown extends Error {
+        override name = "ProviderDown";
+      }
+      await expect(
+        mw.wrapModelCall!(makeModelRequest(), async () => {
+          throw new ProviderDown("529 overloaded");
+        }),
+      ).rejects.toThrow("529 overloaded");
+
+      const span = spanNamed("chat claude-sonnet-4-6");
+      expect(span.status.code).toBe(SpanStatusCode.ERROR);
+      expect(span.attributes["error.type"]).toBe("ProviderDown");
+    });
+  });
+
+  describe("wrapToolCall", () => {
+    it("keeps a thrown tool error's text, which can quote the call's arguments, off the span unless content is on", async () => {
+      // LangChain's schema refusal prints the call's kwargs into its message.
+      const refusal = `Error invoking tool 'echo' with kwargs {"text":"x","token":"canary-arg"}`;
+      const mw = createOtelSpansMiddleware();
+      await expect(mw.wrapToolCall!(makeToolRequest("echo"), async () => Promise.reject(new Error(refusal)))).rejects.toThrow();
+      const off = spanNamed("execute_tool echo");
+      expect(off.status, "no message with content off").toEqual({ code: SpanStatusCode.ERROR });
+      expect(off.events, "no exception event with content off").toEqual([]);
+      expect(JSON.stringify([off.attributes, off.status, off.events])).not.toContain("canary-arg");
+
+      exporter.reset();
+      contentOn();
+      await expect(mw.wrapToolCall!(makeToolRequest("echo"), async () => Promise.reject(new Error(refusal)))).rejects.toThrow();
+      const on = spanNamed("execute_tool echo");
+      expect(on.status.message, "with content on, the text the saved conversation also shows").toBe(refusal);
+      expect(on.events.map((event) => event.name)).toEqual(["exception"]);
+    });
+
+    it("reads a Command's carried tool message as the result, as the task tool answers", async () => {
+      contentOn();
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapToolCall!(makeToolRequest("task", { description: "d", prompt: "p" }), async () =>
+        new Command({ update: { messages: [new ToolMessage({ content: "the sub-agent's answer", tool_call_id: "tc_1" })] } }),
+      );
+      expect(spanNamed("execute_tool task").attributes["gen_ai.tool.call.result"]).toBe("the sub-agent's answer");
+    });
+
+    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);
+
+      const span = spanNamed("execute_tool mcp_tool");
+      expect(span.kind).toBe(SpanKind.INTERNAL);
+      expect(span.attributes).toMatchObject({
+        "gen_ai.operation.name": "execute_tool",
+        "gen_ai.tool.name": "mcp_tool",
+        "gen_ai.tool.call.id": "tc_1",
+        "gen_ai.tool.type": "extension",
+        "mcp.method.name": "tools/call",
+        "stigmer.mcp.server_name": "my-server",
+      });
+    });
+
+    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");
+      expect(spanNamed("execute_tool mcp_tool").status.code).toBe(SpanStatusCode.ERROR);
+    });
+
+    it("spans a built-in tool as a function tool, with no MCP attributes", async () => {
+      const mw = createOtelSpansMiddleware({ toolServerMap: new Map([["other_tool", "server-a"]]) });
+      const msg = new ToolMessage({ content: "ok", tool_call_id: "tc_1", name: "read_file" });
+
+      const result = await mw.wrapToolCall!(makeToolRequest("read_file", { file_path: "/a.txt" }), async () => msg);
+      expect(result).toBe(msg);
+
+      const attributes = spanNamed("execute_tool read_file").attributes;
+      expect(attributes["gen_ai.tool.type"]).toBe("function");
+      expect(attributes["mcp.method.name"]).toBeUndefined();
+      expect(attributes["stigmer.mcp.server_name"]).toBeUndefined();
+    });
+
+    it("carries the arguments and result only with content on", async () => {
+      const mw = createOtelSpansMiddleware();
+      const msg = new ToolMessage({ content: "file body", tool_call_id: "tc_1" });
+      await mw.wrapToolCall!(makeToolRequest("read_file", { file_path: "/a.txt", token: "t0k" }), async () => msg);
+      const off = spanNamed("execute_tool read_file").attributes;
+      expect(off["gen_ai.tool.call.arguments"]).toBeUndefined();
+      expect(off["gen_ai.tool.call.result"]).toBeUndefined();
+
+      exporter.reset();
+      contentOn();
+      await mw.wrapToolCall!(makeToolRequest("read_file", { file_path: "/a.txt", token: "t0k" }), async () => msg);
+      const on = spanNamed("execute_tool read_file").attributes;
+      expect(JSON.parse(String(on["gen_ai.tool.call.arguments"]))).toEqual({ file_path: "/a.txt", token: "[REDACTED]" });
+      expect(on["gen_ai.tool.call.result"]).toBe("file body");
+    });
+
+    it("shows a write to a secret-like path as its path, with no result", async () => {
+      contentOn();
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapToolCall!(
+        makeToolRequest("write_file", { file_path: ".env", content: "API_KEY=shh" }),
+        async () => new ToolMessage({ content: "Successfully wrote .env", tool_call_id: "tc_1" }),
+      );
+
+      const attributes = spanNamed("execute_tool write_file").attributes;
+      expect(JSON.parse(String(attributes["gen_ai.tool.call.arguments"]))).toEqual({ path: ".env" });
+      expect(attributes["gen_ai.tool.call.result"]).toBeUndefined();
+    });
+
+    it("marks a tool that answered with an error", async () => {
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapToolCall!(makeToolRequest("execute"), async () =>
+        new ToolMessage({ content: "exit 1", tool_call_id: "tc_1", status: "error" }),
+      );
+
+      const span = spanNamed("execute_tool execute");
+      expect(span.status.code).toBe(SpanStatusCode.ERROR);
+      expect(span.attributes["error.type"]).toBe("tool_error");
+    });
+
+    it("does not mark a LangGraph pause as a failure", async () => {
+      const mw = createOtelSpansMiddleware();
+      await expect(
+        mw.wrapToolCall!(makeToolRequest("task"), async () => {
+          throw new GraphInterrupt([]);
+        }),
+      ).rejects.toBeInstanceOf(GraphInterrupt);
+
+      expect(spanNamed("execute_tool task").status.code).toBe(SpanStatusCode.UNSET);
+    });
+
+    it("nests a model call made inside the tool under the tool's span", async () => {
+      const mw = createOtelSpansMiddleware();
+      await mw.wrapToolCall!(makeToolRequest("task"), async () => {
+        await mw.wrapModelCall!(makeModelRequest(), async () => answer({ content: "inner" }));
+        return new ToolMessage({ content: "done", tool_call_id: "tc_1" });
+      });
+
+      const tool = spanNamed("execute_tool task");
+      const chat = spanNamed("chat claude-sonnet-4-6");
+      expect(parentOf(chat)).toBe(tool.spanContext().spanId);
+      expect(chat.spanContext().traceId).toBe(tool.spanContext().traceId);
+    });
+  });
+
+  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);
+  });
+});
+
+describe("withSubAgentSpan", () => {
+  it("opens `invoke_agent <name>` under the active span, and what runs inside nests under it", async () => {
+    const tracer = trace.getTracer("test");
+    await tracer.startActiveSpan("execute_tool task", async (outer) => {
+      const result = await withSubAgentSpan("researcher", async () => {
+        tracer.startSpan("inner").end();
+        return 7;
+      });
+      expect(result).toBe(7);
+      outer.end();
+    });
+
+    const outer = spanNamed("execute_tool task");
+    const sub = spanNamed("invoke_agent researcher");
+    expect(sub.attributes).toMatchObject({ "gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": "researcher" });
+    expect(parentOf(sub)).toBe(outer.spanContext().spanId);
+    expect(parentOf(spanNamed("inner"))).toBe(sub.spanContext().spanId);
+  });
+
+  it("marks a failed invocation and rethrows, but not a pause", async () => {
+    await expect(withSubAgentSpan("broken", async () => Promise.reject(new Error("boom")))).rejects.toThrow("boom");
+    expect(spanNamed("invoke_agent broken").status.code).toBe(SpanStatusCode.ERROR);
+
+    await expect(withSubAgentSpan("paused", async () => Promise.reject(new GraphInterrupt([])))).rejects.toBeInstanceOf(GraphInterrupt);
+    expect(spanNamed("invoke_agent paused").status.code).toBe(SpanStatusCode.UNSET);
+  });
+});