@mcpmesh/sdk 2.8.2 → 3.0.1

package/dist/agent.d.ts

@@ -12,6 +12,7 @@ import type { FastMCP } from "fastmcp";
 import type { z } from "zod";
 import { type JsAgentHandle } from "@mcpmesh/core";
 import type { AgentConfig, ResolvedAgentConfig, MeshToolDef, McpMeshTool, LlmProviderConfig } from "./types.js";
+import { type ServiceProducerMethod } from "./service-view.js";
 /**
  * Globally-set symbol that user agent code can check to detect whether it
  * is running inside a mesh tool-isolation worker. The mesh runtime sets
@@ -40,6 +41,7 @@ export declare const IN_WORKER_SYMBOL: unique symbol;
 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;
+export declare function depSignature(endpoint: string, functionName: string, kwargs: unknown, agentId: string): string;
 /**
  * MeshAgent wraps a FastMCP server with MCP Mesh capabilities.
  *
@@ -98,6 +100,7 @@ export declare class MeshAgent {
      * different tags/settings without overwriting each other.
      */
     private resolvedDeps;
+    private appliedDepSignatures;
     private _workerMode;
     /**
      * Phase 1 MeshJob substrate: per-tool ClaimHandler for `task: true`
@@ -150,6 +153,34 @@ export declare class MeshAgent {
      * they will be injected positionally at runtime.
      */
     addTool<T extends z.ZodType>(def: MeshToolDef<T>): 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: string, methods: Record<string, ServiceProducerMethod>): this;
     /**
      * Add an LLM provider to the agent.
      *
@@ -197,19 +228,38 @@ export declare 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.
      */
     private _buildDepSlots;
+    /**
+     * 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.
+     */
+    private _buildServiceViewFacade;
     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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"}