@silver886/mcp-proxy 0.1.3 → 0.2.0

package/dist/proxy/runtime/forwarder.d.ts

@@ -0,0 +1,15 @@
+import type { ProxyState } from "../core/state.js";
+import type { ToolRoute } from "../core/types.js";
+import type { DiscoveryRunner } from "../discovery/runner.js";
+export declare class Forwarder {
+    private readonly state;
+    private readonly runner;
+    private readonly log;
+    private readonly sendError;
+    private readonly writeOut;
+    constructor(state: ProxyState, runner: DiscoveryRunner, log: (line: string) => void, sendError: (code: number, detail: string | undefined, id: string | number | null) => void, writeOut: (line: string) => void);
+    forwardRoutedRequest(id: string | number, route: ToolRoute, method: string, upstreamParams: unknown): Promise<void>;
+    private replaySubscriptions;
+    forwardNotification(route: ToolRoute, method: string, params: unknown): Promise<void>;
+    broadcastSetLogLevel(params: Record<string, unknown>): Promise<void>;
+}

package/dist/proxy/runtime/forwarder.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Forwarder = void 0;
+const protocol_js_1 = require("../../shared/protocol.js");
+const constants_js_1 = require("../core/constants.js");
+const fetch_timeout_js_1 = require("../core/fetch-timeout.js");
+const validation_js_1 = require("../pairing/validation.js");
+const uri_js_1 = require("../routing/uri.js");
+// All agent→server (and proxy→server) HTTP traffic flows through this
+// class. It owns the request/response shape, stale-session 404 retry,
+// resources/read URI wrapping, and the per-request id bookkeeping that
+// notifications/cancelled relies on. It does NOT own discovery/init —
+// when a session is reaped under us it asks DiscoveryRunner to re-init.
+class Forwarder {
+    state;
+    runner;
+    log;
+    sendError;
+    writeOut;
+    constructor(state, runner, log, sendError, writeOut) {
+        this.state = state;
+        this.runner = runner;
+        this.log = log;
+        this.sendError = sendError;
+        this.writeOut = writeOut;
+    }
+    async forwardRoutedRequest(id, route, method, upstreamParams) {
+        const host = this.state.hosts.get(route.hostId);
+        const server = host?.servers.get(route.serverName);
+        if (!host || !server) {
+            this.sendError(protocol_js_1.ErrorCode.INTERNAL, `route stale: ${route.hostId}/${route.serverName}`, id);
+            return;
+        }
+        const targetUrl = `${host.config.tunnelUrl}/servers/${route.serverName}`;
+        const buildHeaders = (sessionId) => {
+            const h = this.state.hostHeaders(host.config);
+            if (sessionId)
+                h["Mcp-Session-Id"] = sessionId;
+            return h;
+        };
+        const body = JSON.stringify({ jsonrpc: "2.0", id, method, params: upstreamParams });
+        this.state.inflight.set(id, route);
+        const progressToken = (upstreamParams?._meta?.progressToken);
+        if (progressToken !== undefined)
+            this.state.progressTokens.set(progressToken, route);
+        try {
+            let upstream = await fetch(targetUrl, {
+                method: "POST",
+                headers: buildHeaders(server.sessionId),
+                signal: (0, fetch_timeout_js_1.timeoutSignal)(constants_js_1.TOOL_FORWARD_TIMEOUT_MS),
+                body,
+            });
+            this.runner.captureSessionId(host, route.serverName, server, upstream.headers.get("mcp-session-id"));
+            let responseBody = await upstream.text();
+            // Stale session recovery: the host now refuses unknown ids with 404
+            // instead of silently spawning a fresh, uninitialized child. Re-run
+            // the MCP handshake for this one server and retry the call exactly
+            // once.
+            if (upstream.status === 404 && (0, validation_js_1.isUnknownSessionError)(responseBody)) {
+                this.log(`[${route.hostId}/${route.serverName}] session lost, re-initializing`);
+                const before = host.servers.get(route.serverName);
+                // Snapshot subscriptions BEFORE initServer overwrites the state
+                // with a fresh empty set. The new session has no record of any
+                // subscribe call the agent made on the old one, so we replay
+                // each URI after init lands.
+                const priorSubscriptions = before ? Array.from(before.subscriptions) : [];
+                await this.runner.initServer(host, route.serverName);
+                const refreshed = host.servers.get(route.serverName);
+                if (!refreshed || refreshed === before) {
+                    this.sendError(protocol_js_1.ErrorCode.HOST_UNREACHABLE, `re-init failed for ${route.hostId}/${route.serverName}`, id);
+                    return;
+                }
+                if (priorSubscriptions.length > 0) {
+                    await this.replaySubscriptions(host, route.serverName, refreshed, priorSubscriptions);
+                }
+                upstream = await fetch(targetUrl, {
+                    method: "POST",
+                    headers: buildHeaders(refreshed.sessionId),
+                    signal: (0, fetch_timeout_js_1.timeoutSignal)(constants_js_1.TOOL_FORWARD_TIMEOUT_MS),
+                    body,
+                });
+                this.runner.captureSessionId(host, route.serverName, refreshed, upstream.headers.get("mcp-session-id"));
+                responseBody = await upstream.text();
+            }
+            if (!upstream.ok) {
+                this.sendError(protocol_js_1.ErrorCode.HOST_UNREACHABLE, `host returned ${upstream.status}: ${responseBody.slice(0, 200)}`, id);
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(responseBody);
+            }
+            catch {
+                this.sendError(protocol_js_1.ErrorCode.INTERNAL, `host returned non-JSON body: ${responseBody.slice(0, 200)}`, id);
+                return;
+            }
+            const isJsonRpc = parsed.jsonrpc === "2.0" && (parsed.result !== undefined || parsed.error !== undefined);
+            if (!isJsonRpc) {
+                this.sendError(protocol_js_1.ErrorCode.INTERNAL, "host returned non-JSON-RPC body", id);
+                return;
+            }
+            // Track subscribe/unsubscribe state on success only — a JSON-RPC
+            // error means the upstream rejected the call and the subscription
+            // state didn't actually change. Use the live `host.servers.get()`
+            // result rather than the captured `server` so a re-init mid-call
+            // commits to the post-recovery state.
+            if (parsed.error === undefined && (method === "resources/subscribe" || method === "resources/unsubscribe")) {
+                const uri = upstreamParams?.uri;
+                if (typeof uri === "string") {
+                    const live = host.servers.get(route.serverName);
+                    if (live) {
+                        if (method === "resources/subscribe")
+                            live.subscriptions.add(uri);
+                        else
+                            live.subscriptions.delete(uri);
+                    }
+                }
+            }
+            // resources/read response carries its own list of `contents[i].uri`,
+            // which the upstream emits in its own URI namespace (e.g., reading a
+            // directory returns concrete file URIs the agent never saw in
+            // resources/list). Wrap each so the agent sees a URI it can route
+            // back through the proxy on a subsequent read/subscribe.
+            if (method === "resources/read" && parsed.result !== undefined) {
+                const result = parsed.result;
+                if (Array.isArray(result.contents)) {
+                    result.contents = result.contents.map((entry) => {
+                        if (entry && typeof entry === "object" && typeof entry.uri === "string") {
+                            const e = entry;
+                            return { ...e, uri: (0, uri_js_1.wrapResourceUri)(route.hostId, route.serverName, e.uri) };
+                        }
+                        return entry;
+                    });
+                }
+            }
+            parsed.id = id;
+            this.writeOut(JSON.stringify(parsed));
+        }
+        catch (err) {
+            this.sendError(protocol_js_1.ErrorCode.HOST_UNREACHABLE, err.message, id);
+        }
+        finally {
+            this.state.inflight.delete(id);
+            if (progressToken !== undefined)
+                this.state.progressTokens.delete(progressToken);
+        }
+    }
+    // Re-issue resources/subscribe for each URI the agent had subscribed on
+    // the prior session. Best-effort: a URI that fails to re-subscribe is
+    // dropped from the new set so we don't claim a subscription we don't
+    // actually hold. Logged for visibility but not surfaced to the agent —
+    // the agent never saw the session rotate.
+    async replaySubscriptions(host, serverName, refreshed, uris) {
+        const targetUrl = `${host.config.tunnelUrl}/servers/${serverName}`;
+        const headers = { ...this.state.hostHeaders(host.config), "Mcp-Session-Id": refreshed.sessionId };
+        await Promise.allSettled(uris.map(async (uri) => {
+            try {
+                const resp = await fetch(targetUrl, {
+                    method: "POST",
+                    headers,
+                    signal: (0, fetch_timeout_js_1.timeoutSignal)(constants_js_1.TOOL_FORWARD_TIMEOUT_MS),
+                    body: JSON.stringify({
+                        jsonrpc: "2.0",
+                        id: `resub-${host.config.id}-${serverName}-${Date.now()}-${uri}`,
+                        method: "resources/subscribe",
+                        params: { uri },
+                    }),
+                });
+                this.runner.captureSessionId(host, serverName, refreshed, resp.headers.get("mcp-session-id"));
+                if (!resp.ok) {
+                    this.log(`  [${host.config.id}/${serverName}] resubscribe ${uri} HTTP ${resp.status}`);
+                    return;
+                }
+                const text = await resp.text();
+                try {
+                    const payload = JSON.parse(text);
+                    if (payload.error) {
+                        this.log(`  [${host.config.id}/${serverName}] resubscribe ${uri} rejected: ${payload.error.message ?? "(no message)"}`);
+                        return;
+                    }
+                }
+                catch {
+                    // unparseable body — treat as best-effort success
+                }
+                refreshed.subscriptions.add(uri);
+            }
+            catch (err) {
+                this.log(`  [${host.config.id}/${serverName}] resubscribe ${uri} failed: ${err.message}`);
+            }
+        }));
+    }
+    async forwardNotification(route, method, params) {
+        const host = this.state.hosts.get(route.hostId);
+        const server = host?.servers.get(route.serverName);
+        if (!host || !server || !server.sessionId)
+            return;
+        const target = `${host.config.tunnelUrl}/servers/${route.serverName}`;
+        const headers = { ...this.state.hostHeaders(host.config), "Mcp-Session-Id": server.sessionId };
+        const resp = await fetch(target, {
+            method: "POST",
+            headers,
+            signal: (0, fetch_timeout_js_1.timeoutSignal)(constants_js_1.TOOL_FORWARD_TIMEOUT_MS),
+            body: JSON.stringify({ jsonrpc: "2.0", method, params }),
+        });
+        this.runner.captureSessionId(host, route.serverName, server, resp.headers.get("mcp-session-id"));
+    }
+    // logging/setLevel has no per-server addressing in the protocol. Issue
+    // the same level to every paired session in parallel; aggregate failures
+    // into stderr and return success to the agent — partial setLevel is
+    // still a meaningful change.
+    async broadcastSetLogLevel(params) {
+        const targets = [];
+        for (const host of this.state.hosts.values()) {
+            for (const [serverName, server] of host.servers) {
+                if (!server.sessionId)
+                    continue;
+                targets.push({ host, serverName, server });
+            }
+        }
+        await Promise.allSettled(targets.map(async ({ host, serverName, server }) => {
+            const target = `${host.config.tunnelUrl}/servers/${serverName}`;
+            const headers = { ...this.state.hostHeaders(host.config), "Mcp-Session-Id": server.sessionId };
+            try {
+                const resp = await fetch(target, {
+                    method: "POST",
+                    headers,
+                    signal: (0, fetch_timeout_js_1.timeoutSignal)(constants_js_1.TOOL_FORWARD_TIMEOUT_MS),
+                    body: JSON.stringify({
+                        jsonrpc: "2.0",
+                        id: `loglevel-${host.config.id}-${serverName}-${Date.now()}`,
+                        method: "logging/setLevel",
+                        params,
+                    }),
+                });
+                this.runner.captureSessionId(host, serverName, server, resp.headers.get("mcp-session-id"));
+                if (!resp.ok) {
+                    this.log(`  [${host.config.id}/${serverName}] logging/setLevel HTTP ${resp.status}`);
+                    return;
+                }
+                // HTTP 200 can still wrap a JSON-RPC error (invalid level, server
+                // rejection). Read the body and surface it — silently ignoring an
+                // upstream's "no thanks" makes invalid levels look applied.
+                const text = await resp.text();
+                if (!text)
+                    return;
+                let payload;
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch {
+                    return; // unparseable — not our concern, treat as best-effort success
+                }
+                if (payload?.error) {
+                    const code = payload.error.code ?? "?";
+                    const message = payload.error.message ?? "(no message)";
+                    this.log(`  [${host.config.id}/${serverName}] logging/setLevel rejected: ${code} ${message}`);
+                }
+            }
+            catch (err) {
+                this.log(`  [${host.config.id}/${serverName}] logging/setLevel failed: ${err.message}`);
+            }
+        }));
+    }
+}
+exports.Forwarder = Forwarder;

