@mcpmesh/sdk 2.8.1 → 3.0.0

package/dist/agent.js

@@ -8,12 +8,14 @@
  * - Dependency injection for tool functions
  * - Graceful shutdown
  */
+import { UserError } from "fastmcp";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { isMainThread } from "node:worker_threads";
 import { startAgent, } from "@mcpmesh/core";
+import { expandDependencies, isServiceView, MeshServiceUnavailableError, CAPABILITY_NAME_PATTERN, defaultProducerParams, } from "./service-view.js";
 import { resolveConfig, generateAgentIdSuffix, findAvailablePort, resolveStartupBindPort, MAX_CONSECUTIVE_NEXT_EVENT_FAILURES, NEXT_EVENT_BACKOFF_CAP_MS, } from "./config.js";
 import { enrichSchemaWithMediaTypes } from "./media-param.js";
-import { createProxy, normalizeDependency, runWithTraceContext, runWithPropagatedHeaders, PROXY_DISPATCH_META } from "./proxy.js";
+import { createProxy, 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";
@@ -275,6 +277,22 @@ export class MeshAgent {
     addTool(def) {
         const toolName = def.name;
         const execute = def.execute;
+        // Issue #1293 item 6: validate the PRODUCED capability name — the value
+        // published to the registry (def.capability ?? toolName) — against the
+        // segment-wise dotted grammar, closing the parity gap with the Go registry
+        // (src/core/registry/validation.go) and the Python runtime
+        // (support_types.py validate_capability_name). Only the produced capability
+        // is checked; dependency capability names are deliberately left unvalidated
+        // (they are unvalidated in the Go registry and every runtime), so checking
+        // them here would be stricter than the contract, not parity. Reuses the
+        // same CAPABILITY_NAME_PATTERN that addService applies to synthesized names.
+        const producedCapability = def.capability ?? toolName;
+        if (!CAPABILITY_NAME_PATTERN.test(producedCapability)) {
+            throw new Error(`addTool: capability '${producedCapability}' is not a valid capability ` +
+                `name — each dot-separated segment must start with a letter and ` +
+                `contain only letters, digits, underscores, and hyphens ` +
+                `(cross-ref src/core/registry/validation.go).`);
+        }
         // Phase 1 MeshJob substrate: validate `task: true` requires an
         // async function. Long-running tools need a Promise-based control
         // flow so the dispatch wrapper (Phase B) can await
@@ -387,6 +405,15 @@ export class MeshAgent {
                 }
             }
         }
+        // Issue #1277: validate resumeCursor at registration so misuse fails loud
+        // before the agent talks to the registry. Mirrors the retryOn check:
+        // resumeCursor requires task: true — only job-bound handlers have a
+        // controller (and a per-filter recvEvent cursor) to resume, so the flag
+        // is meaningless for synchronous tools.
+        if (def.resumeCursor === true && def.task !== true) {
+            throw new Error(`addTool({ resumeCursor }) for tool '${toolName}': resumeCursor is ` +
+                `only valid with task: true; remove resumeCursor or set task: true.`);
+        }
         // Issue #917: validate a2aConfig at registration time so misuse fails
         // loud BEFORE the agent talks to the registry. Match the Python
         // `mesh.a2a_consumer` and Java `@A2AConsumer` startup-time checks.
@@ -445,16 +472,42 @@ export class MeshAgent {
             _workerToolMap.set(toolName, execute);
             return this;
         }
-        // Normalize dependencies
-        const normalizedDeps = (def.dependencies ?? []).map(normalizeDependency);
+        // Normalize dependencies. RFC #1280: a `mesh.serviceView(...)` entry
+        // occupies ONE positional slot but expands into N ordinary edges (name-
+        // sorted, in-place). `normalizedDeps` is the FLAT edge array — the wire
+        // payload, settle keys, resolution events, and resolvedDeps all index it
+        // exactly as before; `depSlots` maps each positional execute slot to its
+        // edge (a `dep`) or edge-range (a `view`). For a view-free tool the edges
+        // are byte-identical to `deps.map(normalizeDependency)` and
+        // `depSlots[i].edgeIndex === i` — zero behavior change.
+        const { edges: normalizedDeps, slots: depSlots } = expandDependencies(def.dependencies ?? [], toolName);
         const depEndpoints = normalizedDeps.map((d) => d.capability);
+        // Phase 1 MeshJob substrate: meshJobDepIndex is an index into the AUTHORED
+        // dependencies array (i.e. a positional slot). It must point at an ordinary
+        // dependency slot, never a service-view slot (a view has no single edge to
+        // swap for a submitter).
+        if (def.meshJobDepIndex !== undefined) {
+            const slot = depSlots[def.meshJobDepIndex];
+            if (slot && slot.kind === "view") {
+                throw new Error(`addTool({ meshJobDepIndex: ${def.meshJobDepIndex} }) for tool ` +
+                    `'${toolName}' points at a mesh.serviceView slot — a MeshJob ` +
+                    `submitter can only replace an ordinary dependency slot.`);
+            }
+        }
+        // The flat edge index of the MeshJob submitter slot (if any). Used by the
+        // edge-indexed skip logic below (settle declaration/wait, required guard).
+        // For a view-free tool this equals `def.meshJobDepIndex` (slot index ===
+        // edge index), so those loops are byte-identical to before.
+        const meshJobEdgeIndex = def.meshJobDepIndex === undefined
+            ? undefined
+            : depSlots[def.meshJobDepIndex].edgeIndex;
         // Settling-window grace (#1193): declare this tool's proxy deps with the
         // process-wide settle state so the agent-level "all declared deps
         // resolved" latch can flip eagerly. The MeshJob slot is excluded — its
         // submitter is constructed locally, not resolved by an event.
         const settleState = getSettleState();
         normalizedDeps.forEach((_dep, depIndex) => {
-            if (depIndex !== def.meshJobDepIndex) {
+            if (depIndex !== meshJobEdgeIndex) {
                 settleState.registerDeclared(`${toolName}:dep_${depIndex}`);
             }
         });
@@ -468,6 +521,10 @@ export class MeshAgent {
         // registered in this.taskHandlers). Captured here so the closure
         // sees a stable reference even if def is mutated post-registration.
         const retryOn = def.retryOn;
+        // Issue #1277: per-tool durable-cursor resume opt-in. Captured here so
+        // the ClaimHandler registration below carries it into the dispatcher
+        // (which seeds the reclaimed controller from the claim's recv_cursor).
+        const resumeCursor = def.resumeCursor === true;
         // Phase 1 MeshJob substrate: when a job-bound tool exists AND the
         // user explicitly opted into worker isolation via env, log a single
         // warning at registration time. The wrapper force-disables
@@ -486,6 +543,18 @@ export class MeshAgent {
                 `(controllers/AsyncLocalStorage don't cross worker boundaries). ` +
                 `Set 'task: true' explicitly if you intend a producer.`);
         }
+        // RFC #1280: same force-disable + non-silent warning for view-bound tools.
+        // A serviceView facade wraps live closures over resolvedDeps and has no
+        // PROXY_DISPATCH_META, so it can't cross the worker_threads boundary — the
+        // wrapper runs view-bound tools inline. Warn once (like the job-bound case)
+        // so users who opted into MCP_MESH_TOOL_ISOLATION know it does not apply.
+        const isViewBoundForLog = depSlots.some((s) => s.kind === "view");
+        if (isViewBoundForLog && isolationEnvSet) {
+            console.warn(`[mesh-tool] '${toolName}' injects a mesh.serviceView facade; worker ` +
+                `isolation is disabled for view-bound tools (facades wrap live ` +
+                `closures over resolved dependencies that don't cross worker ` +
+                `boundaries).`);
+        }
         // Create wrapper that injects dependencies positionally and handles tracing
         const wrappedExecute = async (args) => {
             // Settling-window grace (#1193): while the agent is still settling,
@@ -497,7 +566,7 @@ export class MeshAgent {
                 const pendingSettle = [];
                 normalizedDeps.forEach((dep, depIndex) => {
                     const depKey = `${toolName}:dep_${depIndex}`;
-                    if (depIndex !== meshJobDepIndex &&
+                    if (depIndex !== meshJobEdgeIndex &&
                         !this.resolvedDeps.has(depKey)) {
                         pendingSettle.push({ depKey, capability: dep.capability });
                     }
@@ -506,14 +575,46 @@ export class MeshAgent {
                     await settleState.awaitPending(pendingSettle);
                 }
             }
-            // Build positional deps array using composite keys (toolName:dep_index)
-            // Phase 1 MeshJob substrate (consumer-side): if meshJobDepIndex is
-            // set, swap the McpMeshTool proxy at that slot for a
-            // 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 = this._buildDepSlots(toolName, normalizedDeps, meshJobDepIndex, settleState);
-            const injectedCount = depsArray.filter((d) => d !== null).length;
+            // Build positional deps array (one entry per authored slot). A view slot
+            // yields a facade; the MeshJob slot yields a MeshJobSubmitter; every other
+            // slot yields resolvedDeps.get(...) ?? null.
+            const depsArray = this._buildDepSlots(toolName, depSlots, normalizedDeps, meshJobDepIndex, settleState);
+            // Trace metric: count resolved EDGES, not slots — a view slot always
+            // yields a non-null facade, so counting slots would inflate the numerator
+            // against the edge-based dependency total. Excludes the MeshJob submitter
+            // edge (built locally, never a resolved proxy) and adds it back as one
+            // injected slot so a view-free tool's count is byte-identical to before.
+            let injectedCount = 0;
+            for (let e = 0; e < normalizedDeps.length; e++) {
+                if (e === meshJobEdgeIndex)
+                    continue;
+                if ((this.resolvedDeps.get(`${toolName}:dep_${e}`) ?? null) !== null) {
+                    injectedCount++;
+                }
+            }
+            if (meshJobDepIndex !== undefined)
+                injectedCount++;
+            // Issue #1273: detect a required dependency slot that is still
+            // unresolved AFTER the settle wait above (depsArray was built
+            // post-settle). The ACTION is deferred until the invocation flavor is
+            // known (see the flavor-aware guard below the header extraction) —
+            // direct tools/call refuses, an inbound JOB dispatch releases the
+            // lease. Optional deps keep null-passthrough; the MeshJob submitter
+            // slot is skipped (built locally, never a resolved proxy).
+            // Evaluate per-EDGE against resolvedDeps (not per-slot against depsArray):
+            // a view slot collapses N edges into one non-null facade, so a required
+            // view-method edge must be checked on the flat edge state. For a view-free
+            // tool this is equivalent to the old `depsArray[depIndex] == null` test.
+            let missingRequiredCap = null;
+            for (let depIndex = 0; depIndex < normalizedDeps.length; depIndex++) {
+                const dep = normalizedDeps[depIndex];
+                if (dep.required === true &&
+                    depIndex !== meshJobEdgeIndex &&
+                    (this.resolvedDeps.get(`${toolName}:dep_${depIndex}`) ?? null) == null) {
+                    missingRequiredCap = dep.capability;
+                    break;
+                }
+            }
             // Extract trace context from arguments (injected by upstream proxy)
             // This is the fallback mechanism since fastmcp doesn't expose HTTP headers
             let incomingTraceId = null;
@@ -521,6 +622,14 @@ export class MeshAgent {
             let cleanArgs = args;
             // Extract _mesh_headers from args for header propagation
             let propagatedHeaders = {};
+            // Issue #1273: the RAW inbound _mesh_headers, lowercased but NOT
+            // allowlist-filtered. Job-dispatch infra headers (x-mesh-job-id /
+            // x-mesh-claim-epoch) are the DISPATCH DISCRIMINATOR, deliberately kept
+            // OUT of the propagate allowlist (so a nested outbound call doesn't look
+            // like a job dispatch to every downstream). They must therefore be read
+            // from the raw map — reading them off `propagatedHeaders` would drop them
+            // and misclassify a genuine inbound job dispatch as a plain tools/call.
+            let rawMeshHeaders = null;
             if (args && typeof args === "object") {
                 const argsObj = args;
                 if (typeof argsObj._trace_id === "string") {
@@ -531,9 +640,14 @@ export class MeshAgent {
                 }
                 if (argsObj._mesh_headers && typeof argsObj._mesh_headers === "object") {
                     const meshHeaders = argsObj._mesh_headers;
-                    // Filter against allowlist
+                    rawMeshHeaders = {};
                     for (const [key, value] of Object.entries(meshHeaders)) {
-                        if (typeof value === "string" && matchesPropagateHeader(key)) {
+                        if (typeof value !== "string")
+                            continue;
+                        // Raw copy for job-dispatch detection (bypasses the allowlist).
+                        rawMeshHeaders[key.toLowerCase()] = value;
+                        // Allowlist-filtered copy for onward propagation.
+                        if (matchesPropagateHeader(key)) {
                             propagatedHeaders[key.toLowerCase()] = value;
                         }
                     }
@@ -549,6 +663,54 @@ export class MeshAgent {
             const spanId = generateSpanId();
             const parentSpanId = incomingParentSpan ?? null;
             const traceContext = { traceId, parentSpanId: spanId };
+            // Issue #1273: flavor-aware required-dependency guard. The claim path
+            // (requiredProbe, #1268) and the @mesh.route perimeter (503) already
+            // refuse before a handler can observe a null REQUIRED dep; the plain
+            // tool-dispatch path did not. A required dep flapping DOWN→UP flips the
+            // registry view available before THIS callee's own heartbeat refills
+            // its slot; a call landing in that window would invoke with a null
+            // required proxy. Now that the propagated headers are extracted we can
+            // tell the flavor apart:
+            //   - inbound JOB dispatch (task tool + X-Mesh-Job-Id) → RELEASE the
+            //     lease so the claimed row re-queues (retryable), mirroring the
+            //     claim path — NEVER a bare throw (which would strand the row
+            //     `working` until lease expiry) and never a terminal fail.
+            //   - plain tools/call → structured dependency_unavailable refusal
+            //     (UserError → isError result) so the caller classifies it as
+            //     retryable topology, not application failure.
+            if (missingRequiredCap !== null) {
+                // Read job headers from the RAW inbound map (not the allowlist-filtered
+                // propagatedHeaders), so a genuine inbound job dispatch is classified as
+                // one — and released, not refused — even though x-mesh-job-id is not in
+                // the propagate allowlist.
+                const [guardJobId, , guardClaimEpoch] = readJobHeaders(rawMeshHeaders);
+                const isJobDispatch = isTaskTool &&
+                    guardJobId !== null &&
+                    !!this.config.registryUrl &&
+                    !!this.agentId;
+                if (isJobDispatch) {
+                    console.warn(`[mesh-jobs] releasing job=${guardJobId} for tool '${toolName}' — ` +
+                        `required dependency '${missingRequiredCap}' unavailable at ` +
+                        `invocation time; releasing lease for retry (not invoking, not failing)`);
+                    try {
+                        const controller = makeJobController(guardJobId, this.agentId, this.config.registryUrl, guardClaimEpoch);
+                        await controller.releaseLease(`required dependency '${missingRequiredCap}' unavailable at ` +
+                            `job-dispatch (issue #1273)`);
+                    }
+                    catch (err) {
+                        console.debug(`[mesh-jobs] release-lease for job=${guardJobId} raised:`, err);
+                    }
+                    // The row is released and will be re-claimed; nothing to return.
+                    return "";
+                }
+                console.warn(`🚫 Tool '${toolName}': required dependency '${missingRequiredCap}' ` +
+                    `unavailable at invocation time — refusing with dependency_unavailable ` +
+                    `(not invoking the handler with a null required proxy)`);
+                throw new UserError(JSON.stringify({
+                    error: "dependency_unavailable",
+                    capability: missingRequiredCap,
+                }));
+            }
             const startTime = Date.now() / 1000;
             let success = true;
             let error = null;
@@ -576,8 +738,14 @@ export class MeshAgent {
             // cached client + connection pool intact across calls.
             const isA2aBound = a2aClient !== null;
             const isJobBound = isTaskTool || meshJobDepIndex !== undefined;
+            // RFC #1280: a service-view facade wraps live closures over resolvedDeps
+            // and cannot be serialised across the worker_threads boundary (it has no
+            // PROXY_DISPATCH_META). Force inline execution for view-bound tools, like
+            // job-bound and A2A-bound tools.
+            const isViewBound = depSlots.some((s) => s.kind === "view");
             const isolationEnabled = !isJobBound &&
                 !isA2aBound &&
+                !isViewBound &&
                 (process.env.MCP_MESH_TOOL_ISOLATION ?? "true").toLowerCase() !== "false";
             try {
                 let result;
@@ -753,7 +921,7 @@ export class MeshAgent {
                     const pendingSettle = [];
                     normalizedDeps.forEach((dep, depIndex) => {
                         const depKey = `${toolName}:dep_${depIndex}`;
-                        if (depIndex !== meshJobDepIndex &&
+                        if (depIndex !== meshJobEdgeIndex &&
                             !this.resolvedDeps.has(depKey)) {
                             pendingSettle.push({ depKey, capability: dep.capability });
                         }
@@ -762,7 +930,7 @@ export class MeshAgent {
                         await settleState.awaitPending(pendingSettle);
                     }
                 }
-                const liveDeps = this._buildDepSlots(toolName, normalizedDeps, meshJobDepIndex, settleState);
+                const liveDeps = this._buildDepSlots(toolName, depSlots, 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
@@ -779,7 +947,7 @@ export class MeshAgent {
             // covers both an absent key and an explicit null slot.
             const requiredSlots = [];
             normalizedDeps.forEach((dep, depIndex) => {
-                if (dep.required && depIndex !== meshJobDepIndex) {
+                if (dep.required && depIndex !== meshJobEdgeIndex) {
                     requiredSlots.push([depIndex, dep.capability]);
                 }
             });
@@ -794,7 +962,12 @@ export class MeshAgent {
                     return null;
                 }
                 : undefined;
-            this._taskHandlers.set(capability, { handler, retryOn, requiredProbe });
+            this._taskHandlers.set(capability, {
+                handler,
+                retryOn,
+                requiredProbe,
+                resumeCursor,
+            });
         }
         // Store mesh metadata with JSON Schema for LLM tool resolution
         const inputSchema = this.convertZodToJsonSchema(def.parameters);
@@ -805,6 +978,28 @@ export class MeshAgent {
         if (def.outputSchema) {
             outputSchemaRaw = this.convertZodToJsonSchema(def.outputSchema);
         }
+        // dependencyKwargs is authored per positional SLOT but consumed per flat
+        // EDGE (handleDependencyAvailable reads meta.dependencyKwargs[depIndex] with
+        // the event's edge index). For a view-free tool slot index === edge index,
+        // so pass it through unchanged (byte-identical). When a view slot is present,
+        // remap each slot's kwargs onto its edge(s) — a view's single kwargs entry
+        // applies to each of its method edges.
+        let edgeDependencyKwargs = def.dependencyKwargs;
+        if (def.dependencyKwargs && depSlots.some((s) => s.kind === "view")) {
+            const remapped = new Array(normalizedDeps.length);
+            depSlots.forEach((slot, slotIndex) => {
+                const kw = def.dependencyKwargs?.[slotIndex];
+                if (slot.kind === "dep") {
+                    remapped[slot.edgeIndex] = kw;
+                }
+                else {
+                    for (const m of slot.methods) {
+                        remapped[m.edgeIndex] = kw;
+                    }
+                }
+            });
+            edgeDependencyKwargs = remapped;
+        }
         this.tools.set(toolName, {
             capability: def.capability ?? toolName,
             version: def.version ?? "1.0.0",
@@ -815,7 +1010,7 @@ export class MeshAgent {
             // Issue #547 Phase 4: per-tool override (default true = current behavior).
             outputSchemaStrict: def.outputSchemaStrict !== false,
             dependencies: normalizedDeps,
-            dependencyKwargs: def.dependencyKwargs,
+            dependencyKwargs: edgeDependencyKwargs,
             // Phase 1 MeshJob substrate: stamp producer's long-running flag
             // so the heartbeat pipeline ships it to the registry. Consumers
             // read this to decide between job semantics and a regular
@@ -832,6 +1027,108 @@ export class MeshAgent {
         });
         return this;
     }
+    /**
+     * RFC #1280 producer sugar: publish each entry of `methods` as an ordinary
+     * mesh tool with capability `prefix.<method>`, routed through the SAME
+     * `addTool` machinery (schemas, heartbeat, DI, duplicate handling all fall
+     * out). Entries are registered NAME-SORTED for deterministic registration.
+     *
+     * Each entry is either a bare execute function (shorthand) or an object
+     * `{ execute, parameters?, tags?, version?, description?, dependencies?, ... }`
+     * carrying any `addTool` passthrough (but NOT `name`/`capability` — those are
+     * derived). A method with no `parameters` gets a permissive passthrough schema.
+     *
+     * The prefix AND every derived capability are validated against the segment-
+     * wise dotted grammar (kept in lockstep with the Go registry validator —
+     * src/core/registry/validation.go). addTool applies the same grammar to its
+     * produced capability (#1293 item 6), so both surfaces validate a PRODUCED
+     * capability name before it reaches the registry; dependency capability names
+     * remain the registry's authority.
+     *
+     * @example
+     * ```typescript
+     * agent.addService("media", {
+     *   caption: async (args) => ({ caption: `...${args.text}` }),
+     *   thumbnail: { execute: async (args) => ({ url: "..." }), tags: ["fast"] },
+     * });
+     * // → tools/capabilities "media.caption" and "media.thumbnail"
+     * ```
+     */
+    addService(prefix, methods) {
+        if (typeof prefix !== "string" || prefix.trim() === "") {
+            throw new Error("addService: a non-empty capability prefix is required " +
+                '(e.g. addService("media", { ... })).');
+        }
+        if (!CAPABILITY_NAME_PATTERN.test(prefix)) {
+            throw new Error(`addService: prefix '${prefix}' is not a valid capability name — each ` +
+                `dot-separated segment must start with a letter and contain only ` +
+                `letters, digits, '_' or '-' (cross-ref src/core/registry/validation.go).`);
+        }
+        if (methods == null || typeof methods !== "object") {
+            throw new Error(`addService("${prefix}", ...): methods must be an object mapping ` +
+                `method names to producer functions/definitions.`);
+        }
+        const names = Object.keys(methods).sort();
+        if (names.length === 0) {
+            throw new Error(`addService("${prefix}", ...): at least one method is required.`);
+        }
+        // Pass 1 — validate EVERY derived name/entry before registering any tool so
+        // an invalid method mid-map is atomic (registers nothing). Also rejects a
+        // derived capability that collides with an already-registered tool (scoped
+        // to addService: addTool's own last-wins behavior for hand-written tools is
+        // unchanged).
+        const prepared = [];
+        for (const method of names) {
+            const capability = `${prefix}.${method}`;
+            // Validate the FULL derived capability, not just the prefix: a method
+            // name may contain characters ('$', unicode, ...) the grammar rejects.
+            if (!CAPABILITY_NAME_PATTERN.test(capability)) {
+                throw new Error(`addService("${prefix}", ...): method '${method}' derives capability ` +
+                    `'${capability}', which is not a valid capability name (each ` +
+                    `dot-separated segment must start with a letter and contain only ` +
+                    `letters, digits, '_' or '-'). Rename the method.`);
+            }
+            if (this.tools.has(capability)) {
+                throw new Error(`addService("${prefix}", ...): method '${method}' derives tool/` +
+                    `capability '${capability}', which is already registered. Rename ` +
+                    `the method or the conflicting tool.`);
+            }
+            const entry = methods[method];
+            // Guard: a service-view value here is the consumer surface used in the
+            // wrong role (producer). Fail loud.
+            if (isServiceView(entry)) {
+                throw new Error(`addService("${prefix}", ...): method '${method}' is a ` +
+                    `mesh.serviceView(...) — that is a CONSUMER view, not a producer ` +
+                    `method. Provide an execute function or { execute, ... } object.`);
+            }
+            let def;
+            if (typeof entry === "function") {
+                def = { execute: entry };
+            }
+            else if (entry != null &&
+                typeof entry === "object" &&
+                typeof entry.execute === "function") {
+                def = entry;
+            }
+            else {
+                throw new Error(`addService("${prefix}", ...): method '${method}' must be an execute ` +
+                    `function or an object with an execute function.`);
+            }
+            prepared.push({ capability, def });
+        }
+        // Pass 2 — register through the existing addTool machinery. Derived name ===
+        // derived capability for deterministic uniqueness.
+        for (const { capability, def } of prepared) {
+            this.addTool({
+                ...def,
+                name: capability,
+                capability,
+                parameters: def.parameters ?? defaultProducerParams(),
+                execute: def.execute,
+            });
+        }
+        return this;
+    }
     /**
      * Add an LLM provider to the agent.
      *
@@ -935,27 +1232,36 @@ export class MeshAgent {
      * 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:
+     * two slot-assembly sites identical. One entry per AUTHORED slot:
+     *   - a service-view slot (RFC #1280) → a facade over its method edges
      *   - the MeshJob slot (meshJobDepIndex) → a freshly-bound MeshJobSubmitter
-     *   - every other slot → resolvedDeps.get(`${toolName}:dep_${index}`) ?? null
+     *   - every other slot → resolvedDeps.get(`${toolName}:dep_${edgeIndex}`) ?? null
+     *
+     * `depSlots` carries the slot→edge mapping (a `dep` slot owns one edge; a
+     * `view` slot owns a contiguous edge range). `edges` is the flat edge array;
+     * a slot's proxy/capability is read via its edge index.
      *
      * #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
+     * spam. The warn-once dedupe keys on `${toolName}:dep_${edgeIndex}` 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) {
+    _buildDepSlots(toolName, depSlots, edges, meshJobDepIndex, settleState) {
+        return depSlots.map((slot, slotIndex) => {
+            if (slot.kind === "view") {
+                return this._buildServiceViewFacade(toolName, slot, edges, settleState);
+            }
+            const edgeIndex = slot.edgeIndex;
+            if (slotIndex === 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 new MeshJobSubmitter(edges[edgeIndex].capability, this.agentId, this.config.registryUrl);
             }
-            const slotKey = `${toolName}:dep_${depIndex}`;
+            const slotKey = `${toolName}:dep_${edgeIndex}`;
             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
@@ -964,15 +1270,111 @@ export class MeshAgent {
             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.`);
+                    console.warn(`[mesh-tool] dependency '${edges[edgeIndex].capability}' on ` +
+                        `'${toolName}' is still null after settling — no proxy was ` +
+                        `injected into positional slot ${slotIndex}. Fix: ensure the ` +
+                        `provider for '${edges[edgeIndex].capability}' is registered ` +
+                        `and reachable.`);
                 }
             }
             return proxy;
         });
     }
+    /**
+     * RFC #1280: build the facade injected at a service-view slot. Each facade
+     * method reads its edge's CURRENT proxy from `resolvedDeps` at call time —
+     * rebinding-free: a `dependency_available`/`unavailable` event swapping the
+     * per-edge proxy is observed on the next call without rebuilding the facade.
+     *
+     * The `minAvailable` floor is enforced BEFORE delegation on every call: below
+     * the floor during the settling window (#1193) the method performs the same
+     * bounded, capability-keyed wait the injected-proxy path uses, recounts, then
+     * throws {@link MeshServiceUnavailableError}. An unresolved OPTIONAL method
+     * edge throws a `TypeError` — the same failure shape a directly-injected
+     * unresolved `McpMeshTool` (a null proxy) produces when called.
+     */
+    _buildServiceViewFacade(toolName, slot, edges, settleState) {
+        const total = slot.methods.length;
+        const floor = slot.minAvailable;
+        const viewName = slot.name;
+        const countAvailable = () => {
+            let n = 0;
+            for (const m of slot.methods) {
+                if ((this.resolvedDeps.get(`${toolName}:dep_${m.edgeIndex}`) ?? null) !== null) {
+                    n++;
+                }
+            }
+            return n;
+        };
+        const enforceFloor = async () => {
+            if (floor <= 0)
+                return;
+            let available = countAvailable();
+            // Below the floor during the settling window: perform a bounded wait that
+            // RACES all of the view's still-pending edges (wake on ANY resolution),
+            // recounts, and breaks the moment the floor is met — so a call gated on
+            // the floor wakes when ANY qualifying edge lands, never sleeping the full
+            // window on a still-pending sibling key. Once settled the waits are
+            // no-ops and the floor fails fast.
+            while (available < floor &&
+                !settleState.isSettled() &&
+                settleState.remainingMs() > 0) {
+                // Only edges that can still fire a settle WAKE are worth waiting on: a
+                // key already in the settle ratchet (resolved at least once) will never
+                // re-fire its waiter, so if such an edge has since flapped to a null
+                // proxy `waitForAny` would filter it out and return immediately — a hot
+                // busy-loop until the window expires. Excluding ratchet-resolved keys
+                // here means `pending` empties and we break to the final recount/throw
+                // the instant no wakeable edge remains (no spin).
+                const pending = [];
+                for (const m of slot.methods) {
+                    const key = `${toolName}:dep_${m.edgeIndex}`;
+                    if ((this.resolvedDeps.get(key) ?? null) === null &&
+                        !settleState.isResolved(key)) {
+                        pending.push({ depKey: key, capability: edges[m.edgeIndex].capability });
+                    }
+                }
+                if (pending.length === 0)
+                    break;
+                await settleState.waitForAny(pending);
+                available = countAvailable();
+            }
+            if (available < floor) {
+                throw new MeshServiceUnavailableError(viewName, available, total, floor);
+            }
+        };
+        const facade = {};
+        for (const m of slot.methods) {
+            const key = `${toolName}:dep_${m.edgeIndex}`;
+            const capability = edges[m.edgeIndex].capability;
+            // #1231 parity for view edges: a method edge that resolved at the registry
+            // yet never received an injected proxy stays null after settling. Warn
+            // ONCE per tool+edge (facade is rebuilt per call), naming the view method
+            // and capability so the diagnostic matches the slot-dep warning.
+            if ((this.resolvedDeps.get(key) ?? null) === null && settleState.isSettled()) {
+                if (!_unwiredSlotWarned.has(key)) {
+                    _unwiredSlotWarned.add(key);
+                    console.warn(`[mesh-tool] service view '${viewName}' method '${m.method}' ` +
+                        `(capability '${capability}') on '${toolName}' is still null ` +
+                        `after settling — no proxy was injected. Fix: ensure the provider ` +
+                        `for '${capability}' is registered and reachable.`);
+                }
+            }
+            facade[m.method] = async (args, options) => {
+                await enforceFloor();
+                const proxy = this.resolvedDeps.get(key) ?? null;
+                if (proxy === null) {
+                    // Mirror the failure shape of calling an unresolved McpMeshTool
+                    // (a null proxy) directly — a TypeError.
+                    throw new TypeError(`service view '${viewName}' method '${m.method}' (capability ` +
+                        `'${capability}') is unavailable — the dependency did not ` +
+                        `resolve (unresolved optional edge).`);
+                }
+                return proxy(args, options);
+            };
+        }
+        return facade;
+    }
     _getOrBuildA2AClient(config) {
         const key = [
             config.url,
@@ -1180,7 +1582,7 @@ export class MeshAgent {
         if (this._taskHandlers.size === 0)
             return;
         for (const [capability, entry] of this._taskHandlers.entries()) {
-            const dispatcher = new ClaimDispatcher(capability, this.agentId, this.config.registryUrl, entry.handler, entry.retryOn, entry.requiredProbe);
+            const dispatcher = new ClaimDispatcher(capability, this.agentId, this.config.registryUrl, entry.handler, entry.retryOn, entry.requiredProbe, entry.resumeCursor);
             dispatcher.start();
             this._claimDispatchers.push(dispatcher);
         }