@1mcp/agent 0.39.0-beta.2 → 0.39.0-beta.4

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

@@ -5,7 +5,9 @@ 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 { parseTemplateConnectionKey } from '../../../../core/server/templateIdentity.js';
 import { ClientStatus } from '../../../../core/types/index.js';
+import { writeLocalDiagnostic } from '../../../../logger/localDiagnostics.js';
 import logger, { debugIf } from '../../../../logger/logger.js';
 import { CapabilityError, ClientConnectionError, ClientNotFoundError } from '../../../../utils/core/errorTypes.js';
 import { executeOperation } from '../../../../utils/core/operationExecution.js';
@@ -49,6 +51,12 @@ function isSessionLostError(error) {
     }
     return SESSION_LOST_PATTERN.test(error.message);
 }
+function diagnosticServerName(name) {
+    if (!name)
+        return undefined;
+    const identity = parseTemplateConnectionKey(name);
+    return identity.kind === 'invalid' ? undefined : identity.templateName;
+}
 export class ClientManager extends EventEmitter {
     static instance;
     outboundConns = new Map();
@@ -112,25 +120,19 @@ export class ClientManager extends EventEmitter {
                 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 },
-                }));
+                debugIf(() => ({ message: 'clientManager.cached.instructions.for.characters.60751cf8' }));
             }
             else {
-                debugIf(() => ({ message: `No instructions available for ${cleanName}`, meta: { name: cleanName } }));
+                debugIf(() => ({ message: 'clientManager.no.instructions.available.for.ee166e39' }));
             }
         }
         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,
