@dsh-cc/mcp-client 0.5.0

package/lib/auth.js

@@ -0,0 +1,121 @@
+/**
+ * OAuth support: a `ctx.credentials`-backed `OAuthClientProvider` for the MCP
+ * SDK's streamable-HTTP and SSE transports.
+ *
+ * The SDK implements RFC 9728 → RFC 8414 metadata discovery, PKCE, dynamic
+ * client registration, and token refresh behind its `OAuthClientProvider`
+ * interface (driven by the transport's `authProvider` option). This module
+ * supplies the durable half of that seam: OAuth tokens, registered-client
+ * information, the PKCE code verifier, and discovery state are persisted through
+ * the `ctx.credentials` reference capability — values are stored under
+ * server-derived credential references rather than inline, so configuration
+ * surfaces never see the secret material.
+ *
+ * 401 handling: the transport auto-refreshes an expired access token against a
+ * stored refresh token before a request; a mid-session `401` surfaces as an
+ * `UnauthorizedError`, which the tool bridge retries once after invalidating
+ * and re-running the token flow ({@link retryUnauthorizedOnce}).
+ *
+ * @module
+ */
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+/** Deterministic credential ref for one OAuth artifact, derived per server. */
+function oauthRef(prefix, kind) {
+    const safe = prefix.toUpperCase().replace(/[^A-Za-z0-9_]/g, '_');
+    return credentialRef(`${safe}_${kind}`);
+}
+/**
+ * `ctx.credentials`-backed {@link OAuthClientProvider}. Every artifact is a
+ * JSON value persisted under a derived credential reference; absent refs mean
+ * "no state" (unconfigured), and an empty stored value counts as unset.
+ */
+export class CredentialsOAuthClientProvider {
+    ctx;
+    tokensRef;
+    clientRef;
+    verifierRef;
+    discoveryRef;
+    redirectUrlValue;
+    constructor(ctx, serverName, config) {
+        this.ctx = ctx;
+        const prefix = config.credentialPrefix ?? `MCP_OAUTH_${serverName}`;
+        this.tokensRef = oauthRef(prefix, 'TOKENS');
+        this.clientRef = oauthRef(prefix, 'CLIENT');
+        this.verifierRef = oauthRef(prefix, 'VERIFIER');
+        this.discoveryRef = oauthRef(prefix, 'DISCOVERY');
+        this.redirectUrlValue = config.redirectUrl;
+        void config.clientName; // reserved for client metadata naming
+    }
+    get redirectUrl() {
+        return this.redirectUrlValue;
+    }
+    get clientMetadata() {
+        const redirectUris = this.redirectUrlValue !== undefined ? [this.redirectUrlValue] : [];
+        return {
+            client_name: 'dsh-mcp-client',
+            redirect_uris: redirectUris,
+            grant_types: ['authorization_code', 'refresh_token'],
+            token_endpoint_auth_method: 'none',
+        };
+    }
+    async clientInformation() {
+        const value = await this.read(this.clientRef);
+        return value === undefined ? undefined : JSON.parse(value);
+    }
+    async saveClientInformation(clientInformation) {
+        await this.write(this.clientRef, JSON.stringify(clientInformation));
+    }
+    async tokens() {
+        const value = await this.read(this.tokensRef);
+        return value === undefined ? undefined : JSON.parse(value);
+    }
+    async saveTokens(tokens) {
+        await this.write(this.tokensRef, JSON.stringify(tokens));
+    }
+    redirectToAuthorization(authorizationUrl) {
+        // Headless host: there is no browser to drive. Log the URL so an operator
+        // can complete the flow; the transport raises an UnauthorizedError until
+        // then, which the tool bridge surfaces (retrying once after a refresh).
+        this.ctx.logger.info(`mcp-client oauth: open ${String(authorizationUrl)} to authorize`);
+    }
+    async saveCodeVerifier(codeVerifier) {
+        await this.write(this.verifierRef, codeVerifier);
+    }
+    async codeVerifier() {
+        const value = await this.read(this.verifierRef);
+        return value ?? '';
+    }
+    async saveDiscoveryState(state) {
+        await this.write(this.discoveryRef, JSON.stringify(state));
+    }
+    async discoveryState() {
+        const value = await this.read(this.discoveryRef);
+        return value === undefined ? undefined : JSON.parse(value);
+    }
+    async invalidateCredentials(scope) {
+        const refs = scope === 'all'
+            ? [this.tokensRef, this.clientRef, this.verifierRef, this.discoveryRef]
+            : scope === 'client'
+                ? [this.clientRef]
+                : scope === 'tokens'
+                    ? [this.tokensRef]
+                    : scope === 'verifier'
+                        ? [this.verifierRef]
+                        : [this.discoveryRef];
+        await Promise.all(refs.map(ref => this.ctx.credentials.unset(ref)));
+    }
+    /** Read a credential value, treating an empty value as unset. */
+    async read(ref) {
+        const resolved = await this.ctx.credentials.resolve(ref);
+        return resolved?.value ?? undefined;
+    }
+    /** Persist a value; an empty value is removed rather than stored. */
+    async write(ref, value) {
+        if (value.length === 0) {
+            await this.ctx.credentials.unset(ref);
+            return;
+        }
+        await this.ctx.credentials.set(ref, value);
+    }
+}
+//# sourceMappingURL=auth.js.map

