@prestyj/cli 5.10.0 → 5.12.0

package/dist/core/mcp/client.js

@@ -1,8 +1,5 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { Client, OAuthError, OAuthErrorCode, ProtocolError, SdkError, SdkErrorCode, SdkHttpError, StreamableHTTPClientTransport, SSEClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
 import { z } from "zod";
 import http from "node:http";
 import os from "node:os";
@@ -10,9 +7,222 @@ import { log } from "../logger.js";
 import { McpOAuthProvider, MCP_OAUTH_CALLBACK_PORT, MCP_OAUTH_CALLBACK_PATH, } from "./oauth-provider.js";
 import { McpOAuthStore } from "./oauth-store.js";
 import { isLocalhost, alternateLoopback, isNetworkError } from "./loopback.js";
+import { toToolResult } from "./content.js";
 import { resolveStdioCommand } from "./resolve-stdio.js";
+import { McpCatalogCache } from "./catalog-cache.js";
+import { isShareableServer, sharedMcpPool, } from "./shared-pool.js";
 export class MCPClientManager {
     servers = [];
+    /**
+     * Per-server connection settlement, so a caller holding a cached-only tool
+     * can wait for the live client instead of failing or hanging forever.
+     */
+    connections = new Map();
+    /**
+     * In-flight session rebuilds, keyed by server name. N tool calls to the same
+     * server all 404 at once when its session expires; without coalescing each
+     * would spawn its own reconnect and they would race to replace each other in
+     * `this.servers`. Sharing one promise means exactly one reconnect per outage.
+     */
+    reconnecting = new Map();
+    /**
+     * Claims on process-wide shared connections, keyed by server name. Held so
+     * `dispose` can hand them back: the pooled child only exits once the LAST
+     * manager holding it releases, so leaking a claim here would pin the process
+     * for the daemon's lifetime — the exact bug sharing is meant to fix.
+     */
+    sharedHandles = new Map();
+    catalogCache;
+    /**
+     * Opt into the 2026-07-28 revision. Off by default: `mode: "auto"` probes with
+     * `server/discover` before falling back to `initialize`, and a legacy stdio
+     * server that ignores pre-`initialize` requests pays the full probe timeout.
+     */
+    modernProtocol;
+    /**
+     * Host callback for server-initiated `elicitation/create`. Absent means we
+     * declare no elicitation capability at all — which is protocol-legal and is
+     * how the CLI runs, since it has nowhere to render the form.
+     */
+    onElicit;
+    /**
+     * Pool backing `shared: true` servers. Defaults to the daemon-wide singleton;
+     * injectable so tests can exercise sharing without touching global state.
+     */
+    pool;
+    /**
+     * Fired when a connected server's transport closes on its own — a crashed or
+     * exited child, not our own `dispose`. The pool uses it to drop a dead
+     * connection so the next session rebuilds instead of inheriting a corpse.
+     */
+    onServerClosed;
+    /** Set while `dispose` runs, so our own teardown is not reported as a death. */
+    disposing = false;
+    constructor(opts = {}) {
+        this.catalogCache = opts.catalogCache ?? new McpCatalogCache();
+        this.modernProtocol = opts.modernProtocol ?? false;
+        this.onElicit = opts.onElicit;
+        this.pool = opts.sharedPool ?? sharedMcpPool;
+        this.onServerClosed = opts.onServerClosed;
+    }
+    /**
+     * Build a `Client` for one server, declaring elicitation support and wiring
+     * the handler when the host can actually prompt the user.
+     *
+     * Form mode only. URL mode would have us open a browser tab in the middle of
+     * a tool call with no user gesture behind it — the SDK rejects URL-mode
+     * requests for us when the `url` capability is undeclared.
+     */
+    createClient(serverName, negotiate) {
+        const handler = this.onElicit;
+        if (!handler)
+            return new Client({ name: "ezcoder", version: "1.0.0" }, negotiate);
+        const client = new Client({ name: "ezcoder", version: "1.0.0" }, { ...negotiate, capabilities: { elicitation: { form: {} } } });
+        client.setRequestHandler("elicitation/create", async (request) => {
+            const params = request.params;
+            if (params.mode === "url") {
+                // Unreachable while `url` stays undeclared, but a server that ignores
+                // capabilities must get a clean decline rather than a thrown handler.
+                return { action: "decline" };
+            }
+            return handler({
+                server: serverName,
+                message: params.message,
+                requestedSchema: params.requestedSchema,
+            });
+        });
+        return client;
+    }
+    /**
+     * Version-negotiation options for a real (non-probe) connect. `probe()` is
+     * spawn-per-invocation and deliberately never negotiates: a legacy stdio
+     * server that ignores the discovery request would stall it for the whole
+     * probe timeout, turning "validate this server" into a 30s hang.
+     *
+     * The probe timeout is transport-aware because the SDK's timeout VERDICT is:
+     *
+     * - **stdio** — silence on a local pipe means a legacy server, and the SDK
+     *   falls back to `initialize`. The probe runs on a disposable sibling
+     *   process, so the fallback is clean. Waiting the full connect timeout to
+     *   reach a conclusion we can draw in seconds is pure dead time, so cap it
+     *   short.
+     * - **HTTP** — silence means an outage, and the SDK REJECTS the connect
+     *   rather than falling back. A short timeout would therefore turn a slow
+     *   cold start into a hard connection failure, so inherit the full connect
+     *   timeout and let the normal timeout handling deal with a real outage.
+     */
+    negotiationOptions(transport) {
+        if (!this.modernProtocol)
+            return {};
+        return {
+            versionNegotiation: {
+                mode: "auto",
+                ...(transport === "stdio" ? { probe: { timeoutMs: STDIO_PROBE_TIMEOUT_MS } } : {}),
+            },
+        };
+    }
+    /**
+     * Claim the pooled connection for a shared server and adopt its tools.
+     *
+     * Shaped like `connectServer` (resolve tools / throw on failure) so the
+     * caller's `allSettled` handling is identical for both kinds. The pool
+     * reports failure in-band, so it is rethrown here with the message the pool
+     * already formatted.
+     */
+    async connectShared(config) {
+        const handle = await this.pool.acquire(config, 
+        // The pooled connection is just another manager with sharing switched
+        // off, so it takes the normal connect path instead of recursing into the
+        // pool. Its elicit handler is the pool's dispatcher, NOT this session's:
+        // the connection is shared, so each request has to be routed to whichever
+        // session actually provoked it.
+        (opts) => {
+            const manager = new MCPClientManager({
+                catalogCache: opts.catalogCache,
+                modernProtocol: opts.modernProtocol,
+                onElicit: opts.onElicit,
+                sharedPool: this.pool,
+                // Let the pool retire this connection if its server exits.
+                onServerClosed: opts.onClosed,
+            });
+            return {
+                connect: async (target) => {
+                    const [result] = await manager.connectAllDetailed([{ ...target, shared: false }]);
+                    return (result ?? {
+                        name: target.name,
+                        ok: false,
+                        toolCount: 0,
+                        tools: [],
+                        error: "connection produced no result",
+                    });
+                },
+                dispose: () => manager.dispose(),
+            };
+        }, {
+            catalogCache: this.catalogCache,
+            modernProtocol: this.modernProtocol,
+            onElicit: this.onElicit,
+        });
+        if (!handle.result.ok) {
+            // Nothing was claimed on a failed connect, but releasing is idempotent
+            // and keeps this path honest if that ever changes.
+            await handle.release();
+            throw new Error(handle.result.error ?? "connection failed");
+        }
+        this.sharedHandles.set(config.name, handle);
+        // Wrap each pooled tool so a call from THIS session is attributable while
+        // it runs. The pool needs that to answer "which window asked?" when the
+        // server elicits mid-call; without it a shared server could only ever
+        // cancel its prompts.
+        return handle.result.tools.map((tool) => ({
+            ...tool,
+            execute: async (args, context) => {
+                const endCall = handle.beginCall();
+                try {
+                    return await tool.execute(args, context);
+                }
+                finally {
+                    endCall();
+                }
+            },
+        }));
+    }
+    /** Get-or-create the settlement record for one server name. */
+    connectionSlot(name) {
+        const existing = this.connections.get(name);
+        if (existing)
+            return existing;
+        let settle;
+        const promise = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const slot = { promise, settle };
+        this.connections.set(name, slot);
+        return slot;
+    }
+    /**
+     * Resolve once a server's connection attempt has settled. Returns `ok:false`
+     * with the failure reason when that server could not connect, and times out
+     * rather than hanging when no attempt is ever made (e.g. a server that was
+     * removed from the config since the catalog cache was written).
+     */
+    async whenConnected(name, timeoutMs = 30_000) {
+        if (this.servers.some((server) => server.name === name))
+            return { ok: true };
+        const slot = this.connectionSlot(name);
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ ok: false, error: `timed out after ${timeoutMs}ms` }), timeoutMs);
+            timer.unref?.();
+        });
+        try {
+            return await Promise.race([slot.promise, timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     async connectAll(configs) {
         const results = await this.connectAllDetailed(configs);
         return results.flatMap((r) => r.tools);
@@ -21,12 +231,25 @@ export class MCPClientManager {
      * Connect every enabled server and return one result per server (success →
      * ok + toolCount; failure → ok:false with a human-readable error string).
      * Keeps successfully connected servers in `this.servers`.
+     *
+     * Shareable servers — stdio, unless opted out with `shared: false` — are not
+     * connected here at all: they are claimed from the process-wide pool, so every
+     * session in the daemon multiplexes over one child process instead of spawning
+     * its own. The split is invisible to callers — results and tools come back in
+     * the same shape, `whenConnected` settles for both kinds, and `dispose`
+     * releases the pooled claims — so sharing applies wherever a manager is used
+     * (sessions, CLI, subagents) without each call site opting in.
      */
     async connectAllDetailed(configs) {
         const enabled = configs.filter((c) => c.enabled !== false);
         if (enabled.length === 0)
             return [];
-        const settled = await Promise.allSettled(enabled.map((c) => this.connectServer(c)));
+        // Claim a settlement slot for every server up front, so a `whenConnected`
+        // caller that arrives before a slow server's turn still waits on the right
+        // promise instead of creating a second one.
+        for (const config of enabled)
+            this.connectionSlot(config.name);
+        const settled = await Promise.allSettled(enabled.map((c) => (isShareableServer(c) ? this.connectShared(c) : this.connectServer(c))));
         const results = settled.map((result, i) => {
             const name = enabled[i].name;
             if (result.status === "fulfilled") {
@@ -37,6 +260,10 @@ export class MCPClientManager {
             log("WARN", "mcp", `Failed to connect to MCP server "${name}"`, { error });
             return { name, ok: false, toolCount: 0, tools: [], error, requiresAuth };
         });
+        // Release anyone waiting on a cached-only tool from these servers.
+        for (const result of results) {
+            this.connectionSlot(result.name).settle(result.ok ? { ok: true } : { ok: false, error: result.error ?? "connection failed" });
+        }
         const connected = results.filter((r) => r.ok).length;
         const toolCount = results.reduce((sum, r) => sum + r.toolCount, 0);
         log("INFO", "mcp", `Connected ${connected} MCP server(s), ${toolCount} tool(s)`);
@@ -49,7 +276,7 @@ export class MCPClientManager {
      */
     async probe(config) {
         try {
-            const tools = await this.connectServer(config);
+            const tools = await this.connectServer(config, { probe: true });
             const server = this.servers.find((s) => s.name === config.name);
             if (server) {
                 this.servers = this.servers.filter((s) => s !== server);
@@ -88,6 +315,9 @@ export class MCPClientManager {
         // Fresh PKCE/state for this attempt so a previous half-finished login can't
         // poison the exchange.
         await store.patch(config.name, { codeVerifier: undefined, state: undefined });
+        // The whole callback query string, not just `code`: v2's finishAuth reads
+        // `iss` from it and validates the issuer (RFC 9207) before redeeming the
+        // code, which is the defense against an authorization-server mix-up.
         let codeResolve;
         let codeReject;
         const codePromise = new Promise((resolve, reject) => {
@@ -129,7 +359,7 @@ export class MCPClientManager {
                 return;
             }
             res.end("<html><body><h1>Login successful!</h1><p>You can close this tab and return to EZ Coder.</p></body></html>");
-            codeResolve?.(code);
+            codeResolve?.(reqUrl.searchParams);
         });
         try {
             await new Promise((resolve, reject) => {
@@ -167,9 +397,9 @@ export class MCPClientManager {
                 if (!isUnauthorized(err))
                     throw err;
             }
-            const code = await codePromise;
+            const callbackParams = await codePromise;
             // Exchange the code for tokens (persisted via provider.saveTokens).
-            await loginTransport.finishAuth(code);
+            await loginTransport.finishAuth(callbackParams);
             await loginClient.close().catch(() => { });
             // Verify the authorized connection on a fresh transport + list tools.
             const verifyTransport = new StreamableHTTPClientTransport(url, {
@@ -192,8 +422,20 @@ export class MCPClientManager {
             await store.patch(config.name, { codeVerifier: undefined, state: undefined });
         }
     }
-    async connectServer(config) {
+    async connectServer(config, opts = {}) {
         const timeout = config.timeout ?? 30_000;
+        // `command` is what actually selects the stdio path further down.
+        const negotiate = opts.probe
+            ? {}
+            : this.negotiationOptions(config.command ? "stdio" : "http");
+        // A server we already know speaks the 2025 handshake skips the discovery
+        // probe entirely. Only the legacy verdict is reusable from an era string:
+        // adopting a 'modern' verdict needs the full DiscoverResult, so those still
+        // probe (a modern server answers immediately, so that costs nothing).
+        const prior = "versionNegotiation" in negotiate && (await this.cachedEra(config)) === "legacy"
+            ? { kind: "legacy" }
+            : undefined;
+        const connectOptions = { timeout, ...(prior ? { prior } : {}) };
         let client;
         let transport;
         if (config.command) {
@@ -226,9 +468,9 @@ export class MCPClientManager {
             transport.stderr?.on("data", (chunk) => {
                 stderrChunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
             });
-            client = new Client({ name: "ezcoder", version: "1.0.0" });
+            client = this.createClient(config.name, negotiate);
             try {
-                await client.connect(transport, { timeout });
+                await client.connect(transport, connectOptions);
             }
             catch (err) {
                 const stderr = stderrChunks.join("").slice(-4000);
@@ -244,7 +486,7 @@ export class MCPClientManager {
             const url = new URL(config.url);
             const isLocal = isLocalhost(url);
             try {
-                const r = await this.connectHttp(url, config, isLocal, timeout);
+                const r = await this.connectHttp(url, config, isLocal, negotiate, connectOptions);
                 client = r.client;
                 transport = r.transport;
             }
@@ -261,13 +503,40 @@ export class MCPClientManager {
                 });
                 const altUrl = new URL(url);
                 altUrl.hostname = alt;
-                const r = await this.connectHttp(altUrl, config, isLocal, timeout);
+                const r = await this.connectHttp(altUrl, config, isLocal, negotiate, connectOptions);
                 client = r.client;
                 transport = r.transport;
             }
         }
-        this.servers.push({ name: config.name, client, transport, lastCallTime: 0 });
+        this.servers.push({ name: config.name, client, transport, lastCallTime: 0, config });
+        // Report an unexpected close. A stdio child that crashes has no recovery
+        // path (`canRecoverSession` excludes stdio deliberately: respawning one
+        // mid-call would be a surprise), so the only safe response is to let the
+        // owner drop this connection and rebuild on the next use. That matters most
+        // for a POOLED connection, where a corpse would otherwise be handed to every
+        // session in the daemon, including ones that connect later.
+        client.onclose = () => {
+            if (this.disposing)
+                return;
+            log("WARN", "mcp", `MCP server "${config.name}" closed unexpectedly`);
+            this.onServerClosed?.(config.name);
+        };
         const { tools } = await client.listTools(undefined, { timeout });
+        // Persist the live tool list so the NEXT cold start can answer tool_search
+        // before this server has finished connecting. Awaited (a small serialized
+        // JSON write) so the entry is on disk before the connect is reported done —
+        // otherwise a session that starts right after would still see a cold cache.
+        // A failed write must never fail the connect.
+        try {
+            await this.catalogCache.save(config, tools.map((tool) => ({
+                name: `mcp__${config.name}__${tool.name}`,
+                description: tool.description ?? "",
+                rawInputSchema: tool.inputSchema,
+            })), this.negotiatedEra(client));
+        }
+        catch {
+            // Cache is an optimization; a connected server is still fully usable.
+        }
         return tools.map((tool) => {
             const toolName = `mcp__${config.name}__${tool.name}`;
             return {
@@ -275,7 +544,7 @@ export class MCPClientManager {
                 description: tool.description ?? "",
                 parameters: z.record(z.string(), z.unknown()),
                 rawInputSchema: tool.inputSchema,
-                execute: async (args) => {
+                execute: async (args, context) => {
                     const server = this.servers.find((s) => s.name === config.name);
                     if (server) {
                         const elapsed = Date.now() - server.lastCallTime;
@@ -285,23 +554,37 @@ export class MCPClientManager {
                         }
                         server.lastCallTime = Date.now();
                     }
-                    try {
-                        const result = await client.callTool({ name: tool.name, arguments: args }, undefined, { timeout: config.timeout ?? 60_000 });
+                    // Resolve the client from `this.servers` on every attempt rather than
+                    // closing over the one from connect time: a session rebuild swaps the
+                    // entry, and a stale capture would keep calling the dead client.
+                    const liveClient = () => this.servers.find((s) => s.name === config.name)?.client ?? client;
+                    // The client the attempt actually ran against, so a failure can be
+                    // attributed to "my client was replaced" vs "the server hung up".
+                    let attemptClient = liveClient();
+                    const callOnce = async () => {
+                        attemptClient = liveClient();
+                        const result = await attemptClient.callTool({ name: tool.name, arguments: args }, { timeout: config.timeout ?? 60_000 });
                         if (!("content" in result) || !Array.isArray(result.content)) {
                             return "(empty response)";
                         }
-                        const texts = [];
-                        for (const item of result.content) {
-                            if (item != null &&
-                                typeof item === "object" &&
-                                "text" in item &&
-                                typeof item.text === "string") {
-                                texts.push(item.text);
-                            }
-                        }
-                        return texts.join("\n") || "(empty response)";
+                        return toToolResult(result.content, toolName);
+                    };
+                    try {
+                        return await callOnce();
                     }
                     catch (err) {
+                        // An expired HTTP session is recoverable exactly once: rebuild the
+                        // connection and replay the call. A second failure is a real error.
+                        if (this.canRecoverSession(config, err, attemptClient, context?.signal)) {
+                            try {
+                                await this.reconnectServer(config);
+                                if (!context?.signal?.aborted)
+                                    return await callOnce();
+                            }
+                            catch (retryErr) {
+                                return `MCP tool error: ${formatConnectError(retryErr)}`;
+                            }
+                        }
                         const msg = err instanceof Error ? err.message : String(err);
                         if (msg.includes("Too Many R") || msg.includes("429")) {
                             return "Rate limited — too many requests. Wait a moment before searching again.";
@@ -312,6 +595,66 @@ export class MCPClientManager {
             };
         });
     }
+    /**
+     * Is this failure a recoverable expired HTTP session?
+     *
+     * Stdio servers are excluded: they have no HTTP session to expire, so a 404
+     * from one means something else entirely and respawning the child process
+     * mid-call would be a surprise. An already-aborted call is excluded too —
+     * reconnecting to replay work the user cancelled resurrects it.
+     */
+    canRecoverSession(config, err, attemptClient, signal) {
+        if (config.command)
+            return false;
+        if (signal?.aborted)
+            return false;
+        if (isSessionExpired(err))
+            return true;
+        // A sibling call that hit the same expired session may already have torn
+        // the transport down underneath us, which surfaces as a generic "connection
+        // closed" rather than the 404. Recover only when the client we called has
+        // genuinely been retired — otherwise this is a real disconnect and a retry
+        // would just fail again.
+        const current = this.servers.find((s) => s.name === config.name)?.client;
+        return current !== attemptClient && this.isConnectionClosed(err);
+    }
+    /** A local "the transport went away mid-request" failure, as the SDK reports it. */
+    isConnectionClosed(reason) {
+        return SdkError.isInstance(reason) && reason.code === SdkErrorCode.ConnectionClosed;
+    }
+    /**
+     * Rebuild one server's connection from its stored config, replacing the dead
+     * entry in `this.servers`. Concurrent callers share a single rebuild.
+     *
+     * Rejects if the reconnect itself fails, so the caller reports a real error
+     * rather than retrying against a client that was never replaced.
+     */
+    async reconnectServer(config) {
+        const inFlight = this.reconnecting.get(config.name);
+        if (inFlight)
+            return inFlight;
+        const attempt = (async () => {
+            log("INFO", "mcp", `MCP session expired for "${config.name}", reconnecting`);
+            const dead = this.servers.find((s) => s.name === config.name);
+            if (dead) {
+                this.servers = this.servers.filter((s) => s !== dead);
+                try {
+                    await dead.client.close();
+                }
+                catch {
+                    // The session is already gone server-side; a failed close is expected.
+                }
+            }
+            await this.connectServer(config);
+        })();
+        this.reconnecting.set(config.name, attempt);
+        try {
+            await attempt;
+        }
+        finally {
+            this.reconnecting.delete(config.name);
+        }
+    }
     /**
      * Connect a single HTTP (Streamable HTTP or SSE) server and return the live
      * client + transport. Transport selection:
@@ -322,7 +665,7 @@ export class MCPClientManager {
      * needs OAuth and attaching it there is dead weight that can misdiagnose a
      * protocol mismatch as a login requirement.
      */
-    async connectHttp(url, config, isLocal, timeout) {
+    async connectHttp(url, config, isLocal, negotiate, connectOptions) {
         const reqInit = config.headers ? { headers: config.headers } : undefined;
         const authProvider = isLocal ? undefined : new McpOAuthProvider({ serverName: config.name });
         const sseTransport = () => new SSEClientTransport(url, {
@@ -332,8 +675,8 @@ export class MCPClientManager {
         });
         if (config.transport === "sse") {
             const transport = sseTransport();
-            const client = new Client({ name: "ezcoder", version: "1.0.0" });
-            await client.connect(transport, { timeout });
+            const client = this.createClient(config.name, negotiate);
+            await client.connect(transport, connectOptions);
             return { client, transport };
         }
         try {
@@ -341,8 +684,8 @@ export class MCPClientManager {
                 requestInit: reqInit,
                 authProvider,
             });
-            const client = new Client({ name: "ezcoder", version: "1.0.0" });
-            await client.connect(transport, { timeout });
+            const client = this.createClient(config.name, negotiate);
+            await client.connect(transport, connectOptions);
             return { client, transport };
         }
         catch (streamableErr) {
@@ -356,12 +699,40 @@ export class MCPClientManager {
                 error: String(streamableErr),
             });
             const transport = sseTransport();
-            const client = new Client({ name: "ezcoder", version: "1.0.0" });
-            await client.connect(transport, { timeout });
+            const client = this.createClient(config.name, negotiate);
+            await client.connect(transport, connectOptions);
             return { client, transport };
         }
     }
+    /**
+     * Protocol era actually negotiated with a server, as the SDK reports it.
+     * Undefined before a connect completes; with negotiation off the SDK always
+     * settles on `legacy` (the 2025 `initialize` handshake).
+     */
+    negotiatedEra(client) {
+        return client.getProtocolEra() ?? "legacy";
+    }
+    /** Previously negotiated era for this exact server config, if still cached. */
+    async cachedEra(config) {
+        try {
+            return await this.catalogCache.protocolEraFor(config);
+        }
+        catch {
+            return undefined;
+        }
+    }
     async dispose() {
+        // Our own teardown closes transports too; flag it so those closes are not
+        // reported as unexpected deaths.
+        this.disposing = true;
+        this.connections.clear();
+        this.reconnecting.clear();
+        // Hand back pooled claims first. These are references, not connections —
+        // the shared child survives if another session still holds it, and exits
+        // when this was the last claim.
+        const handles = [...this.sharedHandles.values()];
+        this.sharedHandles.clear();
+        await Promise.all(handles.map((handle) => handle.release()));
         for (const server of this.servers) {
             try {
                 await server.client.close();
@@ -374,25 +745,81 @@ export class MCPClientManager {
     }
 }
 /**
- * Turn a thrown connection error into a short human-readable string. Surfaces
- * the common rate-limit case explicitly; otherwise the underlying message.
+ * Turn a thrown connection error into a short human-readable string.
+ *
+ * v2 splits the old `McpError` into `ProtocolError` (a JSON-RPC error that
+ * crossed the wire) and `SdkError` (a purely local failure: timeout, closed
+ * connection, HTTP status). Matching the typed classes gives far better wording
+ * than sniffing message text, which survives only as the fallback for errors
+ * thrown before the SDK's machinery engages (raw fetch failures).
  */
 function formatConnectError(reason) {
+    if (SdkHttpError.isInstance(reason)) {
+        if (reason.status === 429)
+            return "Rate limited (429) — try again in a moment.";
+        const statusText = reason.statusText ? ` ${reason.statusText}` : "";
+        return `Server responded with HTTP ${reason.status}${statusText}.`;
+    }
+    if (SdkError.isInstance(reason)) {
+        if (reason.code === SdkErrorCode.RequestTimeout) {
+            return "Timed out waiting for the server to respond.";
+        }
+        if (reason.code === SdkErrorCode.ConnectionClosed) {
+            return "Connection closed before the server finished starting up.";
+        }
+        return reason.message;
+    }
+    if (OAuthError.isInstance(reason))
+        return `OAuth error (${reason.code}): ${reason.message}`;
+    if (ProtocolError.isInstance(reason))
+        return reason.message;
     const msg = reason instanceof Error ? reason.message : String(reason);
     if (msg.includes("Too Many R") || msg.includes("429")) {
         return "Rate limited (429) — try again in a moment.";
     }
     return msg;
 }
+/**
+ * How long to wait for a stdio server to answer `server/discover` before
+ * concluding it is a 2025-era server. A local child that has not replied in
+ * this window is not going to; the SDK then falls back to `initialize`.
+ */
+const STDIO_PROBE_TIMEOUT_MS = 2_500;
+/** OAuth failures that mean the saved credentials can no longer be used. */
+const REAUTH_OAUTH_CODES = [
+    OAuthErrorCode.InvalidToken,
+    OAuthErrorCode.InvalidGrant,
+    OAuthErrorCode.InvalidClient,
+    OAuthErrorCode.AccessDenied,
+];
+/**
+ * Whether an error means the remote server has dropped our HTTP session.
+ *
+ * `StreamableHTTPClientTransport.send` handles 401/403 (it re-runs auth) but
+ * returns a bare `SdkHttpError{status:404}` when the `Mcp-Session-Id` we are
+ * carrying is no longer known to the server — which is exactly what happens
+ * after a server restart or an idle-session sweep on a long desktop session.
+ * The SDK has no recovery for it, so we rebuild the connection ourselves.
+ */
+function isSessionExpired(reason) {
+    return SdkHttpError.isInstance(reason) && reason.status === 404;
+}
 /**
  * Whether a connect error means the server needs OAuth login. The SDK throws
- * its typed `UnauthorizedError` when auth is required, but a raw 401 from the
- * initial request (before the auth machinery engages) can also surface as a
- * plain error message — so we check both.
+ * its typed `UnauthorizedError` when auth is required, a `SdkHttpError` for a
+ * bare 401, and an `OAuthError` when the token endpoint rejects the saved
+ * credentials. A raw 401 from before the auth machinery engages can still
+ * surface as a plain message — so the string check remains as a fallback.
  */
 function isUnauthorized(reason) {
-    if (reason instanceof UnauthorizedError)
+    if (UnauthorizedError.isInstance(reason))
         return true;
+    if (SdkHttpError.isInstance(reason))
+        return reason.status === 401;
+    // Token/grant/client codes mean "log in again"; the rest (server_error,
+    // temporarily_unavailable, …) are transient, not an auth gap.
+    if (OAuthError.isInstance(reason))
+        return REAUTH_OAUTH_CODES.includes(reason.code);
     const msg = reason instanceof Error ? reason.message : String(reason);
     return (msg.includes("Unauthorized") ||
         msg.includes("401") ||
@@ -410,12 +837,18 @@ function escapeHtml(value) {
  * Create a custom fetch wrapper that injects extra headers into every request.
  * Used for SSEClientTransport's eventSourceInit to pass auth headers
  * on the initial SSE GET connection (which doesn't use requestInit).
+ *
+ * The incoming headers may be a Web Standard `Headers` instance (v2 uses it
+ * throughout) or a plain object. Spreading a `Headers` yields `{}`, silently
+ * dropping the SDK's own auth header — so normalize through `Headers`, which
+ * accepts both shapes, and merge with `set()` rather than bracket access.
  */
 function createHeaderFetch(extraHeaders) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return (url, init) => {
-        const existing = (init?.headers ?? {});
-        return fetch(url, { ...init, headers: { ...existing, ...extraHeaders } });
+        const headers = new Headers(init?.headers);
+        for (const [name, value] of Object.entries(extraHeaders))
+            headers.set(name, value);
+        return fetch(url, { ...init, headers });
     };
 }
 //# sourceMappingURL=client.js.map