-            });
+            logger.warn('clientManager.failed.to.extract.instructions.from.05217e1a', { error: errorMessage });
+            writeLocalDiagnostic('warn', 'backend.instructions.extraction.failed', () => ({
+                serverName: diagnosticServerName(name),
+                error,
+            }));
         }
     }
     setupConnectionHandlers(name, client) {
@@ -142,7 +144,13 @@ export class ClientManager extends EventEmitter {
             if (!clientInfo || getLegacyClient(clientInfo) !== client) {
                 return;
             }
-            const supervision = getLegacyTransport(clientInfo).stdioSupervision;
+            const transport = getLegacyTransport(clientInfo);
+            writeLocalDiagnostic('info', 'backend.connection.disconnected', () => ({
+                serverName: diagnosticServerName(name),
+                transportType: transport.constructor.name,
+                supervised: !!transport.stdioSupervision,
+            }));
+            const supervision = transport.stdioSupervision;
             if (supervision) {
                 this.getOrCreateBackendSupervisor(name, supervision).handleUnexpectedExit(supervision.getLastExit() ?? {
                     code: null,
@@ -158,15 +166,20 @@ export class ClientManager extends EventEmitter {
             // 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`);
+            logger.info('clientManager.client.disconnected.827fca0a');
         };
         client.onerror = (error) => {
             if (isUnknownMessageIdError(error)) {
-                logger.error(`Client ${name} received a response for an unknown message ID`);
+                logger.error('clientManager.client.received.a.response.for.an.unknown.message.id.a605b144');
+                writeLocalDiagnostic('error', 'backend.client.response.unknown', () => ({
+                    serverName: diagnosticServerName(name),
+                    error,
+                }));
                 return;
             }
             const safeError = sanitizeRuntimeScopeError(error);
-            logger.error(`Client ${name} error: ${safeError}`);
+            logger.error('clientManager.client.error.775bd985');
+            writeLocalDiagnostic('error', 'backend.client.error', () => ({ serverName: diagnosticServerName(name), error }));
             if (isSessionLostError(safeError)) {
                 this.recoverFromSessionLoss(name, client);
             }
@@ -202,22 +215,64 @@ export class ClientManager extends EventEmitter {
             return;
         }
         this.sessionLossRecoveries.add(name);
-        logger.warn(`Session for ${name} was lost (backend likely restarted) — reconnecting with a fresh session`);
+        logger.warn('clientManager.session.for.was.lost.backend.likely.restarted.reconnecting.with.a.fresh.ses.11164b75');
         const staleTransport = this.transports[name] ?? getLegacyTransport(clientInfo);
+        writeLocalDiagnostic('warn', 'backend.session.recovery.started', () => ({
+            serverName: diagnosticServerName(name),
+            transportType: staleTransport.constructor.name,
+            reason: 'session-lost',
+        }));
         let freshTransport;
         try {
             freshTransport = this.transportRecreator.recreateForSessionLoss(staleTransport, name);
         }
-        catch (error) {
+        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)}`);
+            logger.error('clientManager.cannot.recover.from.session.loss.9b3fa9e8', { error: _error });
+            writeLocalDiagnostic('error', 'backend.session.recovery.failed', () => ({
+                serverName: diagnosticServerName(name),
+                transportType: staleTransport.constructor.name,
+                phase: 'transport-recreation',
+                error: _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)}`);
+            .then(() => {
+            const recovered = this.outboundConns.get(name);
+            if (recovered?.status === ClientStatus.Connected) {
+                writeLocalDiagnostic('info', 'backend.session.recovery.connected', () => ({
+                    serverName: diagnosticServerName(name),
+                    transportType: freshTransport.constructor.name,
+                }));
+                return;
+            }
+            if (recovered?.status === ClientStatus.AwaitingOAuth) {
+                writeLocalDiagnostic('info', 'oauth.session.recovery.pending', () => ({
+                    serverName: diagnosticServerName(name),
+                    transportType: freshTransport.constructor.name,
+                    status: recovered.status,
+                }));
+                return;
+            }
+            writeLocalDiagnostic('warn', 'backend.session.recovery.failed', () => ({
+                serverName: diagnosticServerName(name),
+                transportType: freshTransport.constructor.name,
+                phase: 'published-status',
+                status: recovered?.status ?? 'removed',
+                error: recovered?.lastError,
+            }));
+        })
+            .catch((_error) => {
+            logger.error('clientManager.failed.to.recover.after.session.loss.501b50bc');
+            writeLocalDiagnostic('error', 'backend.session.recovery.failed', () => ({
+                serverName: diagnosticServerName(name),
+                transportType: freshTransport.constructor.name,
+                phase: 'connection',
+                error: _error,
+            }));
         })
             .finally(() => {
             this.sessionLossRecoveries.delete(name);
@@ -249,7 +304,6 @@ export class ClientManager extends EventEmitter {
         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,
         });
@@ -279,7 +333,11 @@ export class ClientManager extends EventEmitter {
             }
         }
         if (failedClientCount > 0) {
-            logger.error(`Some clients failed to initialize: ${failedClientCount}/${initialCount}`);
+            logger.error('clientManager.some.clients.failed.to.initialize.cc2bd21d');
+            writeLocalDiagnostic('error', 'backend.initialization.failed', () => ({
+                failedCount: failedClientCount,
+                totalCount: this.outboundConns.size,
+            }));
         }
         let oauthClientCount = 0;
         for (const conn of this.outboundConns.values()) {
@@ -288,12 +346,19 @@ export class ClientManager extends EventEmitter {
             }
         }
         if (oauthClientCount > 0) {
-            logger.info(`Clients awaiting OAuth authorization: ${oauthClientCount}/${initialCount}`);
+            logger.info('clientManager.clients.awaiting.oauth.authorization.cb150b25');
+            writeLocalDiagnostic('info', 'oauth.authorization.pending', () => ({ pendingCount: oauthClientCount }));
         }
         return this.outboundConns;
     }
     async createClient(name, transport, preserveHealthyConnection = false) {
-        logger.info(`Creating client for ${name}`);
+        logger.info('clientManager.creating.client.for.744dd700');
+        writeLocalDiagnostic('info', 'backend.client.creating', () => ({
+            serverName: diagnosticServerName(name),
+            transportType: transport.constructor.name,
+            connectionTimeoutMs: getConnectionTimeout(transport),
+            requestTimeoutMs: transport.requestTimeout,
+        }));
         if (this.isShuttingDown) {
             return;
         }
@@ -325,8 +390,13 @@ export class ClientManager extends EventEmitter {
                 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}`);
+                logger.warn('clientManager.keeping.healthy.client.after.replacement.failed.fe11642b', { error: error });
+                writeLocalDiagnostic('warn', 'backend.replacement.failed', () => ({
+                    serverName: diagnosticServerName(name),
+                    transportType: transport.constructor.name,
+                    outcome: 'healthy-connection-retained',
+                    error,
+                }));
                 return;
             }
             this.handleClientCreationError(name, transport, sanitizeRuntimeScopeError(error));
@@ -335,13 +405,12 @@ export class ClientManager extends EventEmitter {
     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,
+            logger.info('clientManager.oauth.authorization.required.for.c0a14ccd');
+            writeLocalDiagnostic('info', 'oauth.authorization.required', () => ({
+                serverName: diagnosticServerName(name),
                 transportType: activeTransport.constructor.name,
-            });
-            const authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(activeTransport);
+            }));
+            const authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(activeTransport, name);
             this.outboundConns.set(name, createLegacyOutboundConnection({
                 name,
                 transport: activeTransport,
@@ -353,13 +422,12 @@ export class ClientManager extends EventEmitter {
         }
         else {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.error(`Failed to create client for ${name}: ${errorMessage}`, {
-                error: errorMessage,
-                clientName: name,
+            logger.error('clientManager.failed.to.create.client.for.a61aad6b', { error: errorMessage });
+            writeLocalDiagnostic('error', 'backend.client.creation.failed', () => ({
+                serverName: diagnosticServerName(name),
                 transportType: transport.constructor.name,
-                connectionStatus: this.outboundConns.get(name)?.status,
-                stack: error instanceof Error ? error.stack : undefined,
-            });
+                error,
+            }));
             this.outboundConns.set(name, createLegacyOutboundConnection({
                 name,
                 transport,
@@ -399,7 +467,13 @@ export class ClientManager extends EventEmitter {
         }
     }
     async createSingleClientInternal(name, transport, abortSignal) {
-        logger.info(`Creating client for ${name}`);
+        logger.info('clientManager.creating.client.for.744dd700');
+        writeLocalDiagnostic('info', 'backend.client.creating', () => ({
+            serverName: diagnosticServerName(name),
+            transportType: transport.constructor.name,
+            connectionTimeoutMs: getConnectionTimeout(transport),
+            requestTimeoutMs: transport.requestTimeout,
+        }));
         const attemptTransport = this.prepareTransportForAttempt(name, transport);
         this.transports[name] = attemptTransport;
         try {
@@ -447,7 +521,11 @@ export class ClientManager extends EventEmitter {
             capabilities: connected.client.getServerCapabilities?.(),
             supervision,
         }));
-        logger.info(`Client created for ${name}`);
+        logger.info('clientManager.client.created.for.44950b76');
+        writeLocalDiagnostic('info', 'backend.client.created', () => ({
+            serverName: diagnosticServerName(name),
+            transportType: connected.transport.constructor.name,
+        }));
         this.extractAndCacheInstructions(name, connected.client);
         this.setupConnectionHandlers(name, connected.client);
         const metadata = connected.transport.stdioSupervision;
@@ -463,21 +541,28 @@ export class ClientManager extends EventEmitter {
         try {
             await superseded.adapter.close();
         }
-        catch (error) {
-            const safeError = sanitizeRuntimeScopeError(error);
-            logger.warn(`Could not close superseded client ${name}: ${safeError.message}`);
+        catch (_error) {
+            logger.warn('clientManager.could.not.close.superseded.client.3029a8f0', { error: _error });
+            writeLocalDiagnostic('warn', 'backend.replacement.cleanup.failed', () => ({
+                serverName: diagnosticServerName(name),
+                error: _error,
+            }));
         }
+        const provider = getLegacyTransport(superseded).oauthProvider;
+        const current = this.outboundConns.get(name);
+        if (current && getLegacyTransport(current).oauthProvider === provider)
+            return;
+        await provider?.shutdown?.();
     }
     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,
+            logger.info('clientManager.oauth.authorization.required.for.c0a14ccd');
+            writeLocalDiagnostic('info', 'oauth.authorization.required', () => ({
+                serverName: diagnosticServerName(name),
                 transportType: activeTransport.constructor.name,
-            });
-            const authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(activeTransport);
+            }));
+            const authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(activeTransport, name);
             this.outboundConns.set(name, createLegacyOutboundConnection({
                 name,
                 transport: activeTransport,
@@ -489,13 +574,12 @@ export class ClientManager extends EventEmitter {
         }
         else {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.error(`Failed to create client for ${name}: ${errorMessage}`, {
-                error: errorMessage,
-                clientName: name,
+            logger.error('clientManager.failed.to.create.client.for.a61aad6b', { error: errorMessage });
+            writeLocalDiagnostic('error', 'backend.client.creation.failed', () => ({
+                serverName: diagnosticServerName(name),
                 transportType: transport.constructor.name,
-                connectionStatus: this.outboundConns.get(name)?.status,
-                stack: error instanceof Error ? error.stack : undefined,
-            });
+                error,
+            }));
             this.outboundConns.set(name, createLegacyOutboundConnection({
                 name,
                 transport,
@@ -509,7 +593,10 @@ export class ClientManager extends EventEmitter {
         this.assertActive();
         this.transports = transports;
         this.outboundConns.clear();
-        logger.info(`Initialized client storage for ${Object.keys(transports).length} transports`);
+        logger.info('clientManager.initialized.client.storage.for.transports.6bd3aa3d');
+        writeLocalDiagnostic('info', 'backend.initialization.started', () => ({
+            totalCount: Object.keys(transports).length,
+        }));
         return this.outboundConns;
     }
     getTransport(name) {
@@ -518,6 +605,15 @@ export class ClientManager extends EventEmitter {
     getTransportNames() {
         return Object.keys(this.transports);
     }
+    async bindOAuthReturn(serverName, state, origin) {
+        const provider = getLegacyTransport(this.getClient(serverName)).oauthProvider;
+        if (!provider)
+            throw new Error('OAuth authorization provider is unavailable');
+        await provider.bindAdminReturn(state, origin);
+    }
+    getOAuthReturn(serverName, state) {
+        return getLegacyTransport(this.getClient(serverName)).oauthProvider?.getAdminReturn(state);
+    }
     async completeOAuthAndReconnect(serverName, authorizationCode) {
         this.assertActive();
         const clientInfo = this.outboundConns.get(serverName);
@@ -554,9 +650,21 @@ export class ClientManager extends EventEmitter {
     createClientInstance() {
         return this.clientFactory.createClientInstance();
     }
-    async initiateOAuth(serverName) {
+    async initiateOAuth(serverName, options) {
         this.assertActive();
         const connection = this.getClient(serverName);
+        const pendingAuthorization = getLegacyTransport(connection).oauthProvider?.getPendingAuthorizationUrl?.();
+        // A challenge may already have created a scope step-up attempt. Preserve its
+        // state, verifier and scope union; completing it must never replay the Tool.
+        if (pendingAuthorization && !options?.restart) {
+            connection.authorizationUrl = pendingAuthorization;
+            connection.oauthStartTime = new Date().toISOString();
+            connection.status = ClientStatus.AwaitingOAuth;
+            return;
+        }
+        // An explicit new authorization abandons prior attempts/refresh work and
+        // releases old DNS approvals while retaining compatible client registration.
+        await getLegacyTransport(connection).oauthProvider?.invalidateCredentials?.('tokens');
         const superseded = { ...connection };
         const transport = this.transportRecreator.recreateHttpTransport(getLegacyTransport(connection), serverName, {
             preserveSessionId: false,
@@ -567,7 +675,7 @@ export class ClientManager extends EventEmitter {
             await client.connect(transport);
         }
         catch (error) {
-            authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(transport);
+            authorizationUrl = this.oauthFlowHandler.extractAuthorizationUrl(transport, serverName);
             if (!authorizationUrl) {
                 await this.disposeConnectedClient({ client, transport });
                 throw error;
@@ -606,7 +714,8 @@ export class ClientManager extends EventEmitter {
         if (!clientInfo) {
             return;
         }
-        logger.info(`Removing client ${name}...`);
+        logger.info('clientManager.removing.client.833781e6');
+        writeLocalDiagnostic('info', 'backend.client.removing', () => ({ serverName: diagnosticServerName(name) }));
         try {
             const supervisor = this.backendSupervisors.get(name);
             if (supervisor) {
@@ -621,25 +730,27 @@ export class ClientManager extends EventEmitter {
                 }
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);
-                    logger.warn(`Error closing transport for ${name}: ${errorMessage}`, {
-                        error: errorMessage,
-                        clientName: name,
+                    logger.warn('clientManager.error.closing.transport.for.76ac70c0', { error: errorMessage });
+                    writeLocalDiagnostic('warn', 'backend.transport.close.failed', () => ({
+                        serverName: diagnosticServerName(name),
                         transportType: transport.constructor.name,
-                    });
+                        error,
+                    }));
                 }
             }
             this.outboundConns.delete(name);
             delete this.transports[name];
             this.instructionAggregator?.removeServer({ source: 'mcpServers', name: clientInfo.name || name }, name);
-            logger.info(`Client ${name} removed successfully`);
+            logger.info('clientManager.client.removed.successfully.0f36fffb');
+            writeLocalDiagnostic('info', 'backend.client.removed', () => ({ serverName: diagnosticServerName(name) }));
         }
         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,
-            });
+            logger.error('clientManager.error.removing.client.df5d67cc', { error: errorMessage });
+            writeLocalDiagnostic('error', 'backend.client.removal.failed', () => ({
+                serverName: diagnosticServerName(name),
+                error,
+            }));
             throw error;
         }
     }
@@ -687,13 +798,17 @@ export class ClientManager extends EventEmitter {
             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}`);
+            catch (_error) {
+                logger.warn('clientManager.error.closing.client.during.shutdown.for.2f1b1528', { error: _error });
+                writeLocalDiagnostic('warn', 'backend.shutdown.cleanup.failed', () => ({
+                    serverName: diagnosticServerName(name),
+                    error: _error,
+                }));
                 await getLegacyTransport(connection)
                     .close()
                     .catch(() => undefined);
             }
+            await getLegacyTransport(connection).oauthProvider?.shutdown?.();
             this.instructionAggregator?.removeServer({ source: 'mcpServers', name: connection.name }, name);
         }));
         this.outboundConns.clear();
