@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/flows-actors/services/mcp-client.backend.service.d.ts

@@ -0,0 +1,90 @@
+import type { FlowsActors_McpServer } from '@wildo-ai/saas-models';
+import { type McpDiscoveryOutcome, type McpSession, type McpToolCallOutcome } from '../../flows-actors/models/mcp-client.backend.definitions';
+/**
+ * An MCP client over the Streamable HTTP transport.
+ *
+ * ## Why this is hand-written rather than an SDK
+ *
+ * The subset an agent turn needs is three methods — `initialize`, `tools/list`, `tools/call` — over
+ * JSON-RPC. Taking a runtime dependency for that would put the parts this engine must own most
+ * (which targets are refusable, what a timeout costs, what reaches an audit row, what a failure
+ * means to an agent) behind somebody else's abstractions, and it runs against the standing position
+ * that Wildo does not take runtime dependencies on third-party integration packages.
+ *
+ * ## What it is NOT
+ *
+ * Not a second kind of local function (#491). Every method returns a typed OUTCOME and never throws
+ * into the turn, because the failure modes an agent must distinguish — refused, unreachable, timed
+ * out, malformed, or the tool's own error — do not exist for a local call and cannot be flattened
+ * into one exception without losing the distinction that decides what happens next.
+ *
+ * spec-cite: MCP 2025-06-18 — Transports §Streamable HTTP for the request shape, session header and
+ * dual response content types; Lifecycle for the initialize/initialized handshake; Tools for
+ * `tools/list` and `tools/call`.
+ */
+export declare class McpClientBackendService {
+    /**
+     * Open a session and discover the server's tools, bounded by the server's DISCOVERY budget.
+     *
+     * Discovery is where an unreachable server is meant to be found. A server that does not answer
+     * here contributes no tools to the turn, and the agent is never offered a capability it cannot
+     * use — fail-closed on the CLAIM, fail-open on the turn.
+     */
+    openSession(server: FlowsActors_McpServer, accessToken: string | null): Promise<McpDiscoveryOutcome>;
+    /**
+     * Call one tool, bounded by the server's CALL budget — a separate and larger budget than
+     * discovery, because doing the work legitimately takes longer than listing what can be done.
+     */
+    callTool(session: McpSession, toolName: string, args: Record<string, unknown>, accessToken: string | null): Promise<McpToolCallOutcome>;
+    /**
+     * Release a session, best-effort.
+     *
+     * Deliberately returns nothing and reports nothing. A server MAY refuse to let a client terminate
+     * a session, so a failure here is an expected shape rather than a fault — and a turn that has
+     * already produced its answer must not fail on tidying up after itself.
+     */
+    closeSession(session: McpSession, accessToken: string | null): Promise<void>;
+    /**
+     * The one place this service touches the network.
+     *
+     * A protected seam rather than an injected `fetch`, so nothing in production can substitute it and
+     * the DI binding stays parameterless. Tests subclass to drive the protocol deterministically —
+     * which they must, because the outbound guard REFUSES loopback and every private range, so a real
+     * local double could only ever produce `REFUSED_TARGET`. That refusal is itself pinned, against a
+     * genuinely private target, so the guard is proven rather than worked around.
+     */
+    protected performFetch(url: string, init: RequestInit): Promise<Response>;
+    /**
+     * The outbound guard, applied before EVERY request rather than once at registration.
+     *
+     * Registration refuses a plaintext endpoint; this refuses the deeper set — a private or reserved
+     * address, credentials embedded in the URL, a special-use hostname. It runs per call because a
+     * hostname's meaning can change between registration and use, and because an application-declared
+     * URL pointed at a third party is precisely the shape that turns this server into a
+     * request-forgery tool.
+     */
+    private refuseTarget;
+    private headers;
+    /** Send a JSON-RPC REQUEST and resolve its response, from either answer shape. */
+    private request;
+    /**
+     * Send a JSON-RPC NOTIFICATION, whose success is an HTTP status and not a body.
+     *
+     * spec-cite: MCP 2025-06-18 — Transports §Sending Messages to the Server (for a notification, "the
+     * server MUST return HTTP status code 202 Accepted with no body"). Any 2xx is accepted here rather
+     * than 202 exactly, because a proxy that rewrites a 202 to a 200 is not a protocol fault and
+     * refusing it would break a deployment for no gain in correctness.
+     */
+    private notify;
+    /**
+     * Read the JSON-RPC response for `id` out of an SSE body.
+     *
+     * The stream may carry server-initiated requests and notifications BEFORE the response, so this
+     * cannot take the first event — it matches on the id and ignores everything else. Returns `null`
+     * if the stream ends without one, which the caller reports as a protocol error rather than as a
+     * timeout: the connection closed, so no budget was exceeded.
+     */
+    private readJsonRpcFromEventStream;
+    private failure;
+}
+//# sourceMappingURL=mcp-client.backend.service.d.ts.map

package/dist/esm/flows-actors/services/mcp-client.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/services/mcp-client.backend.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAGnE,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,kBAAkB,EAGxB,MAAM,uEAAuE,CAAC;AAK/E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBACa,uBAAuB;IAClC;;;;;;OAMG;IACU,WAAW,CAAC,MAAM,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA6EjH;;;OAGG;IACU,QAAQ,CACnB,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,OAAO,CAAC,kBAAkB,CAAC;IAuC9B;;;;;;OAMG;IACU,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBzF;;;;;;;;OAQG;IACH,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAWzE;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,OAAO;IAaf,kFAAkF;YACpE,OAAO;IAkErB;;;;;;;OAOG;YACW,MAAM;IAyBpB;;;;;;;OAOG;YACW,0BAA0B;IA2CxC,OAAO,CAAC,OAAO;CAYhB"}

