@pharaoh-so/mcp 0.3.21 → 0.3.23

package/dist/gateway.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure-logic device-flow state machine for the auth-required proxy mode.
+ *
+ * When Claude Code spawns the proxy without valid credentials, we can't just
+ * exit — that would force the user to restart their agent every time. Instead,
+ * the proxy stays alive, advertises a single MCP tool, and turns every tool
+ * call into a device-flow lifecycle step: request a code, surface the URL,
+ * poll once per tool call (rate-limited), and swap to the SSE backend once
+ * the user authorizes.
+ *
+ * This module owns the state. It has no MCP imports and no knowledge of the
+ * stdio transport — those live in backend.ts and proxy-server.ts. The only
+ * side effects are (a) POSTing to the Pharaoh /device and /device/token
+ * endpoints via auth.ts, (b) opening a browser once per cycle, and (c)
+ * writing credentials to disk on authorization.
+ */
+import { type Credentials } from "./credentials.js";
+/**
+ * Structured MCP tool response returned when the proxy is waiting for auth.
+ *
+ * Shape rationale: MCP clients that inspect `_meta` can render the auth URL
+ * and user code directly in their UI (Claude Code does this). Clients that
+ * only read `content[0].text` see the same information in human-readable form.
+ * `isError: true` ensures Claude Code surfaces this to the user as an actionable
+ * error rather than silently eating the response.
+ */
+export interface ToolAuthResponse {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+    _meta: {
+        auth_url: string;
+        user_code: string;
+        expires_in_seconds: number;
+    };
+}
+/** Public surface consumed by AuthRequiredBackend. */
+export interface DeviceFlowGateway {
+    /**
+     * Called on every pre-auth tool invocation. Returns null when credentials
+     * just became valid (caller should swap to SSE backend); otherwise returns
+     * the auth-required tool response. Never throws — all error paths collapse
+     * into a ToolAuthResponse the agent can surface.
+     */
+    handleToolCall(): Promise<ToolAuthResponse | null>;
+    /** True when credentials on disk are present and not access-expired. */
+    hasValidCredentials(): boolean;
+    /** The last credentials loaded from disk; null if never loaded successfully. */
+    getCredentials(): Credentials | null;
+}
+/**
+ * Create a fresh state-machine instance. Each proxy spawn gets one gateway;
+ * its lifecycle is the lifecycle of the stdio process.
+ */
+export declare function createGateway(opts: {
+    server: string;
+    credentialsPath?: string;
+    /** Test hook for deterministic expiry/interval math. Do not use in prod. */
+    now?: () => number;
+    /**
+     * Override the browser-open side effect. Tests MUST pass a noop — the real
+     * impl calls `open`/`xdg-open` on the OS, which hits a user's actual browser
+     * even when the URL points at an ephemeral test server that's already closed.
+     * Default: the platform-native open from auth.ts.
+     */
+    openBrowser?: (url: string) => void;
+}): DeviceFlowGateway;

package/dist/gateway.js

