@mcpmesh/sdk 2.6.0 → 2.7.0

package/dist/__tests__/llm-provider-sampling-gating.test.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Mesh-level OpenAI sampling-param gating (cross-runtime parity with Java
+ * `OpenAiHandler.restrictsSamplingParams` and Python `restricts_sampling_params`).
+ *
+ * OpenAI o-series (o1/o3/o4) and gpt-5 (except gpt-5-chat) reject non-default
+ * `temperature`/`top_p` with HTTP 400. This is version-independent HARDENING:
+ * mesh omits temperature/topP for restricted models BEFORE handing off to the
+ * SDK (rather than silently relying on @ai-sdk/openai to strip them) and logs
+ * its own warning. maxOutputTokens is intentionally NOT touched.
+ *
+ * Two layers:
+ *  - the `restrictsSamplingParams` classifier truth table, and
+ *  - behavioral: the options reaching the mocked vendor call (generateText /
+ *    generateObject) carry NO temperature/topP for a restricted model, while a
+ *    non-restricted model (gpt-4o) keeps them.
+ *
+ * The Vercel `ai` module is mocked — no real LLM is invoked.
+ */
+export {};
+//# sourceMappingURL=llm-provider-sampling-gating.test.d.ts.map

package/dist/__tests__/llm-provider-sampling-gating.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-provider-sampling-gating.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/llm-provider-sampling-gating.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/__tests__/llm-provider-sampling-gating.test.js