package/lib/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/lib/connection.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Connection supervisor: owns the MCP client/transport generations for one
+ * plugin instance, keeps the harness registries (tools, resources-as-tools,
+ * and prompt-skills) in sync with the live generation, and — when the
+ * connection drops — restarts the configured server with bounded exponential
+ * backoff.
+ *
+ * One outage shares one attempt budget (`maxAttempts` consecutive failed
+ * attempts, delays doubling from `initialDelayMs` up to `maxDelayMs`). A
+ * connection that stays up past the stability window closes the outage, so
+ * the next disconnect starts a fresh budget while a crash-looping server —
+ * even one whose connects briefly succeed — still exhausts the cap instead of
+ * restarting forever. Exhaustion unregisters the server's tools and stops;
+ * disposal (including HMR) is the only way back from that state.
+ *
+ * Capability branching follows the server's declared `ServerCapabilities`:
+ * `tools`, `resources`, and `prompts` each contribute a disposer map that is
+ * kept live across an outage (last-good wins) and removed on give-up or
+ * disposal. Every swap runs on one serialized chain so generations can never
+ * interleave a dispose-previous/register-next swap.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './index.ts';
+/** Automatic reconnect policy for one MCP server connection. */
+export interface ReconnectConfig {
+    /** Reconnect automatically after a lost connection (default true). */
+    enabled?: boolean;
+    /** First reconnect delay in milliseconds; doubles per consecutive failed attempt (default 500). */
+    initialDelayMs?: number;
+    /** Backoff ceiling in milliseconds; also the uptime after which the attempt budget resets (default 30000). */
+    maxDelayMs?: number;
+    /** Consecutive failed attempts per outage before giving up for good (default 10). */
+    maxAttempts?: number;
+}
+/** Defaults shared by the Config schema and {@link resolveReconnectPolicy}. */
+export declare const RECONNECT_DEFAULTS: Required<ReconnectConfig>;
+/** Fully resolved reconnect policy captured at plugin load. */
+export type ResolvedReconnectPolicy = Readonly<Required<ReconnectConfig>>;
+/**
+ * The one explicit resolve step from raw reconnect config to the policy the
+ * supervisor runs. Programmatic construction may bypass Schemastery
+ * normalization, so every default and bound is re-judged here — misconfiguration
+ * fails the plugin instance at load.
+ *
+ * @param config - Raw `reconnect` config; omission uses the defaults.
+ * @param path - Diagnostic prefix naming the config location in thrown messages.
+ * @returns The frozen resolved policy.
+ */
+export declare function resolveReconnectPolicy(config: ReconnectConfig | undefined, path: string): ResolvedReconnectPolicy;
+/** Result from the initial connection attempt, for startup-await semantics. */
+export interface ConnectionOutcome {
+    /** If the initial connection or tool sync failed, the error; otherwise absent. */
+    error?: unknown;
+}
+/** Handle for one plugin instance's supervised connection. */
+export interface ConnectionHandle {
+    /**
+     * Settles when the first connection attempt completes (success or failure).
+     * The supervisor enters its reconnect loop regardless; the caller decides
+     * whether a failed startup is fatal via `failOnStartupError`.
+     */
+    ready: Promise<ConnectionOutcome>;
+    /**
+     * Stop reconnection, close the live client, wait for the in-flight attempt
+     * and queued capability syncs to quiesce, then unregister every tool,
+     * resource bridge, and prompt skill this server still owns.
+     */
+    dispose(): Promise<void>;
+    /**
+     * How many capabilities this server currently publishes to the tool
+     * registries: bridged MCP tools (deferred reservations included — they are
+     * invisible in the model-facing schema but this server owns them) plus the
+     * resource-bridge tools. Prompts are skills and do not count.
+     */
+    toolCount(): number;
+    /**
+     * Eager/deferred split of {@link toolCount}: eager counts listed tools
+     * registered visibly plus the always-eager resource-bridge tools; deferred
+     * counts listed tools hidden behind ToolSearch. `eager + deferred === toolCount()`.
+     */
+    toolBreakdown(): {
+        eager: number;
+        deferred: number;
+    };
+}
+/**
+ * Start the supervised connection for one MCP server and keep it alive per
+ * the reconnect policy.
+ *
+ * @param ctx - Cordis context providing the `tools` registry and logger.
+ * @param config - Resolved plugin config selecting the transport and server identity.
+ * @param policy - Resolved reconnect policy from {@link resolveReconnectPolicy}.
+ * @returns Handle with a `ready` promise for startup-await and a `dispose` for teardown.
+ */
+export declare function startConnection(ctx: Context, config: Config, policy: ResolvedReconnectPolicy): ConnectionHandle;
+//# sourceMappingURL=connection.d.ts.map

