@akon-labs/nexus-cli 0.1.9 → 0.1.11-rc.2

package/dist/extensions/mcp/server-manager.js

@@ -0,0 +1,1052 @@
+import { mkdirSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
+import { Client, SdkError, SdkErrorCode, SdkHttpError, SSEClientTransport, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { VERSION } from "../../config.js";
+import { abortable, throwIfAborted } from "./abort.js";
+import { handleUrlElicitation, registerElicitationHandler, } from "./elicitation-handler.js";
+import { createJsonSchemaValidator } from "./json-schema-validator.js";
+import { logger } from "./logger.js";
+import { invalidateAuthEntryCache } from "./mcp-auth.js";
+import { extractOAuthConfig, supportsOAuth } from "./mcp-auth-flow.js";
+import { getBearerTokenForUrl } from "./mcp-bearer-store.js";
+import { McpOAuthProvider } from "./mcp-oauth-provider.js";
+import { probeMcpEndpoint } from "./mcp-probe.js";
+import { createMcpTraceWriter, isMcpTraceEnabled, traceTransportKind, wrapTransportWithMcpTrace, } from "./mcp-trace.js";
+import { resolveNpxBinary } from "./npx-resolver.js";
+import { createRequestHeadersCommandFetch } from "./request-headers-command.js";
+import { combineAbortSignals } from "./runtime-owner.js";
+import { registerSamplingHandler } from "./sampling-handler.js";
+import { isServerDisabled, SERVER_STREAM_RESULT_PATCH_METHOD, serverStreamResultPatchNotificationSchema, } from "./types.js";
+import { UnixSocketClientTransport } from "./unix-socket-transport.js";
+import { interpolateEnvVars, resolveBearerToken, resolveCommandSecret, resolveCommandSecretsRecord, resolveConfigPath, resolveServerUrl, } from "./utils.js";
+const MAX_CAPTURED_STDERR_BYTES = 8 * 1024;
+const MAX_CAPTURED_STDERR_LINES = 3;
+const abortCleanupPromises = new WeakMap();
+function isUnauthorizedHttpError(error) {
+    return error instanceof UnauthorizedError || (error instanceof SdkHttpError && error.status === 401);
+}
+function shouldFallbackToSse(error, definition) {
+    if (definition.protocolVersion === "2026-07-28")
+        return false;
+    return error instanceof SdkHttpError && [404, 405, 406, 415].includes(error.status);
+}
+function resolveVersionNegotiation(definition) {
+    switch (definition.protocolVersion) {
+        case undefined:
+        case "legacy":
+            return undefined;
+        case "auto":
+            return { mode: "auto" };
+        case "2026-07-28":
+            return { mode: { pin: "2026-07-28" } };
+        default:
+            throw new Error(`Invalid MCP protocolVersion: ${String(definition.protocolVersion)}`);
+    }
+}
+function boundedStderrChunk(chunk) {
+    if (Buffer.isBuffer(chunk)) {
+        const start = Math.max(0, chunk.byteLength - MAX_CAPTURED_STDERR_BYTES);
+        return Buffer.from(chunk.subarray(start));
+    }
+    // Limit string conversion before encoding; Buffer.from(largeString) would
+    // otherwise allocate the entire stderr event before applying the cap.
+    const suffix = chunk.length > MAX_CAPTURED_STDERR_BYTES ? chunk.slice(-MAX_CAPTURED_STDERR_BYTES) : chunk;
+    const bytes = Buffer.from(suffix, "utf8");
+    return bytes.byteLength > MAX_CAPTURED_STDERR_BYTES
+        ? Buffer.from(bytes.subarray(bytes.byteLength - MAX_CAPTURED_STDERR_BYTES))
+        : bytes;
+}
+function appendStderrTail(tail, chunk) {
+    const bytes = boundedStderrChunk(chunk);
+    if (bytes.length === 0)
+        return tail;
+    if (tail.length === 0)
+        return bytes;
+    const combined = Buffer.concat([tail, bytes]);
+    return combined.length > MAX_CAPTURED_STDERR_BYTES
+        ? Buffer.from(combined.subarray(combined.length - MAX_CAPTURED_STDERR_BYTES))
+        : combined;
+}
+const KEEP_ALIVE_REFRESH_TIMEOUT_MS = 5_000;
+export class McpServerManager {
+    connections = new Map();
+    connectPromises = new Map();
+    reconnectPromises = new Map();
+    uiStreamListeners = new Map();
+    samplingConfig;
+    metadataListChangedListener;
+    pendingMetadataPublications = new Map();
+    elicitationConfig;
+    authStorageOptions = {};
+    oauthRuntime;
+    acceptedUrlElicitations = new Map();
+    defaultRequestTimeoutMs;
+    runtimeSignal;
+    closePromises = new Map();
+    closeGenerations = new Map();
+    connectAttempts = new Map();
+    traceSettings;
+    traceWriter;
+    stopped = false;
+    defaultCwd;
+    /** Default cwd for stdio servers without an explicit config `cwd`. */
+    constructor(defaultCwd) {
+        this.defaultCwd = defaultCwd;
+    }
+    setSamplingConfig(config) {
+        this.samplingConfig = config;
+    }
+    setMetadataListChangedListener(listener) {
+        this.metadataListChangedListener = listener;
+    }
+    publishMetadataChanged(name, expectedConnection, reason) {
+        const current = this.connections.get(name);
+        if (current !== expectedConnection || current.status !== "connected")
+            return false;
+        try {
+            this.metadataListChangedListener?.(name, reason);
+            this.pendingMetadataPublications.delete(name);
+            return true;
+        }
+        catch (error) {
+            this.pendingMetadataPublications.set(name, { connection: expectedConnection, reason });
+            const message = error instanceof Error ? error.message : String(error);
+            logger.debug(`MCP: metadata publication failed for ${name}; queued for retry: ${message}`);
+            return false;
+        }
+    }
+    setElicitationConfig(config) {
+        this.elicitationConfig = config;
+    }
+    setRuntimeSignal(signal) {
+        this.runtimeSignal = signal;
+    }
+    setDefaultRequestTimeoutMs(timeoutMs) {
+        this.defaultRequestTimeoutMs = normalizeRequestTimeoutMs(timeoutMs);
+    }
+    setTraceConfig(settings) {
+        this.traceSettings = settings;
+    }
+    setAuthStorageOptions(options) {
+        this.authStorageOptions = options;
+    }
+    setOAuthRuntime(runtime) {
+        this.oauthRuntime = runtime;
+    }
+    getRequestOptions(name, signal) {
+        const connection = this.connections.get(name);
+        return this.buildRequestOptions(connection?.definition, signal);
+    }
+    getResolvedRequestTimeoutMs(definition) {
+        if (definition?.requestTimeoutMs !== undefined) {
+            return normalizeRequestTimeoutMs(definition.requestTimeoutMs);
+        }
+        return this.defaultRequestTimeoutMs;
+    }
+    buildRequestOptions(definition, signal) {
+        const timeout = this.getResolvedRequestTimeoutMs(definition);
+        const ownedSignal = combineAbortSignals(this.runtimeSignal, signal);
+        if (!ownedSignal && timeout === undefined) {
+            return undefined;
+        }
+        return {
+            ...(ownedSignal ? { signal: ownedSignal } : {}),
+            ...(timeout !== undefined ? { timeout } : {}),
+        };
+    }
+    async connect(name, definition, signal) {
+        if (isServerDisabled(definition))
+            throw new Error(`MCP server "${name}" is disabled`);
+        if (this.stopped)
+            throw new Error("MCP server manager is closed");
+        const ownedSignal = combineAbortSignals(this.runtimeSignal, signal);
+        throwIfAborted(ownedSignal);
+        const closing = this.closePromises.get(name);
+        if (closing)
+            await abortable(closing, ownedSignal);
+        throwIfAborted(ownedSignal);
+        // Dedupe concurrent connection attempts.
+        if (this.connectPromises.has(name)) {
+            return abortable(this.connectPromises.get(name), ownedSignal);
+        }
+        const existing = this.connections.get(name);
+        if (existing?.status === "connected") {
+            existing.lastUsedAt = Date.now();
+            return existing;
+        }
+        const credentialsInvalidated = existing?.status === "needs-auth" && existing.credentialsInvalidated === true;
+        const generation = this.closeGenerations.get(name) ?? 0;
+        const attemptController = new AbortController();
+        const attemptSignal = combineAbortSignals(ownedSignal, attemptController.signal);
+        const connectionAttempt = this.createConnection(name, definition, attemptSignal, ownedSignal, credentialsInvalidated);
+        const promise = definition.url
+            ? connectionAttempt.catch(async (error) => {
+                throw await this.enrichHttpConnectionError(definition, error);
+            })
+            : connectionAttempt;
+        this.connectPromises.set(name, promise);
+        this.connectAttempts.set(name, attemptController);
+        try {
+            const connection = await promise;
+            if (attemptController.signal.aborted || (this.closeGenerations.get(name) ?? 0) !== generation) {
+                await this.disposeConnection(connection);
+                throwIfAborted(attemptSignal);
+                throw new Error(`MCP connection for ${name} was closed while connecting`);
+            }
+            this.connections.set(name, connection);
+            return connection;
+        }
+        finally {
+            if (this.connectPromises.get(name) === promise)
+                this.connectPromises.delete(name);
+            if (this.connectAttempts.get(name) === attemptController)
+                this.connectAttempts.delete(name);
+        }
+    }
+    /**
+     * Reconnect a server whose connection was proven stale (e.g. by a 404
+     * "session no longer exists" response). Single-flight per server name —
+     * concurrent callers that raced to the same failure share one reconnect —
+     * and identity-guarded: `staleConnection` is only torn down if it is
+     * still the manager's current connection for `name`. If a concurrent
+     * reconnect (or an unrelated connect()) already replaced it with a fresh
+     * connection, that fresh connection is returned untouched.
+     */
+    async reconnect(name, definition, staleConnection, signal) {
+        if (isServerDisabled(definition))
+            throw new Error(`MCP server "${name}" is disabled`);
+        if (this.stopped)
+            throw new Error("MCP server manager is closed");
+        const ownedSignal = combineAbortSignals(this.runtimeSignal, signal);
+        throwIfAborted(ownedSignal);
+        const inFlight = this.reconnectPromises.get(name);
+        if (inFlight) {
+            return abortable(inFlight, ownedSignal);
+        }
+        const promise = this.doReconnect(name, definition, staleConnection, ownedSignal).finally(() => {
+            if (this.reconnectPromises.get(name) === promise) {
+                this.reconnectPromises.delete(name);
+            }
+        });
+        this.reconnectPromises.set(name, promise);
+        return abortable(promise, ownedSignal);
+    }
+    /**
+     * Fetch the authoritative tool catalog for a connection that still appears
+     * connected. The SDK response cache is explicitly bypassed so this request
+     * also proves the remote Streamable HTTP session is usable. Results are
+     * identity-guarded: a late response from a replaced connection is ignored.
+     */
+    async refreshTools(name, expectedConnection, signal) {
+        if (this.stopped)
+            throw new Error("MCP server manager is closed");
+        const ownedSignal = combineAbortSignals(this.runtimeSignal, signal);
+        throwIfAborted(ownedSignal);
+        const current = this.connections.get(name);
+        if (current !== expectedConnection || current.status !== "connected") {
+            return "superseded";
+        }
+        const requestOptions = this.buildRequestOptions(expectedConnection.definition, signal);
+        const timeout = Math.min(requestOptions?.timeout ?? KEEP_ALIVE_REFRESH_TIMEOUT_MS, KEEP_ALIVE_REFRESH_TIMEOUT_MS);
+        const healthOptions = {
+            ...requestOptions,
+            timeout,
+        };
+        if (!expectedConnection.client.getServerCapabilities?.()?.tools) {
+            await expectedConnection.client.ping(healthOptions);
+            throwIfAborted(ownedSignal);
+            if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") {
+                return "superseded";
+            }
+            this.retryPendingMetadataPublication(name, expectedConnection);
+            return "unchanged";
+        }
+        const toolsRevision = expectedConnection.toolsRevision ?? 0;
+        const refreshSignal = combineAbortSignals(healthOptions.signal, AbortSignal.timeout(timeout));
+        let tools;
+        try {
+            tools = await this.fetchAllTools(expectedConnection.client, {
+                ...healthOptions,
+                ...(refreshSignal ? { signal: refreshSignal } : {}),
+                cacheMode: "refresh",
+            });
+        }
+        catch (error) {
+            throwIfAborted(ownedSignal);
+            if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") {
+                return "superseded";
+            }
+            if (error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout) {
+                return "refresh-timeout";
+            }
+            throw error;
+        }
+        throwIfAborted(ownedSignal);
+        if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") {
+            return "superseded";
+        }
+        if ((expectedConnection.toolsRevision ?? 0) !== toolsRevision) {
+            return "superseded";
+        }
+        if (isDeepStrictEqual(expectedConnection.tools, tools)) {
+            this.retryPendingMetadataPublication(name, expectedConnection);
+            return "unchanged";
+        }
+        const previousTools = expectedConnection.tools;
+        expectedConnection.tools = tools;
+        expectedConnection.toolsRevision = toolsRevision + 1;
+        try {
+            await this.metadataListChangedListener?.(name, "keep-alive-refresh");
+            this.pendingMetadataPublications.delete(name);
+        }
+        catch (error) {
+            if (this.connections.get(name) === expectedConnection && expectedConnection.tools === tools) {
+                expectedConnection.tools = previousTools;
+                expectedConnection.toolsRevision = toolsRevision;
+            }
+            throw error;
+        }
+        return "updated";
+    }
+    retryPendingMetadataPublication(name, connection) {
+        const pendingPublication = this.pendingMetadataPublications.get(name);
+        if (pendingPublication?.connection !== connection)
+            return;
+        this.metadataListChangedListener?.(name, pendingPublication.reason);
+        if (this.pendingMetadataPublications.get(name) === pendingPublication) {
+            this.pendingMetadataPublications.delete(name);
+        }
+    }
+    async doReconnect(name, definition, staleConnection, signal) {
+        throwIfAborted(signal);
+        const current = this.connections.get(name);
+        // Never tear down a connection we didn't prove stale: if the map no
+        // longer holds the connection we were asked to replace, someone else
+        // already reconnected (or connected) first.
+        if (current !== staleConnection) {
+            return current ?? this.connect(name, definition, signal);
+        }
+        const staleInFlight = staleConnection.inFlight;
+        await this.close(name);
+        const fresh = await this.connect(name, definition, signal);
+        fresh.inFlight = Math.max(fresh.inFlight, staleInFlight);
+        return fresh;
+    }
+    async createConnection(name, definition, signal, requestSignal, credentialsInvalidated = false) {
+        throwIfAborted(signal);
+        const tracingEnabled = isMcpTraceEnabled(definition, this.traceSettings);
+        if (tracingEnabled && !this.traceWriter) {
+            this.traceWriter = createMcpTraceWriter(this.defaultCwd, this.traceSettings ?? {});
+        }
+        const traceWriter = tracingEnabled ? this.traceWriter : undefined;
+        const traceObserver = traceWriter
+            ? { record: (event) => traceWriter.write(event) }
+            : undefined;
+        let client;
+        let transport;
+        let clientConnected = false;
+        let invalidated = credentialsInvalidated;
+        let transportAlreadyTraced = false;
+        let stderrTail = Buffer.alloc(0);
+        const configuredTransports = [definition.command, definition.url, definition.socket].filter((value) => typeof value === "string" && value.length > 0);
+        if (configuredTransports.length !== 1) {
+            throw new Error(`Server ${name} must configure exactly one of command, url, or socket`);
+        }
+        const requestOptions = this.buildRequestOptions(definition, requestSignal);
+        if (definition.command) {
+            client = this.createClient(name, definition);
+            let command = definition.command;
+            let args = (definition.args ?? []).map(interpolateEnvVars);
+            if (command === "npx" || command === "npm") {
+                const resolved = await resolveNpxBinary(command, args, signal);
+                if (resolved) {
+                    command = resolved.isJs ? "node" : resolved.binPath;
+                    args = resolved.isJs ? [resolved.binPath, ...resolved.extraArgs] : resolved.extraArgs;
+                    logger.debug(`${name} resolved to ${resolved.binPath} (skipping npm parent)`);
+                }
+            }
+            throwIfAborted(signal);
+            if (definition.pluginDataDir)
+                mkdirSync(definition.pluginDataDir, { recursive: true });
+            const cwd = resolveConfigPath(definition.cwd) ?? this.defaultCwd;
+            const stdioTransport = new StdioClientTransport({
+                command,
+                args,
+                env: resolveEnv(definition.env, name, definition.literalEnv === true),
+                ...(cwd !== undefined ? { cwd } : {}),
+                stderr: definition.debug ? "inherit" : "pipe",
+            });
+            // Keep non-debug child diagnostics available for connection failures without
+            // retaining an unbounded stream or changing the existing debug behavior.
+            if (stdioTransport.stderr) {
+                stdioTransport.stderr.on("data", (chunk) => {
+                    stderrTail = appendStderrTail(stderrTail, chunk);
+                });
+            }
+            transport = stdioTransport;
+        }
+        else if (definition.url) {
+            const httpConnection = await this.connectHttpClient(definition, name, requestOptions, signal, traceObserver, invalidated);
+            client = httpConnection.client;
+            transport = httpConnection.transport;
+            invalidated = httpConnection.credentialsInvalidated;
+            if (httpConnection.status === "needs-auth") {
+                return {
+                    client,
+                    transport,
+                    definition,
+                    tools: [],
+                    resources: [],
+                    prompts: [],
+                    lastUsedAt: Date.now(),
+                    inFlight: 0,
+                    status: "needs-auth",
+                    credentialsInvalidated: invalidated,
+                };
+            }
+            clientConnected = true;
+            transportAlreadyTraced = traceObserver !== undefined;
+        }
+        else {
+            client = this.createClient(name, definition);
+            transport = new UnixSocketClientTransport(resolveConfigPath(definition.socket));
+        }
+        if (traceObserver && !transportAlreadyTraced) {
+            const traceTransportKindValue = traceTransportKind(definition, transport);
+            transport = wrapTransportWithMcpTrace(transport, name, traceTransportKindValue, traceObserver);
+        }
+        try {
+            throwIfAborted(signal);
+            if (!clientConnected) {
+                await this.connectClientWithAbort(client, transport, requestOptions, signal);
+            }
+            this.attachAdapterNotificationHandlers(name, client);
+            const instructions = client.getInstructions?.();
+            const connection = {
+                client,
+                transport,
+                definition,
+                tools: [],
+                toolsRevision: 0,
+                resources: [],
+                prompts: [],
+                ...(instructions !== undefined ? { instructions } : {}),
+                lastUsedAt: Date.now(),
+                inFlight: 0,
+                status: "connected",
+            };
+            // Reflect the SDK's own close signal in connection status, guarded by
+            // identity so a stale connection's late close can never clobber a fresh
+            // connection. The SDK client owns the transport callbacks.
+            client.onclose = () => {
+                if (this.connections.get(name) === connection) {
+                    connection.status = "closed";
+                }
+            };
+            // Discover tools, resources, and prompts. Resource and prompt listing is
+            // optional: only servers advertising the capability are queried.
+            const [tools, resources, promptResult] = await Promise.all([
+                this.fetchAllTools(client, requestOptions),
+                this.fetchAllResources(client, requestOptions),
+                this.fetchAllPrompts(client, requestOptions),
+            ]);
+            connection.tools = tools;
+            connection.resources = resources;
+            connection.prompts = promptResult.prompts;
+            connection.promptDiscoveryFailed = promptResult.failed;
+            return connection;
+        }
+        catch (error) {
+            // If connectClientWithAbort closed the transport, await that exact close.
+            // Otherwise the SDK client owns its transport and performs cleanup once.
+            const abortCleanup = abortCleanupPromises.get(transport);
+            const abortCleanupFailed = error instanceof AggregateError && error.message === "MCP connection abort cleanup failed";
+            const cleanupResults = abortCleanupFailed
+                ? []
+                : await Promise.allSettled([abortCleanup ?? Promise.resolve().then(() => client.close())]);
+            const cleanupFailures = cleanupResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            let reportedError = error;
+            if (cleanupFailures.length > 0) {
+                reportedError = new AggregateError([error, ...cleanupFailures], "MCP connection setup failed");
+            }
+            // A cleanup failure remains a setup failure rather than being hidden
+            // behind needs-auth.
+            if (isUnauthorizedHttpError(error) && supportsOAuth(definition) && cleanupFailures.length === 0) {
+                if (!invalidated) {
+                    invalidateAuthEntryCache(name);
+                    invalidated = true;
+                }
+                return {
+                    client,
+                    transport,
+                    definition,
+                    tools: [],
+                    resources: [],
+                    prompts: [],
+                    lastUsedAt: Date.now(),
+                    inFlight: 0,
+                    status: "needs-auth",
+                    credentialsInvalidated: invalidated,
+                };
+            }
+            if (stderrTail.length > 0) {
+                const stderrText = stderrTail.toString("utf8").trim();
+                const lines = stderrText
+                    .split(/\r?\n/)
+                    .map((line) => line.trim())
+                    .filter(Boolean);
+                if (lines.length > 0) {
+                    const baseMessage = reportedError instanceof Error ? reportedError.message : String(reportedError);
+                    const detail = lines.slice(-MAX_CAPTURED_STDERR_LINES).join(" — ");
+                    throw new Error(`${baseMessage} (${detail})`, { cause: reportedError });
+                }
+            }
+            throw reportedError;
+        }
+    }
+    async enrichHttpConnectionError(definition, error) {
+        const originalMessage = error instanceof Error ? error.message : String(error);
+        try {
+            const probe = await probeMcpEndpoint(resolveServerUrl(definition));
+            return new Error(`${originalMessage} — probe: ${probe.classification}`, { cause: error });
+        }
+        catch {
+            return error instanceof Error ? error : new Error(originalMessage);
+        }
+    }
+    async connectClientWithAbort(client, transport, requestOptions, signal) {
+        throwIfAborted(signal);
+        let abortCleanup;
+        const closeTransport = () => {
+            abortCleanup = Promise.resolve().then(() => transport.close());
+            abortCleanupPromises.set(transport, abortCleanup);
+        };
+        signal?.addEventListener("abort", closeTransport, { once: true });
+        try {
+            await abortable(client.connect(transport, requestOptions), signal);
+            await abortCleanup;
+        }
+        catch (error) {
+            if (abortCleanup) {
+                try {
+                    await abortCleanup;
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], "MCP connection abort cleanup failed");
+                }
+            }
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener("abort", closeTransport);
+        }
+    }
+    buildClientCapabilities() {
+        return {
+            ...(this.samplingConfig ? { sampling: {} } : {}),
+            ...(this.elicitationConfig
+                ? {
+                    elicitation: {
+                        form: {},
+                        ...(this.elicitationConfig.allowUrl ? { url: {} } : {}),
+                    },
+                }
+                : {}),
+        };
+    }
+    createClient(serverName, definition) {
+        const capabilities = this.buildClientCapabilities();
+        const versionNegotiation = resolveVersionNegotiation(definition);
+        let client;
+        client = new Client({ name: `nexus-cli-mcp-${serverName}`, version: VERSION }, {
+            jsonSchemaValidator: createJsonSchemaValidator(),
+            ...(versionNegotiation ? { versionNegotiation } : {}),
+            ...(Object.keys(capabilities).length > 0 ? { capabilities } : {}),
+            listChanged: {
+                tools: {
+                    onChanged: (error, tools) => {
+                        this.handleToolsListChanged(serverName, client, error, tools);
+                    },
+                },
+                resources: {
+                    onChanged: (error, resources) => {
+                        this.handleResourcesListChanged(serverName, client, error, resources);
+                    },
+                },
+                prompts: {
+                    onChanged: (error, prompts) => {
+                        this.handlePromptsListChanged(serverName, client, error, prompts);
+                    },
+                },
+            },
+        });
+        if (this.samplingConfig) {
+            registerSamplingHandler(client, { ...this.samplingConfig, serverName });
+        }
+        if (this.elicitationConfig) {
+            registerElicitationHandler(client, {
+                ...this.elicitationConfig,
+                serverName,
+                onUrlAccepted: (elicitationId) => this.rememberUrlElicitation(serverName, elicitationId),
+            });
+            if (this.elicitationConfig.allowUrl) {
+                client.setNotificationHandler("notifications/elicitation/complete", (notification) => {
+                    if (this.runtimeSignal?.aborted)
+                        return;
+                    const accepted = this.acceptedUrlElicitations.get(serverName);
+                    if (!accepted?.delete(notification.params.elicitationId))
+                        return;
+                    this.elicitationConfig?.ui.notify(`MCP browser interaction for ${serverName} completed. You can retry the tool now.`, "info");
+                });
+            }
+        }
+        return client;
+    }
+    handleToolsListChanged(serverName, client, error, tools) {
+        if (error) {
+            logger.debug(`MCP: tools/list_changed refresh failed for ${serverName}: ${error.message}`);
+            return;
+        }
+        if (!tools)
+            return;
+        const connection = this.connections.get(serverName);
+        if (!connection || connection.client !== client || connection.status !== "connected")
+            return;
+        connection.tools = tools;
+        connection.toolsRevision = (connection.toolsRevision ?? 0) + 1;
+        this.metadataListChangedListener?.(serverName, "tools-list-changed");
+        this.pendingMetadataPublications.delete(serverName);
+    }
+    handlePromptsListChanged(serverName, client, error, prompts) {
+        if (error) {
+            logger.debug(`MCP: prompts/list_changed refresh failed for ${serverName}: ${error.message}`);
+            return;
+        }
+        if (!prompts)
+            return;
+        const connection = this.connections.get(serverName);
+        if (!connection || connection.client !== client || connection.status !== "connected")
+            return;
+        connection.prompts = prompts;
+        connection.promptDiscoveryFailed = false;
+        this.metadataListChangedListener?.(serverName, "prompts-list-changed");
+        this.pendingMetadataPublications.delete(serverName);
+    }
+    handleResourcesListChanged(serverName, client, error, resources) {
+        if (error) {
+            logger.debug(`MCP: resources/list_changed refresh failed for ${serverName}: ${error.message}`);
+            return;
+        }
+        if (!resources)
+            return;
+        const connection = this.connections.get(serverName);
+        if (!connection || connection.client !== client || connection.status !== "connected")
+            return;
+        connection.resources = resources;
+        this.metadataListChangedListener?.(serverName, "resources-list-changed");
+        this.pendingMetadataPublications.delete(serverName);
+    }
+    async handleUrlElicitationRequired(serverName, error) {
+        if (this.runtimeSignal?.aborted || !this.elicitationConfig?.allowUrl)
+            return "cancel";
+        for (const params of error.elicitations) {
+            const result = await handleUrlElicitation({
+                ...this.elicitationConfig,
+                serverName,
+                onUrlAccepted: (elicitationId) => this.rememberUrlElicitation(serverName, elicitationId),
+            }, params);
+            if (result.action !== "accept")
+                return result.action;
+        }
+        return "accept";
+    }
+    rememberUrlElicitation(serverName, elicitationId) {
+        if (this.runtimeSignal?.aborted)
+            return;
+        let accepted = this.acceptedUrlElicitations.get(serverName);
+        if (!accepted) {
+            accepted = new Set();
+            this.acceptedUrlElicitations.set(serverName, accepted);
+        }
+        accepted.add(elicitationId);
+    }
+    async connectHttpClient(definition, serverName, requestOptions, signal, traceObserver, credentialsInvalidated = false) {
+        throwIfAborted(signal);
+        const serverUrl = resolveServerUrl(definition);
+        const url = new URL(serverUrl);
+        // Resolve secret commands only for this connection attempt, without
+        // mutating the persisted configuration.
+        const hasCommandHeader = Object.values(definition.headers ?? {}).some((value) => value.startsWith("!") && !value.startsWith("!!"));
+        const headers = resolveCommandSecretsRecord(definition.headers, (key) => `MCP server "${serverName}" HTTP header "${key}"`) ??
+            {};
+        // Resolve bearer auth before creating requestInit so every attempted
+        // transport receives the same headers.
+        const commandBearer = definition.bearerToken?.startsWith("!") && !definition.bearerToken.startsWith("!!")
+            ? definition.bearerToken
+            : undefined;
+        if (definition.auth === "bearer") {
+            const token = commandBearer
+                ? resolveCommandSecret(commandBearer, `MCP server "${serverName}" HTTP bearer token`)
+                : (resolveBearerToken(definition) ??
+                    (definition.bearerToken === undefined &&
+                        definition.bearerTokenEnv === undefined &&
+                        definition.bearerTokenStore === true
+                        ? getBearerTokenForUrl(serverName, serverUrl)
+                        : undefined));
+            if (token)
+                headers.Authorization = `Bearer ${token}`;
+        }
+        if (hasCommandHeader || commandBearer) {
+            try {
+                new Headers(headers);
+            }
+            catch {
+                throw new Error(`Failed to resolve MCP server "${serverName}" HTTP command secret: command returned an invalid header value`);
+            }
+        }
+        const requestInit = Object.keys(headers).length > 0 ? { headers } : undefined;
+        const requestFetch = definition.requestHeadersCommand
+            ? createRequestHeadersCommandFetch(definition.requestHeadersCommand)
+            : undefined;
+        const createAuthProvider = () => new McpOAuthProvider(serverName, serverUrl, extractOAuthConfig(definition), { onRedirect: async () => { } }, this.authStorageOptions, this.oauthRuntime?.signal);
+        // Explicit OAuth checks secure storage immediately. Implicit OAuth defers
+        // provider construction until the server proves authentication is needed.
+        let authState = supportsOAuth(definition)
+            ? definition.auth === undefined
+                ? { status: "implicit-deferred" }
+                : { status: "explicit", provider: createAuthProvider() }
+            : { status: "disabled" };
+        const attempt = async (kind) => {
+            const authProvider = "provider" in authState ? authState.provider : undefined;
+            const transportOptions = {
+                ...(requestInit !== undefined ? { requestInit } : {}),
+                ...(requestFetch !== undefined ? { fetch: requestFetch } : {}),
+                ...(authProvider !== undefined ? { authProvider } : {}),
+                ...(authProvider !== undefined &&
+                    definition.oauth !== false &&
+                    definition.oauth?.skipIssuerMetadataValidation === true
+                    ? { skipIssuerMetadataValidation: true }
+                    : {}),
+            };
+            const baseTransport = kind === "streamable-http"
+                ? new StreamableHTTPClientTransport(url, transportOptions)
+                : new SSEClientTransport(url, transportOptions);
+            const transport = traceObserver
+                ? wrapTransportWithMcpTrace(baseTransport, serverName, kind, traceObserver)
+                : baseTransport;
+            const client = this.createClient(serverName, definition);
+            try {
+                await this.connectClientWithAbort(client, transport, requestOptions, signal);
+                return { status: "connected", client, transport };
+            }
+            catch (error) {
+                const abortCleanupFailed = error instanceof AggregateError && error.message === "MCP connection abort cleanup failed";
+                if (!abortCleanupFailed) {
+                    try {
+                        await (abortCleanupPromises.get(transport) ?? client.close());
+                    }
+                    catch (cleanupError) {
+                        throw new AggregateError([error, cleanupError], "MCP HTTP connection cleanup failed");
+                    }
+                }
+                return { status: "failed", client, transport, error };
+            }
+        };
+        // Connect the real client once. Retry Streamable HTTP only for an implicit
+        // OAuth challenge; use SSE only for definitive endpoint incompatibility.
+        // Agent Plugins set httpTransport, and their declared transport is used without fallback.
+        let kind = definition.httpTransport ?? "streamable-http";
+        let invalidated = credentialsInvalidated;
+        for (;;) {
+            const result = await attempt(kind);
+            if (result.status === "connected")
+                return { ...result, credentialsInvalidated: invalidated };
+            if (result.error instanceof AggregateError && result.error.message === "MCP connection abort cleanup failed") {
+                throw result.error;
+            }
+            if (signal?.aborted)
+                throwIfAborted(signal);
+            if (authState.status === "implicit-deferred" && isUnauthorizedHttpError(result.error)) {
+                authState = { status: "implicit-challenged", provider: createAuthProvider() };
+                continue;
+            }
+            if (isUnauthorizedHttpError(result.error)) {
+                if (supportsOAuth(definition)) {
+                    if (!invalidated) {
+                        invalidateAuthEntryCache(serverName);
+                        invalidated = true;
+                    }
+                    return {
+                        client: result.client,
+                        transport: result.transport,
+                        status: "needs-auth",
+                        credentialsInvalidated: invalidated,
+                    };
+                }
+                throw result.error;
+            }
+            if (definition.httpTransport === undefined &&
+                kind === "streamable-http" &&
+                shouldFallbackToSse(result.error, definition)) {
+                kind = "sse";
+                continue;
+            }
+            throw result.error;
+        }
+    }
+    async fetchAllTools(client, requestOptions) {
+        const allTools = [];
+        let cursor;
+        do {
+            const result = await client.listTools(cursor ? { cursor } : undefined, requestOptions);
+            allTools.push(...(result.tools ?? []));
+            cursor = result.nextCursor;
+        } while (cursor);
+        return allTools;
+    }
+    async fetchAllPrompts(client, requestOptions) {
+        const capabilities = client.getServerCapabilities?.();
+        if (!capabilities?.prompts)
+            return { prompts: [], failed: false };
+        try {
+            const prompts = [];
+            let cursor;
+            do {
+                const result = await client.listPrompts(cursor ? { cursor } : undefined, requestOptions);
+                prompts.push(...(result.prompts ?? []));
+                cursor = result.nextCursor;
+            } while (cursor);
+            return { prompts, failed: false };
+        }
+        catch (error) {
+            if (requestOptions?.signal?.aborted)
+                throwIfAborted(requestOptions.signal);
+            if (isUnauthorizedHttpError(error))
+                throw error;
+            const message = error instanceof Error ? error.message : String(error);
+            logger.debug(`MCP: prompts/list failed: ${message}`);
+            return { prompts: [], failed: true };
+        }
+    }
+    async fetchAllResources(client, requestOptions) {
+        const capabilities = client.getServerCapabilities?.();
+        if (!capabilities?.resources)
+            return [];
+        try {
+            const allResources = [];
+            let cursor;
+            do {
+                const result = await client.listResources(cursor ? { cursor } : undefined, requestOptions);
+                allResources.push(...(result.resources ?? []));
+                cursor = result.nextCursor;
+            } while (cursor);
+            return allResources;
+        }
+        catch (error) {
+            if (requestOptions?.signal?.aborted) {
+                throwIfAborted(requestOptions.signal);
+            }
+            if (isUnauthorizedHttpError(error))
+                throw error;
+            // The server advertises resources but the listing failed
+            return [];
+        }
+    }
+    attachAdapterNotificationHandlers(serverName, client) {
+        client.setNotificationHandler(SERVER_STREAM_RESULT_PATCH_METHOD, { params: serverStreamResultPatchNotificationSchema.shape.params }, (params) => {
+            const listener = this.uiStreamListeners.get(params.streamToken);
+            if (!listener)
+                return;
+            listener(serverName, params);
+        });
+    }
+    registerUiStreamListener(streamToken, listener) {
+        this.uiStreamListeners.set(streamToken, listener);
+    }
+    removeUiStreamListener(streamToken) {
+        this.uiStreamListeners.delete(streamToken);
+    }
+    async getPrompt(name, promptName, args, signal) {
+        const connection = this.connections.get(name);
+        if (!connection || connection.status !== "connected") {
+            throw new Error(`Server "${name}" is not connected`);
+        }
+        try {
+            this.touch(name);
+            this.incrementInFlight(name);
+            return await connection.client.getPrompt({ name: promptName, ...(args ? { arguments: args } : {}) }, this.getRequestOptions(name, signal));
+        }
+        finally {
+            this.decrementInFlight(name);
+            this.touch(name);
+        }
+    }
+    async readResource(name, uri, signal) {
+        if (isServerDisabled(this.connections.get(name)?.definition)) {
+            throw new Error(`MCP server "${name}" is disabled`);
+        }
+        const connection = this.connections.get(name);
+        if (!connection || connection.status !== "connected") {
+            throw new Error(`Server "${name}" is not connected`);
+        }
+        try {
+            this.touch(name);
+            this.incrementInFlight(name);
+            return await connection.client.readResource({ uri }, this.getRequestOptions(name, signal));
+        }
+        finally {
+            this.decrementInFlight(name);
+            this.touch(name);
+        }
+    }
+    async close(name) {
+        this.closeGenerations.set(name, (this.closeGenerations.get(name) ?? 0) + 1);
+        this.connectAttempts.get(name)?.abort(new Error(`MCP connection ${name} was closed`));
+        this.pendingMetadataPublications.delete(name);
+        const connection = this.connections.get(name);
+        if (!connection) {
+            const pendingClose = this.closePromises.get(name);
+            if (pendingClose) {
+                await pendingClose;
+                return;
+            }
+            const pendingConnect = this.connectPromises.get(name);
+            if (pendingConnect) {
+                try {
+                    await pendingConnect;
+                }
+                catch (error) {
+                    if (this.containsCleanupFailure(error))
+                        throw error;
+                }
+            }
+            return;
+        }
+        // Delete before awaiting SDK cleanup so a replacement cannot be removed by
+        // an old close operation finishing later.
+        connection.status = "closed";
+        this.connections.delete(name);
+        this.acceptedUrlElicitations.delete(name);
+        const closing = this.disposeConnection(connection).finally(() => {
+            if (this.closePromises.get(name) === closing)
+                this.closePromises.delete(name);
+        });
+        this.closePromises.set(name, closing);
+        return closing;
+    }
+    async closeIfCurrent(name, expected) {
+        if (this.connections.get(name) !== expected)
+            return false;
+        await this.close(name);
+        return true;
+    }
+    async disposeConnection(connection) {
+        const results = await Promise.allSettled([
+            // Only client.close() is needed; the client owns the transport and will close it internally.
+            Promise.resolve().then(() => connection.client.close()),
+            this.traceWriter?.flush() ?? Promise.resolve(),
+        ]);
+        const failures = results.flatMap((result) => (result.status === "rejected" ? [result.reason] : []));
+        if (failures.length > 0)
+            throw new AggregateError(failures, "MCP connection cleanup failed");
+    }
+    async closeAll() {
+        this.stopped = true;
+        const names = new Set([...this.connections.keys(), ...this.connectPromises.keys()]);
+        for (const name of names) {
+            this.closeGenerations.set(name, (this.closeGenerations.get(name) ?? 0) + 1);
+            this.connectAttempts.get(name)?.abort(new Error(`MCP connection ${name} was closed`));
+        }
+        const pendingConnects = [...this.connectPromises.values()];
+        const currentNames = [...this.connections.keys()];
+        const pendingResults = await Promise.allSettled(pendingConnects);
+        const results = await Promise.allSettled(currentNames.map((name) => this.close(name)));
+        // A connect that resolved during the first close snapshot is still fenced;
+        // close any handle that was already inserted before its attempt settled.
+        const lateNames = [...this.connections.keys()];
+        const lateResults = await Promise.allSettled(lateNames.map((name) => this.close(name)));
+        const failures = [...pendingResults, ...results, ...lateResults]
+            .flatMap((result) => (result.status === "rejected" ? [result.reason] : []))
+            .filter((error) => this.containsCleanupFailure(error));
+        this.uiStreamListeners.clear();
+        this.acceptedUrlElicitations.clear();
+        this.pendingMetadataPublications.clear();
+        this.samplingConfig = undefined;
+        this.elicitationConfig = undefined;
+        await this.traceWriter?.flush();
+        if (failures.length > 0)
+            throw new AggregateError(failures, "MCP manager cleanup failed");
+    }
+    containsCleanupFailure(error) {
+        const pending = [error];
+        const seen = new Set();
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (!(current instanceof Error) || seen.has(current))
+                continue;
+            seen.add(current);
+            if (current instanceof AggregateError) {
+                if (/cleanup failed|setup failed/.test(current.message))
+                    return true;
+                pending.push(...current.errors);
+            }
+            if (current.cause !== undefined)
+                pending.push(current.cause);
+        }
+        return false;
+    }
+    isConnecting(name) {
+        return this.connectPromises.has(name);
+    }
+    getConnection(name) {
+        return this.connections.get(name);
+    }
+    getAllConnections() {
+        return new Map(this.connections);
+    }
+    touch(name) {
+        const connection = this.connections.get(name);
+        if (connection) {
+            connection.lastUsedAt = Date.now();
+        }
+    }
+    incrementInFlight(name) {
+        const connection = this.connections.get(name);
+        if (connection) {
+            connection.inFlight = (connection.inFlight ?? 0) + 1;
+        }
+    }
+    decrementInFlight(name) {
+        const connection = this.connections.get(name);
+        if (connection?.inFlight) {
+            connection.inFlight--;
+        }
+    }
+    isIdle(name, timeoutMs) {
+        const connection = this.connections.get(name);
+        if (!connection || connection.status !== "connected")
+            return false;
+        if (connection.inFlight > 0)
+            return false;
+        return Date.now() - connection.lastUsedAt > timeoutMs;
+    }
+}
+/**
+ * Resolve environment variables with interpolation.
+ */
+function resolveEnv(env, serverName, literalEnv = false) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined)
+            resolved[key] = value;
+    }
+    if (literalEnv)
+        return env ? { ...resolved, ...env } : resolved;
+    const overrides = resolveCommandSecretsRecord(env, (key) => `MCP server "${serverName}" stdio env "${key}"`);
+    return overrides ? { ...resolved, ...overrides } : resolved;
+}
+function normalizeRequestTimeoutMs(timeoutMs) {
+    return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
+}
+//# sourceMappingURL=server-manager.js.map