@mcpmesh/sdk 2.6.0 → 2.8.0

package/dist/__tests__/route-required.spec.js

@@ -0,0 +1,154 @@
+/**
+ * Issue #1249: per-dependency `required` flag + route perimeter 503.
+ *
+ * Uses the REAL `normalizeDependency` (proxy.js) and the REAL route
+ * middleware — no proxy mock — so the declaration → normalized-dep → wire
+ * mapping and the perimeter check are genuinely exercised.
+ */
+import { describe, it, expect, vi, beforeEach, afterAll } from "vitest";
+import { normalizeDependency } from "../proxy.js";
+import { route, RouteRegistry } from "../route.js";
+import { resetSettleStateForTests } from "../settle.js";
+// Disable the settling-window grace (#1193) so the perimeter is judged
+// immediately (MCP_MESH_SETTLE_TIMEOUT=0 tuning case). The perimeter runs
+// AFTER the settle wait, so with the grace on a still-settling dep would get
+// its full window before being called unavailable — covered elsewhere.
+const savedSettleTimeout = process.env.MCP_MESH_SETTLE_TIMEOUT;
+beforeEach(() => {
+    process.env.MCP_MESH_SETTLE_TIMEOUT = "0";
+    resetSettleStateForTests();
+    RouteRegistry.reset();
+});
+afterAll(() => {
+    if (savedSettleTimeout === undefined) {
+        delete process.env.MCP_MESH_SETTLE_TIMEOUT;
+    }
+    else {
+        process.env.MCP_MESH_SETTLE_TIMEOUT = savedSettleTimeout;
+    }
+    resetSettleStateForTests();
+});
+function mockRes() {
+    return {
+        status: vi.fn().mockReturnThis(),
+        json: vi.fn().mockReturnThis(),
+    };
+}
+describe("normalizeDependency required flag (#1249)", () => {
+    it("carries required:true through to the normalized dep (napi wire seam)", () => {
+        const norm = normalizeDependency({ capability: "weather-api", required: true });
+        expect(norm.capability).toBe("weather-api");
+        expect(norm.required).toBe(true);
+        // The three JsDependencySpec builders map `dep.required ? true : undefined`,
+        // so a true here becomes required:true on the napi DependencySpec.
+        expect(norm.required ? true : undefined).toBe(true);
+    });
+    it("omits required when declared false (byte-identical soft-fail default)", () => {
+        const norm = normalizeDependency({ capability: "weather-api", required: false });
+        expect(norm.required).toBeUndefined();
+        expect(norm.required ? true : undefined).toBeUndefined();
+    });
+    it("omits required when absent (default optional)", () => {
+        const norm = normalizeDependency({ capability: "weather-api" });
+        expect(norm.required).toBeUndefined();
+    });
+    it("string-form deps are always optional", () => {
+        const norm = normalizeDependency("weather-api");
+        expect(norm.required).toBeUndefined();
+    });
+});
+describe("RouteRegistry stores required in route metadata (#1249)", () => {
+    it("persists required:true on the declared route dep", () => {
+        const registry = RouteRegistry.getInstance();
+        const routeId = registry.registerRoute("GET", "/x", [
+            { capability: "weather-api", required: true },
+            { capability: "logger" },
+        ]);
+        const meta = registry.getRoute(routeId);
+        expect(meta?.dependencies[0].required).toBe(true);
+        expect(meta?.dependencies[1].required).toBeUndefined();
+    });
+});
+describe("route perimeter 503 (#1249)", () => {
+    it("returns 503 before user code when a required dep is unavailable", async () => {
+        const handler = vi.fn();
+        const middleware = route([{ capability: "calculator", required: true }], handler);
+        const req = { method: "POST", path: "/compute", headers: {} };
+        const res = mockRes();
+        const next = vi.fn();
+        await middleware(req, res, next);
+        expect(res.status).toHaveBeenCalledWith(503);
+        expect(res.json).toHaveBeenCalledWith({
+            error: "dependency_unavailable",
+            capability: "calculator",
+        });
+        // User code must NOT run.
+        expect(handler).not.toHaveBeenCalled();
+        expect(next).not.toHaveBeenCalled();
+    });
+    it("runs the handler (no 503) when the required dep IS available", async () => {
+        const registry = RouteRegistry.getInstance();
+        const handler = vi.fn();
+        const middleware = route([{ capability: "calculator", required: true }], handler);
+        const mockCalc = (async () => "result");
+        registry.setDependency(middleware._meshRouteId, 0, mockCalc);
+        const req = { method: "POST", path: "/compute", headers: {} };
+        const res = mockRes();
+        const next = vi.fn();
+        await middleware(req, res, next);
+        expect(res.status).not.toHaveBeenCalled();
+        expect(handler).toHaveBeenCalledWith(req, res, expect.objectContaining({ calculator: mockCalc }));
+    });
+    it("does NOT 503 for an unavailable OPTIONAL dep (soft-fail preserved)", async () => {
+        const handler = vi.fn();
+        const middleware = route([{ capability: "calculator" }], handler);
+        const req = { method: "POST", path: "/compute", headers: {} };
+        const res = mockRes();
+        const next = vi.fn();
+        await middleware(req, res, next);
+        expect(res.status).not.toHaveBeenCalled();
+        // Handler runs with a null proxy — the existing degraded behavior.
+        expect(handler).toHaveBeenCalledWith(req, res, expect.objectContaining({ calculator: null }));
+    });
+    it("does NOT 503 when a duplicate capability is live in the winning slot", async () => {
+        // A capability declared twice collapses to one capability-keyed `deps`
+        // slot (last resolution wins). The perimeter must judge the same slot the
+        // handler sees — not a dead sibling index — so a live proxy means run.
+        const registry = RouteRegistry.getInstance();
+        const handler = vi.fn();
+        const middleware = route([
+            { capability: "calculator", required: true }, // required, its index unresolved
+            { capability: "calculator" }, // optional, this index is live → wins deps[cap]
+        ], handler);
+        const mockCalc = (async () => "result");
+        registry.setDependency(middleware._meshRouteId, 1, mockCalc);
+        const req = { method: "POST", path: "/compute", headers: {} };
+        const res = mockRes();
+        const next = vi.fn();
+        await middleware(req, res, next);
+        expect(res.status).not.toHaveBeenCalled();
+        expect(handler).toHaveBeenCalledWith(req, res, expect.objectContaining({ calculator: mockCalc }));
+    });
+    it("503s on the first unavailable required dep among a mix", async () => {
+        const registry = RouteRegistry.getInstance();
+        const handler = vi.fn();
+        const middleware = route([
+            { capability: "logger" }, // optional, unresolved
+            { capability: "calculator", required: true }, // required, resolved
+            { capability: "weather-api", required: true }, // required, unresolved
+        ], handler);
+        const mockCalc = (async () => "result");
+        registry.setDependency(middleware._meshRouteId, 1, mockCalc);
+        const req = { method: "POST", path: "/compute", headers: {} };
+        const res = mockRes();
+        const next = vi.fn();
+        await middleware(req, res, next);
+        expect(res.status).toHaveBeenCalledWith(503);
+        expect(res.json).toHaveBeenCalledWith({
+            error: "dependency_unavailable",
+            capability: "weather-api",
+        });
+        expect(handler).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=route-required.spec.js.map

package/dist/__tests__/route-required.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-required.spec.js","sourceRoot":"","sources":["../../src/__tests__/route-required.spec.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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"}

package/dist/agent.d.ts

@@ -38,6 +38,8 @@ export declare const IN_WORKER_SYMBOL: unique symbol;
  * module. Not part of the public API.
  */
 export declare function __getWorkerToolMap(): Map<string, (...args: unknown[]) => unknown>;
+/** Test support: drop the warn-once dedupe so a fresh suite warns again. */
+export declare function __resetUnwiredSlotWarnedForTests(): void;
 /**
  * MeshAgent wraps a FastMCP server with MCP Mesh capabilities.
  *
@@ -184,6 +186,23 @@ export declare class MeshAgent {
      * tool-A's bearer onto tool-B's outbound traffic.
      */
     private _bearerCacheKey;
+    /**
+     * Build the positional dependency-slot array for one tool call, shared by
+     * BOTH the inbound HTTP wrapper (wrappedExecute) and the claim-dispatch
+     * path (the ClaimHandler for task:true tools). Centralising this keeps the
+     * two slot-assembly sites identical:
+     *   - the MeshJob slot (meshJobDepIndex) → a freshly-bound MeshJobSubmitter
+     *   - every other slot → resolvedDeps.get(`${toolName}:dep_${index}`) ?? null
+     *
+     * #1231: a typed dep slot can resolve at the registry yet never receive an
+     * injected proxy, leaving the parameter null. Once the settle latch has
+     * flipped (during settling the proxy may still land), warn ONCE per
+     * tool+slot — the array is rebuilt per call, so a per-call warning would
+     * spam. The warn-once dedupe keys on `${toolName}:dep_${index}` via the
+     * module-level `_unwiredSlotWarned` Set, so a tool exercised via BOTH the
+     * inbound and claim paths warns at most once total.
+     */
+    private _buildDepSlots;
     private _getOrBuildA2AClient;
     /**
      * Convert Zod schema to JSON Schema.

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -16,7 +16,7 @@ import { enrichSchemaWithMediaTypes } from "./media-param.js";
 import { createProxy, normalizeDependency, runWithTraceContext, runWithPropagatedHeaders, PROXY_DISPATCH_META } from "./proxy.js";
 import { readJobHeaders, runWithJobContext, makeJobController, spliceJobController, } from "./inbound-job-dispatch.js";
 import { MeshJobSubmitter } from "./mesh-job-submitter.js";
-import { getSettleState } from "./settle.js";
+import { getSettleState, } from "./settle.js";
 import { ClaimDispatcher, stopDispatchers, } from "./claim-dispatcher.js";
 import { registerJobHelperTools } from "./jobs-helper-tools.js";
 import { registerCancelRoute } from "./jobs-cancel-route.js";
@@ -84,6 +84,16 @@ let autoStartScheduled = false;
 // pre-consumption danger zone, while sequential constructions across
 // async boundaries (e.g. one agent per test in a harness) stay allowed.
 let constructionGuardName = null;
+// #1231: warn-once dedupe for typed dependency slots that resolved at the
+// registry ("N/N deps resolved") but did not actually wire — the proxy was
+// never injected and the slot stays null. The deps array is rebuilt PER
+// CALL, so a per-call warn would spam; this set keys on `${toolName}:${dep}`
+// so each unwired slot warns exactly once per process.
+const _unwiredSlotWarned = new Set();
+/** Test support: drop the warn-once dedupe so a fresh suite warns again. */
+export function __resetUnwiredSlotWarnedForTests() {
+    _unwiredSlotWarned.clear();
+}
 // Schedule auto-start after module loading completes
 function scheduleAutoStart() {
     if (autoStartScheduled)
@@ -495,15 +505,7 @@ export class MeshAgent {
             // MeshJobSubmitter targeting that dep's capability. We bind the
             // submitter to the live registryUrl/agentId so it can submit
             // jobs without needing access to the agent instance.
-            const depsArray = normalizedDeps.map((dep, depIndex) => {
-                if (depIndex === meshJobDepIndex) {
-                    // Build the submitter lazily per call so we always pick
-                    // up the current registryUrl (test harnesses sometimes
-                    // mutate it between calls).
-                    return new MeshJobSubmitter(dep.capability, this.agentId, this.config.registryUrl);
-                }
-                return this.resolvedDeps.get(`${toolName}:dep_${depIndex}`) ?? null;
-            });
+            const depsArray = this._buildDepSlots(toolName, normalizedDeps, meshJobDepIndex, settleState);
             const injectedCount = depsArray.filter((d) => d !== null).length;
             // Extract trace context from arguments (injected by upstream proxy)
             // This is the fallback mechanism since fastmcp doesn't expose HTTP headers
@@ -619,11 +621,11 @@ export class MeshAgent {
                     result = await runWithTraceContext(traceContext, async () => {
                         return await runWithPropagatedHeaders(propagatedHeaders, async () => {
                             if (isTaskTool) {
-                                const [jobId, deadlineSecs] = readJobHeaders(propagatedHeaders);
+                                const [jobId, deadlineSecs, claimEpoch] = readJobHeaders(propagatedHeaders);
                                 let controller = null;
                                 if (jobId && this.config.registryUrl && this.agentId) {
                                     try {
-                                        controller = makeJobController(jobId, this.agentId, this.config.registryUrl);
+                                        controller = makeJobController(jobId, this.agentId, this.config.registryUrl, claimEpoch);
                                     }
                                     catch (err) {
                                         // Don't silently fall back to a regular tool call —
@@ -653,7 +655,7 @@ export class MeshAgent {
                                 if (a2aClient !== null) {
                                     callArgs.push(a2aClient);
                                 }
-                                return await runWithJobContext(jobId, deadlineSecs, controller, () => Promise.resolve(execute(...callArgs)), retryOn);
+                                return await runWithJobContext(jobId, deadlineSecs, controller, () => Promise.resolve(execute(...callArgs)), retryOn, claimEpoch);
                             }
                             if (a2aClient !== null) {
                                 return await execute(cleanArgs, ...depsArray, a2aClient);
@@ -753,12 +755,7 @@ export class MeshAgent {
                         await settleState.awaitPending(pendingSettle);
                     }
                 }
-                const liveDeps = normalizedDeps.map((dep, depIndex) => {
-                    if (depIndex === meshJobDepIndex) {
-                        return new MeshJobSubmitter(dep.capability, this.agentId, this.config.registryUrl);
-                    }
-                    return this.resolvedDeps.get(`${toolName}:dep_${depIndex}`) ?? null;
-                });
+                const liveDeps = this._buildDepSlots(toolName, normalizedDeps, meshJobDepIndex, settleState);
                 const callArgs = spliceJobController(payload, liveDeps, controller, meshJobParamIndex);
                 // Issue #917: A2A consumer tools dispatched via the claim
                 // path get the same trailing A2AClient argument as the
@@ -905,6 +902,48 @@ export class MeshAgent {
         }
         return id;
     }
+    /**
+     * Build the positional dependency-slot array for one tool call, shared by
+     * BOTH the inbound HTTP wrapper (wrappedExecute) and the claim-dispatch
+     * path (the ClaimHandler for task:true tools). Centralising this keeps the
+     * two slot-assembly sites identical:
+     *   - the MeshJob slot (meshJobDepIndex) → a freshly-bound MeshJobSubmitter
+     *   - every other slot → resolvedDeps.get(`${toolName}:dep_${index}`) ?? null
+     *
+     * #1231: a typed dep slot can resolve at the registry yet never receive an
+     * injected proxy, leaving the parameter null. Once the settle latch has
+     * flipped (during settling the proxy may still land), warn ONCE per
+     * tool+slot — the array is rebuilt per call, so a per-call warning would
+     * spam. The warn-once dedupe keys on `${toolName}:dep_${index}` via the
+     * module-level `_unwiredSlotWarned` Set, so a tool exercised via BOTH the
+     * inbound and claim paths warns at most once total.
+     */
+    _buildDepSlots(toolName, normalizedDeps, meshJobDepIndex, settleState) {
+        return normalizedDeps.map((dep, depIndex) => {
+            if (depIndex === meshJobDepIndex) {
+                // Build the submitter lazily per call so we always pick up the
+                // current registryUrl (test harnesses sometimes mutate it between
+                // calls).
+                return new MeshJobSubmitter(dep.capability, this.agentId, this.config.registryUrl);
+            }
+            const slotKey = `${toolName}:dep_${depIndex}`;
+            const proxy = this.resolvedDeps.get(slotKey) ?? null;
+            // #1231: a declared typed dep slot that is still null AFTER settling
+            // never received an injected proxy. Warn ONCE per tool+slot. Note this
+            // is a post-settle null — there is no per-slot "resolved" signal here,
+            // so the message must not claim registry resolution.
+            if (proxy === null && settleState.isSettled()) {
+                if (!_unwiredSlotWarned.has(slotKey)) {
+                    _unwiredSlotWarned.add(slotKey);
+                    console.warn(`[mesh-tool] dependency '${dep.capability}' on '${toolName}' ` +
+                        `is still null after settling — no proxy was injected into ` +
+                        `positional slot ${depIndex}. Fix: ensure the provider for ` +
+                        `'${dep.capability}' is registered and reachable.`);
+                }
+            }
+            return proxy;
+        });
+    }
     _getOrBuildA2AClient(config) {
         const key = [
             config.url,
@@ -1300,6 +1339,9 @@ export class MeshAgent {
                         expectedSchemaCanonical: expectedCanonical,
                         expectedSchemaHash: expectedHash,
                         matchMode: dep.matchMode,
+                        // Issue #1249: only carry `required` when opted in (absent →
+                        // false) so existing heartbeats stay byte-identical.
+                        required: dep.required ? true : undefined,
                     };
                 }),
                 inputSchema: meta.inputSchema,