@1mcp/agent 0.37.0 → 0.38.0

package/build/sdk/legacy/client/runtime/clientManager.js

@@ -0,0 +1,834 @@
+import { EventEmitter } from 'node:events';
+import { sanitizeRuntimeScopeError } from '../../../../config/runtimeScopeEnv.js';
+import { MCP_SERVER_NAME } from '../../../../constants.js';
+import { DEFAULT_MAX_CONCURRENT_LOADS } from '../../../../constants/mcp.js';
+import { registerCapabilityPaginationNotifications } from '../../../../core/capabilities/capabilityPagination.js';
+import { ParallelExecutor } from '../../../../core/loading/parallelExecutor.js';
+import { BackendStdioSupervisor } from '../../../../core/server/backendStdioSupervisor.js';
+import { ClientStatus } from '../../../../core/types/index.js';
+import logger, { debugIf } from '../../../../logger/logger.js';
+import { CapabilityError, ClientConnectionError, ClientNotFoundError } from '../../../../utils/core/errorTypes.js';
+import { executeOperation } from '../../../../utils/core/operationExecution.js';
+import { getConnectionTimeout } from '../../../../utils/core/timeoutUtils.js';
+import { ClientFactory } from './clientFactory.js';
+import { ConnectionHandler } from './connectionHandler.js';
+import { createLegacyOutboundConnection, getLegacyClient, getLegacyTransport, snapshotSupervision, } from './legacyOutboundConnection.js';
+import { OAuthFlowHandler } from './oauthFlowHandler.js';
+import { TransportRecreator } from './transportRecreator.js';
+import { OAuthRequiredError } from './types.js';
+export { OAuthRequiredError };
+export var ClientManagerEvent;
+(function (ClientManagerEvent) {
+    ClientManagerEvent["BackendSupervisionStateChanged"] = "backend-supervision-state-changed";
+})(ClientManagerEvent || (ClientManagerEvent = {}));
+// Matches the two message shapes downstream servers are observed to send back
+// when a Streamable HTTP / SSE session ID they issued no longer exists on
+// their side (e.g. the backend process restarted and its in-memory session
+// store was wiped): the MCP spec's own "Session not found" wording, and the
+// free-form "Could not find session ID '...'" text some server SDKs use. The
+// second alternative spells out "session id" (rather than a bare "session")
+// so we don't also match unrelated "could not find session <noun>" wording
+// that isn't the specific session-loss shape this recovery path handles.
+const SESSION_LOST_PATTERN = /session (?:id )?not found|could not find session id/i;
+function isSessionLostError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return SESSION_LOST_PATTERN.test(error.message);
+}
+export class ClientManager extends EventEmitter {
+    static instance;
+    outboundConns = new Map();
+    transports = {};
+    connectionSemaphore = new Map();
+    bulkConnectionOperations = new Set();
+    // Backends currently running a session-loss recovery (see recoverFromSessionLoss).
+    // Guards against the same dead client's onerror firing more than once — e.g.
+    // several in-flight requests all failing around the same time — from each
+    // kicking off its own redundant recreateForSessionLoss + createSingleClient.
+    sessionLossRecoveries = new Set();
+    instructionAggregator;
+    clientFactory;
+    connectionHandler;
+    oauthFlowHandler;
+    transportRecreator;
+    backendSupervisors = new Map();
+    backendAvailabilityHandler;
+    isShuttingDown = false;
+    shutdownPromise;
+    constructor() {
+        super();
+        this.clientFactory = new ClientFactory();
+        this.connectionHandler = new ConnectionHandler();
+        this.oauthFlowHandler = new OAuthFlowHandler();
+        this.transportRecreator = new TransportRecreator();
+    }
+    static getOrCreateInstance() {
+        if (!ClientManager.instance) {
+            ClientManager.instance = new ClientManager();
+        }
+        return ClientManager.instance;
+    }
+    static get current() {
+        return ClientManager.instance;
+    }
+    static resetInstance() {
+        ClientManager.instance = undefined;
+    }
+    static async shutdownCurrent() {
+        await ClientManager.instance?.shutdown();
+    }
+    setInstructionAggregator(aggregator) {
+        this.instructionAggregator = aggregator;
+    }
+    setBackendAvailabilityHandler(handler) {
+        this.backendAvailabilityHandler = handler;
+    }
+    extractAndCacheInstructions(name, client) {
+        try {
+            const instructions = client.getInstructions();
+            const connectionInfo = this.outboundConns.get(name);
+            if (connectionInfo) {
+                connectionInfo.instructions = instructions;
+            }
+            // Use clean name from connection object for instruction aggregation
+            // Template servers use hash-based keys (e.g., "serena:6fa053f1...") but we want
+            // to display the clean name (e.g., "serena") in instructions
+            const cleanName = connectionInfo?.name || name;
+            if (this.instructionAggregator) {
+                this.instructionAggregator.setInstructions({ source: 'mcpServers', name: cleanName }, instructions, name);
+            }
+            if (instructions?.trim()) {
+                debugIf(() => ({
+                    message: `Cached instructions for ${cleanName}: ${instructions.length} characters`,
+                    meta: { name: cleanName, instructionLength: instructions.length },
+                }));
+            }
+            else {
+                debugIf(() => ({ message: `No instructions available for ${cleanName}`, meta: { name: cleanName } }));
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.warn(`Failed to extract instructions from ${name}: ${errorMessage}`, {
+                error: errorMessage,
+                clientName: name,
+                transportType: this.outboundConns.has(name)
+                    ? getLegacyTransport(this.outboundConns.get(name)).constructor.name
+                    : undefined,
+                connectionStatus: this.outboundConns.get(name)?.status,
+            });
+        }
+    }
+    setupConnectionHandlers(name, client) {
+        client.onclose = () => {
+            if (this.isShuttingDown) {
+                return;
+            }
+            const clientInfo = this.outboundConns.get(name);
+            if (!clientInfo || getLegacyClient(clientInfo) !== client) {
+                return;
+            }
+            const supervision = getLegacyTransport(clientInfo).stdioSupervision;
+            if (supervision) {
+                this.getOrCreateBackendSupervisor(name, supervision).handleUnexpectedExit(supervision.getLastExit() ?? {
+                    code: null,
+                    signal: null,
+                    pid: this.getTransportPid(getLegacyTransport(clientInfo)),
+                    at: new Date(),
+                });
+                return;
+            }
+            if (clientInfo) {
+                clientInfo.status = ClientStatus.Disconnected;
+            }
+            // Use cleanName for removal to match the key used during caching
+            const cleanName = clientInfo?.name || name;
+            this.instructionAggregator?.removeServer({ source: 'mcpServers', name: cleanName }, name);
+            logger.info(`Client ${name} disconnected`);
+        };
+        client.onerror = (error) => {
+            if (isUnknownMessageIdError(error)) {
+                logger.error(`Client ${name} received a response for an unknown message ID`);
+                return;
+            }
+            const safeError = sanitizeRuntimeScopeError(error);
+            logger.error(`Client ${name} error: ${safeError}`);
+            if (isSessionLostError(safeError)) {
+                this.recoverFromSessionLoss(name, client);
+            }
+        };
+        const connection = this.outboundConns.get(name);
+        if (connection && getLegacyClient(connection) === client) {
+            registerCapabilityPaginationNotifications(this.outboundConns, connection);
+        }
+    }
+    /**
+     * Reconnects a backend whose Streamable HTTP / SSE session was invalidated
+     * server-side (typically because the backend process restarted and lost its
+     * in-memory session store). Without this, the client keeps reusing the dead
+     * session ID on every subsequent request and the backend never recovers
+     * until the whole 1MCP process is restarted.
+     */
+    recoverFromSessionLoss(name, erroredClient) {
+        if (this.isShuttingDown) {
+            return;
+        }
+        // The client that errored may already have been superseded by a newer
+        // connection attempt (e.g. a concurrent recovery, or the server coming
+        // back mid-retry) — only recover if it's still the one on record.
+        const clientInfo = this.outboundConns.get(name);
+        if (!clientInfo || getLegacyClient(clientInfo) !== erroredClient) {
+            return;
+        }
+        // A recovery for this exact dead client is already in flight — e.g. several
+        // requests in flight against the same lost session can each independently
+        // fire onerror around the same time. Let the one already running finish
+        // rather than building a second, redundant replacement transport.
+        if (this.sessionLossRecoveries.has(name)) {
+            return;
+        }
+        this.sessionLossRecoveries.add(name);
+        logger.warn(`Session for ${name} was lost (backend likely restarted) — reconnecting with a fresh session`);
+        const staleTransport = this.transports[name] ?? getLegacyTransport(clientInfo);
+        let freshTransport;
+        try {
+            freshTransport = this.transportRecreator.recreateForSessionLoss(staleTransport, name);
+        }
+        catch (error) {
+            // recreateForSessionLoss only supports HTTP/SSE transports; a session-loss-shaped
+            // error message from some other transport kind must not escape client.onerror.
+            logger.error(`Cannot recover ${name} from session loss: ${error instanceof Error ? error.message : String(error)}`);
+            this.sessionLossRecoveries.delete(name);
+            return;
+        }
+        void this.createSingleClient(name, freshTransport)
+            .catch((error) => {
+            logger.error(`Failed to recover ${name} after session loss: ${error instanceof Error ? error.message : String(error)}`);
+        })
+            .finally(() => {
+            this.sessionLossRecoveries.delete(name);
+            // Whether recovery succeeded or failed, this dead client/transport is no
+            // longer on record for `name` (createSingleClient always replaces it,
+            // even with an error-status placeholder) — close it so its underlying
+            // connection and any pending SSE reconnection timers don't linger.
+            void this.disposeConnectedClient({ client: erroredClient, transport: staleTransport });
+        });
+    }
+    /**
+     * Create multiple MCP clients in parallel with controlled concurrency
+     *
+     * @remarks Uses ParallelExecutor to create clients concurrently with a maximum
+     * of DEFAULT_MAX_CONCURRENT_LOADS (5) simultaneous connections. Individual
+     * client creation failures are captured in the OutboundConnections map with
+     * appropriate error status, allowing other clients to continue loading.
+     *
+     * Error handling details:
+     * - OAuthRequiredError: Client status set to AwaitingOAuth
+     * - Other errors: Client status set to Error with lastError populated
+     *
+     * @param transports - Map of server names to their transport configurations
+     * @returns Map of all attempted connections (successful, failed, and awaiting OAuth)
+     */
+    async createClients(transports) {
+        this.assertActive();
+        const previousNames = [...this.outboundConns.keys()];
+        const nextNames = new Set(Object.keys(transports));
+        const executor = new ParallelExecutor();
+        const serverEntries = Object.entries(transports);
+        const initialCount = serverEntries.length;
+        const bulkOperation = executor.execute(serverEntries, async ([name, transport]) => this.createClient(name, transport, true), {
+            maxConcurrent: DEFAULT_MAX_CONCURRENT_LOADS,
+        });
+        this.bulkConnectionOperations.add(bulkOperation);
+        try {
+            await bulkOperation;
+        }
+        finally {
+            this.bulkConnectionOperations.delete(bulkOperation);
+            for (const name of previousNames) {
+                if (nextNames.has(name))
+                    continue;
+                const connection = this.outboundConns.get(name);
+                // Revoke publication before closing: session recovery may have replaced
+                // the original snapshot, or still be connecting when this name is removed.
+                this.outboundConns.delete(name);
+                delete this.transports[name];
+                this.instructionAggregator?.removeServer({ source: 'mcpServers', name: connection?.name || name }, name);
+                await this.disposeSupersededConnection(name, connection);
+            }
+        }
+        // Check for failures and log summary
+        let failedClientCount = 0;
+        for (const conn of this.outboundConns.values()) {
+            if (conn.status === ClientStatus.Error) {
+                failedClientCount++;
+            }
+        }
+        if (failedClientCount > 0) {
+            logger.error(`Some clients failed to initialize: ${failedClientCount}/${initialCount}`);
+        }
+        let oauthClientCount = 0;
+        for (const conn of this.outboundConns.values()) {
+            if (conn.status === ClientStatus.AwaitingOAuth) {
+                oauthClientCount++;
+            }
+        }
+        if (oauthClientCount > 0) {
+            logger.info(`Clients awaiting OAuth authorization: ${oauthClientCount}/${initialCount}`);
+        }
+        return this.outboundConns;
+    }
+    async createClient(name, transport, preserveHealthyConnection = false) {
+        logger.info(`Creating client for ${name}`);
+        if (this.isShuttingDown) {
+            return;
+        }
+        const existing = this.outboundConns.get(name);
+        const preserveExisting = preserveHealthyConnection && existing?.status === ClientStatus.Connected;
+        if (!preserveExisting)
+            this.transports[name] = transport;
+        try {
+            const client = this.clientFactory.createClient(transport);
+            const connected = await this.connectionHandler.connectWithRetry(client, transport, name, undefined, (t) => this.transportRecreator.recreateForRetry(t, name, { preserveSessionId: false }), (t) => this.clientFactory.createClient(t));
+            if (this.isShuttingDown) {
+                await this.disposeConnectedClient(connected);
+                return;
+            }
+            const superseded = this.outboundConns.get(name);
+            this.recordConnectedClient(name, connected);
+            await this.disposeSupersededConnection(name, superseded, connected.client);
+        }
+        catch (error) {
+            if (this.isShuttingDown) {
+                return;
+            }
+            if (preserveExisting) {
+                if (error instanceof OAuthRequiredError) {
+                    error.client.onclose = undefined;
+                    error.client.onerror = undefined;
+                    await Promise.allSettled([error.client.close(), (error.transport ?? transport).close()]);
+                }
+                if (!(error instanceof OAuthRequiredError) || (error.transport && error.transport !== transport)) {
+                    await transport.close().catch(() => undefined);
+                }
+                const safeError = sanitizeRuntimeScopeError(error);
+                logger.warn(`Keeping healthy client ${name} after replacement failed: ${safeError.message}`);
+                return;
+            }
+            this.handleClientCreationError(name, transport, sanitizeRuntimeScopeError(error));
+        }
+    }
+    handleClientCreationError(name, transport, error) {
+        if (error instanceof OAuthRequiredError) {
+            const activeTransport = error.transport ?? transport;
+            logger.info(`OAuth authorization required for ${name}`, {
+                reason: error.message,
+                hasAuthorizationUrl: !!this.oauthFlowHandler.extractAuthorizationUrl(activeTransport),
+                clientName: name,
+                transportType: activeTransport.constructor.name,
+            });
+            const authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(activeTransport);
+            this.outboundConns.set(name, createLegacyOutboundConnection({
+                name,
+                transport: activeTransport,
+                client: error.client,
+                status: ClientStatus.AwaitingOAuth,
+                authorizationUrl,
+                oauthStartTime: new Date(),
+            }));
+        }
+        else {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Failed to create client for ${name}: ${errorMessage}`, {
+                error: errorMessage,
+                clientName: name,
+                transportType: transport.constructor.name,
+                connectionStatus: this.outboundConns.get(name)?.status,
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            this.outboundConns.set(name, createLegacyOutboundConnection({
+                name,
+                transport,
+                client: this.clientFactory.createClient(transport),
+                status: ClientStatus.Error,
+                lastError: error,
+            }));
+        }
+    }
+    getClient(clientName) {
+        const client = this.outboundConns.get(clientName);
+        if (!client) {
+            throw new ClientNotFoundError(clientName);
+        }
+        return client;
+    }
+    getClients() {
+        return this.outboundConns;
+    }
+    async createSingleClient(name, transport, abortSignal) {
+        this.assertActive();
+        const existingPromise = this.connectionSemaphore.get(name);
+        if (existingPromise) {
+            await existingPromise;
+            return;
+        }
+        if (abortSignal?.aborted) {
+            throw new Error(`Operation aborted: ${abortSignal.reason || 'Request cancelled'}`);
+        }
+        const connectionPromise = this.createSingleClientInternal(name, transport, abortSignal);
+        this.connectionSemaphore.set(name, connectionPromise);
+        try {
+            await connectionPromise;
+        }
+        finally {
+            this.connectionSemaphore.delete(name);
+        }
+    }
+    async createSingleClientInternal(name, transport, abortSignal) {
+        logger.info(`Creating client for ${name}`);
+        const attemptTransport = this.prepareTransportForAttempt(name, transport);
+        this.transports[name] = attemptTransport;
+        try {
+            if (abortSignal?.aborted) {
+                throw new Error(`Operation aborted: ${abortSignal.reason || 'Request cancelled'}`);
+            }
+            const client = this.clientFactory.createClient(attemptTransport);
+            const connected = await this.connectionHandler.connectWithRetry(client, attemptTransport, name, abortSignal, (t) => this.transportRecreator.recreateForRetry(t, name, { preserveSessionId: false }), (t) => this.clientFactory.createClient(t));
+            if (this.isShuttingDown || this.transports[name] !== attemptTransport) {
+                await this.disposeConnectedClient(connected);
+                throw new Error(this.isShuttingDown ? 'ClientManager is shutting down' : `Client ${name} was removed or replaced`);
+            }
+            const superseded = this.outboundConns.get(name);
+            this.recordConnectedClient(name, connected);
+            await this.disposeSupersededConnection(name, superseded, connected.client);
+        }
+        catch (error) {
+            if (this.isShuttingDown || this.transports[name] !== attemptTransport) {
+                if (error instanceof OAuthRequiredError) {
+                    await this.disposeConnectedClient({ client: error.client, transport: error.transport ?? attemptTransport });
+                }
+                throw sanitizeRuntimeScopeError(error);
+            }
+            const safeError = sanitizeRuntimeScopeError(error);
+            this.handleSingleClientError(name, attemptTransport, safeError);
+            throw safeError;
+        }
+    }
+    prepareTransportForAttempt(name, requestedTransport) {
+        const previousConnection = this.outboundConns.get(name);
+        if (previousConnection?.status !== ClientStatus.Error) {
+            return requestedTransport;
+        }
+        return this.transportRecreator.recreateForRetry(requestedTransport, name, { preserveSessionId: false });
+    }
+    recordConnectedClient(name, connected) {
+        const supervision = this.backendSupervisors.get(name)?.snapshot();
+        this.transports[name] = connected.transport;
+        this.outboundConns.set(name, createLegacyOutboundConnection({
+            name,
+            transport: connected.transport,
+            client: connected.client,
+            status: ClientStatus.Connected,
+            lastConnected: new Date(),
+            capabilities: connected.client.getServerCapabilities?.(),
+            supervision,
+        }));
+        logger.info(`Client created for ${name}`);
+        this.extractAndCacheInstructions(name, connected.client);
+        this.setupConnectionHandlers(name, connected.client);
+        const metadata = connected.transport.stdioSupervision;
+        if (metadata) {
+            const supervisor = this.getOrCreateBackendSupervisor(name, metadata);
+            this.applyBackendSupervisionState(name, supervisor.snapshot());
+        }
+    }
+    async disposeSupersededConnection(name, superseded, publishedClient) {
+        if (!superseded || (publishedClient && getLegacyClient(superseded) === publishedClient))
+            return;
+        getLegacyClient(superseded).onclose = undefined;
+        try {
+            await superseded.adapter.close();
+        }
+        catch (error) {
+            const safeError = sanitizeRuntimeScopeError(error);
+            logger.warn(`Could not close superseded client ${name}: ${safeError.message}`);
+        }
+    }
+    handleSingleClientError(name, transport, error) {
+        if (error instanceof OAuthRequiredError) {
+            const activeTransport = error.transport ?? transport;
+            logger.info(`OAuth authorization required for ${name}`, {
+                reason: error.message,
+                hasAuthorizationUrl: !!this.oauthFlowHandler.extractAuthorizationUrl(activeTransport),
+                clientName: name,
+                transportType: activeTransport.constructor.name,
+            });
+            const authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(activeTransport);
+            this.outboundConns.set(name, createLegacyOutboundConnection({
+                name,
+                transport: activeTransport,
+                client: error.client,
+                status: ClientStatus.AwaitingOAuth,
+                authorizationUrl,
+                oauthStartTime: new Date(),
+            }));
+        }
+        else {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Failed to create client for ${name}: ${errorMessage}`, {
+                error: errorMessage,
+                clientName: name,
+                transportType: transport.constructor.name,
+                connectionStatus: this.outboundConns.get(name)?.status,
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            this.outboundConns.set(name, createLegacyOutboundConnection({
+                name,
+                transport,
+                client: this.clientFactory.createClient(transport),
+                status: ClientStatus.Error,
+                lastError: error,
+            }));
+        }
+    }
+    initializeClientsAsync(transports) {
+        this.assertActive();
+        this.transports = transports;
+        this.outboundConns.clear();
+        logger.info(`Initialized client storage for ${Object.keys(transports).length} transports`);
+        return this.outboundConns;
+    }
+    getTransport(name) {
+        return this.transports[name];
+    }
+    getTransportNames() {
+        return Object.keys(this.transports);
+    }
+    async completeOAuthAndReconnect(serverName, authorizationCode) {
+        this.assertActive();
+        const clientInfo = this.outboundConns.get(serverName);
+        if (!clientInfo) {
+            throw new ClientNotFoundError(serverName);
+        }
+        const oldTransport = getLegacyTransport(clientInfo);
+        const newTransport = this.transportRecreator.recreateHttpTransport(oldTransport, serverName, {
+            preserveSessionId: false,
+        });
+        const updatedInfo = await this.oauthFlowHandler.completeOAuthAndReconnect(serverName, oldTransport, newTransport, authorizationCode, clientInfo);
+        if (this.isShuttingDown) {
+            getLegacyClient(updatedInfo).onclose = undefined;
+            await updatedInfo.adapter.close().catch(() => getLegacyTransport(updatedInfo)
+                .close()
+                .catch(() => undefined));
+            throw new Error('ClientManager is shutting down');
+        }
+        this.outboundConns.set(serverName, updatedInfo);
+        this.transports[serverName] = getLegacyTransport(updatedInfo);
+        this.extractAndCacheInstructions(serverName, getLegacyClient(updatedInfo));
+        this.setupConnectionHandlers(serverName, getLegacyClient(updatedInfo));
+    }
+    async executeClientOperation(clientName, operation, options = {}, requiredCapability) {
+        const outboundConn = this.getClient(clientName);
+        if (outboundConn.status !== ClientStatus.Connected) {
+            throw new ClientConnectionError(clientName, new Error('Client not connected'));
+        }
+        if (requiredCapability && !outboundConn.capabilities?.[requiredCapability]) {
+            throw new CapabilityError(clientName, String(requiredCapability));
+        }
+        return executeOperation(() => operation(outboundConn), `client ${clientName}`, options);
+    }
+    createClientInstance() {
+        return this.clientFactory.createClientInstance();
+    }
+    async initiateOAuth(serverName) {
+        this.assertActive();
+        const connection = this.getClient(serverName);
+        const superseded = { ...connection };
+        const transport = this.transportRecreator.recreateHttpTransport(getLegacyTransport(connection), serverName, {
+            preserveSessionId: false,
+        });
+        const client = this.clientFactory.createClient(transport);
+        let authorizationUrl;
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(transport);
+            if (!authorizationUrl) {
+                await this.disposeConnectedClient({ client, transport });
+                throw error;
+            }
+        }
+        if (this.isShuttingDown || this.outboundConns.get(serverName) !== connection) {
+            await this.disposeConnectedClient({ client, transport });
+            throw new Error(`Client ${serverName} was removed or replaced during OAuth initiation`);
+        }
+        // The authorization flow retains this snapshot while initiating OAuth.
+        // Keep its identity, but bind the candidate used to generate the callback state.
+        Object.assign(connection, createLegacyOutboundConnection({
+            name: serverName,
+            client,
+            transport,
+            status: authorizationUrl ? ClientStatus.AwaitingOAuth : ClientStatus.Connected,
+            authorizationUrl,
+            oauthStartTime: authorizationUrl ? new Date() : undefined,
+            capabilities: authorizationUrl ? undefined : client.getServerCapabilities(),
+            lastConnected: authorizationUrl ? undefined : new Date(),
+        }));
+        this.transports[serverName] = transport;
+        if (!authorizationUrl) {
+            connection.authorizationUrl = undefined;
+            connection.oauthStartTime = undefined;
+            this.extractAndCacheInstructions(serverName, client);
+            this.setupConnectionHandlers(serverName, client);
+        }
+        await this.disposeSupersededConnection(serverName, superseded, client);
+    }
+    createPooledClientInstance() {
+        return this.clientFactory.createPooledClientInstance();
+    }
+    async removeClient(name) {
+        const clientInfo = this.outboundConns.get(name);
+        if (!clientInfo) {
+            return;
+        }
+        logger.info(`Removing client ${name}...`);
+        try {
+            const supervisor = this.backendSupervisors.get(name);
+            if (supervisor) {
+                await supervisor.stop();
+                this.backendSupervisors.delete(name);
+            }
+            getLegacyClient(clientInfo).onclose = undefined;
+            const transport = getLegacyTransport(clientInfo);
+            if (transport) {
+                try {
+                    await transport.close();
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.warn(`Error closing transport for ${name}: ${errorMessage}`, {
+                        error: errorMessage,
+                        clientName: name,
+                        transportType: transport.constructor.name,
+                    });
+                }
+            }
+            this.outboundConns.delete(name);
+            delete this.transports[name];
+            this.instructionAggregator?.removeServer({ source: 'mcpServers', name: clientInfo.name || name }, name);
+            logger.info(`Client ${name} removed successfully`);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Error removing client ${name}: ${errorMessage}`, {
+                error: errorMessage,
+                clientName: name,
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            throw error;
+        }
+    }
+    async restartBackend(name) {
+        this.assertActive();
+        const connection = this.getClient(name);
+        const metadata = getLegacyTransport(connection).stdioSupervision;
+        if (!metadata) {
+            throw new ClientConnectionError(name, new Error('Backend stdio supervision is not enabled'));
+        }
+        const supervisor = this.getOrCreateBackendSupervisor(name, metadata);
+        await supervisor.restartNow();
+        return supervisor.snapshot();
+    }
+    getBackendSupervision(name) {
+        return this.backendSupervisors.get(name)?.snapshot();
+    }
+    publishBackendSupervisionState(name, snapshot) {
+        this.applyBackendSupervisionState(name, snapshot);
+    }
+    async shutdown() {
+        if (this.shutdownPromise) {
+            return this.shutdownPromise;
+        }
+        this.isShuttingDown = true;
+        this.shutdownPromise = this.performShutdown();
+        return this.shutdownPromise;
+    }
+    async performShutdown() {
+        const supervisors = Array.from(this.backendSupervisors.values());
+        await Promise.allSettled(supervisors.map((supervisor) => supervisor.stop()));
+        this.backendSupervisors.clear();
+        // Initial connections are not supervisor-owned. Wait for both loading paths
+        // to observe the shutdown gate and dispose their just-connected clients
+        // before clearing the shared maps.
+        await Promise.allSettled([
+            ...Array.from(this.connectionSemaphore.values()),
+            ...Array.from(this.bulkConnectionOperations),
+        ]);
+        const connections = Array.from(this.outboundConns.entries());
+        for (const [, connection] of connections) {
+            getLegacyClient(connection).onclose = undefined;
+        }
+        await Promise.allSettled(connections.map(async ([name, connection]) => {
+            try {
+                await connection.adapter.close();
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn(`Error closing client during shutdown for ${name}: ${errorMessage}`);
+                await getLegacyTransport(connection)
+                    .close()
+                    .catch(() => undefined);
+            }
+            this.instructionAggregator?.removeServer({ source: 'mcpServers', name: connection.name }, name);
+        }));
+        this.outboundConns.clear();
+        this.transports = {};
+        this.connectionSemaphore.clear();
+        this.bulkConnectionOperations.clear();
+        this.backendAvailabilityHandler = undefined;
+        logger.info('ClientManager shutdown complete');
+    }
+    getOrCreateBackendSupervisor(name, metadata) {
+        this.assertActive();
+        const existing = this.backendSupervisors.get(name);
+        if (existing) {
+            return existing;
+        }
+        const supervisor = new BackendStdioSupervisor({
+            backendId: `static:${name}`,
+            policy: metadata.policy,
+            initialPid: this.outboundConns.has(name)
+                ? (getLegacyTransport(this.outboundConns.get(name)).pid ?? null)
+                : null,
+            recover: (signal) => this.recoverSupervisedBackend(name, metadata, signal),
+            onStateChange: (snapshot) => this.applyBackendSupervisionState(name, snapshot),
+        });
+        this.backendSupervisors.set(name, supervisor);
+        return supervisor;
+    }
+    async recoverSupervisedBackend(name, metadata, signal) {
+        const current = this.outboundConns.get(name);
+        if (current) {
+            getLegacyClient(current).onclose = undefined;
+            try {
+                await current.adapter.close();
+            }
+            catch (error) {
+                const safeError = sanitizeRuntimeScopeError(error);
+                debugIf(() => ({ message: `Could not close previous supervised client ${name}: ${safeError}` }));
+            }
+        }
+        if (signal.aborted) {
+            throw new Error(`Backend recovery cancelled for ${name}`);
+        }
+        let transport;
+        let client;
+        const dispose = async () => {
+            if (!client) {
+                await transport?.close().catch(() => undefined);
+                return;
+            }
+            client.onclose = undefined;
+            try {
+                await client.close();
+            }
+            catch {
+                await transport?.close().catch(() => undefined);
+            }
+        };
+        try {
+            transport = metadata.recreate();
+            client = this.clientFactory.createClient(transport);
+            const timeout = getConnectionTimeout(transport);
+            await client.connect(transport, timeout ? { timeout } : undefined);
+            const serverVersion = await client.getServerVersion();
+            if (serverVersion?.name === MCP_SERVER_NAME) {
+                throw new ClientConnectionError(name, new Error('Aborted to prevent circular dependency'));
+            }
+            if (signal.aborted) {
+                throw new Error(`Backend recovery cancelled for ${name}`);
+            }
+            const recoveredClient = client;
+            const recoveredTransport = transport;
+            return {
+                pid: this.getTransportPid(recoveredTransport),
+                activate: () => this.recordConnectedClient(name, { client: recoveredClient, transport: recoveredTransport }),
+                dispose,
+            };
+        }
+        catch (error) {
+            await dispose();
+            throw sanitizeRuntimeScopeError(error);
+        }
+    }
+    applyBackendSupervisionState(name, snapshot) {
+        const connection = this.outboundConns.get(name);
+        if (connection) {
+            connection.supervision = snapshotSupervision(snapshot);
+            logger.info(`Backend stdio supervision state changed for ${name}`, {
+                backendId: snapshot.backendId,
+                state: snapshot.state,
+                attempt: snapshot.attempt,
+                limit: snapshot.limit,
+                nextRetryAt: snapshot.nextRetryAt,
+                lastExit: snapshot.lastExit,
+                currentPid: snapshot.currentPid,
+                error: snapshot.lastError?.message,
+            });
+            if (snapshot.state === 'restarting') {
+                connection.status = ClientStatus.Restarting;
+                connection.capabilities = undefined;
+                connection.instructions = undefined;
+                if (snapshot.backendId.startsWith('static:')) {
+                    this.instructionAggregator?.removeServer({ source: 'mcpServers', name: connection.name }, name);
+                }
+            }
+            else if (snapshot.state === 'crash-loop') {
+                connection.status = ClientStatus.CrashLoop;
+                connection.capabilities = undefined;
+                connection.instructions = undefined;
+                if (snapshot.backendId.startsWith('static:')) {
+                    this.instructionAggregator?.removeServer({ source: 'mcpServers', name: connection.name }, name);
+                }
+            }
+            else if (snapshot.state === 'connected') {
+                connection.status = ClientStatus.Connected;
+            }
+        }
+        this.emit(ClientManagerEvent.BackendSupervisionStateChanged, name, snapshot);
+        try {
+            void Promise.resolve(this.backendAvailabilityHandler?.(name, snapshot)).catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.warn(`Failed to publish backend availability for ${name}: ${message}`);
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(`Failed to publish backend availability for ${name}: ${message}`);
+        }
+    }
+    getTransportPid(transport) {
+        return transport.pid ?? null;
+    }
+    assertActive() {
+        if (this.isShuttingDown) {
+            throw new Error('ClientManager is shutting down');
+        }
+    }
+    async disposeConnectedClient(connected) {
+        connected.client.onclose = undefined;
+        try {
+            await connected.client.close();
+        }
+        catch {
+            await connected.transport.close().catch(() => undefined);
+        }
+    }
+}
+function isUnknownMessageIdError(error) {
+    return error.message.startsWith('Received a response for an unknown message ID:');
+}
+export default ClientManager;
+//# sourceMappingURL=clientManager.js.map