@@ -0,0 +1,162 @@
+/**
+ * Pure-logic device-flow state machine for the auth-required proxy mode.
+ *
+ * When Claude Code spawns the proxy without valid credentials, we can't just
+ * exit — that would force the user to restart their agent every time. Instead,
+ * the proxy stays alive, advertises a single MCP tool, and turns every tool
+ * call into a device-flow lifecycle step: request a code, surface the URL,
+ * poll once per tool call (rate-limited), and swap to the SSE backend once
+ * the user authorizes.
+ *
+ * This module owns the state. It has no MCP imports and no knowledge of the
+ * stdio transport — those live in backend.ts and proxy-server.ts. The only
+ * side effects are (a) POSTing to the Pharaoh /device and /device/token
+ * endpoints via auth.ts, (b) opening a browser once per cycle, and (c)
+ * writing credentials to disk on authorization.
+ */
+import { openBrowser, pollOnce, requestDeviceCode, } from "./auth.js";
+import { readCredentials, writeCredentials } from "./credentials.js";
+import { resolveSseUrl, tokenToCredentials } from "./helpers.js";
+function isAccessExpired(creds) {
+    const expiresAt = new Date(creds.expires_at).getTime();
+    if (Number.isNaN(expiresAt))
+        return true;
+    return Date.now() >= expiresAt;
+}
+function buildAuthResponse(device) {
+    const prefix = device.errorMessage ? `${device.errorMessage}\n\n` : "";
+    const text = `${prefix}Pharaoh authentication required.\n\n` +
+        `  1. Visit ${device.verification_uri_complete}\n` +
+        `  2. Enter code: ${device.user_code}\n` +
+        `  3. Re-run this tool after authorizing.`;
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+        _meta: {
+            auth_url: device.verification_uri_complete,
+            user_code: device.user_code,
+            expires_in_seconds: device.expires_in,
+        },
+    };
+}
+/**
+ * Create a fresh state-machine instance. Each proxy spawn gets one gateway;
+ * its lifecycle is the lifecycle of the stdio process.
+ */
+export function createGateway(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const openBrowserImpl = opts.openBrowser ?? openBrowser;
+    let pending = null;
+    let lastCreds = null;
+    /** Start a new device-flow cycle: POST /device, open browser, cache state. */
+    async function startNewCycle() {
+        const device = await requestDeviceCode(opts.server);
+        // Browser-open is opportunistic. Headless environments (SSH, containers,
+        // CI runners with no DE) are first-class — the URL surfaces in the tool
+        // response regardless, so a throwing opener must not mask it.
+        try {
+            openBrowserImpl(device.verification_uri_complete);
+        }
+        catch {
+            // ALLOWED-CATCH: browser-open failures are non-fatal by design
+        }
+        const response = buildAuthResponse(device);
+        // last_poll_at is seeded with now() — the cycle start counts as a
+        // server round-trip, so the next tool call shouldn't immediately
+        // re-hit /device/token within the interval window. This is what
+        // makes scenario "rapid-fire calls right after auth URL appears"
+        // not flood the server's 20/min rate limiter.
+        pending = {
+            device_code: device.device_code,
+            user_code: device.user_code,
+            verification_uri: device.verification_uri,
+            verification_uri_complete: device.verification_uri_complete,
+            expires_at: now() + device.expires_in * 1000,
+            interval_ms: device.interval * 1000,
+            last_poll_at: now(),
+            response,
+        };
+        return response;
+    }
+    /**
+     * Persist a new session's credentials. Separated so handleToolCall stays
+     * simple — see how success is collapsed into `pending = null; return null`.
+     */
+    function persistAuthorizedToken(token) {
+        const sseUrl = resolveSseUrl(token.sse_url, opts.server);
+        const creds = tokenToCredentials(token, sseUrl);
+        writeCredentials(creds, opts.credentialsPath);
+        lastCreds = creds;
+        pending = null;
+    }
+    /** Decide whether the cached response is still valid without polling. */
+    function shouldSkipPoll(state) {
+        if (state.last_poll_at === null)
+            return false;
+        return now() - state.last_poll_at < state.interval_ms;
+    }
+    /**
+     * Handle the result of a single /device/token poll. Mutates state as a
+     * side effect and returns the outbound response (or null on authorization).
+     * Network errors fall through silently (no state change, retry on next call).
+     */
+    function applyPollResult(state, result) {
+        if (result.status === "authorized") {
+            persistAuthorizedToken(result.token);
+            return null;
+        }
+        if (result.status === "denied") {
+            // Clear state so the next call starts fresh. Return the error text
+            // inline so the agent sees why; the user will naturally retry.
+            pending = null;
+            return {
+                content: [{ type: "text", text: `Pharaoh auth denied: ${result.error}` }],
+                isError: true,
+                _meta: {
+                    auth_url: state.verification_uri,
+                    user_code: state.user_code,
+                    expires_in_seconds: 0,
+                },
+            };
+        }
+        // pending, expired, network_error: keep cached response. Expired is
+        // handled by the expiry check in handleToolCall; we don't force it here
+        // because applyPollResult runs AFTER the expiry check, which means an
+        // expired server code here is a rare race (<1s window) and getting the
+        // same response back is fine.
+        return state.response;
+    }
+    async function handleToolCall() {
+        // No active cycle — start one.
+        if (pending === null) {
+            return startNewCycle();
+        }
+        // Client-side expiry check. If the device code has expired, the server
+        // will reject further polls; clear state and start a fresh cycle. This
+        // is the only state transition triggered purely by time.
+        if (now() >= pending.expires_at) {
+            pending = null;
+            return startNewCycle();
+        }
+        // Rate-limit: respect the server's interval so we don't hammer /token
+        // when agents rapid-fire tool calls on failure.
+        if (shouldSkipPoll(pending)) {
+            return pending.response;
+        }
+        const state = pending;
+        state.last_poll_at = now();
+        const result = await pollOnce(opts.server, state.device_code);
+        return applyPollResult(state, result);
+    }
+    function hasValidCredentials() {
+        const creds = readCredentials(opts.credentialsPath);
+        if (!creds)
+            return false;
+        lastCreds = creds;
+        return !isAccessExpired(creds);
+    }
+    function getCredentials() {
+        return lastCreds;
+    }
+    return { handleToolCall, hasValidCredentials, getCredentials };
+}