package/dist/proxy/runtime/handlers.d.ts

@@ -0,0 +1,48 @@
+import type { ProxyState } from "../core/state.js";
+import type { DiscoveryRunner } from "../discovery/runner.js";
+import type { PairingController } from "../pairing/controller.js";
+import type { Forwarder } from "./forwarder.js";
+import type { UpstreamBridge } from "./upstream-bridge.js";
+export declare class RequestHandlers {
+    private readonly state;
+    private readonly runner;
+    private readonly forwarder;
+    private readonly pairing;
+    private readonly bridge;
+    private readonly sendResult;
+    private readonly sendError;
+    constructor(state: ProxyState, runner: DiscoveryRunner, forwarder: Forwarder, pairing: PairingController, bridge: UpstreamBridge, sendResult: (id: string | number | null, result: unknown) => void, sendError: (code: number, detail: string | undefined, id: string | number | null) => void);
+    handleInitialize(id: string | number, params: {
+        capabilities?: Record<string, unknown>;
+        clientInfo?: {
+            name?: string;
+            version?: string;
+        };
+    } | undefined): void;
+    handleToolsList(id: string | number): Promise<void>;
+    handlePromptsList(id: string | number): Promise<void>;
+    handlePromptDispatch(id: string | number, params: {
+        name?: string;
+        arguments?: Record<string, unknown>;
+    } | undefined): Promise<void>;
+    handleResourcesList(id: string | number): Promise<void>;
+    handleResourceTemplatesList(id: string | number): Promise<void>;
+    handleResourceMethod(id: string | number, method: string, params: {
+        uri?: string;
+    } | undefined): Promise<void>;
+    handleLoggingSetLevel(id: string | number, params: Record<string, unknown>): Promise<void>;
+    handleCompletion(id: string | number, params: {
+        ref?: {
+            type?: string;
+            name?: string;
+            uri?: string;
+        };
+        argument?: unknown;
+    }): Promise<void>;
+    handleToolDispatch(id: string | number, params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: unknown;
+    }): Promise<void>;
+    handleClientNotification(method: string, params: Record<string, unknown>): Promise<void>;
+}

