@herbertgao/pi-extensions 2026.9.17 → 2026.9.18

package/node_modules/pi-mcp-adapter/server-manager.ts

@@ -1,2088 +0,0 @@
-import { mkdirSync, statSync } from "node:fs";
-import { BlockList, isIP } from "node:net";
-import { isDeepStrictEqual } from "node:util";
-import {
-  Client,
-  SdkError,
-  SdkErrorCode,
-  SdkHttpError,
-  SseError,
-  SSEClientTransport,
-  StreamableHTTPClientTransport,
-  UnauthorizedError,
-  type FetchLike,
-  type GetPromptResult,
-  type ListToolsResult,
-  type ReadResourceResult,
-  type McpSubscription,
-  type SubscriptionFilter,
-  type CacheableRequestOptions,
-  type RequestOptions,
-  type UrlElicitationRequiredError,
-  type VersionNegotiationOptions,
-} from "@modelcontextprotocol/client";
-import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
-import { UnixSocketClientTransport } from "./unix-socket-transport.ts";
-import { probeMcpEndpoint } from "./mcp-probe.ts";
-import {
-  isServerDisabled,
-  type McpTool,
-  type McpResource,
-  type McpPrompt,
-  type ServerDefinition,
-  type ServerStreamResultPatchNotification,
-  type Transport,
-  type McpTraceSettings,
-  type McpListenState,
-  SERVER_STREAM_RESULT_PATCH_METHOD,
-  serverStreamResultPatchNotificationSchema,
-} from "./types.ts";
-import { resolveNpxBinary } from "./npx-resolver.ts";
-import { createJsonSchemaValidator } from "./json-schema-validator.ts";
-import { logger } from "./logger.ts";
-import { RESOURCE_MIME_TYPE } from "./ui-app-bridge-helpers.ts";
-import { isBuiltInAgentPlugin } from "./agent-plugin-provenance.ts";
-import { McpOAuthProvider } from "./mcp-oauth-provider.ts";
-import { extractOAuthConfig, supportsOAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
-import {
-  captureOAuthAuthority,
-  inspectAuthForUrl,
-  invalidateAuthEntryCache,
-  type AuthStorageOptions,
-  type OAuthAuthority,
-} from "./mcp-auth.ts";
-import { getBearerTokenForUrl } from "./mcp-bearer-store.ts";
-import { handleSamplingRequest, registerSamplingHandler, type ServerSamplingConfig } from "./sampling-handler.ts";
-import {
-  handleElicitationRequest,
-  handleUrlElicitation,
-  registerElicitationHandler,
-  type ServerElicitationConfig,
-} from "./elicitation-handler.ts";
-import { attachTaskSession, type RawRequestChannel } from "./mcp-tasks.ts";
-import type { TaskEnabledSession } from "@modelcontextprotocol/ext-tasks/client";
-import {
-  interpolateEnvVars,
-  expandHomePath,
-  resolveBearerToken,
-  resolveCommandSecret,
-  resolveCommandSecretsRecord,
-  resolveConfigPath,
-  resolveServerUrl,
-} from "./utils.ts";
-import { abortable, throwIfAborted } from "./abort.ts";
-import { combineAbortSignals } from "./runtime-owner.ts";
-import {
-  createMcpTraceWriter,
-  isMcpTraceEnabled,
-  McpTraceWriter,
-  type McpTraceObserver,
-  traceTransportKind,
-  wrapTransportWithMcpTrace,
-} from "./mcp-trace.ts";
-import { createOAuthFetch, resolveOAuthHeaders } from "./mcp-auth-fetch.ts";
-import { createRequestHeadersCommandFetch } from "./request-headers-command.ts";
-import { createCaFetch, validateCaFile } from "./http-ca.ts";
-import { BearerCommandResolver } from "./bearer-command-resolver.ts";
-
-const MAX_CAPTURED_STDERR_BYTES = 8 * 1024;
-const MAX_CAPTURED_STDERR_LINES = 3;
-const abortCleanupPromises = new WeakMap<object, Promise<void>>();
-
-type HttpAuthProviderState =
-  | { status: "disabled" }
-  | { status: "implicit-deferred" }
-  | { status: "implicit-stored"; provider: McpOAuthProvider }
-  | { status: "explicit"; provider: McpOAuthProvider }
-  | { status: "implicit-challenged"; provider: McpOAuthProvider };
-
-function isLiteralLocalAddress(url: string): boolean {
-  const hostname = new URL(url).hostname.replace(/^\[|\]$/g, "");
-  const family = isIP(hostname);
-  if (!family) return false;
-  const local = new BlockList();
-  local.addSubnet("10.0.0.0", 8);
-  local.addSubnet("172.16.0.0", 12);
-  local.addSubnet("192.168.0.0", 16);
-  local.addSubnet("169.254.0.0", 16);
-  local.addSubnet("fc00::", 7, "ipv6");
-  local.addSubnet("fe80::", 10, "ipv6");
-  return local.check(hostname, family === 6 ? "ipv6" : "ipv4");
-}
-
-function localNetworkFailureCodes(error: unknown, seen = new Set<object>()): string[] {
-  if (typeof error !== "object" || error === null || seen.has(error)) return [];
-  seen.add(error);
-  const codes: string[] = [];
-  if ("code" in error && typeof error.code === "string"
-    && ["EHOSTUNREACH", "ENETUNREACH", "EACCES"].includes(error.code)) {
-    codes.push(error.code);
-  }
-  if ("cause" in error) codes.push(...localNetworkFailureCodes(error.cause, seen));
-  if (error instanceof AggregateError) {
-    for (const nested of error.errors) codes.push(...localNetworkFailureCodes(nested, seen));
-  }
-  return [...new Set(codes)];
-}
-
-export function isUnauthorizedHttpError(error: unknown): boolean {
-  return error instanceof UnauthorizedError
-    || (error instanceof SdkHttpError && error.status === 401)
-    // Some pinned-SDK transport paths emit this plain Error when bearer
-    // request headers are used without an OAuth authProvider.
-    || (error instanceof Error && /^Error POSTing to endpoint \(HTTP 401\):/.test(error.message));
-}
-
-function shouldFallbackToSse(error: unknown, definition: ServerDefinition): boolean {
-  if (definition.protocolVersion === "2026-07-28") return false;
-  return error instanceof SdkHttpError && [404, 405, 406, 415].includes(error.status);
-}
-
-function resolveVersionNegotiation(definition: ServerDefinition): VersionNegotiationOptions | undefined {
-  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: Buffer | string): Buffer {
-  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: Buffer, chunk: Buffer | string): Buffer {
-  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;
-}
-
-export interface ServerConnection {
-  client: Client;
-  transport: Transport;
-  definition: ServerDefinition;
-  tools: McpTool[];
-  /** Cache hints from the server's aggregated tools/list result. */
-  toolListHints?: Partial<Pick<ListToolsResult, "ttlMs" | "cacheScope">> | undefined;
-  /** Monotonic guard against older refresh responses replacing newer notifications. */
-  toolsRevision?: number;
-  resources: McpResource[];
-  /** True when resources were advertised but resources/list failed. */
-  resourceDiscoveryFailed?: boolean;
-  prompts: McpPrompt[];
-  /** True when prompts were advertised but prompts/list failed. */
-  promptDiscoveryFailed?: boolean;
-  instructions?: string;
-  lastUsedAt: number;
-  inFlight: number;
-  status: "connected" | "closed" | "needs-auth";
-  /** Catalog subscription health, tracked independently from transport health. */
-  listenState: McpListenState;
-  /** ext-tasks requester session, attached when `tasks: true` and the server advertises the extension. */
-  taskSession?: TaskEnabledSession;
-  /** Raw JSON-RPC channel backing the task session on 2026-07-28 connections. */
-  taskChannel?: RawRequestChannel;
-  listenSubscription?: McpSubscription;
-  /** Last requested filter; the server's honored filter may be a subset. */
-  listenFilter?: SubscriptionFilter;
-  /** True when recovery has an active listen but could not confirm every catalog list. */
-  listenCatalogStale?: boolean;
-  listenPromise?: Promise<void>;
-  listenRetryAfter?: number;
-  listenStopped?: boolean;
-  recentResourceUris?: Map<string, number>;
-  resourceReadRefreshUris?: Set<string>;
-  /** True once this needs-auth episode discarded the cached credential. */
-  credentialsInvalidated?: boolean;
-}
-
-
-type UiStreamListener = (serverName: string, notification: ServerStreamResultPatchNotification["params"]) => void;
-type MetadataListChangedListener = (serverName: string, reason: string) => void;
-type ListenStateChangedListener = (serverName: string, state: McpListenState) => void;
-type ResourceUpdatedListener = (serverName: string, uri: string) => void;
-
-export type ToolRefreshResult = "updated" | "unchanged" | "superseded" | "refresh-timeout";
-
-type ToolListCacheHints = Partial<Pick<ListToolsResult, "ttlMs" | "cacheScope">>;
-type ToolListResult = { tools: McpTool[]; hints?: ToolListCacheHints };
-type ResourceListResult = { resources: McpResource[]; failed: boolean };
-
-const KEEP_ALIVE_REFRESH_TIMEOUT_MS = 5_000;
-const LISTEN_RETRY_DELAY_MS = 5_000;
-const RECENT_RESOURCE_TTL_MS = 10 * 60_000;
-const MAX_RESOURCE_SUBSCRIPTIONS = 32;
-
-export function isTransientHttpConnectError(error: unknown): boolean {
-  let current: unknown = error;
-  while (current instanceof Error) {
-    if (current instanceof SdkHttpError && current.status === 503) return true;
-    current = current.cause;
-  }
-  return false;
-}
-
-/** Wrap a FetchLike so each request re-resolves the bearer token via the resolver. */
-function createBearerCommandFetch(
-  resolver: BearerCommandResolver,
-  delegate: FetchLike | undefined,
-): FetchLike {
-  const innerFetch = delegate
-    ? (input: URL | RequestInfo, init?: RequestInit) => delegate(input as URL, init)
-    : (input: URL | RequestInfo, init?: RequestInit) => globalThis.fetch(input, init);
-  return async (input, init) => {
-    const request = new Request(input, init);
-    const token = await resolver.resolve(request.signal);
-    const headers = new Headers(request.headers);
-    headers.set("Authorization", `Bearer ${token}`);
-    // Composed runtime fetches accept Request despite the SDK's narrower type.
-    return innerFetch(new Request(request, { headers }));
-  };
-}
-
-export class McpServerManager {
-  private connections = new Map<string, ServerConnection>();
-  private connectPromises = new Map<string, Promise<ServerConnection>>();
-  private connectOAuthAuthorities = new Map<string, OAuthAuthority>();
-  private reconnectPromises = new Map<string, Promise<ServerConnection>>();
-  private reconnectOAuthAuthorities = new Map<string, OAuthAuthority>();
-  private reconnectAttempts = new Map<string, AbortController>();
-  private uiStreamListeners = new Map<string, UiStreamListener>();
-  private samplingConfig: ServerSamplingConfig | undefined;
-  private metadataListChangedListener: MetadataListChangedListener | undefined;
-  private listenStateChangedListener: ListenStateChangedListener | undefined;
-  private resourceUpdatedListeners = new Map<string, {
-    serverName: string;
-    uri: string;
-    listener: ResourceUpdatedListener;
-  }>();
-  private pendingMetadataPublications = new Map<
-    string,
-    { connection: ServerConnection; reason: string }
-  >();
-  private elicitationConfig: ServerElicitationConfig | undefined;
-  private authStorageOptions: AuthStorageOptions = {};
-  private oauthRuntime: McpOAuthRuntime | undefined;
-  private acceptedUrlElicitations = new Map<string, Set<string>>();
-  private defaultRequestTimeoutMs: number | undefined;
-  private runtimeSignal: AbortSignal | undefined;
-  private closePromises = new Map<string, Promise<void>>();
-  private closeGenerations = new Map<string, number>();
-  private connectAttempts = new Map<string, AbortController>();
-  private traceSettings: McpTraceSettings | undefined;
-  private traceWriter: McpTraceWriter | undefined;
-  private stopped = false;
-
-  /** Default cwd for stdio servers without an explicit config `cwd`. */
-  constructor(private readonly defaultCwd?: string) {}
-
-  setSamplingConfig(config: ServerSamplingConfig | undefined): void {
-    this.samplingConfig = config;
-  }
-
-  setMetadataListChangedListener(listener: MetadataListChangedListener | undefined): void {
-    this.metadataListChangedListener = listener;
-  }
-
-  setListenStateChangedListener(listener: ListenStateChangedListener | undefined): void {
-    this.listenStateChangedListener = listener;
-  }
-
-  publishMetadataChanged(
-    name: string,
-    expectedConnection: ServerConnection,
-    reason: string,
-  ): boolean {
-    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: ServerElicitationConfig | undefined): void {
-    this.elicitationConfig = config;
-  }
-
-  setRuntimeSignal(signal: AbortSignal | undefined): void {
-    this.runtimeSignal = signal;
-  }
-
-  setDefaultRequestTimeoutMs(timeoutMs: number | undefined): void {
-    this.defaultRequestTimeoutMs = normalizeRequestTimeoutMs(timeoutMs);
-  }
-
-  setTraceConfig(settings: McpTraceSettings | undefined): void {
-    this.traceSettings = settings;
-  }
-
-  setAuthStorageOptions(options: AuthStorageOptions): void {
-    this.authStorageOptions = options;
-  }
-
-  setOAuthRuntime(runtime: McpOAuthRuntime): void {
-    this.oauthRuntime = runtime;
-  }
-
-  getRequestOptions(name: string, signal?: AbortSignal): RequestOptions | undefined {
-    const connection = this.connections.get(name);
-    return this.buildRequestOptions(connection?.definition, signal);
-  }
-
-  private getResolvedRequestTimeoutMs(definition?: ServerDefinition): number | undefined {
-    if (definition?.requestTimeoutMs !== undefined) {
-      return normalizeRequestTimeoutMs(definition.requestTimeoutMs);
-    }
-    return this.defaultRequestTimeoutMs;
-  }
-
-  private buildRequestOptions(
-    definition?: ServerDefinition,
-    signal?: AbortSignal,
-  ): RequestOptions | undefined {
-    const timeout = this.getResolvedRequestTimeoutMs(definition);
-    const ownedSignal = combineAbortSignals(this.runtimeSignal, signal);
-
-    if (!ownedSignal && timeout === undefined) {
-      return undefined;
-    }
-
-    return {
-      ...(ownedSignal ? { signal: ownedSignal } : {}),
-      ...(timeout !== undefined ? { timeout } : {}),
-    };
-  }
-
-  private arbitrateConnectionAttempt(
-    name: string,
-    oauthAuthority: OAuthAuthority | undefined,
-    promises: Map<string, Promise<ServerConnection>>,
-    authorities: Map<string, OAuthAuthority>,
-    attempts: Map<string, AbortController>,
-  ): Promise<ServerConnection> | undefined {
-    const existingPromise = promises.get(name);
-    if (!existingPromise) return undefined;
-
-    const existingAuthority = authorities.get(name);
-    let reusable = oauthAuthority === undefined && existingAuthority === undefined;
-    if (oauthAuthority && existingAuthority) {
-      try {
-        existingAuthority();
-        reusable = true;
-      } catch {
-        reusable = false;
-      }
-    }
-    if (reusable) return existingPromise;
-
-    const replacedAttempt = attempts.get(name);
-    replacedAttempt?.abort(new Error(`MCP connection ${name} was replaced`));
-    if (attempts.get(name) === replacedAttempt) attempts.delete(name);
-    if (promises.get(name) === existingPromise) promises.delete(name);
-    if (authorities.get(name) === existingAuthority) authorities.delete(name);
-    return undefined;
-  }
-
-  async connect(name: string, definition: ServerDefinition, signal?: AbortSignal): Promise<ServerConnection> {
-    validateCaFile(definition);
-    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 oauthAuthority = definition.url && supportsOAuth(definition)
-      ? captureOAuthAuthority(name, false)
-      : undefined;
-    const closing = this.closePromises.get(name);
-    if (closing) await abortable(closing, ownedSignal);
-    throwIfAborted(ownedSignal);
-
-    // Dedupe concurrent connection attempts.
-    const existingConnect = this.arbitrateConnectionAttempt(
-      name,
-      oauthAuthority,
-      this.connectPromises,
-      this.connectOAuthAuthorities,
-      this.connectAttempts,
-    );
-    if (existingConnect) return abortable(existingConnect, ownedSignal);
-
-    const existing = this.connections.get(name);
-    if (existing?.status === "connected") {
-      existing.lastUsedAt = Date.now();
-      return existing;
-    }
-
-    // A needs-auth route can be retried through either public path. Share an
-    // authority-compatible reconnect candidate instead of creating a second
-    // owner for the same server.
-    const existingReconnect = this.arbitrateConnectionAttempt(
-      name,
-      oauthAuthority,
-      this.reconnectPromises,
-      this.reconnectOAuthAuthorities,
-      this.reconnectAttempts,
-    );
-    if (existingReconnect) return abortable(existingReconnect, ownedSignal);
-
-    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,
-      oauthAuthority,
-      attemptController,
-    );
-    const promise = definition.url
-      ? connectionAttempt.catch(async error => { throw await this.enrichHttpConnectionError(definition, error); })
-      : connectionAttempt;
-    this.connectPromises.set(name, promise);
-    if (oauthAuthority) this.connectOAuthAuthorities.set(name, oauthAuthority);
-    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);
-      this.watchListenSubscription(name, connection, connection.listenSubscription);
-      if ([...this.resourceUpdatedListeners.values()].some(registration => registration.serverName === name)) {
-        void this.ensureListen(name, connection);
-      }
-      return connection;
-    } finally {
-      if (this.connectPromises.get(name) === promise) this.connectPromises.delete(name);
-      if (this.connectOAuthAuthorities.get(name) === oauthAuthority) {
-        this.connectOAuthAuthorities.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: string,
-    definition: ServerDefinition,
-    staleConnection: ServerConnection,
-    signal?: AbortSignal,
-  ): Promise<ServerConnection> {
-    validateCaFile(definition);
-    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 oauthAuthority = definition.url && supportsOAuth(definition)
-      ? captureOAuthAuthority(name, false)
-      : undefined;
-    // connect() and reconnect() are interchangeable retry entry points for a
-    // published needs-auth route. They must not create competing OAuth owners.
-    const existingConnect = this.arbitrateConnectionAttempt(
-      name,
-      oauthAuthority,
-      this.connectPromises,
-      this.connectOAuthAuthorities,
-      this.connectAttempts,
-    );
-    if (existingConnect) return abortable(existingConnect, ownedSignal);
-    const inFlight = this.arbitrateConnectionAttempt(
-      name,
-      oauthAuthority,
-      this.reconnectPromises,
-      this.reconnectOAuthAuthorities,
-      this.reconnectAttempts,
-    );
-    if (inFlight) return abortable(inFlight, ownedSignal);
-
-    const attemptController = new AbortController();
-    const attemptSignal = combineAbortSignals(ownedSignal, attemptController.signal);
-    const promise = this.doReconnect(
-      name,
-      definition,
-      staleConnection,
-      attemptSignal,
-      oauthAuthority,
-      attemptController,
-    )
-      .catch(error => {
-        if (attemptController.signal.aborted && !this.containsCleanupFailure(error)) {
-          throw new Error(`MCP connection for ${name} was closed while reconnecting`, { cause: error });
-        }
-        throw error;
-      })
-      .finally(() => {
-        if (this.reconnectPromises.get(name) === promise) {
-          this.reconnectPromises.delete(name);
-        }
-        if (this.reconnectAttempts.get(name) === attemptController) {
-          this.reconnectAttempts.delete(name);
-        }
-        if (this.reconnectOAuthAuthorities.get(name) === oauthAuthority) {
-          this.reconnectOAuthAuthorities.delete(name);
-        }
-      });
-    this.reconnectPromises.set(name, promise);
-    if (oauthAuthority) this.reconnectOAuthAuthorities.set(name, oauthAuthority);
-    this.reconnectAttempts.set(name, attemptController);
-    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: string,
-    expectedConnection: ServerConnection,
-    signal?: AbortSignal,
-  ): Promise<ToolRefreshResult> {
-    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";
-    }
-
-    await this.ensureListen(name, expectedConnection);
-
-    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 toolResult: ToolListResult;
-    try {
-      toolResult = 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, toolResult.tools) &&
-      isDeepStrictEqual(expectedConnection.toolListHints, toolResult.hints)
-    ) {
-      this.retryPendingMetadataPublication(name, expectedConnection);
-      return "unchanged";
-    }
-
-    const previousTools = expectedConnection.tools;
-    const previousToolListHints = expectedConnection.toolListHints;
-    expectedConnection.tools = toolResult.tools;
-    expectedConnection.toolListHints = toolResult.hints;
-    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 === toolResult.tools &&
-        expectedConnection.toolListHints === toolResult.hints
-      ) {
-        expectedConnection.tools = previousTools;
-        expectedConnection.toolListHints = previousToolListHints;
-        expectedConnection.toolsRevision = toolsRevision;
-      }
-      throw error;
-    }
-    return "updated";
-  }
-
-  private retryPendingMetadataPublication(name: string, connection: ServerConnection): void {
-    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);
-    }
-  }
-
-  private setListenState(name: string, connection: ServerConnection, state: McpListenState): void {
-    if (connection.listenState === state) return;
-    connection.listenState = state;
-    if (this.connections.get(name) === connection) {
-      try {
-        this.listenStateChangedListener?.(name, state);
-      } catch {
-        // Status consumers must not interrupt listen lifecycle recovery.
-      }
-    }
-  }
-
-  private catalogListenFilter(connection: ServerConnection): SubscriptionFilter {
-    const capabilities = connection.client.getServerCapabilities?.();
-    return {
-      ...(capabilities?.tools?.listChanged ? { toolsListChanged: true } : {}),
-      ...(capabilities?.prompts?.listChanged ? { promptsListChanged: true } : {}),
-      ...(capabilities?.resources?.listChanged ? { resourcesListChanged: true } : {}),
-    };
-  }
-
-  private currentListenFilter(name: string, connection: ServerConnection): SubscriptionFilter {
-    const now = Date.now();
-    const recent = connection.recentResourceUris;
-    if (recent) {
-      for (const [uri, touchedAt] of recent) {
-        if (now - touchedAt > RECENT_RESOURCE_TTL_MS) recent.delete(uri);
-      }
-    }
-    const openResourceUris = [...new Set(
-      [...this.resourceUpdatedListeners.values()]
-        .filter(registration => registration.serverName === name)
-        .map(registration => registration.uri),
-    )].slice(-MAX_RESOURCE_SUBSCRIPTIONS);
-    const openSet = new Set(openResourceUris);
-    const recentSlots = MAX_RESOURCE_SUBSCRIPTIONS - openResourceUris.length;
-    const recentResourceUris = recentSlots > 0
-      ? [...(recent?.keys() ?? [])].filter(uri => !openSet.has(uri)).slice(-recentSlots)
-      : [];
-    const resourceSubscriptions = [...openResourceUris, ...recentResourceUris];
-    return {
-      ...this.catalogListenFilter(connection),
-      ...(resourceSubscriptions.length > 0 ? { resourceSubscriptions } : {}),
-    };
-  }
-
-  private watchListenSubscription(
-    name: string,
-    connection: ServerConnection,
-    subscription: McpSubscription | undefined,
-  ): void {
-    if (!subscription) return;
-    void subscription.closed.then(cause => {
-      if (
-        this.stopped ||
-        this.connections.get(name) !== connection ||
-        connection.status !== "connected" ||
-        connection.listenSubscription !== subscription
-      ) return;
-      if (cause === "remote") {
-        const staleUris = connection.listenFilter?.resourceSubscriptions ?? [];
-        if (staleUris.length > 0) connection.resourceReadRefreshUris = new Set(staleUris);
-        connection.listenCatalogStale = true;
-        connection.listenRetryAfter = Date.now();
-        this.setListenState(name, connection, "dropped");
-      } else if (cause === "graceful" || connection.listenState !== "re-establishing") {
-        connection.listenStopped = true;
-        this.setListenState(name, connection, "not-listening");
-      }
-    });
-  }
-
-  /** Quietly repairs a modern catalog listen at an existing activity boundary. */
-  async ensureListen(name: string, expectedConnection: ServerConnection): Promise<void> {
-    if (
-      this.stopped ||
-      this.connections.get(name) !== expectedConnection ||
-      expectedConnection.status !== "connected" ||
-      expectedConnection.listenStopped ||
-      expectedConnection.client.getProtocolEra?.() !== "modern"
-    ) return;
-
-    const filter = this.currentListenFilter(name, expectedConnection);
-    if (Object.keys(filter).length === 0) {
-      this.setListenState(name, expectedConnection, "not-listening");
-      return;
-    }
-    if (expectedConnection.listenPromise) {
-      await expectedConnection.listenPromise;
-      return this.ensureListen(name, expectedConnection);
-    }
-    if ((expectedConnection.listenRetryAfter ?? 0) > Date.now()) return;
-
-    const sameFilter = isDeepStrictEqual(expectedConnection.listenFilter, filter);
-    if (expectedConnection.listenState === "active" && sameFilter) {
-      if (!expectedConnection.listenCatalogStale) return;
-      const attempt = (async () => {
-        this.setListenState(name, expectedConnection, "re-establishing");
-        const confirmed = await this.reconcileCatalogAfterListen(name, expectedConnection, this.buildRequestOptions(expectedConnection.definition));
-        if (!confirmed) expectedConnection.listenRetryAfter = Date.now() + LISTEN_RETRY_DELAY_MS;
-        this.setListenState(name, expectedConnection, "active");
-      })().finally(() => {
-        if (expectedConnection.listenPromise === attempt) delete expectedConnection.listenPromise;
-      });
-      expectedConnection.listenPromise = attempt;
-      return attempt;
-    }
-
-    const attempt = (async () => {
-      const recoverDroppedListen = expectedConnection.listenState === "dropped";
-      this.setListenState(name, expectedConnection, "re-establishing");
-      const previous = expectedConnection.listenSubscription;
-      if (previous) await previous.close().catch(() => {});
-      if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") return;
-      try {
-        const requestOptions = this.buildRequestOptions(expectedConnection.definition);
-        const subscription = await expectedConnection.client.listen(
-          filter,
-          {
-            ...requestOptions,
-            timeout: Math.min(requestOptions?.timeout ?? KEEP_ALIVE_REFRESH_TIMEOUT_MS, KEEP_ALIVE_REFRESH_TIMEOUT_MS),
-          },
-        );
-        if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") {
-          await subscription.close().catch(() => {});
-          return;
-        }
-        expectedConnection.listenSubscription = subscription;
-        expectedConnection.listenFilter = filter;
-        delete expectedConnection.listenStopped;
-        delete expectedConnection.listenRetryAfter;
-        this.watchListenSubscription(name, expectedConnection, subscription);
-        const confirmed = recoverDroppedListen
-          ? await this.reconcileCatalogAfterListen(name, expectedConnection, requestOptions)
-          : true;
-        if (!confirmed) expectedConnection.listenRetryAfter = Date.now() + LISTEN_RETRY_DELAY_MS;
-        this.setListenState(name, expectedConnection, "active");
-      } catch (error) {
-        if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") return;
-        if (expectedConnection.listenSubscription) await expectedConnection.listenSubscription.close().catch(() => {});
-        expectedConnection.listenRetryAfter = Date.now() + LISTEN_RETRY_DELAY_MS;
-        this.setListenState(name, expectedConnection, "dropped");
-        logger.debug(`MCP: catalog listen repair failed for ${name}: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    })().finally(() => {
-      if (expectedConnection.listenPromise === attempt) delete expectedConnection.listenPromise;
-    });
-    expectedConnection.listenPromise = attempt;
-    return attempt;
-  }
-
-  private async reconcileCatalogAfterListen(
-    name: string,
-    expectedConnection: ServerConnection,
-    requestOptions?: CacheableRequestOptions,
-  ): Promise<boolean> {
-    const timeout = Math.min(requestOptions?.timeout ?? KEEP_ALIVE_REFRESH_TIMEOUT_MS, KEEP_ALIVE_REFRESH_TIMEOUT_MS);
-    const refreshSignal = combineAbortSignals(requestOptions?.signal, AbortSignal.timeout(timeout));
-    const refreshOptions: CacheableRequestOptions = {
-      ...requestOptions,
-      timeout,
-      cacheMode: "refresh",
-      ...(refreshSignal ? { signal: refreshSignal } : {}),
-    };
-    const [toolResult, resources, promptResult] = await Promise.allSettled([
-      this.fetchAllTools(expectedConnection.client, refreshOptions),
-      this.fetchAllResources(expectedConnection.client, refreshOptions, true),
-      this.fetchAllPrompts(expectedConnection.client, refreshOptions),
-    ]);
-    if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") return false;
-
-    const nextTools = toolResult.status === "fulfilled" ? toolResult.value : undefined;
-    const nextResources = resources.status === "fulfilled" ? resources.value : undefined;
-    const nextPrompts = promptResult.status === "fulfilled" && !promptResult.value.failed ? promptResult.value : undefined;
-    const confirmed = nextTools !== undefined && nextResources !== undefined && nextPrompts !== undefined;
-    const changed = (nextTools !== undefined && (
-      !isDeepStrictEqual(expectedConnection.tools, nextTools.tools) ||
-      !isDeepStrictEqual(expectedConnection.toolListHints, nextTools.hints)
-    )) ||
-      (nextResources !== undefined && (
-        !isDeepStrictEqual(expectedConnection.resources, nextResources.resources) ||
-        expectedConnection.resourceDiscoveryFailed !== nextResources.failed
-      )) ||
-      (nextPrompts !== undefined && (
-        !isDeepStrictEqual(expectedConnection.prompts, nextPrompts.prompts) ||
-        expectedConnection.promptDiscoveryFailed !== false
-      ));
-    if (!changed) {
-      this.retryPendingMetadataPublication(name, expectedConnection);
-      if (confirmed) delete expectedConnection.listenCatalogStale;
-      else expectedConnection.listenCatalogStale = true;
-      return confirmed;
-    }
-
-    if (nextTools !== undefined) {
-      expectedConnection.tools = nextTools.tools;
-      expectedConnection.toolListHints = nextTools.hints;
-      expectedConnection.toolsRevision = (expectedConnection.toolsRevision ?? 0) + 1;
-    }
-    if (nextResources !== undefined) {
-      expectedConnection.resources = nextResources.resources;
-      expectedConnection.resourceDiscoveryFailed = nextResources.failed;
-    }
-    if (nextPrompts !== undefined) {
-      expectedConnection.prompts = nextPrompts.prompts;
-      expectedConnection.promptDiscoveryFailed = false;
-    }
-    if (confirmed) delete expectedConnection.listenCatalogStale;
-    else expectedConnection.listenCatalogStale = true;
-    this.metadataListChangedListener?.(name, "listen-recovered");
-    this.pendingMetadataPublications.delete(name);
-    return confirmed;
-  }
-
-  async prepareResourceUse(name: string, uri: string, expectedConnection: ServerConnection): Promise<boolean> {
-    if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") return false;
-    const refreshRead = expectedConnection.listenState === "dropped" ||
-      expectedConnection.listenState === "re-establishing" ||
-      expectedConnection.resourceReadRefreshUris?.has(uri) === true;
-    const recent = expectedConnection.recentResourceUris ?? new Map<string, number>();
-    recent.delete(uri);
-    recent.set(uri, Date.now());
-    while (recent.size > MAX_RESOURCE_SUBSCRIPTIONS) {
-      const oldest = recent.keys().next().value as string | undefined;
-      if (oldest === undefined) break;
-      recent.delete(oldest);
-    }
-    expectedConnection.recentResourceUris = recent;
-    await this.ensureListen(name, expectedConnection);
-    expectedConnection.resourceReadRefreshUris?.delete(uri);
-    return refreshRead;
-  }
-
-  registerResourceUpdatedListener(
-    token: string,
-    serverName: string,
-    uri: string,
-    listener: ResourceUpdatedListener,
-  ): void {
-    this.removeResourceUpdatedListener(token);
-    this.resourceUpdatedListeners.set(token, { serverName, uri, listener });
-    const connection = this.connections.get(serverName);
-    if (!connection || connection.status !== "connected") return;
-    void this.prepareResourceUse(serverName, uri, connection);
-  }
-
-  removeResourceUpdatedListener(token: string): void {
-    this.resourceUpdatedListeners.delete(token);
-  }
-
-  private async doReconnect(
-    name: string,
-    definition: ServerDefinition,
-    staleConnection: ServerConnection,
-    signal?: AbortSignal,
-    oauthAuthority?: OAuthAuthority,
-    attemptOwner?: AbortController,
-  ): Promise<ServerConnection> {
-    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);
-    }
-
-    // Build the replacement privately. The current route remains usable until
-    // the candidate has completed its handshake and metadata discovery. A
-    // failed candidate therefore cannot remove or close the last good route.
-    const generation = this.closeGenerations.get(name) ?? 0;
-    const credentialsInvalidated = staleConnection.status === "needs-auth"
-      && staleConnection.credentialsInvalidated === true;
-    const candidateAttempt = this.createConnection(
-      name,
-      definition,
-      signal,
-      signal,
-      credentialsInvalidated,
-      oauthAuthority,
-      attemptOwner,
-    );
-    const fresh = definition.url
-      ? await candidateAttempt.catch(async error => { throw await this.enrichHttpConnectionError(definition, error); })
-      : await candidateAttempt;
-
-    // An explicit close or a concurrent replacement supersedes this candidate.
-    // Dispose only the candidate we own; never close whichever route is now
-    // registered under the shared server name.
-    if (signal?.aborted
-      || this.reconnectAttempts.get(name) !== attemptOwner
-      || (this.closeGenerations.get(name) ?? 0) !== generation) {
-      await this.disposeConnection(fresh);
-      throwIfAborted(signal);
-      throw new Error(`MCP connection for ${name} was closed while reconnecting`);
-    }
-    const routeAtPublish = this.connections.get(name);
-    if (routeAtPublish !== staleConnection) {
-      await this.disposeConnection(fresh);
-      return routeAtPublish ?? this.connect(name, definition, signal);
-    }
-
-    fresh.inFlight = Math.max(fresh.inFlight, staleConnection.inFlight);
-    this.connections.set(name, fresh);
-    this.watchListenSubscription(name, fresh, fresh.listenSubscription);
-    if ([...this.resourceUpdatedListeners.values()].some(registration => registration.serverName === name)) {
-      void this.ensureListen(name, fresh);
-    }
-
-    // Publish first so calls route to the fresh image while the exact displaced
-    // child is terminated and reaped. Late close callbacks are identity-guarded.
-    staleConnection.status = "closed";
-    try {
-      await this.disposeConnection(staleConnection);
-    } catch (error) {
-      const failures = error instanceof AggregateError ? error.errors : [error];
-      const details = failures
-        .map(failure => failure instanceof Error ? failure.message : String(failure))
-        .join("; ");
-      logger.debug(`MCP: stale connection cleanup failed for ${name}: ${details}`);
-    }
-
-    // Publication is not permission to return a route that close() disposed
-    // while stale cleanup was pending.
-    if ((this.closeGenerations.get(name) ?? 0) !== generation
-      || this.connections.get(name) !== fresh
-      || fresh.status === "closed") {
-      throw new Error(`MCP connection for ${name} was closed while reconnecting`);
-    }
-    return fresh;
-  }
-
-  private async createConnection(
-    name: string,
-    definition: ServerDefinition,
-    signal?: AbortSignal,
-    requestSignal?: AbortSignal,
-    credentialsInvalidated = false,
-    oauthAuthority?: OAuthAuthority,
-    attemptOwner?: AbortController,
-  ): Promise<ServerConnection> {
-    throwIfAborted(signal);
-
-    const tracingEnabled = isMcpTraceEnabled(definition, this.traceSettings);
-    const traceWriter = tracingEnabled
-      ? (this.traceWriter ??= createMcpTraceWriter(this.defaultCwd, this.traceSettings ?? {}))
-      : undefined;
-    const traceObserver: McpTraceObserver | undefined = traceWriter
-      ? { record: event => traceWriter.write(event) }
-      : undefined;
-
-    let client: Client;
-    let transport: Transport;
-    let clientConnected = false;
-    let invalidated = credentialsInvalidated;
-    let transportAlreadyTraced = false;
-    let stderrTail: Buffer<ArrayBufferLike> = 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 = resolveConfigPath(definition.command) ?? definition.command;
-      const literalArgs = isBuiltInAgentPlugin(definition, "args");
-      const literalCwd = isBuiltInAgentPlugin(definition, "cwd");
-      let args = literalArgs
-        ? [...(definition.args ?? [])]
-        : (definition.args ?? []).map((argument) => expandHomePath(interpolateEnvVars(argument)) ?? argument);
-      const cwd = (literalCwd ? expandHomePath(definition.cwd) : resolveConfigPath(definition.cwd)) ?? this.defaultCwd;
-      if (definition.pluginDataDir) mkdirSync(definition.pluginDataDir, { recursive: true });
-      if (cwd !== undefined) {
-        const cwdStats = statSync(cwd, { throwIfNoEntry: false });
-        if (!cwdStats) throw new Error(`MCP server "${name}" configured cwd does not exist: "${cwd}"`);
-        if (!cwdStats.isDirectory()) throw new Error(`MCP server "${name}" configured cwd is not a directory: "${cwd}"`);
-      }
-
-      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);
-
-      const stdioTransport = new StdioClientTransport({
-        command,
-        args,
-        env: resolveEnv(
-          definition.env,
-          name,
-          isBuiltInAgentPlugin(definition, "env") || definition.literalEnv === true,
-          definition.inheritEnv !== false,
-        ),
-        ...(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: Buffer | string) => {
-          stderrTail = appendStderrTail(stderrTail, chunk);
-        });
-      }
-      transport = stdioTransport;
-    } else if (definition.url) {
-      const httpConnection = await this.connectHttpClient(
-        definition,
-        name,
-        requestOptions,
-        signal,
-        traceObserver,
-        invalidated,
-        oauthAuthority,
-        attemptOwner,
-      );
-      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",
-          listenState: "disconnected",
-          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 protocolEra = client.getProtocolEra?.();
-      const autoOpenedSubscription = client.autoOpenedSubscription;
-      const connection: ServerConnection = {
-        client,
-        transport,
-        definition,
-        tools: [],
-        toolsRevision: 0,
-        resources: [],
-        prompts: [],
-        ...(instructions !== undefined ? { instructions } : {}),
-        lastUsedAt: Date.now(),
-        inFlight: 0,
-        status: "connected",
-        listenState: protocolEra === "modern"
-          ? autoOpenedSubscription
-            ? "active"
-            : "not-listening"
-          : "legacy",
-        ...(autoOpenedSubscription ? {
-          listenSubscription: autoOpenedSubscription,
-        } : {}),
-      };
-      if (autoOpenedSubscription) connection.listenFilter = this.catalogListenFilter(connection);
-
-      // 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 (connection.status === "closed") return;
-        connection.status = "closed";
-        if (this.connections.get(name) !== connection) return;
-        this.metadataListChangedListener?.(name, "remote-close");
-      };
-
-      // Discover tools, resources, and prompts. Resource and prompt listing is
-      // optional: only servers advertising the capability are queried.
-      const [toolResult, resources, promptResult] = await Promise.all([
-        this.fetchAllTools(client, requestOptions),
-        this.fetchAllResources(client, requestOptions),
-        this.fetchAllPrompts(client, requestOptions),
-      ]);
-      if (connection.status !== "connected") {
-        throw new Error(`MCP connection for ${name} closed during metadata discovery`);
-      }
-      connection.tools = toolResult.tools;
-      connection.toolListHints = toolResult.hints;
-      connection.resources = resources.resources;
-      connection.resourceDiscoveryFailed = resources.failed;
-      connection.prompts = promptResult.prompts;
-      connection.promptDiscoveryFailed = promptResult.failed;
-
-      if (definition.tasks !== false) {
-        try {
-          const attachment = await attachTaskSession({
-            client,
-            serverName: name,
-            definition,
-            transport,
-            requestTimeoutMs: this.getResolvedRequestTimeoutMs(definition),
-            clientInfo: { name: `pi-mcp-${name}`, version: "1.0.0" },
-            clientCapabilities: this.buildClientCapabilities(),
-            ...(this.elicitationConfig
-              ? {
-                  onElicitation: (request: Parameters<typeof handleElicitationRequest>[1], signal?: AbortSignal) =>
-                    handleElicitationRequest({
-                      ...this.elicitationConfig!,
-                      serverName: name,
-                      onUrlAccepted: elicitationId => this.rememberUrlElicitation(name, elicitationId),
-                    }, request, signal),
-                }
-              : {}),
-            ...(this.samplingConfig
-              ? {
-                  onSampling: (request: Parameters<typeof handleSamplingRequest>[1], signal?: AbortSignal) =>
-                    handleSamplingRequest({
-                      ...this.samplingConfig!,
-                      serverName: name,
-                      // Cancelling the task should also stop the local sampling run.
-                      getSignal: () => combineAbortSignals(this.samplingConfig!.getSignal(), signal),
-                    }, request),
-                }
-              : {}),
-          });
-          if (attachment && connection.status === "connected") {
-            connection.taskSession = attachment.session;
-            connection.taskChannel = attachment.channel;
-          } else if (attachment) {
-            attachment.channel.rejectAll("MCP connection closed");
-            await attachment.session.close().catch(() => {});
-          }
-        } catch (error) {
-          logger.debug(`Task session attach failed for ${name}: ${String(error)}`);
-        }
-      }
-
-      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: unknown = 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",
-          listenState: "disconnected",
-          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;
-    }
-  }
-
-  private async enrichHttpConnectionError(definition: ServerDefinition, error: unknown): Promise<Error> {
-    const originalMessage = error instanceof Error ? error.message : String(error);
-    if (process.platform === "darwin") {
-      const codes = localNetworkFailureCodes(error);
-      if (codes.length > 0 && isLiteralLocalAddress(resolveServerUrl(definition)!)) {
-        return new Error(`${originalMessage} — ${codes.join(", ")} — macOS Local Network Privacy may be blocking access. Check System Settings > Privacy & Security > Local Network for the app hosting Pi; enable access if listed and restart it. Try launching Pi from Terminal.app or SSH. Routing or firewall problems can also cause this error.`, { cause: error });
-      }
-    }
-    if (isTransientHttpConnectError(error)) {
-      return new Error(`${originalMessage} — endpoint is temporarily unavailable (HTTP 503)`, { cause: 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);
-    }
-  }
-
-  private async connectClientWithAbort(
-    client: Client,
-    transport: Transport,
-    requestOptions?: RequestOptions,
-    signal?: AbortSignal,
-  ): Promise<void> {
-    throwIfAborted(signal);
-    let abortCleanup: Promise<void> | undefined;
-    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);
-    }
-  }
-
-  private buildClientCapabilities() {
-    return {
-      extensions: {
-        "io.modelcontextprotocol/ui": {
-          mimeTypes: [RESOURCE_MIME_TYPE],
-        },
-      },
-      ...(this.samplingConfig ? { sampling: {} } : {}),
-      ...(this.elicitationConfig
-        ? {
-            elicitation: {
-              form: {},
-              ...(this.elicitationConfig.allowUrl ? { url: {} } : {}),
-            },
-          }
-        : {}),
-    };
-  }
-
-  private createClient(serverName: string, definition: ServerDefinition): Client {
-    const capabilities = this.buildClientCapabilities();
-    const versionNegotiation = resolveVersionNegotiation(definition);
-    let client: Client;
-    client = new Client(
-      { name: `pi-mcp-${serverName}`, version: "1.0.0" },
-      {
-        jsonSchemaValidator: createJsonSchemaValidator(),
-        ...(versionNegotiation ? { versionNegotiation } : {}),
-        ...(Object.keys(capabilities).length > 0 ? { capabilities } : {}),
-        listChanged: {
-          tools: {
-            onChanged: (error: Error | null, tools: McpTool[] | null) => {
-              this.handleToolsListChanged(serverName, client, error, tools);
-            },
-          },
-          resources: {
-            onChanged: (error: Error | null, resources: McpResource[] | null) => {
-              this.handleResourcesListChanged(serverName, client, error, resources);
-            },
-          },
-          prompts: {
-            onChanged: (error: Error | null, prompts: McpPrompt[] | null) => {
-              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;
-  }
-
-  private handleToolsListChanged(
-    serverName: string,
-    client: Client,
-    error: Error | null,
-    tools: McpTool[] | null,
-  ): void {
-    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);
-  }
-
-  private handlePromptsListChanged(
-    serverName: string,
-    client: Client,
-    error: Error | null,
-    prompts: McpPrompt[] | null,
-  ): void {
-    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);
-  }
-
-  private handleResourcesListChanged(
-    serverName: string,
-    client: Client,
-    error: Error | null,
-    resources: McpResource[] | null,
-  ): void {
-    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;
-    connection.resourceDiscoveryFailed = false;
-    this.metadataListChangedListener?.(serverName, "resources-list-changed");
-    this.pendingMetadataPublications.delete(serverName);
-  }
-
-  async handleUrlElicitationRequired(
-    serverName: string,
-    error: UrlElicitationRequiredError,
-  ): Promise<"accept" | "decline" | "cancel"> {
-    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";
-  }
-
-  private rememberUrlElicitation(serverName: string, elicitationId: string): void {
-    if (this.runtimeSignal?.aborted) return;
-    let accepted = this.acceptedUrlElicitations.get(serverName);
-    if (!accepted) {
-      accepted = new Set();
-      this.acceptedUrlElicitations.set(serverName, accepted);
-    }
-    accepted.add(elicitationId);
-  }
-
-  private async connectHttpClient(
-    definition: ServerDefinition,
-    serverName: string,
-    requestOptions: RequestOptions | undefined,
-    signal?: AbortSignal,
-    traceObserver?: McpTraceObserver,
-    credentialsInvalidated = false,
-    oauthAuthority?: OAuthAuthority,
-    attemptOwner?: AbortController,
-  ): Promise<{ client: Client; transport: Transport; status: "connected" | "needs-auth"; credentialsInvalidated: boolean }> {
-    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 literalHeaders = isBuiltInAgentPlugin(definition, "headers");
-    const hasCommandHeader = !literalHeaders && Object.values(definition.headers ?? {})
-      .some(value => value.startsWith("!") && !value.startsWith("!!"));
-    const oauthEnabled = supportsOAuth(definition);
-    let headers: Record<string, string>;
-    if (literalHeaders) {
-      headers = { ...definition.headers };
-    } else if (oauthEnabled) {
-      headers = Object.fromEntries(resolveOAuthHeaders(definition.headers));
-    } else {
-      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;
-    // Command-backed bearers resolve eagerly, then refresh through a TTL cache.
-    let bearerCommandResolver: BearerCommandResolver | undefined;
-    if (definition.auth === "bearer") {
-      if (commandBearer) {
-        bearerCommandResolver = new BearerCommandResolver(
-          commandBearer,
-          `MCP server "${serverName}" HTTP bearer token`,
-        );
-        // Eager resolve so a broken command surfaces at connect time, not at
-        // the first tool call.
-        await bearerCommandResolver.resolve(signal);
-      } else {
-        const 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`);
-      }
-    }
-
-    // Do not give origin-bound headers to SDK requestInit: it reuses those
-    // defaults for discovered OAuth endpoints, including other origins.
-    const requestInit = !oauthEnabled && Object.keys(headers).length > 0 ? { headers } : undefined;
-    const serviceHeaders = oauthEnabled ? new Headers(headers) : new Headers();
-    let caFetch = createCaFetch(definition);
-    try {
-    const createAuthProvider = (): McpOAuthProvider => {
-      const currentConnectAttempt = this.connectAttempts.get(serverName);
-      const currentReconnectAttempt = this.reconnectAttempts.get(serverName);
-      if ((currentConnectAttempt && currentConnectAttempt !== attemptOwner)
-        || (currentReconnectAttempt && currentReconnectAttempt !== attemptOwner)) {
-        throw new Error(`MCP connection for ${serverName} was replaced while connecting`);
-      }
-      if (!oauthAuthority) throw new Error(`Missing OAuth authority for ${serverName}`);
-      const provider = new McpOAuthProvider(
-        serverName,
-        serverUrl,
-        extractOAuthConfig(definition),
-        { onRedirect: async () => {} },
-        this.authStorageOptions,
-        this.oauthRuntime?.signal,
-        undefined,
-        oauthAuthority,
-      );
-      provider.setAuthFetch(createOAuthFetch(serverUrl, () => serviceHeaders,
-        combineAbortSignals(this.oauthRuntime?.signal, signal), {
-          ...(caFetch ? { delegate: caFetch.fetch } : {}),
-        }));
-      return provider;
-    };
-
-    // Explicit OAuth checks secure storage immediately. Implicit OAuth keeps
-    // anonymous servers provider-free unless URL-bound credentials are already
-    // stored, so an unavailable credential store does not break anonymous use.
-    let implicitStoredAuth: ReturnType<typeof inspectAuthForUrl> | undefined;
-    if (definition.auth === undefined && supportsOAuth(definition)) {
-      try {
-        implicitStoredAuth = inspectAuthForUrl(serverName, serverUrl, this.authStorageOptions);
-      } catch {
-        // Implicit preflight is opportunistic; malformed records must not block
-        // an otherwise anonymous-capable server from connecting.
-      }
-    }
-    const hasImplicitStoredTokens = implicitStoredAuth?.status === "present"
-      && implicitStoredAuth.entry.tokens !== undefined;
-    if (hasImplicitStoredTokens) invalidateAuthEntryCache(serverName);
-    let authState: HttpAuthProviderState = supportsOAuth(definition)
-      ? definition.auth === undefined
-        ? hasImplicitStoredTokens
-          ? { status: "implicit-stored", provider: createAuthProvider() }
-          : { status: "implicit-deferred" }
-        : { status: "explicit", provider: createAuthProvider() }
-      : { status: "disabled" };
-
-    const commandFetch = definition.requestHeadersCommand
-      ? createRequestHeadersCommandFetch(definition.requestHeadersCommand, caFetch?.fetch)
-      : caFetch?.fetch;
-    // requestHeadersCommand stays last in the header chain.
-    const bearerFetch = bearerCommandResolver
-      ? createBearerCommandFetch(bearerCommandResolver, commandFetch)
-      : commandFetch;
-    const requestFetch = oauthEnabled
-      ? createOAuthFetch(serverUrl, () => serviceHeaders, this.oauthRuntime?.signal, {
-        // MCP streams outlive individual auth requests; retain SDK request deadlines.
-        timeout: false,
-        ...(bearerFetch ? { delegate: bearerFetch } : {}),
-      })
-      : bearerFetch;
-    const attempt = async (
-      kind: "streamable-http" | "sse",
-    ): Promise<
-      | { status: "connected"; client: Client; transport: Transport }
-      | { status: "failed"; client: Client; transport: Transport; error: unknown }
-    > => {
-      const authProvider = "provider" in authState ? authState.provider : undefined;
-      let sseFetchFailure: unknown;
-      const transportFetch: FetchLike | undefined = kind === "sse" && process.platform === "darwin" && isLiteralLocalAddress(serverUrl)
-        ? async (input, init) => {
-          try {
-            return await (requestFetch ?? globalThis.fetch)(input, init);
-          } catch (error) {
-            // EventSource discards the fetch cause before the SDK creates SseError.
-            if (localNetworkFailureCodes(error).length > 0) sseFetchFailure = error;
-            throw error;
-          }
-        }
-        : requestFetch;
-      const transportOptions = {
-        ...(requestInit !== undefined ? { requestInit } : {}),
-        ...(transportFetch !== undefined ? { fetch: transportFetch } : {}),
-        ...(authProvider !== undefined ? { authProvider } : {}),
-        ...(authProvider !== undefined
-          && definition.oauth !== false
-          && definition.oauth?.skipIssuerMetadataValidation === true
-          ? { skipIssuerMetadataValidation: true }
-          : {}),
-      };
-      const baseTransport: Transport = 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) {
-        if (error instanceof SseError && sseFetchFailure !== undefined) {
-          error = new AggregateError([error, sseFetchFailure], error.message);
-        }
-        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: "streamable-http" | "sse" = definition.httpTransport ?? "streamable-http";
-    let invalidated = credentialsInvalidated;
-    for (;;) {
-      const result = await attempt(kind);
-      if (result.status === "connected") {
-        const ownedCa = caFetch;
-        if (ownedCa) {
-          const close = result.transport.close.bind(result.transport);
-          const onclose = result.transport.onclose;
-          result.transport.onclose = () => {
-            void ownedCa.close().catch(error => {
-              logger.debug(`MCP: CA dispatcher cleanup failed for ${serverName}: ${String(error)}`);
-            });
-            onclose?.();
-          };
-          result.transport.close = async () => {
-            try { await close(); } finally { await ownedCa.close(); }
-          };
-          caFetch = undefined;
-        }
-        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;
-    }
-    } finally {
-      await caFetch?.close();
-    }
-  }
-
-  private async fetchAllTools(client: Client, requestOptions?: CacheableRequestOptions): Promise<ToolListResult> {
-    const allTools: McpTool[] = [];
-    let cursor: string | undefined;
-    let hints: ToolListCacheHints | undefined;
-    let firstPage = true;
-
-    do {
-      const result = await client.listTools(cursor ? { cursor } : undefined, requestOptions);
-      if (firstPage) {
-        const ttlMs = typeof result.ttlMs === "number" && Number.isSafeInteger(result.ttlMs) && result.ttlMs >= 0
-          ? result.ttlMs
-          : undefined;
-        const cacheScope = result.cacheScope === "public" || result.cacheScope === "private"
-          ? result.cacheScope
-          : undefined;
-        if (ttlMs !== undefined || cacheScope !== undefined) {
-          hints = {
-            ...(ttlMs !== undefined ? { ttlMs } : {}),
-            ...(cacheScope !== undefined ? { cacheScope } : {}),
-          };
-        }
-        firstPage = false;
-      }
-      allTools.push(...(result.tools ?? []));
-      cursor = result.nextCursor;
-    } while (cursor);
-
-    return { tools: allTools, ...(hints !== undefined ? { hints } : {}) };
-  }
-
-  private async fetchAllPrompts(
-    client: Client,
-    requestOptions?: RequestOptions,
-  ): Promise<{ prompts: McpPrompt[]; failed: boolean }> {
-    const capabilities = client.getServerCapabilities?.();
-    if (!capabilities?.prompts) return { prompts: [], failed: false };
-
-    try {
-      const prompts: McpPrompt[] = [];
-      let cursor: string | undefined;
-      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 };
-    }
-  }
-
-  private async fetchAllResources(client: Client, requestOptions?: RequestOptions, strict = false): Promise<ResourceListResult> {
-    const capabilities = client.getServerCapabilities?.();
-    if (!capabilities?.resources) return { resources: [], failed: false };
-
-    try {
-      const allResources: McpResource[] = [];
-      let cursor: string | undefined;
-
-      do {
-        const result = await client.listResources(cursor ? { cursor } : undefined, requestOptions);
-        allResources.push(...(result.resources ?? []));
-        cursor = result.nextCursor;
-      } while (cursor);
-
-      return { resources: allResources, failed: false };
-    } catch (error) {
-      if (requestOptions?.signal?.aborted) {
-        throwIfAborted(requestOptions.signal);
-      }
-      if (isUnauthorizedHttpError(error)) throw error;
-      if (strict) throw error;
-      // The server advertises resources but the listing failed
-      return { resources: [], failed: true };
-    }
-  }
-
-  private attachAdapterNotificationHandlers(serverName: string, client: Client): void {
-    client.setNotificationHandler("notifications/resources/updated", notification => {
-      const uri = notification.params.uri;
-      const connection = this.connections.get(serverName);
-      if (!connection || connection.client !== client || connection.status !== "connected") return;
-      for (const registration of this.resourceUpdatedListeners.values()) {
-        if (registration.serverName === serverName && registration.uri === uri) {
-          try {
-            registration.listener(serverName, uri);
-          } catch {
-            // One UI listener must not block resource invalidation for others.
-          }
-        }
-      }
-    });
-    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: string, listener: UiStreamListener): void {
-    this.uiStreamListeners.set(streamToken, listener);
-  }
-
-  removeUiStreamListener(streamToken: string): void {
-    this.uiStreamListeners.delete(streamToken);
-  }
-
-  async getPrompt(
-    name: string,
-    promptName: string,
-    args?: Record<string, string>,
-    signal?: AbortSignal,
-  ): Promise<GetPromptResult> {
-    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);
-      await this.ensureListen(name, connection);
-      return await connection.client.getPrompt(
-        { name: promptName, ...(args ? { arguments: args } : {}) },
-        this.getRequestOptions(name, signal),
-      );
-    } finally {
-      this.decrementInFlight(name);
-      this.touch(name);
-    }
-  }
-
-  async readResource(name: string, uri: string, signal?: AbortSignal): Promise<ReadResourceResult> {
-    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);
-      const refreshRead = await this.prepareResourceUse(name, uri, connection);
-      const requestOptions = this.getRequestOptions(name, signal);
-      return await connection.client.readResource(
-        { uri },
-        refreshRead ? { ...requestOptions, cacheMode: "refresh" } : requestOptions,
-      );
-    } finally {
-      this.decrementInFlight(name);
-      this.touch(name);
-    }
-  }
-
-  async close(name: string): Promise<void> {
-    this.closeGenerations.set(name, (this.closeGenerations.get(name) ?? 0) + 1);
-    this.connectAttempts.get(name)?.abort(new Error(`MCP connection ${name} was closed`));
-    this.reconnectAttempts.get(name)?.abort(new Error(`MCP connection ${name} was closed`));
-    this.pendingMetadataPublications.delete(name);
-
-    const pendingReconnect = this.reconnectPromises.get(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);
-      for (const pending of [pendingConnect, pendingReconnect]) {
-        if (!pending) continue;
-        try {
-          await pending;
-        } 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);
-    await closing;
-    if (pendingReconnect) {
-      try {
-        await pendingReconnect;
-      } catch (error) {
-        if (this.containsCleanupFailure(error)) throw error;
-      }
-    }
-  }
-
-  private async disposeConnection(connection: ServerConnection): Promise<void> {
-    const results = await Promise.allSettled([
-      // Release ext-tasks state first so its SDK adapter detaches before close.
-      Promise.resolve().then(async () => {
-        connection.taskChannel?.rejectAll("MCP connection closed");
-        await connection.taskSession?.close();
-      }).catch(() => {}),
-      // 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(): Promise<void> {
-    this.stopped = true;
-    const names = new Set([
-      ...this.connections.keys(),
-      ...this.connectPromises.keys(),
-      ...this.reconnectPromises.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`));
-      this.reconnectAttempts.get(name)?.abort(new Error(`MCP connection ${name} was closed`));
-    }
-
-    const pendingConnects = [...this.connectPromises.values(), ...this.reconnectPromises.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.resourceUpdatedListeners.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");
-  }
-
-  private containsCleanupFailure(error: unknown): boolean {
-    const pending: unknown[] = [error];
-    const seen = new Set<unknown>();
-    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: string): boolean {
-    return this.connectPromises.has(name);
-  }
-
-  getConnection(name: string): ServerConnection | undefined {
-    return this.connections.get(name);
-  }
-
-  getAllConnections(): Map<string, ServerConnection> {
-    return new Map(this.connections);
-  }
-
-  touch(name: string): void {
-    const connection = this.connections.get(name);
-    if (connection) {
-      connection.lastUsedAt = Date.now();
-    }
-  }
-
-  incrementInFlight(name: string): void {
-    const connection = this.connections.get(name);
-    if (connection) {
-      connection.inFlight = (connection.inFlight ?? 0) + 1;
-    }
-  }
-
-  decrementInFlight(name: string): void {
-    const connection = this.connections.get(name);
-    if (connection && connection.inFlight) {
-      connection.inFlight--;
-    }
-  }
-
-  isIdle(name: string, timeoutMs: number): boolean {
-    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: Record<string, string> | undefined,
-  serverName: string,
-  literalEnv = false,
-  inheritEnv = true,
-): Record<string, string> {
-  const resolved: Record<string, string> = {};
-  if (inheritEnv) {
-    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: number | undefined): number | undefined {
-  return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0
-    ? timeoutMs
-    : undefined;
-}