@@ -0,0 +1,192 @@
+/**
+ * Mesh-level OpenAI sampling-param gating (cross-runtime parity with Java
+ * `OpenAiHandler.restrictsSamplingParams` and Python `restricts_sampling_params`).
+ *
+ * OpenAI o-series (o1/o3/o4) and gpt-5 (except gpt-5-chat) reject non-default
+ * `temperature`/`top_p` with HTTP 400. This is version-independent HARDENING:
+ * mesh omits temperature/topP for restricted models BEFORE handing off to the
+ * SDK (rather than silently relying on @ai-sdk/openai to strip them) and logs
+ * its own warning. maxOutputTokens is intentionally NOT touched.
+ *
+ * Two layers:
+ *  - the `restrictsSamplingParams` classifier truth table, and
+ *  - behavioral: the options reaching the mocked vendor call (generateText /
+ *    generateObject) carry NO temperature/topP for a restricted model, while a
+ *    non-restricted model (gpt-4o) keeps them.
+ *
+ * The Vercel `ai` module is mocked — no real LLM is invoked.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+const generateObjectMock = vi.fn();
+const generateTextMock = vi.fn();
+vi.mock("ai", () => ({
+    generateText: (opts) => generateTextMock(opts),
+    generateObject: (opts) => generateObjectMock(opts),
+    jsonSchema: (schema) => schema,
+    tool: (config) => config,
+    stepCountIs: (n) => ({ steps }) => steps.length === n,
+}));
+// Keep tracing inert/deterministic (publishTraceSpan is best-effort anyway).
+vi.mock("../tracing.js", () => ({
+    generateTraceId: () => "trace-mock",
+    generateSpanId: () => "span-mock",
+    publishTraceSpan: vi.fn(async () => { }),
+    matchesPropagateHeader: () => false,
+}));
+import { llmProvider, restrictsSamplingParams } from "../llm-provider.js";
+// ----------------------------------------------------------------------------
+// Classifier truth table
+// ----------------------------------------------------------------------------
+describe("restrictsSamplingParams truth table", () => {
+    it.each([
+        "o1",
+        "o3-mini",
+        "o4-mini",
+        "gpt-5",
+        "gpt-5-mini",
+        "gpt-5-nano",
+        "openai/o3-mini",
+        "openai/gpt-5",
+        "O3-MINI", // case-insensitive
+    ])("restricts %s", (model) => {
+        expect(restrictsSamplingParams(model)).toBe(true);
+    });
+    it.each([
+        "gpt-4o",
+        "gpt-4.1",
+        "gpt-5-chat-latest",
+        "openai/gpt-4o",
+        "gemini/gemini-2.0-flash",
+        "anthropic/claude-sonnet-4-5",
+        "o5", // not an o1/o3/o4 series
+        undefined,
+        null,
+        "",
+    ])("does not restrict %s", (model) => {
+        expect(restrictsSamplingParams(model)).toBe(false);
+    });
+});
+// ----------------------------------------------------------------------------
+// Behavioral — the options reaching the vendor SDK call
+// ----------------------------------------------------------------------------
+const SCHEMA = {
+    type: "object",
+    properties: { answer: { type: "string" } },
+    required: ["answer"],
+};
+function baseRequest(modelParams, opts = {}) {
+    const mp = { ...modelParams };
+    if (opts.withSchema) {
+        mp.output_schema = SCHEMA;
+        mp.output_type_name = "Answer";
+    }
+    return {
+        request: {
+            messages: [
+                { role: "system", content: "You are helpful." },
+                { role: "user", content: "hi" },
+            ],
+            model_params: mp,
+        },
+    };
+}
+describe("OpenAI sampling-param gating — vendor call options", () => {
+    let warnSpy;
+    beforeEach(() => {
+        generateObjectMock.mockReset();
+        generateTextMock.mockReset();
+        generateObjectMock.mockResolvedValue({
+            object: { answer: "ok" },
+            usage: { inputTokens: 1, outputTokens: 1 },
+            finishReason: "stop",
+        });
+        generateTextMock.mockResolvedValue({
+            text: "ok",
+            toolCalls: [],
+            usage: { inputTokens: 1, outputTokens: 1 },
+            finishReason: "stop",
+        });
+        warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    // --- generateText (plain / no schema) path ---
+    it("omits temperature/topP for a restricted model (o3-mini) — generateText", async () => {
+        const tool = llmProvider({
+            model: "openai/o3-mini",
+            capability: "llm",
+            temperature: 0.7,
+            topP: 0.9,
+        });
+        await tool.execute(baseRequest({}));
+        expect(generateTextMock).toHaveBeenCalledTimes(1);
+        const opts = generateTextMock.mock.calls[0][0];
+        expect("temperature" in opts).toBe(false);
+        expect("topP" in opts).toBe(false);
+        // mesh surfaces its own warning (one per omitted param).
+        expect(warnSpy).toHaveBeenCalledTimes(2);
+    });
+    it("keeps temperature/topP for a non-restricted model (gpt-4o) — generateText", async () => {
+        const tool = llmProvider({
+            model: "openai/gpt-4o",
+            capability: "llm",
+            temperature: 0.7,
+            topP: 0.9,
+        });
+        await tool.execute(baseRequest({}));
+        expect(generateTextMock).toHaveBeenCalledTimes(1);
+        const opts = generateTextMock.mock.calls[0][0];
+        expect(opts.temperature).toBe(0.7);
+        expect(opts.topP).toBe(0.9);
+        expect(warnSpy).not.toHaveBeenCalled();
+    });
+    it("omits temperature/topP supplied via model_params for a restricted model", async () => {
+        const tool = llmProvider({ model: "openai/gpt-5", capability: "llm" });
+        await tool.execute(baseRequest({ temperature: 0.3, top_p: 0.5 }));
+        expect(generateTextMock).toHaveBeenCalledTimes(1);
+        const opts = generateTextMock.mock.calls[0][0];
+        expect("temperature" in opts).toBe(false);
+        expect("topP" in opts).toBe(false);
+    });
+    it("does not touch maxOutputTokens for a restricted model", async () => {
+        const tool = llmProvider({
+            model: "openai/o3-mini",
+            capability: "llm",
+            maxOutputTokens: 4096,
+            temperature: 0.7,
+        });
+        await tool.execute(baseRequest({}));
+        const opts = generateTextMock.mock.calls[0][0];
+        expect(opts.maxOutputTokens).toBe(4096);
+        expect("temperature" in opts).toBe(false);
+    });
+    // --- generateObject (structured output) path ---
+    it("omits temperature/topP for a restricted model (o3-mini) — generateObject", async () => {
+        const tool = llmProvider({
+            model: "openai/o3-mini",
+            capability: "llm",
+            temperature: 0.7,
+            topP: 0.9,
+        });
+        await tool.execute(baseRequest({}, { withSchema: true }));
+        expect(generateObjectMock).toHaveBeenCalledTimes(1);
+        const opts = generateObjectMock.mock.calls[0][0];
+        expect("temperature" in opts).toBe(false);
+        expect("topP" in opts).toBe(false);
+    });
+    it("keeps temperature/topP for a non-restricted model (gpt-4o) — generateObject", async () => {
+        const tool = llmProvider({
+            model: "openai/gpt-4o",
+            capability: "llm",
+            temperature: 0.7,
+            topP: 0.9,
+        });
+        await tool.execute(baseRequest({}, { withSchema: true }));
+        expect(generateObjectMock).toHaveBeenCalledTimes(1);
+        const opts = generateObjectMock.mock.calls[0][0];
+        expect(opts.temperature).toBe(0.7);
+        expect(opts.topP).toBe(0.9);
+    });
+});
+//# sourceMappingURL=llm-provider-sampling-gating.test.js.map

package/dist/__tests__/llm-provider-sampling-gating.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-provider-sampling-gating.test.js","sourceRoot":"","sources":["../../src/__tests__/llm-provider-sampling-gating.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/llm-token-telemetry.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Consumer-span LLM token telemetry — regression test for #1228.
+ *
+ * The dashboard aggregates per-agent / per-model token usage from `mesh:trace`
+ * span fields `llm_input_tokens` / `llm_output_tokens` / `llm_total_tokens` /
+ * `llm_model`. Python already stamps the consumer's own execution span (via the
+ * `set_llm_metadata` contextvar read in ExecutionTracer); this asserts the TS
+ * `@mesh.llm` consumer span reaches parity.
+ *
+ * The mesh-delegated provider is reached through `callMcpTool`, mocked here to
+ * return the canned provider response JSON (incl. `_mesh_usage`). The agentic
+ * loop in MeshLlmAgent parses `_mesh_usage`, accumulates totals across
+ * iterations, finalizes `_meta`, and the `@mesh.llm` consumer span published in
+ * llm.ts stamps the llm_* SpanData fields from it.
+ */
+export {};
+//# sourceMappingURL=llm-token-telemetry.test.d.ts.map