package/dist/helpers.d.ts

@@ -20,7 +20,14 @@ export declare function printUsage(): void;
  * Falls back to `${server}/sse` if the URL is missing, malformed, or cross-origin.
  */
 export declare function resolveSseUrl(tokenSseUrl: string | undefined, server: string): string;
-/** Convert a token response to storable credentials. */
+/**
+ * Convert a token response to storable credentials.
+ *
+ * @throws if the server response omits refresh_token — this is a breaking
+ * contract, not a graceful degradation: without a refresh token the proxy
+ * will eventually hit the same silent-expiry cliff we're trying to eliminate.
+ * Fail loud so the server regression surfaces instead of being absorbed.
+ */
 export declare function tokenToCredentials(token: TokenResponse, sseUrl: string): Credentials;
 /** Format remaining TTL as human-readable string (e.g. "5d 12h"). */
 export declare function formatTtl(expiresAt: string): string;

package/dist/helpers.js

@@ -66,12 +66,26 @@ export function resolveSseUrl(tokenSseUrl, server) {
         return fallback;
     }
 }
-/** Convert a token response to storable credentials. */
+/**
+ * Convert a token response to storable credentials.
+ *
+ * @throws if the server response omits refresh_token — this is a breaking
+ * contract, not a graceful degradation: without a refresh token the proxy
+ * will eventually hit the same silent-expiry cliff we're trying to eliminate.
+ * Fail loud so the server regression surfaces instead of being absorbed.
+ */
 export function tokenToCredentials(token, sseUrl) {
+    if (!token.refresh_token || !token.refresh_token_expires_in) {
+        throw new Error("Pharaoh server response missing refresh_token — server is older than this client. " +
+            "Update the server to a version that issues refresh tokens, or downgrade the client.");
+    }
+    const now = Date.now();
     return {
-        version: 1,
+        version: 2,
         access_token: token.access_token,
-        expires_at: new Date(Date.now() + token.expires_in * 1000).toISOString(),
+        refresh_token: token.refresh_token,
+        expires_at: new Date(now + token.expires_in * 1000).toISOString(),
+        refresh_expires_at: new Date(now + token.refresh_token_expires_in * 1000).toISOString(),
         expires_in: token.expires_in,
         sse_url: sseUrl,
         github_login: token.github_login ?? null,

package/dist/index.js

@@ -11,10 +11,12 @@
  * - Proxy (pipe):      require pre-existing credentials, bridge stdio ↔ SSE.
  */
 import { pollForToken, printActivationPrompt, printAuthSuccess, requestDeviceCode, } from "./auth.js";
-import { deleteCredentials, isExpired, readCredentials, writeCredentials } from "./credentials.js";
-import { formatTtl, NPX_COMMAND, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
+import { deleteCredentials, writeCredentials } from "./credentials.js";
+import { formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
 import { runInstallSkills } from "./install-skills.js";
+import { exitForReauth, handleRefreshFailure, tryMidSessionRefresh } from "./lifecycle.js";
 import { startProxy, TenantSuspendedError, TokenExpiredError } from "./proxy.js";
+import { loadAndRefresh } from "./refresh.js";
 const BANNER = [
     "",
     "  ___  _  _   _   ___    _    ___  _  _ ",
@@ -57,7 +59,6 @@ async function main() {
         printLines("Pharaoh: credentials and MCP config cleared");
         process.exit(0);
     }
-    const creds = readCredentials();
     const isInteractive = Boolean(process.stdin.isTTY);
     // ── Interactive mode (user running in a terminal) ──
     // Full setup every time: fresh auth → register MCP → install skills → done.
@@ -86,11 +87,18 @@ async function main() {
         process.exit(0);
     }
     // ── Proxy mode (Claude Code spawned us as a stdio MCP server) ──
-    // If no credentials, we can't run the device flow (no TTY for user interaction).
-    if (!creds || isExpired(creds)) {
-        printLines("Pharaoh: no valid credentials — cannot start proxy.", "Run this command first to authenticate:", `  ${NPX_COMMAND}`, "");
-        process.exit(1);
+    // Load credentials; refresh silently if the access token is expired but the
+    // refresh token is still valid. Anything else → exit with guidance.
+    const outcome = await loadAndRefresh(server);
+    if (outcome === null) {
+        // No credentials file at all — first-time run or user logged out.
+        exitForReauth("no credentials — run authentication first");
     }
+    if (!outcome.ok) {
+        handleRefreshFailure(outcome.action, outcome.message);
+        return; // unreachable — handleRefreshFailure calls process.exit
+    }
+    let creds = outcome.creds;
     // Valid credentials — ensure skills are installed before starting proxy
     // Silently installs/updates on first run or package update; fast no-op if current.
     try {
@@ -105,8 +113,35 @@ async function main() {
     }
     catch (err) {
         if (err instanceof TokenExpiredError) {
-            printLines("Pharaoh: token expired or revoked.", "Run this command to re-authenticate:", `  ${NPX_COMMAND}`, "");
-            deleteCredentials();
+            // Mid-session token expired — attempt one silent refresh + retry
+            // before giving up. This is what makes the proxy self-heal across
+            // long sessions rather than dying at arbitrary moments.
+            const retryCreds = await tryMidSessionRefresh(creds, server);
+            if (retryCreds) {
+                creds = retryCreds;
+                printLines("Pharaoh: token refreshed mid-session — reconnecting");
+                try {
+                    await startProxy(creds.sse_url, creds.access_token);
+                    return;
+                }
+                catch (retryErr) {
+                    if (retryErr instanceof TokenExpiredError) {
+                        // Second 401 after a successful refresh — the fresh tokens
+                        // are already rejected, so the session is genuinely dead.
+                        // Delete creds before exit so the next spawn shows the
+                        // re-auth prompt instead of looping on the just-rejected
+                        // access token (which `isExpired` would still say is fresh).
+                        deleteCredentials();
+                        exitForReauth("token rejected after refresh");
+                    }
+                    if (retryErr instanceof TenantSuspendedError) {
+                        printLines(`Pharaoh: ${retryErr.message}`);
+                        process.exit(1);
+                    }
+                    throw retryErr;
+                }
+            }
+            // Refresh failed — exit message already printed by tryMidSessionRefresh
             process.exit(1);
         }
         if (err instanceof TenantSuspendedError) {

package/dist/lifecycle.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Proxy lifecycle helpers — credential state transitions and re-auth messaging.
+ *
+ * Extracted from index.ts so the branching logic can be unit-tested without
+ * booting the full CLI. Imported by main() and exercised as a real runtime
+ * dependency — no "test-only exports" here.
+ */
+import { type Credentials } from "./credentials.js";
+import { type RefreshFailureAction } from "./refresh.js";
+/**
+ * Attempt a silent refresh triggered by a mid-session TokenExpiredError.
+ * Returns new credentials on success, null on any failure (messages already
+ * printed). Caller decides whether to retry startProxy.
+ */
+export declare function tryMidSessionRefresh(creds: Credentials, server: string): Promise<Credentials | null>;
+/**
+ * Handle a failed `loadAndRefresh` at startup. Exits the process with the
+ * appropriate message and creds-file state per the classified action.
+ */
+export declare function handleRefreshFailure(action: RefreshFailureAction, message: string): never;
+/**
+ * Print a re-auth prompt and exit.
+ *
+ * Used for terminal lifecycle states where no refresh is possible:
+ * - Missing credentials file (first-time run, post-logout)
+ * - A fresh access token is rejected mid-session AFTER a successful refresh
+ *   (deleteCredentials is called explicitly before this in that case so the
+ *   next spawn sees a cold-start rather than looping on stale creds)
+ */
+export declare function exitForReauth(reason: string): never;

package/dist/lifecycle.js

@@ -0,0 +1,59 @@
+/**
+ * Proxy lifecycle helpers — credential state transitions and re-auth messaging.
+ *
+ * Extracted from index.ts so the branching logic can be unit-tested without
+ * booting the full CLI. Imported by main() and exercised as a real runtime
+ * dependency — no "test-only exports" here.
+ */
+import { deleteCredentials } from "./credentials.js";
+import { NPX_COMMAND, printLines } from "./helpers.js";
+import { refreshIfNeeded } from "./refresh.js";
+/**
+ * Attempt a silent refresh triggered by a mid-session TokenExpiredError.
+ * Returns new credentials on success, null on any failure (messages already
+ * printed). Caller decides whether to retry startProxy.
+ */
+export async function tryMidSessionRefresh(creds, server) {
+    const outcome = await refreshIfNeeded(creds, server);
+    if (outcome.ok)
+        return outcome.creds;
+    // Log the failure reason before caller's exit path runs.
+    if (outcome.action === "reauth") {
+        printLines("Pharaoh: refresh rejected — re-authentication required.", `  ${NPX_COMMAND}`, "");
+        deleteCredentials();
+    }
+    else {
+        // preserve / transient — keep creds, print diagnostic + next-step hint so
+        // the user knows their credentials file is intact (matches startup path).
+        printLines(`Pharaoh: refresh failed (${outcome.action}) — ${outcome.message}`, "Credentials preserved; next startup will retry.", "");
+    }
+    return null;
+}
+/**
+ * Handle a failed `loadAndRefresh` at startup. Exits the process with the
+ * appropriate message and creds-file state per the classified action.
+ */
+export function handleRefreshFailure(action, message) {
+    if (action === "reauth") {
+        deleteCredentials();
+        printLines("Pharaoh: session no longer valid — re-authenticate.", `  ${NPX_COMMAND}`, "");
+        process.exit(1);
+    }
+    // preserve / transient — keep creds, exit with diagnostic. Next spawn will
+    // try again; if the underlying cause clears, it just works.
+    printLines(`Pharaoh: refresh failed (${action}) — ${message}`, "Credentials preserved; next startup will retry.", "");
+    process.exit(1);
+}
+/**
+ * Print a re-auth prompt and exit.
+ *
+ * Used for terminal lifecycle states where no refresh is possible:
+ * - Missing credentials file (first-time run, post-logout)
+ * - A fresh access token is rejected mid-session AFTER a successful refresh
+ *   (deleteCredentials is called explicitly before this in that case so the
+ *   next spawn sees a cold-start rather than looping on stale creds)
+ */
+export function exitForReauth(reason) {
+    printLines(`Pharaoh: ${reason}.`, "Run this command to authenticate:", `  ${NPX_COMMAND}`, "");
+    process.exit(1);
+}

package/dist/proxy-server.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ProxyServer — owns the stdio MCP Server and delegates tool calls through a
+ * mutable Backend reference. The whole point of this abstraction is that we
+ * can swap the backend under a running server without restarting stdio, which
+ * means Claude Code never has to reconnect.
+ *
+ * Two entry points cover the interesting startup shapes:
+ *
+ * - startInAuthRequiredMode: cold start, no (or expired-refresh) credentials.
+ *   Spins up a gateway, wraps it in AuthRequiredBackend, starts the server.
+ *   Session C then polls hasValidCredentials() and calls setBackend() to swap
+ *   to the SSE backend once the user finishes the device flow.
+ *
+ * - startInSseMode: happy path — valid credentials are already on disk. Starts
+ *   the server directly with an SSE backend.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { type Backend } from "./backend.js";
+import type { Credentials } from "./credentials.js";
+import { type DeviceFlowGateway } from "./gateway.js";
+/**
+ * Stdio MCP server with a swappable backend. The Server instance is
+ * long-lived across backend swaps; only the Backend reference moves.
+ */
+export declare class ProxyServer {
+    private server;
+    private transport;
+    private backend;
+    private started;
+    constructor(initialBackend: Backend);
+    /**
+     * Wire up list/call handlers. Each handler reads this.backend fresh at
+     * dispatch time — do NOT hoist the reference into a local, or setBackend()
+     * won't take effect for subsequent calls. This is the core property that
+     * makes mutable-backend swaps safe.
+     */
+    private registerHandlers;
+    /**
+     * Start the backend (if it has a start hook) and connect stdio. Idempotent.
+     * Tests inject an alternate transport via startWithTransport().
+     */
+    start(): Promise<void>;
+    /**
+     * Test hook: start with a caller-supplied transport (e.g. InMemoryTransport).
+     * Kept separate from start() so the stdio wiring stays implicit in prod.
+     */
+    startWithTransport(transport: StdioServerTransport): Promise<void>;
+    /**
+     * Swap the backend reference and fire a tools/list_changed notification so
+     * the client re-fetches. No in-flight tracking — the SDK routes each call
+     * to whichever backend is current at dispatch time.
+     */
+    setBackend(next: Backend): Promise<void>;
+    stop(): Promise<void>;
+    getBackend(): Backend;
+}
+/**
+ * Cold-start entry point. No credentials (or refresh-expired creds) — start
+ * the proxy in auth-required mode so the stdio connection stays alive while
+ * the user completes the device flow.
+ *
+ * Returns the running ProxyServer and its gateway. Session C awaits
+ * gateway.hasValidCredentials() on each tool call boundary, and once that
+ * flips true, calls proxy.setBackend(createSseBackend(...)) to swap in the
+ * real catalog.
+ */
+export declare function startInAuthRequiredMode(server: string): Promise<{
+    proxy: ProxyServer;
+    gateway: DeviceFlowGateway;
+}>;
+/**
+ * Happy-path entry point. Credentials are fresh — start directly with the
+ * SSE backend. Returned proxy is running and ready for tool calls.
+ */
+export declare function startInSseMode(creds: Credentials): Promise<ProxyServer>;

package/dist/proxy-server.js

@@ -0,0 +1,143 @@
+/**
+ * ProxyServer — owns the stdio MCP Server and delegates tool calls through a
+ * mutable Backend reference. The whole point of this abstraction is that we
+ * can swap the backend under a running server without restarting stdio, which
+ * means Claude Code never has to reconnect.
+ *
+ * Two entry points cover the interesting startup shapes:
+ *
+ * - startInAuthRequiredMode: cold start, no (or expired-refresh) credentials.
+ *   Spins up a gateway, wraps it in AuthRequiredBackend, starts the server.
+ *   Session C then polls hasValidCredentials() and calls setBackend() to swap
+ *   to the SSE backend once the user finishes the device flow.
+ *
+ * - startInSseMode: happy path — valid credentials are already on disk. Starts
+ *   the server directly with an SSE backend.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { AuthRequiredBackend, createSseBackend } from "./backend.js";
+import { createGateway } from "./gateway.js";
+import { getPackageVersion } from "./version.js";
+/**
+ * Stdio MCP server with a swappable backend. The Server instance is
+ * long-lived across backend swaps; only the Backend reference moves.
+ */
+export class ProxyServer {
+    server;
+    transport = null;
+    backend;
+    started = false;
+    constructor(initialBackend) {
+        this.backend = initialBackend;
+        this.server = new Server({ name: "pharaoh-proxy", version: getPackageVersion() }, {
+            // tools.listChanged is required for sendToolListChanged() not
+            // to throw; the SDK's assertNotificationCapability gates it.
+            capabilities: { tools: { listChanged: true } },
+        });
+        this.registerHandlers();
+    }
+    /**
+     * Wire up list/call handlers. Each handler reads this.backend fresh at
+     * dispatch time — do NOT hoist the reference into a local, or setBackend()
+     * won't take effect for subsequent calls. This is the core property that
+     * makes mutable-backend swaps safe.
+     */
+    registerHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: await this.backend.listTools(),
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (req) => {
+            const result = await this.backend.callTool(req.params.name, req.params.arguments ?? {});
+            return result;
+        });
+    }
+    /**
+     * Start the backend (if it has a start hook) and connect stdio. Idempotent.
+     * Tests inject an alternate transport via startWithTransport().
+     */
+    async start() {
+        if (this.started)
+            return;
+        if (this.backend.start)
+            await this.backend.start();
+        this.transport = new StdioServerTransport();
+        await this.server.connect(this.transport);
+        this.started = true;
+    }
+    /**
+     * Test hook: start with a caller-supplied transport (e.g. InMemoryTransport).
+     * Kept separate from start() so the stdio wiring stays implicit in prod.
+     */
+    async startWithTransport(transport) {
+        if (this.started)
+            return;
+        if (this.backend.start)
+            await this.backend.start();
+        this.transport = transport;
+        // biome-ignore lint/suspicious/noExplicitAny: test transport is a Transport, but the type import chain is awkward here
+        await this.server.connect(transport);
+        this.started = true;
+    }
+    /**
+     * Swap the backend reference and fire a tools/list_changed notification so
+     * the client re-fetches. No in-flight tracking — the SDK routes each call
+     * to whichever backend is current at dispatch time.
+     */
+    async setBackend(next) {
+        const prev = this.backend;
+        this.backend = next;
+        if (next.start)
+            await next.start();
+        // Only emit after backend reference is swapped — if the client races
+        // a list request against the notification, we want them to see the
+        // new catalog.
+        await this.server.sendToolListChanged();
+        // Fire-and-forget stop of the old backend. Errors here don't affect
+        // the running session — the swap has already happened.
+        if (prev !== next && prev.stop) {
+            prev.stop().catch(() => { });
+        }
+    }
+    async stop() {
+        if (this.backend.stop) {
+            await this.backend.stop().catch(() => { });
+        }
+        if (this.transport) {
+            await this.server.close().catch(() => { });
+            this.transport = null;
+        }
+        this.started = false;
+    }
+    getBackend() {
+        return this.backend;
+    }
+}
+/**
+ * Cold-start entry point. No credentials (or refresh-expired creds) — start
+ * the proxy in auth-required mode so the stdio connection stays alive while
+ * the user completes the device flow.
+ *
+ * Returns the running ProxyServer and its gateway. Session C awaits
+ * gateway.hasValidCredentials() on each tool call boundary, and once that
+ * flips true, calls proxy.setBackend(createSseBackend(...)) to swap in the
+ * real catalog.
+ */
+export async function startInAuthRequiredMode(server) {
+    const gateway = createGateway({ server });
+    const backend = new AuthRequiredBackend(gateway);
+    const proxy = new ProxyServer(backend);
+    await proxy.start();
+    return { proxy, gateway };
+}
+/**
+ * Happy-path entry point. Credentials are fresh — start directly with the
+ * SSE backend. Returned proxy is running and ready for tool calls.
+ */
+export async function startInSseMode(creds) {
+    const backend = createSseBackend(creds.sse_url, creds.access_token);
+    const proxy = new ProxyServer(backend);
+    await proxy.start();
+    return proxy;
+}