package/dist/proxy/runtime/handlers.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestHandlers = void 0;
+const protocol_js_1 = require("../../shared/protocol.js");
+const constants_js_1 = require("../core/constants.js");
+const filtering_js_1 = require("../routing/filtering.js");
+const uri_js_1 = require("../routing/uri.js");
+// One method per JSON-RPC verb the agent can send. Each handler is
+// responsible for: parameter validation, looking up the route from the
+// (already discovered) state, and either answering locally or delegating
+// to Forwarder. Lives here rather than on ProxyServer so the router file
+// stays a thin dispatcher and the per-method logic doesn't have to share
+// a 1k-line class with discovery, pairing, and forwarding.
+class RequestHandlers {
+    state;
+    runner;
+    forwarder;
+    pairing;
+    bridge;
+    sendResult;
+    sendError;
+    constructor(state, runner, forwarder, pairing, bridge, sendResult, sendError) {
+        this.state = state;
+        this.runner = runner;
+        this.forwarder = forwarder;
+        this.pairing = pairing;
+        this.bridge = bridge;
+        this.sendResult = sendResult;
+        this.sendError = sendError;
+    }
+    handleInitialize(id, params) {
+        this.state.clientCapabilities = params?.capabilities ?? {};
+        if (params?.clientInfo?.name) {
+            this.state.clientInfo = {
+                name: params.clientInfo.name,
+                version: params.clientInfo.version ?? "unknown",
+            };
+        }
+        this.sendResult(id, {
+            protocolVersion: protocol_js_1.MCP_PROTOCOL_VERSION,
+            // listChanged is honest in both directions: SSE listeners relay
+            // notifications/{tools,prompts,resources}/list_changed from each
+            // upstream server with a cache refresh in between, so the agent's
+            // follow-up list call sees fresh data.
+            capabilities: {
+                tools: { listChanged: true },
+                prompts: { listChanged: true },
+                resources: { listChanged: true, subscribe: true },
+                logging: {},
+                completions: {},
+            },
+            serverInfo: { name: protocol_js_1.PACKAGE_NAME, version: protocol_js_1.PACKAGE_VERSION },
+        });
+    }
+    async handleToolsList(id) {
+        if (!this.state.config) {
+            this.sendResult(id, { tools: [constants_js_1.CONFIGURE_TOOL] });
+            return;
+        }
+        await this.runner.retryDiscoveryIfNeeded();
+        this.sendResult(id, {
+            tools: [constants_js_1.CONFIGURE_TOOL, ...(0, filtering_js_1.getFilteredTools)(this.state.config, this.state.hosts, this.state.toolRoute)],
+        });
+    }
+    async handlePromptsList(id) {
+        if (!this.state.config) {
+            this.sendResult(id, { prompts: [constants_js_1.CONFIGURE_PROMPT] });
+            return;
+        }
+        await this.runner.retryDiscoveryIfNeeded();
+        // Inject CONFIGURE_PROMPT first so re-pairing is always one prompt away
+        // regardless of upstream state.
+        this.sendResult(id, {
+            prompts: [constants_js_1.CONFIGURE_PROMPT, ...(0, filtering_js_1.getAggregatedPrompts)(this.state.config, this.state.hosts, this.state.promptRoute)],
+        });
+    }
+    async handlePromptDispatch(id, params) {
+        const promptName = params?.name;
+        if (promptName === "configure") {
+            let text;
+            try {
+                text = await this.pairing.handleConfigure();
+            }
+            catch (err) {
+                // handleConfigure throws when the pairing tunnel can't come up
+                // (cloudflared missing, network unreachable, startup timeout, etc.).
+                // Surface the cause as a JSON-RPC error so the agent doesn't hang
+                // waiting on a response that never arrives.
+                this.sendError(protocol_js_1.ErrorCode.INTERNAL, err.message, id);
+                return;
+            }
+            this.sendResult(id, {
+                messages: [
+                    { role: "user", content: { type: "text", text: "Show the MCP Proxy setup URL. Do not add any follow-up — do not ask me to let you know or report back." } },
+                    { role: "assistant", content: { type: "text", text } },
+                ],
+            });
+            return;
+        }
+        if (!promptName) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, "name is required", id);
+            return;
+        }
+        if (!this.state.config) {
+            this.sendError(protocol_js_1.ErrorCode.PROXY_NOT_CONFIGURED, "Call the `configure` tool first.", id);
+            return;
+        }
+        const route = this.state.promptRoute.get(promptName);
+        if (!route || !(0, filtering_js_1.isServerSelected)(this.state.config, route.hostId, route.serverName)) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown prompt: ${promptName}`, id);
+            return;
+        }
+        const upstream = { name: route.originalName };
+        if (params?.arguments !== undefined)
+            upstream.arguments = params.arguments;
+        const meta = params?._meta;
+        if (meta !== undefined)
+            upstream._meta = meta;
+        await this.forwarder.forwardRoutedRequest(id, route, "prompts/get", upstream);
+    }
+    async handleResourcesList(id) {
+        if (!this.state.config) {
+            this.sendResult(id, { resources: [] });
+            return;
+        }
+        await this.runner.retryDiscoveryIfNeeded();
+        this.sendResult(id, {
+            resources: (0, filtering_js_1.getAggregatedResources)(this.state.config, this.state.hosts, this.state.resources.exactEntries()),
+        });
+    }
+    async handleResourceTemplatesList(id) {
+        if (!this.state.config) {
+            this.sendResult(id, { resourceTemplates: [] });
+            return;
+        }
+        await this.runner.retryDiscoveryIfNeeded();
+        this.sendResult(id, {
+            resourceTemplates: (0, filtering_js_1.getAggregatedResourceTemplates)(this.state.config, this.state.hosts, this.state.templateRoutes),
+        });
+    }
+    async handleResourceMethod(id, method, params) {
+        if (!this.state.config) {
+            this.sendError(protocol_js_1.ErrorCode.PROXY_NOT_CONFIGURED, "Call the `configure` tool first.", id);
+            return;
+        }
+        const uri = params?.uri;
+        if (!uri) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, "uri is required", id);
+            return;
+        }
+        const parsed = (0, uri_js_1.unwrapResourceUri)(uri);
+        if (!parsed) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Not a recognised resource URI: ${uri}`, id);
+            return;
+        }
+        if (!(0, filtering_js_1.isServerSelected)(this.state.config, parsed.hostId, parsed.serverName)) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `No upstream server owns resource URI: ${uri}`, id);
+            return;
+        }
+        if (!this.state.hosts.get(parsed.hostId)?.servers.has(parsed.serverName)) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `No upstream server owns resource URI: ${uri}`, id);
+            return;
+        }
+        // Deliberately NO per-URI allowlist here. The host's authority model is
+        // "anyone holding (tunnelUrl, authToken) can call any MCP method on any
+        // child server" — there is no resource-level ACL on the host side, no
+        // `selectedResources` field on PairingConfig, and no resource picker in
+        // the setup UI. The proxy's selection gates (selectedServers,
+        // selectedTools) constrain what the agent can reach THROUGH the proxy;
+        // a credentialed attacker bypasses the proxy entirely, so adding a
+        // proxy-side resource check would not raise the privilege floor. A
+        // discovered-set check would also reject legitimate dynamic URIs
+        // returned by resources/read on directory-style resources (see
+        // forwarder.ts wrapResourceUri block) — false positives with no
+        // matching security gain. handleCompletion's ref/resource branch
+        // intentionally mirrors this.
+        const route = {
+            hostId: parsed.hostId,
+            serverName: parsed.serverName,
+            originalName: parsed.originalUri,
+        };
+        await this.forwarder.forwardRoutedRequest(id, route, method, { ...(params ?? {}), uri: parsed.originalUri });
+    }
+    async handleLoggingSetLevel(id, params) {
+        if (!this.state.config) {
+            this.sendResult(id, {});
+            return;
+        }
+        await this.forwarder.broadcastSetLogLevel(params);
+        this.sendResult(id, {});
+    }
+    async handleCompletion(id, params) {
+        if (!this.state.config) {
+            this.sendError(protocol_js_1.ErrorCode.PROXY_NOT_CONFIGURED, "Call the `configure` tool first.", id);
+            return;
+        }
+        const ref = params.ref;
+        if (!ref || typeof ref.type !== "string") {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, "ref.type is required", id);
+            return;
+        }
+        let route = null;
+        let upstreamRef = null;
+        if (ref.type === "ref/prompt") {
+            if (!ref.name) {
+                this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, "ref.name is required for ref/prompt", id);
+                return;
+            }
+            route = this.state.promptRoute.get(ref.name) ?? null;
+            if (route)
+                upstreamRef = { type: ref.type, name: route.originalName };
+        }
+        else if (ref.type === "ref/resource") {
+            if (!ref.uri) {
+                this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, "ref.uri is required for ref/resource", id);
+                return;
+            }
+            const parsed = (0, uri_js_1.unwrapResourceUri)(ref.uri);
+            // Server-level gate only — no per-URI allowlist. See the comment in
+            // handleResourceMethod for the threat-model reasoning.
+            if (parsed && this.state.hosts.get(parsed.hostId)?.servers.has(parsed.serverName)) {
+                route = {
+                    hostId: parsed.hostId,
+                    serverName: parsed.serverName,
+                    originalName: parsed.originalUri,
+                };
+                upstreamRef = { type: ref.type, uri: parsed.originalUri };
+            }
+        }
+        else {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown ref.type: ${ref.type}`, id);
+            return;
+        }
+        if (!route || !upstreamRef || !(0, filtering_js_1.isServerSelected)(this.state.config, route.hostId, route.serverName)) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `No upstream server matches ref`, id);
+            return;
+        }
+        await this.forwarder.forwardRoutedRequest(id, route, "completion/complete", {
+            ref: upstreamRef,
+            ...(params.argument !== undefined ? { argument: params.argument } : {}),
+        });
+    }
+    async handleToolDispatch(id, params) {
+        if (params.name === "configure") {
+            let text;
+            try {
+                text = await this.pairing.handleConfigure();
+            }
+            catch (err) {
+                this.sendError(protocol_js_1.ErrorCode.INTERNAL, err.message, id);
+                return;
+            }
+            this.sendResult(id, { content: [{ type: "text", text }] });
+            return;
+        }
+        if (!this.state.config) {
+            this.sendError(protocol_js_1.ErrorCode.PROXY_NOT_CONFIGURED, "Call the `configure` tool first.", id);
+            return;
+        }
+        const route = this.state.toolRoute.get(params.name);
+        if (!route || !(0, filtering_js_1.isServerSelected)(this.state.config, route.hostId, route.serverName)) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown tool: ${params.name}`, id);
+            return;
+        }
+        // selectedTools is a tool-level filter on top of the server-level gate.
+        if (this.state.config.selectedTools !== undefined && !this.state.config.selectedTools.includes(params.name)) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown tool: ${params.name}`, id);
+            return;
+        }
+        // Preserve `_meta` so the upstream server still sees the agent's
+        // progressToken and can emit notifications/progress against it.
+        const upstream = { name: route.originalName, arguments: params.arguments };
+        if (params._meta !== undefined)
+            upstream._meta = params._meta;
+        await this.forwarder.forwardRoutedRequest(id, route, "tools/call", upstream);
+    }
+    async handleClientNotification(method, params) {
+        // Sent during initServer for each upstream session — never re-broadcast.
+        if (method === "notifications/initialized")
+            return;
+        if (method === "notifications/cancelled") {
+            const reqId = params.requestId;
+            if (reqId === undefined)
+                return;
+            // Two id namespaces. `inflight` covers requests we sent upstream
+            // (tools/call, prompts/get, resources/*). `bridge` covers
+            // server→client requests we forwarded out (sampling, elicitation,
+            // roots/list, ping): the client sees our synthetic id and cancels
+            // using that, so we translate it back to the upstream's original id
+            // before forwarding. Without this branch the upstream child waited
+            // the full UPSTREAM_REQUEST_TIMEOUT_MS for a response the client had
+            // already abandoned.
+            const route = this.state.inflight.get(reqId);
+            if (route) {
+                this.forwarder.forwardNotification(route, method, params).catch(() => { });
+                return;
+            }
+            const ctx = this.bridge.consumeForCancel(reqId);
+            if (ctx) {
+                const translated = { ...params, requestId: ctx.originalId };
+                this.forwarder.forwardNotification({ hostId: ctx.hostId, serverName: ctx.serverName, originalName: "" }, method, translated).catch(() => { });
+            }
+            return;
+        }
+        if (method === "notifications/roots/list_changed") {
+            const targets = [];
+            for (const host of this.state.hosts.values()) {
+                for (const serverName of host.servers.keys()) {
+                    if (!(0, filtering_js_1.isServerSelected)(this.state.config, host.config.id, serverName))
+                        continue;
+                    targets.push({ hostId: host.config.id, serverName, originalName: "" });
+                }
+            }
+            await Promise.all(targets.map((t) => this.forwarder.forwardNotification(t, method, params).catch(() => { })));
+            return;
+        }
+        if (method === "notifications/progress") {
+            const progressToken = params.progressToken;
+            if (progressToken === undefined)
+                return;
+            const route = this.state.progressTokens.get(progressToken);
+            if (!route)
+                return;
+            this.forwarder.forwardNotification(route, method, params).catch(() => { });
+            return;
+        }
+    }
+}
+exports.RequestHandlers = RequestHandlers;

package/dist/proxy/runtime/sse.d.ts

@@ -0,0 +1,19 @@
+import type { HostState } from "../core/types.js";
+export interface SseCallbacks {
+    isCurrent: (host: HostState, name: string, sessionId: string) => boolean;
+    onUpstreamRequest: (host: HostState, name: string, msg: {
+        id: string | number;
+        method: string;
+        params?: unknown;
+    }) => void;
+    onListChanged: (host: HostState, name: string, kind: "tools" | "prompts" | "resources") => Promise<void>;
+    onNotification: (msg: unknown) => void;
+}
+export declare class SseReader {
+    private readonly cb;
+    constructor(cb: SseCallbacks);
+    start(host: HostState, name: string, sessionId: string): void;
+    private loop;
+    private consume;
+    private dispatchData;
+}