package/dist/esm/flows-actors/services/mcp-client.backend.service.js

@@ -0,0 +1,371 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from 'inversify';
+import { mcpServerDestinationHost } from '@wildo-ai/saas-models';
+import { MCP_CLIENT_INFO, MCP_CLIENT_PROTOCOL_VERSION, McpOutcomeKind, } from '../../flows-actors/models/mcp-client.backend.definitions.js';
+import { classifyOutboundTargetUrl, } from '../../security/ssrf/outbound-target-guard.backend.utils.js';
+/**
+ * An MCP client over the Streamable HTTP transport.
+ *
+ * ## Why this is hand-written rather than an SDK
+ *
+ * The subset an agent turn needs is three methods — `initialize`, `tools/list`, `tools/call` — over
+ * JSON-RPC. Taking a runtime dependency for that would put the parts this engine must own most
+ * (which targets are refusable, what a timeout costs, what reaches an audit row, what a failure
+ * means to an agent) behind somebody else's abstractions, and it runs against the standing position
+ * that Wildo does not take runtime dependencies on third-party integration packages.
+ *
+ * ## What it is NOT
+ *
+ * Not a second kind of local function (#491). Every method returns a typed OUTCOME and never throws
+ * into the turn, because the failure modes an agent must distinguish — refused, unreachable, timed
+ * out, malformed, or the tool's own error — do not exist for a local call and cannot be flattened
+ * into one exception without losing the distinction that decides what happens next.
+ *
+ * spec-cite: MCP 2025-06-18 — Transports §Streamable HTTP for the request shape, session header and
+ * dual response content types; Lifecycle for the initialize/initialized handshake; Tools for
+ * `tools/list` and `tools/call`.
+ */
+let McpClientBackendService = class McpClientBackendService {
+    /**
+     * Open a session and discover the server's tools, bounded by the server's DISCOVERY budget.
+     *
+     * Discovery is where an unreachable server is meant to be found. A server that does not answer
+     * here contributes no tools to the turn, and the agent is never offered a capability it cannot
+     * use — fail-closed on the CLAIM, fail-open on the turn.
+     */
+    async openSession(server, accessToken) {
+        const refusal = this.refuseTarget(server);
+        if (refusal)
+            return refusal;
+        const initialize = await this.request(server, {
+            method: 'initialize',
+            params: {
+                protocolVersion: MCP_CLIENT_PROTOCOL_VERSION,
+                // Declared EMPTY on purpose. `roots`, `sampling` and `elicitation` are client capabilities a
+                // server may then exercise — sampling in particular asks this process to run a model on the
+                // server's behalf. Declaring a capability we do not implement would invite a request we
+                // cannot answer; adding one is a deliberate decision, not a default.
+                capabilities: {},
+                clientInfo: MCP_CLIENT_INFO,
+            },
+            accessToken,
+            sessionId: null,
+            timeoutMs: server.timeouts.discoveryMs,
+        });
+        if (initialize.kind !== McpOutcomeKind.OK)
+            return initialize;
+        /*
+         * The session id arrives on the InitializeResult's HTTP response and must be echoed afterwards.
+         * A server that assigns none is stateless, which is a supported shape rather than a failure.
+         */
+        const sessionId = initialize.sessionId;
+        /*
+         * The `initialized` notification. A notification carries no id and expects 202 with no body, so
+         * its failure cannot be read from a JSON-RPC result — only from the HTTP status, which
+         * `notify` reports. It is sent BEFORE `tools/list` because a server SHOULD NOT be asked for
+         * anything else until it arrives.
+         */
+        const initialized = await this.notify(server, {
+            method: 'notifications/initialized',
+            accessToken,
+            sessionId,
+            timeoutMs: server.timeouts.discoveryMs,
+        });
+        if (initialized.kind !== McpOutcomeKind.OK)
+            return initialized;
+        const listed = await this.request(server, {
+            method: 'tools/list',
+            params: {},
+            accessToken,
+            sessionId,
+            timeoutMs: server.timeouts.discoveryMs,
+        });
+        if (listed.kind !== McpOutcomeKind.OK)
+            return listed;
+        const rawTools = listed.result?.tools;
+        if (!Array.isArray(rawTools)) {
+            return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, 'tools/list returned no tools array');
+        }
+        /*
+         * Every entry is validated. A tool descriptor reaches a model as a callable contract, so one
+         * missing its name or its input schema must be DROPPED rather than passed through half-formed:
+         * the model would be offered a tool it cannot correctly call, which is the same shape of defect
+         * as advertising a server that does not exist.
+         */
+        const tools = [];
+        for (const candidate of rawTools) {
+            const tool = candidate;
+            if (typeof tool?.name !== 'string' || tool.name.length === 0)
+                continue;
+            if (typeof tool.inputSchema !== 'object' || tool.inputSchema === null)
+                continue;
+            tools.push({
+                name: tool.name,
+                title: typeof tool.title === 'string' ? tool.title : undefined,
+                description: typeof tool.description === 'string' ? tool.description : undefined,
+                inputSchema: tool.inputSchema,
+            });
+        }
+        return { kind: McpOutcomeKind.OK, session: { server, sessionId, tools } };
+    }
+    /**
+     * Call one tool, bounded by the server's CALL budget — a separate and larger budget than
+     * discovery, because doing the work legitimately takes longer than listing what can be done.
+     */
+    async callTool(session, toolName, args, accessToken) {
+        const { server } = session;
+        const refusal = this.refuseTarget(server);
+        if (refusal)
+            return refusal;
+        const called = await this.request(server, {
+            method: 'tools/call',
+            params: { name: toolName, arguments: args },
+            accessToken,
+            sessionId: session.sessionId,
+            timeoutMs: server.timeouts.callMs,
+        });
+        if (called.kind !== McpOutcomeKind.OK)
+            return called;
+        const result = called.result;
+        /*
+         * `isError: true` is a TOOL failure on a working protocol, and it is reported as its own kind.
+         * The server did everything right; the tool did not. An agent can read that and try something
+         * else, and an operator should not be paged for it.
+         */
+        if (result?.isError === true) {
+            return this.failure(server, McpOutcomeKind.TOOL_ERROR, `tool "${toolName}" reported isError`);
+        }
+        if (!Array.isArray(result?.content)) {
+            return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `tools/call for "${toolName}" returned no content array`);
+        }
+        return {
+            kind: McpOutcomeKind.OK,
+            content: result.content,
+            structuredContent: typeof result.structuredContent === 'object' && result.structuredContent !== null
+                ? result.structuredContent
+                : undefined,
+        };
+    }
+    /**
+     * Release a session, best-effort.
+     *
+     * Deliberately returns nothing and reports nothing. A server MAY refuse to let a client terminate
+     * a session, so a failure here is an expected shape rather than a fault — and a turn that has
+     * already produced its answer must not fail on tidying up after itself.
+     */
+    async closeSession(session, accessToken) {
+        if (session.sessionId === null)
+            return;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), session.server.timeouts.discoveryMs);
+        try {
+            await this.performFetch(session.server.url, {
+                method: 'DELETE',
+                headers: this.headers(accessToken, session.sessionId),
+                signal: controller.signal,
+            });
+        }
+        catch {
+            // Intentionally swallowed — see the docstring.
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * The one place this service touches the network.
+     *
+     * A protected seam rather than an injected `fetch`, so nothing in production can substitute it and
+     * the DI binding stays parameterless. Tests subclass to drive the protocol deterministically —
+     * which they must, because the outbound guard REFUSES loopback and every private range, so a real
+     * local double could only ever produce `REFUSED_TARGET`. That refusal is itself pinned, against a
+     * genuinely private target, so the guard is proven rather than worked around.
+     */
+    performFetch(url, init) {
+        // outbound-deadline: a forwarding seam. Each of the three callers arms its own
+        // `AbortController` from the server's declared `timeouts.discoveryMs` / `timeouts.callMs` and
+        // passes it in `init.signal` — the budget is per SERVER, so it cannot be decided here.
+        return fetch(url, init);
+    }
+    // ================================
+    // Transport
+    // ================================
+    /**
+     * The outbound guard, applied before EVERY request rather than once at registration.
+     *
+     * Registration refuses a plaintext endpoint; this refuses the deeper set — a private or reserved
+     * address, credentials embedded in the URL, a special-use hostname. It runs per call because a
+     * hostname's meaning can change between registration and use, and because an application-declared
+     * URL pointed at a third party is precisely the shape that turns this server into a
+     * request-forgery tool.
+     */
+    refuseTarget(server) {
+        const rejection = classifyOutboundTargetUrl(server.url, { admittedProtocols: ['https:'] });
+        if (!rejection)
+            return null;
+        return this.failure(server, McpOutcomeKind.REFUSED_TARGET, rejection);
+    }
+    headers(accessToken, sessionId) {
+        const headers = {
+            'content-type': 'application/json',
+            // Both content types are listed because the server chooses which to answer with, and a client
+            // that named only one would be refusing a response shape the transport permits.
+            accept: 'application/json, text/event-stream',
+            'mcp-protocol-version': MCP_CLIENT_PROTOCOL_VERSION,
+        };
+        if (sessionId !== null)
+            headers['mcp-session-id'] = sessionId;
+        if (accessToken !== null)
+            headers.authorization = `Bearer ${accessToken}`;
+        return headers;
+    }
+    /** Send a JSON-RPC REQUEST and resolve its response, from either answer shape. */
+    async request(server, input) {
+        const id = 1;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), input.timeoutMs);
+        let response;
+        try {
+            response = await this.performFetch(server.url, {
+                method: 'POST',
+                headers: this.headers(input.accessToken, input.sessionId),
+                body: JSON.stringify({ jsonrpc: '2.0', id, method: input.method, params: input.params }),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            // An abort and a connection failure arrive through the same catch and mean different things:
+            // a slow server is not a down one, and the remedies differ.
+            const kind = controller.signal.aborted ? McpOutcomeKind.TIMED_OUT : McpOutcomeKind.UNREACHABLE;
+            return this.failure(server, kind, `${input.method}: ${kind === McpOutcomeKind.TIMED_OUT ? `exceeded ${input.timeoutMs}ms` : 'request failed'}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            return this.failure(server, McpOutcomeKind.UNREACHABLE, `${input.method}: HTTP ${response.status}`);
+        }
+        // Only present on the initialize response in practice, and read from every response so a server
+        // that assigns one later is not ignored.
+        const sessionId = response.headers.get('mcp-session-id') ?? input.sessionId;
+        let envelope;
+        try {
+            envelope = (response.headers.get('content-type') ?? '').includes('text/event-stream')
+                ? await this.readJsonRpcFromEventStream(response, id)
+                : (await response.json());
+        }
+        catch {
+            return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `${input.method}: response was not readable JSON-RPC`);
+        }
+        if (!envelope) {
+            return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `${input.method}: no JSON-RPC response for the request`);
+        }
+        if (envelope.error) {
+            // The server's own message is NOT forwarded: it is third-party text that would land in a log
+            // and an audit row. The code identifies the fault; the message is the server's to keep.
+            return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `${input.method}: JSON-RPC error ${envelope.error.code ?? 'unknown'}`);
+        }
+        if (envelope.result === undefined) {
+            return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `${input.method}: response carried neither result nor error`);
+        }
+        return { kind: McpOutcomeKind.OK, result: envelope.result, sessionId };
+    }
+    /**
+     * Send a JSON-RPC NOTIFICATION, whose success is an HTTP status and not a body.
+     *
+     * spec-cite: MCP 2025-06-18 — Transports §Sending Messages to the Server (for a notification, "the
+     * server MUST return HTTP status code 202 Accepted with no body"). Any 2xx is accepted here rather
+     * than 202 exactly, because a proxy that rewrites a 202 to a 200 is not a protocol fault and
+     * refusing it would break a deployment for no gain in correctness.
+     */
+    async notify(server, input) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), input.timeoutMs);
+        try {
+            const response = await this.performFetch(server.url, {
+                method: 'POST',
+                headers: this.headers(input.accessToken, input.sessionId),
+                body: JSON.stringify({ jsonrpc: '2.0', method: input.method }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                return this.failure(server, McpOutcomeKind.UNREACHABLE, `${input.method}: HTTP ${response.status}`);
+            }
+            return { kind: McpOutcomeKind.OK };
+        }
+        catch {
+            const kind = controller.signal.aborted ? McpOutcomeKind.TIMED_OUT : McpOutcomeKind.UNREACHABLE;
+            return this.failure(server, kind, `${input.method}: ${kind === McpOutcomeKind.TIMED_OUT ? `exceeded ${input.timeoutMs}ms` : 'request failed'}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Read the JSON-RPC response for `id` out of an SSE body.
+     *
+     * The stream may carry server-initiated requests and notifications BEFORE the response, so this
+     * cannot take the first event — it matches on the id and ignores everything else. Returns `null`
+     * if the stream ends without one, which the caller reports as a protocol error rather than as a
+     * timeout: the connection closed, so no budget was exceeded.
+     */
+    async readJsonRpcFromEventStream(response, id) {
+        const body = response.body;
+        if (!body)
+            return null;
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffered = '';
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return null;
+                buffered += decoder.decode(value, { stream: true });
+                // Events are separated by a blank line; a partial trailing event stays buffered.
+                let boundary = buffered.indexOf('\n\n');
+                while (boundary !== -1) {
+                    const rawEvent = buffered.slice(0, boundary);
+                    buffered = buffered.slice(boundary + 2);
+                    const data = rawEvent
+                        .split('\n')
+                        .filter((line) => line.startsWith('data:'))
+                        .map((line) => line.slice('data:'.length).trim())
+                        .join('');
+                    if (data.length > 0) {
+                        try {
+                            const parsed = JSON.parse(data);
+                            if (parsed?.id === id)
+                                return parsed;
+                        }
+                        catch {
+                            // A single unparseable event does not end the stream — the response may still arrive.
+                        }
+                    }
+                    boundary = buffered.indexOf('\n\n');
+                }
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+        }
+    }
+    failure(server, kind, detail) {
+        return {
+            kind,
+            mcpServerRef: server.ref,
+            destinationHost: mcpServerDestinationHost(server.url),
+            detail,
+        };
+    }
+};
+McpClientBackendService = __decorate([
+    injectable()
+], McpClientBackendService);
+export { McpClientBackendService };
+//# sourceMappingURL=mcp-client.backend.service.js.map

package/dist/esm/flows-actors/services/mcp-client.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.backend.service.js","sourceRoot":"","sources":["../../../../src/flows-actors/services/mcp-client.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable } from 'inversify';\n\nimport type { FlowsActors_McpServer } from '@wildo-ai/saas-models';\nimport { mcpServerDestinationHost } from '@wildo-ai/saas-models';\n\nimport {\n  MCP_CLIENT_INFO,\n  MCP_CLIENT_PROTOCOL_VERSION,\n  McpOutcomeKind,\n  type McpDiscoveryOutcome,\n  type McpSession,\n  type McpToolCallOutcome,\n  type McpToolDescriptor,\n  type McpFailureOutcome,\n} from '~wildo-backend-lib/flows-actors/models/mcp-client.backend.definitions';\nimport {\n  classifyOutboundTargetUrl,\n} from '~wildo-backend-lib/security/ssrf/outbound-target-guard.backend.utils';\n\n/**\n * An MCP client over the Streamable HTTP transport.\n *\n * ## Why this is hand-written rather than an SDK\n *\n * The subset an agent turn needs is three methods — `initialize`, `tools/list`, `tools/call` — over\n * JSON-RPC. Taking a runtime dependency for that would put the parts this engine must own most\n * (which targets are refusable, what a timeout costs, what reaches an audit row, what a failure\n * means to an agent) behind somebody else's abstractions, and it runs against the standing position\n * that Wildo does not take runtime dependencies on third-party integration packages.\n *\n * ## What it is NOT\n *\n * Not a second kind of local function (#491). Every method returns a typed OUTCOME and never throws\n * into the turn, because the failure modes an agent must distinguish — refused, unreachable, timed\n * out, malformed, or the tool's own error — do not exist for a local call and cannot be flattened\n * into one exception without losing the distinction that decides what happens next.\n *\n * spec-cite: MCP 2025-06-18 — Transports §Streamable HTTP for the request shape, session header and\n * dual response content types; Lifecycle for the initialize/initialized handshake; Tools for\n * `tools/list` and `tools/call`.\n */\n@injectable()\nexport class McpClientBackendService {\n  /**\n   * Open a session and discover the server's tools, bounded by the server's DISCOVERY budget.\n   *\n   * Discovery is where an unreachable server is meant to be found. A server that does not answer\n   * here contributes no tools to the turn, and the agent is never offered a capability it cannot\n   * use — fail-closed on the CLAIM, fail-open on the turn.\n   */\n  public async openSession(server: FlowsActors_McpServer, accessToken: string | null): Promise<McpDiscoveryOutcome> {\n    const refusal = this.refuseTarget(server);\n    if (refusal) return refusal;\n\n    const initialize = await this.request(server, {\n      method: 'initialize',\n      params: {\n        protocolVersion: MCP_CLIENT_PROTOCOL_VERSION,\n        // Declared EMPTY on purpose. `roots`, `sampling` and `elicitation` are client capabilities a\n        // server may then exercise — sampling in particular asks this process to run a model on the\n        // server's behalf. Declaring a capability we do not implement would invite a request we\n        // cannot answer; adding one is a deliberate decision, not a default.\n        capabilities: {},\n        clientInfo: MCP_CLIENT_INFO,\n      },\n      accessToken,\n      sessionId: null,\n      timeoutMs: server.timeouts.discoveryMs,\n    });\n    if (initialize.kind !== McpOutcomeKind.OK) return initialize;\n\n    /*\n     * The session id arrives on the InitializeResult's HTTP response and must be echoed afterwards.\n     * A server that assigns none is stateless, which is a supported shape rather than a failure.\n     */\n    const sessionId = initialize.sessionId;\n\n    /*\n     * The `initialized` notification. A notification carries no id and expects 202 with no body, so\n     * its failure cannot be read from a JSON-RPC result — only from the HTTP status, which\n     * `notify` reports. It is sent BEFORE `tools/list` because a server SHOULD NOT be asked for\n     * anything else until it arrives.\n     */\n    const initialized = await this.notify(server, {\n      method: 'notifications/initialized',\n      accessToken,\n      sessionId,\n      timeoutMs: server.timeouts.discoveryMs,\n    });\n    if (initialized.kind !== McpOutcomeKind.OK) return initialized;\n\n    const listed = await this.request(server, {\n      method: 'tools/list',\n      params: {},\n      accessToken,\n      sessionId,\n      timeoutMs: server.timeouts.discoveryMs,\n    });\n    if (listed.kind !== McpOutcomeKind.OK) return listed;\n\n    const rawTools = (listed.result as { tools?: unknown })?.tools;\n    if (!Array.isArray(rawTools)) {\n      return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, 'tools/list returned no tools array');\n    }\n\n    /*\n     * Every entry is validated. A tool descriptor reaches a model as a callable contract, so one\n     * missing its name or its input schema must be DROPPED rather than passed through half-formed:\n     * the model would be offered a tool it cannot correctly call, which is the same shape of defect\n     * as advertising a server that does not exist.\n     */\n    const tools: McpToolDescriptor[] = [];\n    for (const candidate of rawTools) {\n      const tool = candidate as Partial<McpToolDescriptor>;\n      if (typeof tool?.name !== 'string' || tool.name.length === 0) continue;\n      if (typeof tool.inputSchema !== 'object' || tool.inputSchema === null) continue;\n      tools.push({\n        name: tool.name,\n        title: typeof tool.title === 'string' ? tool.title : undefined,\n        description: typeof tool.description === 'string' ? tool.description : undefined,\n        inputSchema: tool.inputSchema as Record<string, unknown>,\n      });\n    }\n\n    return { kind: McpOutcomeKind.OK, session: { server, sessionId, tools } };\n  }\n\n  /**\n   * Call one tool, bounded by the server's CALL budget — a separate and larger budget than\n   * discovery, because doing the work legitimately takes longer than listing what can be done.\n   */\n  public async callTool(\n    session: McpSession,\n    toolName: string,\n    args: Record<string, unknown>,\n    accessToken: string | null,\n  ): Promise<McpToolCallOutcome> {\n    const { server } = session;\n    const refusal = this.refuseTarget(server);\n    if (refusal) return refusal;\n\n    const called = await this.request(server, {\n      method: 'tools/call',\n      params: { name: toolName, arguments: args },\n      accessToken,\n      sessionId: session.sessionId,\n      timeoutMs: server.timeouts.callMs,\n    });\n    if (called.kind !== McpOutcomeKind.OK) return called;\n\n    const result = called.result as { content?: unknown; structuredContent?: unknown; isError?: unknown };\n\n    /*\n     * `isError: true` is a TOOL failure on a working protocol, and it is reported as its own kind.\n     * The server did everything right; the tool did not. An agent can read that and try something\n     * else, and an operator should not be paged for it.\n     */\n    if (result?.isError === true) {\n      return this.failure(server, McpOutcomeKind.TOOL_ERROR, `tool \"${toolName}\" reported isError`);\n    }\n\n    if (!Array.isArray(result?.content)) {\n      return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `tools/call for \"${toolName}\" returned no content array`);\n    }\n\n    return {\n      kind: McpOutcomeKind.OK,\n      content: result.content,\n      structuredContent:\n        typeof result.structuredContent === 'object' && result.structuredContent !== null\n          ? (result.structuredContent as Record<string, unknown>)\n          : undefined,\n    };\n  }\n\n  /**\n   * Release a session, best-effort.\n   *\n   * Deliberately returns nothing and reports nothing. A server MAY refuse to let a client terminate\n   * a session, so a failure here is an expected shape rather than a fault — and a turn that has\n   * already produced its answer must not fail on tidying up after itself.\n   */\n  public async closeSession(session: McpSession, accessToken: string | null): Promise<void> {\n    if (session.sessionId === null) return;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), session.server.timeouts.discoveryMs);\n    try {\n      await this.performFetch(session.server.url, {\n        method: 'DELETE',\n        headers: this.headers(accessToken, session.sessionId),\n        signal: controller.signal,\n      });\n    } catch {\n      // Intentionally swallowed — see the docstring.\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n\n  /**\n   * The one place this service touches the network.\n   *\n   * A protected seam rather than an injected `fetch`, so nothing in production can substitute it and\n   * the DI binding stays parameterless. Tests subclass to drive the protocol deterministically —\n   * which they must, because the outbound guard REFUSES loopback and every private range, so a real\n   * local double could only ever produce `REFUSED_TARGET`. That refusal is itself pinned, against a\n   * genuinely private target, so the guard is proven rather than worked around.\n   */\n  protected performFetch(url: string, init: RequestInit): Promise<Response> {\n    // outbound-deadline: a forwarding seam. Each of the three callers arms its own\n    // `AbortController` from the server's declared `timeouts.discoveryMs` / `timeouts.callMs` and\n    // passes it in `init.signal` — the budget is per SERVER, so it cannot be decided here.\n    return fetch(url, init);\n  }\n\n  // ================================\n  // Transport\n  // ================================\n\n  /**\n   * The outbound guard, applied before EVERY request rather than once at registration.\n   *\n   * Registration refuses a plaintext endpoint; this refuses the deeper set — a private or reserved\n   * address, credentials embedded in the URL, a special-use hostname. It runs per call because a\n   * hostname's meaning can change between registration and use, and because an application-declared\n   * URL pointed at a third party is precisely the shape that turns this server into a\n   * request-forgery tool.\n   */\n  private refuseTarget(server: FlowsActors_McpServer): McpFailureOutcome | null {\n    const rejection = classifyOutboundTargetUrl(server.url, { admittedProtocols: ['https:'] });\n    if (!rejection) return null;\n    return this.failure(server, McpOutcomeKind.REFUSED_TARGET, rejection);\n  }\n\n  private headers(accessToken: string | null, sessionId: string | null): Record<string, string> {\n    const headers: Record<string, string> = {\n      'content-type': 'application/json',\n      // Both content types are listed because the server chooses which to answer with, and a client\n      // that named only one would be refusing a response shape the transport permits.\n      accept: 'application/json, text/event-stream',\n      'mcp-protocol-version': MCP_CLIENT_PROTOCOL_VERSION,\n    };\n    if (sessionId !== null) headers['mcp-session-id'] = sessionId;\n    if (accessToken !== null) headers.authorization = `Bearer ${accessToken}`;\n    return headers;\n  }\n\n  /** Send a JSON-RPC REQUEST and resolve its response, from either answer shape. */\n  private async request(\n    server: FlowsActors_McpServer,\n    input: {\n      method: string;\n      params: Record<string, unknown>;\n      accessToken: string | null;\n      sessionId: string | null;\n      timeoutMs: number;\n    },\n  ): Promise<\n    | { kind: McpOutcomeKind.OK; result: unknown; sessionId: string | null }\n    | McpFailureOutcome\n  > {\n    const id = 1;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), input.timeoutMs);\n\n    let response: Response;\n    try {\n      response = await this.performFetch(server.url, {\n        method: 'POST',\n        headers: this.headers(input.accessToken, input.sessionId),\n        body: JSON.stringify({ jsonrpc: '2.0', id, method: input.method, params: input.params }),\n        signal: controller.signal,\n      });\n    } catch (error) {\n      // An abort and a connection failure arrive through the same catch and mean different things:\n      // a slow server is not a down one, and the remedies differ.\n      const kind = controller.signal.aborted ? McpOutcomeKind.TIMED_OUT : McpOutcomeKind.UNREACHABLE;\n      return this.failure(server, kind, `${input.method}: ${kind === McpOutcomeKind.TIMED_OUT ? `exceeded ${input.timeoutMs}ms` : 'request failed'}`);\n    } finally {\n      clearTimeout(timer);\n    }\n\n    if (!response.ok) {\n      return this.failure(server, McpOutcomeKind.UNREACHABLE, `${input.method}: HTTP ${response.status}`);\n    }\n\n    // Only present on the initialize response in practice, and read from every response so a server\n    // that assigns one later is not ignored.\n    const sessionId = response.headers.get('mcp-session-id') ?? input.sessionId;\n\n    let envelope: { result?: unknown; error?: { code?: number; message?: string } } | null;\n    try {\n      envelope = (response.headers.get('content-type') ?? '').includes('text/event-stream')\n        ? await this.readJsonRpcFromEventStream(response, id)\n        : ((await response.json()) as typeof envelope);\n    } catch {\n      return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `${input.method}: response was not readable JSON-RPC`);\n    }\n\n    if (!envelope) {\n      return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `${input.method}: no JSON-RPC response for the request`);\n    }\n    if (envelope.error) {\n      // The server's own message is NOT forwarded: it is third-party text that would land in a log\n      // and an audit row. The code identifies the fault; the message is the server's to keep.\n      return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `${input.method}: JSON-RPC error ${envelope.error.code ?? 'unknown'}`);\n    }\n    if (envelope.result === undefined) {\n      return this.failure(server, McpOutcomeKind.PROTOCOL_ERROR, `${input.method}: response carried neither result nor error`);\n    }\n\n    return { kind: McpOutcomeKind.OK, result: envelope.result, sessionId };\n  }\n\n  /**\n   * Send a JSON-RPC NOTIFICATION, whose success is an HTTP status and not a body.\n   *\n   * spec-cite: MCP 2025-06-18 — Transports §Sending Messages to the Server (for a notification, \"the\n   * server MUST return HTTP status code 202 Accepted with no body\"). Any 2xx is accepted here rather\n   * than 202 exactly, because a proxy that rewrites a 202 to a 200 is not a protocol fault and\n   * refusing it would break a deployment for no gain in correctness.\n   */\n  private async notify(\n    server: FlowsActors_McpServer,\n    input: { method: string; accessToken: string | null; sessionId: string | null; timeoutMs: number },\n  ): Promise<{ kind: McpOutcomeKind.OK } | McpFailureOutcome> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), input.timeoutMs);\n    try {\n      const response = await this.performFetch(server.url, {\n        method: 'POST',\n        headers: this.headers(input.accessToken, input.sessionId),\n        body: JSON.stringify({ jsonrpc: '2.0', method: input.method }),\n        signal: controller.signal,\n      });\n      if (!response.ok) {\n        return this.failure(server, McpOutcomeKind.UNREACHABLE, `${input.method}: HTTP ${response.status}`);\n      }\n      return { kind: McpOutcomeKind.OK };\n    } catch {\n      const kind = controller.signal.aborted ? McpOutcomeKind.TIMED_OUT : McpOutcomeKind.UNREACHABLE;\n      return this.failure(server, kind, `${input.method}: ${kind === McpOutcomeKind.TIMED_OUT ? `exceeded ${input.timeoutMs}ms` : 'request failed'}`);\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n\n  /**\n   * Read the JSON-RPC response for `id` out of an SSE body.\n   *\n   * The stream may carry server-initiated requests and notifications BEFORE the response, so this\n   * cannot take the first event — it matches on the id and ignores everything else. Returns `null`\n   * if the stream ends without one, which the caller reports as a protocol error rather than as a\n   * timeout: the connection closed, so no budget was exceeded.\n   */\n  private async readJsonRpcFromEventStream(\n    response: Response,\n    id: number,\n  ): Promise<{ result?: unknown; error?: { code?: number; message?: string } } | null> {\n    const body = response.body;\n    if (!body) return null;\n\n    const reader = body.getReader();\n    const decoder = new TextDecoder();\n    let buffered = '';\n\n    try {\n      for (;;) {\n        const { done, value } = await reader.read();\n        if (done) return null;\n        buffered += decoder.decode(value, { stream: true });\n\n        // Events are separated by a blank line; a partial trailing event stays buffered.\n        let boundary = buffered.indexOf('\\n\\n');\n        while (boundary !== -1) {\n          const rawEvent = buffered.slice(0, boundary);\n          buffered = buffered.slice(boundary + 2);\n          const data = rawEvent\n            .split('\\n')\n            .filter((line) => line.startsWith('data:'))\n            .map((line) => line.slice('data:'.length).trim())\n            .join('');\n          if (data.length > 0) {\n            try {\n              const parsed = JSON.parse(data) as { id?: unknown; result?: unknown; error?: { code?: number; message?: string } };\n              if (parsed?.id === id) return parsed;\n            } catch {\n              // A single unparseable event does not end the stream — the response may still arrive.\n            }\n          }\n          boundary = buffered.indexOf('\\n\\n');\n        }\n      }\n    } finally {\n      await reader.cancel().catch(() => {});\n    }\n  }\n\n  private failure(\n    server: FlowsActors_McpServer,\n    kind: Exclude<McpOutcomeKind, McpOutcomeKind.OK>,\n    detail: string,\n  ): McpFailureOutcome {\n    return {\n      kind,\n      mcpServerRef: server.ref,\n      destinationHost: mcpServerDestinationHost(server.url),\n      detail,\n    };\n  }\n}\n"]}

package/dist/esm/flows-actors/services/mcp-credential-resolver.backend.service.d.ts

@@ -0,0 +1,99 @@
+import type { FlowsActors_McpServer } from '@wildo-ai/saas-models';
+import type { OrganizationProviderCredentialResolverPort } from '../../security/connected-accounts/organization-provider-credential-resolver.port';
+import type { UserProviderCredentialResolverPort } from '../../security/connected-accounts/user-provider-credential-resolver.port';
+/** Whose stored credential answered. Recorded so an audit row can say who the far server saw. */
+export declare enum McpCredentialSource {
+    USER = "user",
+    ORGANIZATION = "organization"
+}
+/**
+ * How the credential lookup ended.
+ *
+ * ONE string-enum discriminant, uniform with the client's `McpOutcomeKind`, and that uniformity is
+ * not only taste. This package compiles with `strict: false`, so `strictNullChecks` is off — and a
+ * union discriminated on a BOOLEAN literal does not narrow on its false branch under that setting.
+ * `{ resolved: true } | { resolved: false; reason }` type-checks at the declaration and then refuses
+ * to give a consumer `reason`, which is a compile error at every call site and no error here. A
+ * string discriminant narrows in both directions regardless.
+ *
+ * The three failure kinds are kept apart because they have three different remedies and only one of
+ * them is anybody's fault.
+ */
+export declare enum McpCredentialOutcomeKind {
+    /** Found, opened, spendable. */
+    RESOLVED = "resolved",
+    /**
+     * Nobody has connected this provider — the ordinary state, and the one a user fixes by connecting
+     * an account. The turn should say WHICH provider rather than reporting a failure.
+     */
+    NOT_CONNECTED = "not_connected",
+    /**
+     * The call has no acting identity for the subject the server declares — a `USER` server reached by
+     * an unattended turn, or an `ORGANIZATION` server reached outside any tenant. A configuration
+     * mismatch between who the server expects and who is calling, not a missing connection.
+     */
+    NO_ACTING_IDENTITY = "no_acting_identity",
+    /**
+     * The resolver port is not bound in this deployment, so the question could not be ASKED.
+     *
+     * Distinct from NOT_CONNECTED on the rule that governs this whole subsystem: an unanswerable
+     * question must never be reported as a negative answer. Reporting it as "not connected" would send
+     * a user to connect an account that would then still not be readable.
+     */
+    RESOLVER_UNAVAILABLE = "resolver_unavailable"
+}
+export type McpCredentialOutcome = {
+    kind: McpCredentialOutcomeKind.RESOLVED;
+    /** The plaintext credential. Never logged, never stored, never returned to a client. */
+    token: string;
+    source: McpCredentialSource;
+    /** The row it came from, for the audit trail. */
+    credentialId: string;
+} | {
+    kind: Exclude<McpCredentialOutcomeKind, McpCredentialOutcomeKind.RESOLVED>;
+};
+/** Who the turn is acting as. Both are absent for an unattended run with no tenant. */
+export interface McpActingIdentity {
+    userId?: string;
+    organizationId?: string;
+}
+/**
+ * Resolves the credential an MCP tool call carries, honouring the server's declared subject (#491).
+ *
+ * ## Why it reuses the provider-credential ports
+ *
+ * Decided 2026-09-09. `userProviderCredentials` and `organizationProviderCredentials` already exist,
+ * carry per-tenant isolation by construction, and have the connect and consent flow in front of
+ * them. A store invented for MCP would be a second thing to rotate, audit and leak, holding the same
+ * kind of secret for the same kind of purpose.
+ *
+ * ## Why the user's credential is preferred
+ *
+ * A tool call reaching a third party on a person's behalf should be attributable to that person AT
+ * THE FAR END — that is what makes it revocable there and auditable by the party being called. An
+ * application-wide service identity loses exactly that: every user's call looks identical to the
+ * server, and one leaked credential exposes every tenant.
+ *
+ * The organization fallback exists because without it an agent acting for a user who has never
+ * connected the server would have no path at all, which would make every unattended and batch turn
+ * impossible. A server that must not be reached that way declares `USER`, and then there is no
+ * fallback — the port itself refuses to have one, for the same reason.
+ */
+export declare class McpCredentialResolverBackendService {
+    /**
+     * OPTIONAL, matching how the external-providers registry consults the same ports. A deployment
+     * that has not bound them is a real shape, and the absence is reported as RESOLVER_UNAVAILABLE
+     * rather than collapsing into "nothing is connected".
+     */
+    private readonly userResolver?;
+    private readonly organizationResolver?;
+    constructor(
+    /**
+     * OPTIONAL, matching how the external-providers registry consults the same ports. A deployment
+     * that has not bound them is a real shape, and the absence is reported as RESOLVER_UNAVAILABLE
+     * rather than collapsing into "nothing is connected".
+     */
+    userResolver?: UserProviderCredentialResolverPort, organizationResolver?: OrganizationProviderCredentialResolverPort);
+    resolve(server: FlowsActors_McpServer, actor: McpActingIdentity): Promise<McpCredentialOutcome>;
+}
+//# sourceMappingURL=mcp-credential-resolver.backend.service.d.ts.map

package/dist/esm/flows-actors/services/mcp-credential-resolver.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-credential-resolver.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/services/mcp-credential-resolver.backend.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAInE,OAAO,KAAK,EAAE,0CAA0C,EAAE,MAAM,+FAA+F,CAAC;AAChK,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,uFAAuF,CAAC;AAEhJ,iGAAiG;AACjG,oBAAY,mBAAmB;IAC7B,IAAI,SAAS;IACb,YAAY,iBAAiB;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,oBAAY,wBAAwB;IAClC,gCAAgC;IAChC,QAAQ,aAAa;IACrB;;;OAGG;IACH,aAAa,kBAAkB;IAC/B;;;;OAIG;IACH,kBAAkB,uBAAuB;IACzC;;;;;;OAMG;IACH,oBAAoB,yBAAyB;CAC9C;AAED,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,wBAAwB,CAAC,QAAQ,CAAC;IACxC,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;CACtB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC,wBAAwB,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAA;CAAE,CAAC;AAEnF,uFAAuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBACa,mCAAmC;IAE5C;;;;OAIG;IAEH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAE9B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;;IARtC;;;;OAIG;IAEc,YAAY,CAAC,EAAE,kCAAkC,EAEjD,oBAAoB,CAAC,EAAE,0CAA0C;IAGvE,OAAO,CAAC,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA4D7G"}