@vurb/swarm 3.8.2

package/dist/UpstreamMcpClient.js

@@ -0,0 +1,266 @@
+/**
+ * Federated Handoff Protocol — Upstream MCP Client
+ *
+ * Outbound MCP client that tunnels from the SwarmGateway to an upstream
+ * micro-server. Implements:
+ *
+ * - **AbortSignal cascade**: closing the parent connection aborts the tunnel
+ * - **Connect timeout**: the timeout AbortController cancels the in-flight HTTP request
+ * - **Idle timeout**: closes zombie tunnels after configurable inactivity
+ * - **Progress passthrough**: pipes `notifications/progress` and
+ *   `notifications/message` from upstream back to the LLM client
+ *
+ * @module
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/**
+ * Outbound MCP client for the SwarmGateway B2BUA face.
+ *
+ * One instance per active handoff session. Closed via `dispose()` or
+ * automatically when the idle timeout or AbortSignal fires.
+ */
+export class UpstreamMcpClient {
+    _targetUri;
+    _config;
+    _abortController;
+    // keep ref to listener so we can remove it in dispose() to prevent
+    // the closure from holding a reference to this instance after the session ends.
+    _onParentAbort;
+    _parentSignal;
+    _client;
+    _idleTimer;
+    _progressForwarder;
+    // tracks concurrent tool calls to suspend the idle timer during execution
+    _activeCalls = 0;
+    // set to true by dispose() to prevent orphan timers from firing
+    _disposed = false;
+    constructor(_targetUri, _config, parentSignal) {
+        this._targetUri = _targetUri;
+        this._config = _config;
+        this._abortController = new AbortController();
+        // save ref to both signal and listener for cleanup in dispose().
+        // Using `{ once: true }` auto-removes on fire, but NOT on voluntary dispose().
+        // Without explicit removal, the closure keeps this entire instance alive
+        // in memory for as long as parentSignal lives (typically the MCP connection lifetime).
+        this._onParentAbort = () => this._abortController.abort();
+        this._parentSignal = parentSignal;
+        parentSignal.addEventListener('abort', this._onParentAbort, { once: true });
+    }
+    /** Register a forwarder for upstream progress/logging notifications. */
+    setProgressForwarder(forwarder) {
+        this._progressForwarder = forwarder;
+    }
+    /**
+     * Connect to the upstream server.
+     *
+     * @throws `Error` with `code: 'UPSTREAM_CONNECT_TIMEOUT'` if unreachable within `connectTimeoutMs`
+     */
+    async connect() {
+        const headers = {
+            'x-vurb-delegation': this._config.delegationToken,
+        };
+        if (this._config.traceparent) {
+            headers['traceparent'] = this._config.traceparent;
+        }
+        // use a dedicated connect-phase controller merged with the session-lifetime
+        // signal. The SSEClientTransport holds the signal for the full SSE stream lifetime,
+        // so it must be the session signal — not the one-shot connect timeout signal.
+        // We create a merged signal that fires on either: (a) connect timeout, or (b) session abort.
+        const connectController = new AbortController();
+        // AbortSignal.any is available in Node ≥18.17.
+        // the old fallback used only connectController.signal, ignoring
+        // _abortController.signal entirely on older runtimes. This meant a parent-abort
+        // during connect() would not cancel the in-flight TCP/HTTP request immediately.
+        // The manual merge below ensures both signals are observed on all runtimes.
+        const connectSignal = typeof AbortSignal.any === 'function'
+            ? AbortSignal.any([connectController.signal, this._abortController.signal])
+            : (() => {
+                const mergedController = new AbortController();
+                const abort = () => mergedController.abort();
+                connectController.signal.addEventListener('abort', abort, { once: true });
+                this._abortController.signal.addEventListener('abort', abort, { once: true });
+                return mergedController.signal;
+            })();
+        const transport = this._resolveTransport(headers, connectSignal);
+        // do NOT set this._client before the promise settles.
+        // We use a local variable during connect; only assign to this._client on success.
+        const client = new Client({ name: 'vurb-swarm-gateway', version: '0.1.0' });
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                connectController.abort(); // cancel the in-flight request
+                reject(Object.assign(new Error(`[vurb/swarm] Upstream "${this._targetUri}" did not respond within ${this._config.connectTimeoutMs}ms.`), { code: 'UPSTREAM_CONNECT_TIMEOUT' }));
+            }, this._config.connectTimeoutMs);
+            void client.connect(transport).then(() => {
+                clearTimeout(timer);
+                resolve();
+            }, (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+        // only set this._client AFTER a successful connect.
+        // If the promise above rejected (timeout, network error), this line is never reached
+        // and _client remains undefined — _assertConnected() correctly blocks further calls.
+        this._client = client;
+        this._wireNotifications();
+        this._resetIdleTimer();
+    }
+    /** List all tools exposed by the upstream server. */
+    async listTools() {
+        this._assertConnected();
+        // apply the same idle-timer suspension pattern as callTool.
+        // Without this, a slow upstream (large tool list) could cause the idle timer
+        // to fire mid-awaiting the listTools RPC and close the tunnel prematurely.
+        this._activeCalls++;
+        clearTimeout(this._idleTimer);
+        this._idleTimer = undefined;
+        try {
+            // declare inside the try block (same pattern as callTool)
+            // so TypeScript never infers `response` as `T | undefined` outside it.
+            const response = await this._client.listTools();
+            return response.tools;
+        }
+        finally {
+            this._activeCalls--;
+            if (this._activeCalls === 0) {
+                this._resetIdleTimer();
+            }
+        }
+    }
+    /**
+     * Call a tool on the upstream server.
+     * @param name   - Tool name (without namespace prefix)
+     * @param args   - Tool arguments
+     * @param signal - AbortSignal from the parent tools/call request
+     */
+    async callTool(name, args, signal) {
+        this._assertConnected();
+        // suspend the idle timer while a tool call is in progress.
+        // Previously, the timer was reset only at the START of the call. A long-running
+        // tool (e.g., 4+ minutes) would not reset the timer on completion, causing
+        // the tunnel to close while the tool is still executing. Now we pause the
+        // timer during the call and restart it only after the call completes.
+        this._activeCalls++;
+        clearTimeout(this._idleTimer);
+        this._idleTimer = undefined;
+        // declare result inside the try block (same pattern as listTools after ).
+        // With `let result` outside, TypeScript infers `result: T | undefined` — if callTool()
+        // throws, `result.content` below would never execute but TS doesn't know that.
+        // Moving everything inside the try makes the types strict and intent crystal-clear.
+        try {
+            const result = await this._client.callTool({ name, arguments: args }, undefined, { signal });
+            // ToolResponse only supports type:'text'. Produce human-readable representations
+            // for non-text blocks (image, resource, audio) rather than losing type information
+            // via a raw JSON.stringify. LLMs benefit from knowing what was returned.
+            const content = result.content.map(c => {
+                if (c.type === 'text') {
+                    return { type: 'text', text: c.text ?? '' };
+                }
+                if (c.type === 'image') {
+                    const size = c.data?.length ?? 0;
+                    return { type: 'text', text: `[Image (${c.mimeType ?? 'unknown type'}); ${size} base64 chars — not renderable as text]` };
+                }
+                if (c.type === 'resource') {
+                    return { type: 'text', text: `[Resource: ${JSON.stringify(c.resource)}]` };
+                }
+                return { type: 'text', text: `[${c.type}: ${JSON.stringify(c)}]` };
+            });
+            return { content, isError: result.isError === true };
+        }
+        finally {
+            this._activeCalls--;
+            // Restart the idle timer only when no other calls are pending
+            if (this._activeCalls === 0) {
+                this._resetIdleTimer();
+            }
+        }
+    }
+    /** Close the connection and clear all timers. */
+    async dispose() {
+        // mark as disposed FIRST so any in-flight finally blocks
+        // (e.g. callTool's _activeCalls--) won't restart the idle timer.
+        this._disposed = true;
+        // remove the parent signal listener to break the closure reference.
+        // Without this, parentSignal retains a reference to this instance for its entire
+        // lifetime (usually the MCP connection), preventing GC after the session ends.
+        this._parentSignal.removeEventListener('abort', this._onParentAbort);
+        clearTimeout(this._idleTimer);
+        this._abortController.abort();
+        try {
+            await this._client?.close();
+        }
+        catch {
+            // Best-effort close — swallow errors during cleanup
+        }
+        this._client = undefined;
+    }
+    // ── Private ─────────────────────────────────────────────
+    _assertConnected() {
+        if (!this._client) {
+            throw new Error('[vurb/swarm] UpstreamMcpClient is not connected. Call connect() first.');
+        }
+    }
+    /**
+     * Build the MCP transport for the given headers and connect-phase abort signal.
+     *
+     * The `connectSignal` is only used for the initial TCP/SSE handshake.
+     * It is NOT the same as the session lifetime signal (`_abortController`).
+     *
+     * `mcps://` (secure MCP) is mapped to `https://`.
+     */
+    _resolveTransport(headers, sessionSignal) {
+        const mode = this._config.transport ?? 'auto';
+        const useHttp = mode === 'http' ||
+            (mode === 'auto' && typeof globalThis['EdgeRuntime'] !== 'undefined');
+        const url = new URL(this._targetUri
+            .replace(/^mcps:\/\//, 'https://') // secure MCP scheme
+            .replace(/^mcp:\/\//, 'http://'));
+        if (useHttp) {
+            return new StreamableHTTPClientTransport(url, {
+                requestInit: { headers, signal: sessionSignal },
+            });
+        }
+        return new SSEClientTransport(url, {
+            requestInit: { headers, signal: sessionSignal },
+        });
+    }
+    /**
+     * Register notification handlers with correctly typed wrappers.
+     *
+     * The MCP SDK's `setNotificationHandler` expects a Zod schema as the first argument.
+     * We create a minimal compliant object that satisfies the runtime duck-type without
+     * importing Zod directly (the SDK validates at transport level, not via our schema).
+     * The `as never` cast is retained on the schema only — all handler types are explicit.
+     */
+    _wireNotifications() {
+        if (!this._client)
+            return;
+        // include safeParse() so future MCP SDK versions that call it
+        // don't silently break notification forwarding. The cast to `never` is retained
+        // only on the schema argument — handler types remain explicit.
+        const makeSchema = (method) => ({
+            parse: (v) => v,
+            safeParse: (v) => ({ success: true, data: v }),
+            shape: { method: { value: method } },
+        });
+        this._client.setNotificationHandler(makeSchema('notifications/progress'), (n) => {
+            this._progressForwarder?.({ method: 'notifications/progress', params: n.params ?? {} });
+        });
+        this._client.setNotificationHandler(makeSchema('notifications/message'), (n) => {
+            this._progressForwarder?.({ method: 'notifications/message', params: n.params ?? {} });
+        });
+    }
+    _resetIdleTimer() {
+        // never restart the timer after dispose() — that would schedule
+        // another dispose() call on a dead client, leaking the timer handle.
+        if (this._disposed)
+            return;
+        clearTimeout(this._idleTimer);
+        this._idleTimer = setTimeout(() => {
+            void this.dispose();
+        }, this._config.idleTimeoutMs);
+    }
+}
+//# sourceMappingURL=UpstreamMcpClient.js.map

package/dist/UpstreamMcpClient.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @vurb/swarm — Federated Handoff Protocol
+ *
+ * Multi-agent orchestration for Vurb MCP servers.
+ * Implements the SwarmGateway B2BUA pattern for secure, efficient
+ * agent handoffs with zero-trust delegation and distributed tracing.
+ *
+ * @example Gateway setup
+ * ```typescript
+ * import { SwarmGateway } from '@vurb/swarm';
+ * import { f } from '@vurb/core';
+ *
+ * const gateway = new SwarmGateway({
+ *     registry: { finance: 'http://finance-agent:8081' },
+ *     delegationSecret: process.env.VURB_DELEGATION_SECRET!,
+ * });
+ *
+ * export const triage = f.tool('system.triage')
+ *     .withEnum('domain', ['finance', 'devops'])
+ *     .withString('context', 'What the user needs.')
+ *     .handle(async (input) => f.handoff(`mcp://${input.domain}-agent`, {
+ *         carryOverState: { intent: input.context },
+ *         reason: `Triage → ${input.domain}`,
+ *     }));
+ * ```
+ *
+ * @example Upstream micro-server
+ * ```typescript
+ * import { requireGatewayClearance } from '@vurb/core';
+ *
+ * export const refund = f.tool('finance.refund')
+ *     .use(requireGatewayClearance(process.env.VURB_DELEGATION_SECRET!))
+ *     .withString('invoiceId', 'Invoice ID')
+ *     .handle(async (input, ctx) => success(await stripe.refund(input.invoiceId)));
+ * ```
+ *
+ * @module
+ */
+export { SwarmGateway } from './SwarmGateway.js';
+export type { SwarmGatewayConfig } from './SwarmGateway.js';
+export { UpstreamMcpClient } from './UpstreamMcpClient.js';
+export type { UpstreamMcpClientConfig, ProgressForwarder, ProgressNotification } from './UpstreamMcpClient.js';
+export { NamespaceRewriter, NamespaceError } from './NamespaceRewriter.js';
+export { injectReturnTripTool, formatSafeReturn } from './ReturnTripInjector.js';
+export { handoff, isHandoffResponse, mintDelegationToken, verifyDelegationToken, HandoffAuthError, InMemoryHandoffStateStore, requireGatewayClearance, } from '@vurb/core';
+export type { HandoffPayload, HandoffResponse, HandoffStateStore, DelegationClaims, GatewayClearanceContext, } from '@vurb/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG/G,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAMjF,OAAO,EACH,OAAO,EAAE,iBAAiB,EAC1B,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAC5D,yBAAyB,EACzB,uBAAuB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EACR,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAClD,gBAAgB,EAChB,uBAAuB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,51 @@
+/**
+ * @vurb/swarm — Federated Handoff Protocol
+ *
+ * Multi-agent orchestration for Vurb MCP servers.
+ * Implements the SwarmGateway B2BUA pattern for secure, efficient
+ * agent handoffs with zero-trust delegation and distributed tracing.
+ *
+ * @example Gateway setup
+ * ```typescript
+ * import { SwarmGateway } from '@vurb/swarm';
+ * import { f } from '@vurb/core';
+ *
+ * const gateway = new SwarmGateway({
+ *     registry: { finance: 'http://finance-agent:8081' },
+ *     delegationSecret: process.env.VURB_DELEGATION_SECRET!,
+ * });
+ *
+ * export const triage = f.tool('system.triage')
+ *     .withEnum('domain', ['finance', 'devops'])
+ *     .withString('context', 'What the user needs.')
+ *     .handle(async (input) => f.handoff(`mcp://${input.domain}-agent`, {
+ *         carryOverState: { intent: input.context },
+ *         reason: `Triage → ${input.domain}`,
+ *     }));
+ * ```
+ *
+ * @example Upstream micro-server
+ * ```typescript
+ * import { requireGatewayClearance } from '@vurb/core';
+ *
+ * export const refund = f.tool('finance.refund')
+ *     .use(requireGatewayClearance(process.env.VURB_DELEGATION_SECRET!))
+ *     .withString('invoiceId', 'Invoice ID')
+ *     .handle(async (input, ctx) => success(await stripe.refund(input.invoiceId)));
+ * ```
+ *
+ * @module
+ */
+// ── Gateway ──────────────────────────────────────────────
+export { SwarmGateway } from './SwarmGateway.js';
+// ── Client (upstream connection) ─────────────────────────
+export { UpstreamMcpClient } from './UpstreamMcpClient.js';
+// ── Utilities ────────────────────────────────────────────
+export { NamespaceRewriter, NamespaceError } from './NamespaceRewriter.js';
+export { injectReturnTripTool, formatSafeReturn } from './ReturnTripInjector.js';
+// ── FHP primitives (re-exported from @vurb/core) ────────
+// Provided here for convenience — teams importing from @vurb/swarm
+// get the full FHP API surface without a separate @vurb/core import.
+// The canonical source is always @vurb/core.
+export { handoff, isHandoffResponse, mintDelegationToken, verifyDelegationToken, HandoffAuthError, InMemoryHandoffStateStore, requireGatewayClearance, } from '@vurb/core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,4DAA4D;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,4DAA4D;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,4DAA4D;AAC5D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEjF,2DAA2D;AAC3D,mEAAmE;AACnE,qEAAqE;AACrE,6CAA6C;AAC7C,OAAO,EACH,OAAO,EAAE,iBAAiB,EAC1B,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAC5D,yBAAyB,EACzB,uBAAuB,GAC1B,MAAM,YAAY,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@vurb/swarm",
+  "version": "3.8.2",
+  "description": "Federated Handoff Protocol for Vurb — SwarmGateway B2BUA, multi-agent orchestration, zero-trust delegation, and upstream MCP client tunneling.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "vurb",
+    "swarm",
+    "multi-agent",
+    "handoff",
+    "gateway",
+    "b2bua",
+    "federation",
+    "ai",
+    "llm",
+    "delegation",
+    "zero-trust"
+  ],
+  "author": "Renato Marinho",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vinkius-labs/vurb.ts.git",
+    "directory": "packages/swarm"
+  },
+  "bugs": {
+    "url": "https://github.com/vinkius-labs/vurb.ts/issues"
+  },
+  "homepage": "https://vurb.vinkius.com/",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@vurb/core": "^3.8.0",
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@vurb/core": ">=3.8.0",
+    "rimraf": "^6.0.0",
+    "vitest": "^3.0.0"
+  }
+}