@@ -701,7 +816,8 @@ export class ClientManager extends EventEmitter {
         this.connectionSemaphore.clear();
         this.bulkConnectionOperations.clear();
         this.backendAvailabilityHandler = undefined;
-        logger.info('ClientManager shutdown complete');
+        logger.info('clientManager.clientmanager.shutdown.complete.30a0c3d8');
+        writeLocalDiagnostic('info', 'backend.shutdown.completed', () => ({ totalCount: connections.length }));
     }
     getOrCreateBackendSupervisor(name, metadata) {
         this.assertActive();
@@ -728,9 +844,12 @@ export class ClientManager extends EventEmitter {
             try {
                 await current.adapter.close();
             }
-            catch (error) {
-                const safeError = sanitizeRuntimeScopeError(error);
-                debugIf(() => ({ message: `Could not close previous supervised client ${name}: ${safeError}` }));
+            catch (_error) {
+                debugIf(() => ({ message: 'clientManager.could.not.close.previous.supervised.client.b79e7fcc' }));
+                writeLocalDiagnostic('debug', 'backend.supervision.cleanup.failed', () => ({
+                    serverName: diagnosticServerName(name),
+                    error: _error,
+                }));
             }
         }
         if (signal.aborted) {
@@ -755,6 +874,11 @@ export class ClientManager extends EventEmitter {
             transport = metadata.recreate();
             client = this.clientFactory.createClient(transport);
             const timeout = getConnectionTimeout(transport);
+            writeLocalDiagnostic('info', 'backend.supervision.recovery.connecting', () => ({
+                serverName: diagnosticServerName(name),
+                transportType: transport?.constructor.name,
+                connectionTimeoutMs: timeout,
+            }));
             await client.connect(transport, timeout ? { timeout } : undefined);
             const serverVersion = await client.getServerVersion();
             if (serverVersion?.name === MCP_SERVER_NAME) {
@@ -767,11 +891,23 @@ export class ClientManager extends EventEmitter {
             const recoveredTransport = transport;
             return {
                 pid: this.getTransportPid(recoveredTransport),
-                activate: () => this.recordConnectedClient(name, { client: recoveredClient, transport: recoveredTransport }),
+                activate: () => {
+                    this.recordConnectedClient(name, { client: recoveredClient, transport: recoveredTransport });
+                    writeLocalDiagnostic('info', 'backend.supervision.recovery.connected', () => ({
+                        serverName: diagnosticServerName(name),
+                        transportType: recoveredTransport.constructor.name,
+                        serverVersion: serverVersion?.version,
+                        serverImplementation: serverVersion?.name,
+                    }));
+                },
                 dispose,
             };
         }
         catch (error) {
+            writeLocalDiagnostic('error', 'backend.supervision.recovery.failed', () => ({
+                serverName: diagnosticServerName(name),
+                error,
+            }));
             await dispose();
             throw sanitizeRuntimeScopeError(error);
         }
@@ -780,15 +916,26 @@ export class ClientManager extends EventEmitter {
         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,
+            writeLocalDiagnostic('info', 'backend.supervision.state.changed', () => ({
+                serverName: diagnosticServerName(name),
+                supervisionStatus: snapshot.state,
                 attempt: snapshot.attempt,
-                limit: snapshot.limit,
-                nextRetryAt: snapshot.nextRetryAt,
-                lastExit: snapshot.lastExit,
-                currentPid: snapshot.currentPid,
-                error: snapshot.lastError?.message,
+                maxAttempts: snapshot.limit,
+                nextRetryAt: snapshot.nextRetryAt?.toISOString(),
+                exitCode: snapshot.lastExit?.code,
+                exitSignal: snapshot.lastExit?.signal,
+            }));
+            if (snapshot.lastError) {
+                writeLocalDiagnostic('warn', 'backend.supervision.recovery.error', () => ({
+                    serverName: diagnosticServerName(name),
+                    supervisionStatus: snapshot.state,
+                    attempt: snapshot.attempt,
+                    error: snapshot.lastError,
+                }));
+            }
+            logger.info('clientManager.backend.stdio.supervision.state.changed.for.3a724099', {
+                attempt: snapshot.attempt,
+                error: snapshot.lastError,
             });
             if (snapshot.state === 'restarting') {
                 connection.status = ClientStatus.Restarting;
@@ -812,14 +959,20 @@ export class ClientManager extends EventEmitter {
         }
         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}`);
+            void Promise.resolve(this.backendAvailabilityHandler?.(name, snapshot)).catch((_error) => {
+                logger.warn('clientManager.failed.to.publish.backend.availability.for.9f2d28de');
+                writeLocalDiagnostic('warn', 'backend.availability.publish.failed', () => ({
+                    serverName: diagnosticServerName(name),
+                    error: _error,
+                }));
             });
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.warn(`Failed to publish backend availability for ${name}: ${message}`);
+        catch (_error) {
+            logger.warn('clientManager.failed.to.publish.backend.availability.for.9f2d28de', { error: _error });
+            writeLocalDiagnostic('warn', 'backend.availability.publish.failed', () => ({
+                serverName: diagnosticServerName(name),
+                error: _error,
+            }));
         }
     }
     getTransportPid(transport) {
@@ -838,6 +991,7 @@ export class ClientManager extends EventEmitter {
         catch {
             await connected.transport.close().catch(() => undefined);
         }
+        await connected.transport.oauthProvider?.shutdown?.();
     }
 }
 function isUnknownMessageIdError(error) {