package/dist/__tests__/llm-token-telemetry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-token-telemetry.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/llm-token-telemetry.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/__tests__/llm-token-telemetry.test.js

@@ -0,0 +1,199 @@
+/**
+ * Consumer-span LLM token telemetry — regression test for #1228.
+ *
+ * The dashboard aggregates per-agent / per-model token usage from `mesh:trace`
+ * span fields `llm_input_tokens` / `llm_output_tokens` / `llm_total_tokens` /
+ * `llm_model`. Python already stamps the consumer's own execution span (via the
+ * `set_llm_metadata` contextvar read in ExecutionTracer); this asserts the TS
+ * `@mesh.llm` consumer span reaches parity.
+ *
+ * The mesh-delegated provider is reached through `callMcpTool`, mocked here to
+ * return the canned provider response JSON (incl. `_mesh_usage`). The agentic
+ * loop in MeshLlmAgent parses `_mesh_usage`, accumulates totals across
+ * iterations, finalizes `_meta`, and the `@mesh.llm` consumer span published in
+ * llm.ts stamps the llm_* SpanData fields from it.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { z } from "zod";
+const callMcpToolMock = vi.hoisted(() => vi.fn());
+const publishTraceSpanMock = vi.hoisted(() => vi.fn(async () => true));
+// Replace only callMcpTool — keep runWithTraceContext etc. real so the
+// consumer span's trace context propagation behaves normally.
+vi.mock("../proxy.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, callMcpTool: callMcpToolMock };
+});
+// Capture published spans; keep everything else real.
+vi.mock("../tracing.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, publishTraceSpan: publishTraceSpanMock };
+});
+import { llm, LlmToolRegistry } from "../llm.js";
+import { createLlmToolProxy } from "../llm-agent.js";
+const FUNCTION_ID = "summarize";
+const PROVIDER_ENDPOINT = "http://llm-provider.local:9200";
+/** Provider response carrying token usage and (optionally) a tool call. */
+function providerResponse(opts) {
+    return JSON.stringify({
+        role: "assistant",
+        content: opts.content,
+        ...(opts.toolCall
+            ? {
+                tool_calls: [
+                    {
+                        id: opts.toolCall.id,
+                        type: "function",
+                        function: { name: opts.toolCall.name, arguments: opts.toolCall.args },
+                    },
+                ],
+            }
+            : {}),
+        _mesh_usage: {
+            prompt_tokens: opts.inputTokens,
+            completion_tokens: opts.outputTokens,
+        },
+    });
+}
+/** The consumer's own `@mesh.llm` execution span (function_name === FUNCTION_ID). */
+function consumerSpan() {
+    const calls = publishTraceSpanMock.mock.calls;
+    return calls.map((c) => c[0]).find((s) => s.functionName === FUNCTION_ID);
+}
+describe("consumer-span LLM token telemetry (#1228)", () => {
+    beforeEach(() => {
+        LlmToolRegistry.reset();
+        callMcpToolMock.mockReset();
+        publishTraceSpanMock.mockClear();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("stamps llm_* token fields on the consumer span for a single-iteration call", async () => {
+        const tool = llm({
+            name: FUNCTION_ID,
+            provider: { capability: "llm-service" },
+            parameters: z.object({}),
+            execute: async (_args, { llm: llmCallable }) => {
+                return llmCallable("Summarize the doc");
+            },
+        });
+        LlmToolRegistry.getInstance().setResolvedProvider(FUNCTION_ID, {
+            endpoint: PROVIDER_ENDPOINT,
+            functionName: "process_chat",
+            model: "claude-sonnet-4",
+            agentId: "provider-agent",
+        });
+        callMcpToolMock.mockResolvedValue(providerResponse({ content: "A short summary.", inputTokens: 100, outputTokens: 40 }));
+        await tool.execute({});
+        const span = consumerSpan();
+        expect(span).toBeDefined();
+        expect(span.llmInputTokens).toBe(100);
+        expect(span.llmOutputTokens).toBe(40);
+        expect(span.llmTotalTokens).toBe(140);
+        expect(span.llmModel).toBe("claude-sonnet-4");
+        expect(span.llmProvider).toBe(`mesh:${PROVIDER_ENDPOINT}`);
+    });
+    it("accumulates token usage across a multi-iteration agentic loop", async () => {
+        const tool = llm({
+            name: FUNCTION_ID,
+            provider: { capability: "llm-service" },
+            parameters: z.object({}),
+            execute: async (_args, { llm: llmCallable }) => {
+                return llmCallable("Look something up then answer");
+            },
+        });
+        LlmToolRegistry.getInstance().setResolvedProvider(FUNCTION_ID, {
+            endpoint: PROVIDER_ENDPOINT,
+            functionName: "process_chat",
+            model: "claude-sonnet-4",
+            agentId: "provider-agent",
+        });
+        // Register a resolved tool so the loop has a tool to call on iteration 1.
+        // The proxy routes through the mocked callMcpTool for its result.
+        LlmToolRegistry.getInstance().setResolvedTools(FUNCTION_ID, [
+            createLlmToolProxy({
+                functionName: "lookup",
+                capability: "lookup",
+                endpoint: "http://tool-agent.local:9300",
+                agentId: "tool-agent",
+            }, "Look up a value"),
+        ]);
+        // Iteration 1: provider asks for a tool call (usage 50/20).
+        // Tool result returned by the proxy/callMcpTool.
+        // Iteration 2: provider returns final text (usage 70/30).
+        callMcpToolMock
+            .mockResolvedValueOnce(providerResponse({
+            content: "",
+            inputTokens: 50,
+            outputTokens: 20,
+            toolCall: { id: "call-1", name: "lookup", args: "{}" },
+        }))
+            .mockResolvedValueOnce(JSON.stringify({ value: 42 })) // tool result
+            .mockResolvedValueOnce(providerResponse({ content: "The answer is 42.", inputTokens: 70, outputTokens: 30 }));
+        await tool.execute({});
+        const span = consumerSpan();
+        expect(span).toBeDefined();
+        // Accumulated across both provider calls: 50+70 input, 20+30 output.
+        expect(span.llmInputTokens).toBe(120);
+        expect(span.llmOutputTokens).toBe(50);
+        expect(span.llmTotalTokens).toBe(170);
+        expect(span.llmModel).toBe("claude-sonnet-4");
+    });
+    it("stamps llm_* token fields when the handler throws AFTER an LLM call recorded usage", async () => {
+        const boom = new Error("handler failed after LLM call");
+        const tool = llm({
+            name: FUNCTION_ID,
+            provider: { capability: "llm-service" },
+            parameters: z.object({}),
+            execute: async (_args, { llm: llmCallable }) => {
+                // Real LLM call records usage, THEN the handler fails.
+                await llmCallable("Summarize the doc");
+                throw boom;
+            },
+        });
+        LlmToolRegistry.getInstance().setResolvedProvider(FUNCTION_ID, {
+            endpoint: PROVIDER_ENDPOINT,
+            functionName: "process_chat",
+            model: "claude-sonnet-4",
+            agentId: "provider-agent",
+        });
+        callMcpToolMock.mockResolvedValue(providerResponse({ content: "A short summary.", inputTokens: 100, outputTokens: 40 }));
+        // The handler's exception must still propagate.
+        await expect(tool.execute({})).rejects.toThrow("handler failed after LLM call");
+        const span = consumerSpan();
+        expect(span).toBeDefined();
+        expect(span.success).toBe(false);
+        // Accumulated usage from the LLM call before the throw is preserved.
+        expect(span.llmInputTokens).toBe(100);
+        expect(span.llmOutputTokens).toBe(40);
+        expect(span.llmTotalTokens).toBe(140);
+        expect(span.llmModel).toBe("claude-sonnet-4");
+        expect(span.llmProvider).toBe(`mesh:${PROVIDER_ENDPOINT}`);
+    });
+    it("publishes the consumer span WITHOUT llm_* fields when execute never calls the llm", async () => {
+        const tool = llm({
+            name: FUNCTION_ID,
+            provider: { capability: "llm-service" },
+            parameters: z.object({}),
+            // Non-LLM path through the same wrapper: returns directly, no llm() call.
+            execute: async () => "static result",
+        });
+        LlmToolRegistry.getInstance().setResolvedProvider(FUNCTION_ID, {
+            endpoint: PROVIDER_ENDPOINT,
+            functionName: "process_chat",
+            model: "claude-sonnet-4",
+            agentId: "provider-agent",
+        });
+        await tool.execute({});
+        const span = consumerSpan();
+        expect(span).toBeDefined();
+        expect(span.llmInputTokens).toBeUndefined();
+        expect(span.llmOutputTokens).toBeUndefined();
+        expect(span.llmTotalTokens).toBeUndefined();
+        expect(span.llmModel).toBeUndefined();
+        expect(span.llmProvider).toBeUndefined();
+        // callMcpTool must not have been invoked on this non-LLM path.
+        expect(callMcpToolMock).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=llm-token-telemetry.test.js.map

package/dist/__tests__/llm-token-telemetry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-token-telemetry.test.js","sourceRoot":"","sources":["../../src/__tests__/llm-token-telemetry.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/unwired-slot-warn.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=unwired-slot-warn.spec.d.ts.map

package/dist/__tests__/unwired-slot-warn.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unwired-slot-warn.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/unwired-slot-warn.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/unwired-slot-warn.spec.js

@@ -0,0 +1,167 @@
+/**
+ * Unwired typed-dependency-slot diagnostics (issue #1231).
+ *
+ * A declared typed dependency slot can remain null after the settle window
+ * closes — no proxy was ever injected — leaving the parameter silently null.
+ * The deps array is rebuilt PER CALL, so the diagnostic must warn ONCE per
+ * tool+slot (a per-call warning would spam) and only AFTER the settle latch
+ * has flipped (during settling the proxy may still land). The same warn-once
+ * dedupe spans BOTH the inbound HTTP path and the claim-dispatch path.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { z } from "zod";
+import { MeshAgent, __resetUnwiredSlotWarnedForTests } from "../agent.js";
+import { RouteRegistry } from "../route.js";
+import { resetSettleStateForTests } from "../settle.js";
+function makeFastMCPStub() {
+    return {
+        addTool: vi.fn(),
+        start: vi.fn(),
+        getApp: vi.fn(),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+}
+let autoStartSpy = null;
+let warnSpy = null;
+const savedEnv = {};
+beforeEach(() => {
+    autoStartSpy = vi
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .spyOn(MeshAgent.prototype, "_autoStart")
+        .mockImplementation(async () => {
+        /* no-op */
+    });
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {
+        /* swallow */
+    });
+    savedEnv.MCP_MESH_SETTLE_TIMEOUT = process.env.MCP_MESH_SETTLE_TIMEOUT;
+    savedEnv.MCP_MESH_TOOL_ISOLATION = process.env.MCP_MESH_TOOL_ISOLATION;
+    process.env.MCP_MESH_TOOL_ISOLATION = "false";
+    // Disable the settle grace so the agent is settled immediately — a null
+    // slot here is genuinely unwired, exactly the case the warning targets.
+    process.env.MCP_MESH_SETTLE_TIMEOUT = "0";
+    resetSettleStateForTests();
+    RouteRegistry.reset();
+    __resetUnwiredSlotWarnedForTests();
+});
+afterEach(() => {
+    if (autoStartSpy) {
+        autoStartSpy.mockRestore();
+        autoStartSpy = null;
+    }
+    if (warnSpy) {
+        warnSpy.mockRestore();
+        warnSpy = null;
+    }
+    for (const [key, value] of Object.entries(savedEnv)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    resetSettleStateForTests();
+    RouteRegistry.reset();
+    __resetUnwiredSlotWarnedForTests();
+});
+function unwiredWarnings() {
+    return (warnSpy?.mock.calls ?? [])
+        .map((call) => String(call[0]))
+        .filter((msg) => msg.includes("no proxy was injected"));
+}
+describe("unwired typed-slot warning (#1231)", () => {
+    it("warns ONCE per tool+slot across multiple calls, not per-call", async () => {
+        const fastmcp = makeFastMCPStub();
+        const agent = new MeshAgent(fastmcp, {
+            name: "unwired-agent",
+            httpPort: 0,
+        });
+        agent.addTool({
+            name: "consumer_tool",
+            parameters: z.object({}),
+            dependencies: [{ capability: "missing_cap" }],
+            // Defensive user idiom — the dep slot is never resolved, so it stays
+            // null on every call.
+            execute: async (_args, dep) => dep ? "wired" : "unwired",
+        });
+        const execute = fastmcp.addTool.mock.calls[0][0].execute;
+        for (let i = 0; i < 3; i++) {
+            expect(await execute({})).toBe("unwired");
+        }
+        const warnings = unwiredWarnings();
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain("missing_cap");
+        expect(warnings[0]).toContain("consumer_tool");
+        expect(warnings[0]).toContain("slot 0");
+    });
+    it("does not warn when the slot actually wires", async () => {
+        const fastmcp = makeFastMCPStub();
+        const agent = new MeshAgent(fastmcp, {
+            name: "wired-agent",
+            httpPort: 0,
+        });
+        agent.addTool({
+            name: "wired_tool",
+            parameters: z.object({}),
+            dependencies: [{ capability: "present_cap" }],
+            execute: async (_args, dep) => dep ? "wired" : "unwired",
+        });
+        const execute = fastmcp.addTool.mock.calls[0][0].execute;
+        // Resolve the dependency so a real proxy lands in the slot.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        agent.handleDependencyAvailable("present_cap", "http://localhost:19999", "remote_fn", "provider-agent", "wired_tool", 0);
+        expect(await execute({})).toBe("wired");
+        expect(unwiredWarnings()).toHaveLength(0);
+    });
+    it("warns ONCE for an unwired slot on the claim-dispatch path", async () => {
+        const fastmcp = makeFastMCPStub();
+        const agent = new MeshAgent(fastmcp, {
+            name: "claim-agent",
+            httpPort: 0,
+        });
+        agent.addTool({
+            name: "task_tool",
+            task: true,
+            parameters: z.object({}),
+            dependencies: [{ capability: "missing_cap" }],
+            execute: async (_args, dep) => dep ? "wired" : "unwired",
+        });
+        // The claim-dispatch path is exercised via the registered ClaimHandler
+        // (one per task: true tool), not via FastMCP's execute().
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { handler } = agent._taskHandlers.get("task_tool");
+        // meshJobParamIndex is unset, so the dummy controller is never spliced
+        // into callArgs — the user execute() only sees (payload, dep).
+        for (let i = 0; i < 3; i++) {
+            expect(await handler({}, {})).toBe("unwired");
+        }
+        const warnings = unwiredWarnings();
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain("missing_cap");
+        expect(warnings[0]).toContain("task_tool");
+        expect(warnings[0]).toContain("slot 0");
+    });
+    it("dedupes the unwired warning ACROSS the inbound and claim paths", async () => {
+        const fastmcp = makeFastMCPStub();
+        const agent = new MeshAgent(fastmcp, {
+            name: "both-paths-agent",
+            httpPort: 0,
+        });
+        agent.addTool({
+            name: "task_tool",
+            task: true,
+            parameters: z.object({}),
+            dependencies: [{ capability: "missing_cap" }],
+            execute: async (_args, dep) => dep ? "wired" : "unwired",
+        });
+        const execute = fastmcp.addTool.mock.calls[0][0].execute;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { handler } = agent._taskHandlers.get("task_tool");
+        // Exercise the same tool+slot via BOTH paths — the shared
+        // _unwiredSlotWarned Set must dedupe to a single warning total.
+        expect(await execute({})).toBe("unwired");
+        expect(await handler({}, {})).toBe("unwired");
+        expect(await execute({})).toBe("unwired");
+        expect(unwiredWarnings()).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=unwired-slot-warn.spec.js.map

package/dist/__tests__/unwired-slot-warn.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unwired-slot-warn.spec.js","sourceRoot":"","sources":["../../src/__tests__/unwired-slot-warn.spec.ts"],"names":[],"mappings":"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"}