package/lib/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAWlD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,mGAAmG;IACnG,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,8GAA8G;IAC9G,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,eAAe,CAKvD,CAAA;AAOF,+DAA+D;AAC/D,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAA;AAEzE;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,uBAAuB,CAyBjH;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACjC;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB;;;;;OAKG;IACH,SAAS,IAAI,MAAM,CAAA;IACnB;;;;OAIG;IACH,aAAa,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CACrD;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAsT/G"}

package/lib/connection.js

@@ -0,0 +1,409 @@
+/**
+ * Connection supervisor: owns the MCP client/transport generations for one
+ * plugin instance, keeps the harness registries (tools, resources-as-tools,
+ * and prompt-skills) in sync with the live generation, and — when the
+ * connection drops — restarts the configured server with bounded exponential
+ * backoff.
+ *
+ * One outage shares one attempt budget (`maxAttempts` consecutive failed
+ * attempts, delays doubling from `initialDelayMs` up to `maxDelayMs`). A
+ * connection that stays up past the stability window closes the outage, so
+ * the next disconnect starts a fresh budget while a crash-looping server —
+ * even one whose connects briefly succeed — still exhausts the cap instead of
+ * restarting forever. Exhaustion unregisters the server's tools and stops;
+ * disposal (including HMR) is the only way back from that state.
+ *
+ * Capability branching follows the server's declared `ServerCapabilities`:
+ * `tools`, `resources`, and `prompts` each contribute a disposer map that is
+ * kept live across an outage (last-good wins) and removed on give-up or
+ * disposal. Every swap runs on one serialized chain so generations can never
+ * interleave a dispose-previous/register-next swap.
+ *
+ * @module
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { PromptListChangedNotificationSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout';
+import { createTransport, buildAuthProvider } from "./transport.js";
+import { formatStdioStderrForWarn, stdioStderrTail } from "./stdio-stderr.js";
+import { DEFAULT_DEFER_TOOL_THRESHOLD, emptyToolGeneration, syncTools } from "./tools.js";
+import { syncResources } from "./resources.js";
+import { syncPrompts } from "./prompts.js";
+/** Defaults shared by the Config schema and {@link resolveReconnectPolicy}. */
+export const RECONNECT_DEFAULTS = Object.freeze({
+    enabled: true,
+    initialDelayMs: 500,
+    maxDelayMs: 30_000,
+    maxAttempts: 10,
+});
+// The SDK's stdio transport owns two two-second termination grace periods.
+// Keep one additional second for the process-close event that proves the old
+// generation is gone; timing out fails closed instead of overlapping children.
+const GENERATION_CLOSE_TIMEOUT_MS = 5_000;
+/**
+ * The one explicit resolve step from raw reconnect config to the policy the
+ * supervisor runs. Programmatic construction may bypass Schemastery
+ * normalization, so every default and bound is re-judged here — misconfiguration
+ * fails the plugin instance at load.
+ *
+ * @param config - Raw `reconnect` config; omission uses the defaults.
+ * @param path - Diagnostic prefix naming the config location in thrown messages.
+ * @returns The frozen resolved policy.
+ */
+export function resolveReconnectPolicy(config, path) {
+    if (config !== undefined) {
+        for (const key of Object.keys(config)) {
+            if (!Object.hasOwn(RECONNECT_DEFAULTS, key))
+                throw new Error(`${path}.${key} is not a reconnect option`);
+        }
+    }
+    const enabled = config?.enabled ?? RECONNECT_DEFAULTS.enabled;
+    const initialDelayMs = config?.initialDelayMs ?? RECONNECT_DEFAULTS.initialDelayMs;
+    const maxDelayMs = config?.maxDelayMs ?? RECONNECT_DEFAULTS.maxDelayMs;
+    const maxAttempts = config?.maxAttempts ?? RECONNECT_DEFAULTS.maxAttempts;
+    /* jscpd:ignore-start — domain-specific delay validation parallels llm retry-policy; not extractable */
+    if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0 || initialDelayMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${path}.initialDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    if (!Number.isFinite(maxDelayMs) || maxDelayMs <= 0 || maxDelayMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${path}.maxDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    if (initialDelayMs > maxDelayMs) {
+        throw new Error(`${path}.initialDelayMs must be less than or equal to maxDelayMs`);
+    }
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new Error(`${path}.maxAttempts must be a positive integer`);
+    }
+    /* jscpd:ignore-end */
+    return Object.freeze({ enabled, initialDelayMs, maxDelayMs, maxAttempts });
+}
+function clear(entry) {
+    const disposers = entry instanceof Map ? entry.values() : entry.disposers.values();
+    for (const dispose of disposers)
+        dispose();
+    return entry instanceof Map ? new Map() : emptyToolGeneration();
+}
+/**
+ * Start the supervised connection for one MCP server and keep it alive per
+ * the reconnect policy.
+ *
+ * @param ctx - Cordis context providing the `tools` registry and logger.
+ * @param config - Resolved plugin config selecting the transport and server identity.
+ * @param policy - Resolved reconnect policy from {@link resolveReconnectPolicy}.
+ * @returns Handle with a `ready` promise for startup-await and a `dispose` for teardown.
+ */
+export function startConnection(ctx, config, policy) {
+    const label = `mcp-client(${config.serverName})`;
+    // OAuth provider shared by the transport and the 401-retry hook.
+    const authProvider = config.transport !== 'stdio' && config.oauth !== undefined
+        && ctx.get('credentials') !== undefined
+        ? buildAuthProvider(ctx, config.serverName, config.oauth)
+        : undefined;
+    const transportCtx = { ctx, ...authProvider !== undefined ? { authProvider } : {} };
+    const opts = {
+        registrationFailure: 'contain',
+        serverName: config.serverName,
+        toolCallTimeoutMs: config.toolCallTimeoutMs,
+        deferToolThreshold: DEFAULT_DEFER_TOOL_THRESHOLD,
+        ...authProvider !== undefined ? { onUnauthorized: () => authProvider.invalidateCredentials('tokens') } : {},
+    };
+    // The initial sync uses 'throw' when failOnStartupError is configured, so
+    // a registration conflict propagates to the startup-await path. Re-syncs
+    // and reconnect syncs always contain conflicts.
+    const startupOpts = config.failOnStartupError
+        ? { ...opts, registrationFailure: 'throw' }
+        : opts;
+    let disposed = false;
+    /** Current generation: the connecting or connected client; undefined during backoff waits and after final failure. */
+    let client;
+    /** Close signal paired with {@link client}; captured by dispose before current ownership is cleared. */
+    let clientClosed;
+    /** Live registrations owned by this server; each map is swapped by its own sync task or clear. */
+    let registrations = { tools: emptyToolGeneration(), resources: new Map(), prompts: new Map() };
+    let reconnectTimer;
+    /** Consecutive failed connection attempts within the current outage. */
+    let failedAttempts = 0;
+    /** When the current generation finished connect + initial sync; undefined while down. */
+    let connectedAt;
+    /** The real error from the first connection attempt, for startup-await diagnostics. */
+    let firstAttemptError;
+    /** Most recent stdio transport; snapshotted at warn time after stdio has flushed. */
+    let lastTransport;
+    /** One-line `; stderr: …` suffix, omitted when the ring is empty. */
+    function stderrWarnSuffix() {
+        if (lastTransport === undefined)
+            return '';
+        const formatted = formatStdioStderrForWarn(stdioStderrTail(lastTransport));
+        return formatted === undefined ? '' : `; stderr: ${formatted}`;
+    }
+    /** A generation may act only while it is the current one on a live plugin. */
+    const isCurrent = (generation) => !disposed && client === generation;
+    /**
+     * Serializes every registration swap — tool syncs, resource registration,
+     * and prompt syncs, initial and notification-driven, across all generations —
+     * so two swaps can never interleave their dispose-previous/register-next
+     * phase (which would double-dispose one generation and leak another).
+     */
+    let syncChain = Promise.resolve();
+    function enqueue(task) {
+        const run = syncChain.then(task);
+        // The chain tail must survive a failed sync; the enqueuing caller owns reporting.
+        syncChain = run.catch(() => { });
+        return run;
+    }
+    /** Swap the tool generation on connect / tools-list-changed / reconnect. */
+    function syncToolGeneration(generation, syncOpts = opts) {
+        return enqueue(async () => {
+            if (!isCurrent(generation))
+                return;
+            const next = await syncTools(generation, ctx, syncOpts, registrations.tools);
+            registrations = { ...registrations, tools: next };
+        });
+    }
+    /** Register the resource bridge once the server declares the capability. */
+    function syncResourceGeneration(generation) {
+        return enqueue(() => {
+            if (!isCurrent(generation))
+                return;
+            const next = syncResources(generation, ctx, config.serverName);
+            const old = registrations.resources;
+            registrations = { ...registrations, resources: next };
+            for (const dispose of old.values())
+                dispose();
+        });
+    }
+    /** Sync prompt-skills once the server declares the capability. */
+    function syncPromptGeneration(generation) {
+        return enqueue(async () => {
+            if (!isCurrent(generation))
+                return;
+            const next = await syncPrompts(generation, ctx, config.serverName);
+            for (const dispose of registrations.prompts.values())
+                dispose();
+            registrations = { ...registrations, prompts: next };
+        });
+    }
+    /** One disconnect decision per generation: the isCurrent guard makes racing close/error signals idempotent. */
+    function generationDown(generation) {
+        if (!isCurrent(generation))
+            return;
+        client = undefined;
+        clientClosed = undefined;
+        scheduleReconnect();
+    }
+    /** Wait for the transport-owned close signal without letting a broken transport wedge teardown forever. */
+    function waitForClose(closed) {
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => { resolve(false); }, GENERATION_CLOSE_TIMEOUT_MS);
+            timeout.unref();
+            void closed.then(() => {
+                clearTimeout(timeout);
+                resolve(true);
+            });
+        });
+    }
+    function scheduleReconnect() {
+        const lostEstablishedConnection = connectedAt !== undefined;
+        if (!policy.enabled) {
+            const message = lostEstablishedConnection
+                ? 'connection lost and reconnect is disabled — registered tools will fail until an HMR reload or Host restart'
+                : 'connection failed and reconnect is disabled — no tools were registered; reload the plugin or restart the Host to connect';
+            ctx.logger.error(`${label}: ${message}${stderrWarnSuffix()}`);
+            return;
+        }
+        // A connection that stayed up past the stability window (= maxDelayMs, the
+        // longest backoff spacing) ended the previous outage: start a fresh budget.
+        if (connectedAt !== undefined && Date.now() - connectedAt >= policy.maxDelayMs)
+            failedAttempts = 0;
+        connectedAt = undefined;
+        failedAttempts += 1;
+        if (failedAttempts > policy.maxAttempts) {
+            // Enqueue the give-up disposal so it cannot race an in-flight sync's
+            // swap (which checks isCurrent inside the queue).
+            void enqueue(() => {
+                registrations = {
+                    tools: clear(registrations.tools),
+                    resources: clear(registrations.resources),
+                    prompts: clear(registrations.prompts),
+                };
+            });
+            ctx.logger.error(`${label}: giving up after ${policy.maxAttempts} consecutive failed reconnect attempts — tools unregistered; reload the plugin or restart the Host to reconnect`);
+            return;
+        }
+        const delayMs = Math.min(policy.maxDelayMs, policy.initialDelayMs * 2 ** (failedAttempts - 1));
+        const action = lostEstablishedConnection ? 'connection lost; reconnecting' : 'connection failed; retrying';
+        ctx.logger.warn(`${label}: ${action} in ${delayMs}ms (attempt ${failedAttempts}/${policy.maxAttempts})${stderrWarnSuffix()}`);
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = undefined;
+            settling = connectGeneration(false);
+        }, delayMs);
+        // An armed reconnect timer must never hold the process open on its own.
+        reconnectTimer.unref();
+    }
+    /**
+     * One connection attempt: fresh transport + client (the MCP SDK binds a
+     * Protocol to one transport for life), connect, then queue the capability
+     * syncs for the declared server capabilities. The startup flag belongs to the
+     * attempt rather than the shared sync queue, so an early notification cannot
+     * consume strict startup semantics. Every failure funnels through
+     * {@link generationDown}; success arms the onclose-driven disconnect path.
+     * Never rejects.
+     *
+     * @param startup - Whether this is the plugin's activation attempt.
+     */
+    async function connectGeneration(startup) {
+        const generation = new Client({ name: 'dsh-mcp-client', version: '0.0.1' }, { capabilities: {} });
+        const closed = Promise.withResolvers();
+        let attemptSettled = false;
+        let closeObserved = false;
+        const hasClosed = () => closeObserved;
+        client = generation;
+        clientClosed = closed.promise;
+        generation.onclose = () => {
+            closeObserved = true;
+            closed.resolve();
+            // A failed connect owns its close barrier in the catch path below. An
+            // established generation can transition down directly from this signal.
+            if (attemptSettled)
+                generationDown(generation);
+        };
+        // Registered before connect so a list change during an initial sync is
+        // queued behind it rather than dropped.
+        generation.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+            if (!isCurrent(generation))
+                return;
+            ctx.logger.info(`${label}: tool list changed, re-syncing`);
+            try {
+                await syncToolGeneration(generation);
+            }
+            catch (error) {
+                // Fetch-phase failure: the previous generation is still registered
+                // and `registrations.tools` still owns it — keep serving the last good list.
+                if (!disposed)
+                    ctx.logger.error(`${label}: tool re-sync failed: ${String(error)}`);
+            }
+        });
+        generation.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
+            if (!isCurrent(generation))
+                return;
+            ctx.logger.info(`${label}: resource list changed, re-syncing resources`);
+            await syncResourceGeneration(generation);
+        });
+        generation.setNotificationHandler(PromptListChangedNotificationSchema, async () => {
+            if (!isCurrent(generation))
+                return;
+            ctx.logger.info(`${label}: prompt list changed, re-syncing prompts`);
+            await syncPromptGeneration(generation);
+        });
+        try {
+            const transport = createTransport(config, transportCtx);
+            lastTransport = transport;
+            await generation.connect(transport);
+            if (hasClosed()) {
+                attemptSettled = true;
+                generationDown(generation);
+                return;
+            }
+            const caps = typeof generation.getServerCapabilities === 'function'
+                ? generation.getServerCapabilities()
+                : undefined;
+            // Tools are bridged unconditionally (the long-standing behavior); only
+            // the optional resource and prompt bridges are capability-gated.
+            await syncToolGeneration(generation, startup ? startupOpts : opts);
+            if (caps?.resources !== undefined)
+                await syncResourceGeneration(generation);
+            if (caps?.prompts !== undefined)
+                await syncPromptGeneration(generation);
+        }
+        catch (error) {
+            if (firstAttemptError === undefined)
+                firstAttemptError = error;
+            // Disposal clears current ownership before it closes the generation, so
+            // only a live supervisor reports an attempt failure.
+            if (isCurrent(generation))
+                ctx.logger.warn(`${label}: connection attempt failed: ${String(error)}${stderrWarnSuffix()}`);
+            try {
+                await generation.close();
+            }
+            catch { /* transport already gone */ }
+            const quiesced = hasClosed() || await waitForClose(closed.promise);
+            attemptSettled = true;
+            if (!isCurrent(generation))
+                return;
+            if (!quiesced) {
+                client = undefined;
+                clientClosed = undefined;
+                ctx.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes; reload the plugin or restart the Host to retry`);
+                return;
+            }
+            generationDown(generation);
+            return;
+        }
+        attemptSettled = true;
+        if (hasClosed()) {
+            generationDown(generation);
+            return;
+        }
+        if (!isCurrent(generation))
+            return;
+        connectedAt = Date.now();
+        if (failedAttempts > 0)
+            ctx.logger.info(`${label}: reconnected and re-synced tools (attempt ${failedAttempts}/${policy.maxAttempts})`);
+    }
+    /** The in-flight (or last settled) connection attempt; dispose awaits it for quiescence. */
+    let settling = connectGeneration(true);
+    // The ready promise settles when the first attempt finishes (regardless of
+    // success). If the first attempt fails and reconnect is enabled, the
+    // supervisor is already scheduling a retry — ready just reports the outcome.
+    const ready = settling.then(() => {
+        // After settling: if client is set the initial connect+sync succeeded.
+        // If not, the supervisor either scheduled a retry (error logged) or gave
+        // up (error logged). Either way the outcome is reported with the real error.
+        if (client !== undefined)
+            return {};
+        /* v8 ignore next -- defensive: firstAttemptError is always set when connect/sync fails */
+        return { error: firstAttemptError ?? new Error(`${label}: initial connection failed`) };
+    });
+    return {
+        ready,
+        toolCount() {
+            return registrations.tools.disposers.size + registrations.resources.size;
+        },
+        toolBreakdown() {
+            return {
+                eager: registrations.tools.eagerCount + registrations.resources.size,
+                deferred: registrations.tools.deferredCount,
+            };
+        },
+        async dispose() {
+            disposed = true;
+            if (reconnectTimer !== undefined) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = undefined;
+            }
+            const current = client;
+            const currentClosed = clientClosed;
+            client = undefined;
+            clientClosed = undefined;
+            if (current !== undefined) {
+                try {
+                    await current.close();
+                }
+                catch { /* transport already gone */ }
+                if (currentClosed !== undefined && !await waitForClose(currentClosed)) {
+                    ctx.logger.error(`${label}: generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms during disposal — server shutdown may be incomplete`);
+                }
+            }
+            // Quiesce, don't just request it: the in-flight attempt enqueues its
+            // syncs before settling, so awaiting both leaves `registrations` final.
+            await settling;
+            await syncChain;
+            registrations = {
+                tools: clear(registrations.tools),
+                resources: clear(registrations.resources),
+                prompts: clear(registrations.prompts),
+            };
+        },
+    };
+}
+//# sourceMappingURL=connection.js.map