@agent-deck/cli 1.8.2 → 1.10.0

package/dist/mcp-bridge.d.ts

@@ -0,0 +1,182 @@
+import type { Readable, Writable } from 'node:stream';
+/** JSON-RPC message as it crosses the bridge — we route on shape, not on schema. */
+type JsonRpcMessage = {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: unknown;
+};
+export type McpBridgeOptions = {
+    url: string;
+    /** Sent on every request — the server re-validates the launch deck each call. */
+    headers: Record<string, string>;
+    /**
+     * Re-read the folder assignment before replaying a handshake. It can have moved
+     * to another deck — or another endpoint — while we were connected
+     * (`switch_bound_deck`, `agent-deck use`), and the values we launched with would
+     * otherwise reconnect us to the deck and server we started on.
+     */
+    resolveTarget?: () => Promise<{
+        url?: string;
+        headers?: Record<string, string>;
+    } | undefined>;
+    stdin: Readable;
+    stdout: Writable;
+    /** Diagnostics only; never stdout, which carries the protocol. */
+    log?: (message: string) => void;
+    /** Backoff between failed server→client stream reconnects. */
+    streamRetryDelayMs?: number;
+    /** How long `run()` waits for in-flight requests after the host closes stdin. */
+    drainTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+};
+export declare function isSessionInvalidResponse(status: number, body: string): boolean;
+/**
+ * Deck id out of an MCP tool result — the binding tools answer with one JSON
+ * document in a text content block.
+ */
+export declare function readDeckIdFromToolResult(result: unknown): string | undefined;
+/** Pull JSON-RPC payloads out of an SSE body (`data:` lines, blank-line delimited). */
+export declare function parseSseMessages(chunk: string): JsonRpcMessage[];
+export declare class McpStdioHttpBridge {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly log;
+    private sessionId;
+    /**
+     * Bumped every time the session id changes — including to `undefined`. A reply
+     * is only about the session it was sent on, and after a recovery the id alone
+     * cannot say that (the replacement may reuse a value we once held).
+     */
+    private sessionGeneration;
+    /** MCP endpoint as it stands now — re-read from the assignment on recovery. */
+    private url;
+    /** Launch headers as they stand now — re-read from the assignment on recovery. */
+    private launchHeaders;
+    /** The deck the client is working against: launch deck, or whatever it bound to. */
+    private boundDeckId;
+    /**
+     * In-flight `bind_workspace` / `switch_bound_deck` calls: request id → the session
+     * generation the call went out on. A binding result only describes the session that
+     * answered it, so one that arrives after a restart must not be read as the deck the
+     * replacement session is on.
+     */
+    private readonly pendingDeckRebinds;
+    /**
+     * The deck the *client* asked for, if it ever did. Only a client that bound a deck
+     * itself can be surprised by a reconnect landing somewhere else — a client that
+     * simply took the folder assignment gets whatever that assignment says now.
+     */
+    private clientChosenDeckId;
+    /**
+     * Set when a recovery moved the session off the deck the client chose. Held until
+     * it binds again: reporting the gap on the one request that happened to be in
+     * flight is not enough, because the call the client sends next would go to the
+     * new deck with nothing to show for it.
+     */
+    private deckAwaitingRebind;
+    /**
+     * A session lost to a restart that the server still counts as stranded. Held
+     * across failed recovery attempts so the handshake that finally lands can name
+     * it — dropping it would leave that client unresolved on the server forever.
+     */
+    private unresolvedSessionId;
+    private bindingProbeSeq;
+    /** The client's own handshake, replayed verbatim when a session disappears. */
+    private cachedInitialize;
+    private cachedInitialized;
+    private streamAbort;
+    private closed;
+    private recovering;
+    /** The in-flight `initialize` exchange; later messages wait for it, not for each other. */
+    private handshake;
+    /** Every dispatched client message, so stdin closing can drain instead of cutting them off. */
+    private readonly inFlight;
+    /** How many times we re-initialized after a restart — otherwise invisible, so the tests read it. */
+    private recoveryCount;
+    constructor(options: McpBridgeOptions);
+    getSessionId(): string | undefined;
+    getRecoveryCount(): number;
+    /** The deck this bridge believes its session acts on — diagnostics and tests. */
+    getBoundDeckId(): string | undefined;
+    /** Resolves when stdin ends (the host closed the server). */
+    run(): Promise<void>;
+    /**
+     * Start one client message and keep it tracked. Nothing here may reject: an
+     * escaping error would tear down `run()` and, with it, the whole bridge process
+     * — the exact failure mode a restart is supposed to be recoverable from.
+     */
+    private dispatch;
+    /** Give in-flight exchanges a bounded chance to finish once stdin is gone. */
+    private drain;
+    close(): void;
+    /**
+     * Hand a message to the client. `sentOnGeneration` is the session generation the
+     * response came back on — absent for anything the bridge writes itself.
+     */
+    private writeToClient;
+    /**
+     * Follow the client's own binding calls. `bind_workspace` moves the session to a
+     * deck the launch headers know nothing about, so this is the only place the
+     * bridge can learn which deck a later request expects to act on.
+     *
+     * Returns a replacement message when the binding answer belongs to a session a
+     * restart has since taken away: the deck it names is not where the bridge is now,
+     * and letting the success through would leave the client acting on the wrong deck
+     * believing it had bound.
+     */
+    private noteDeckRebinding;
+    private requestHeaders;
+    private post;
+    private forwardFromClient;
+    /**
+     * Refuse a deck-scoped call while the session sits on a deck the client never
+     * chose. The binding tools themselves go through — they are how it gets out.
+     */
+    private refuseUntilRebound;
+    /**
+     * Hold a message only for the two exchanges that own the session id — the
+     * handshake and a restart recovery. Everything else goes out concurrently, so
+     * one long tool call cannot block the cancellation that would end it.
+     */
+    private awaitSession;
+    /** POST one client message, recovering once if the session went away. */
+    private deliver;
+    /** Every session change goes through here, so the generation cannot drift. */
+    private setSessionId;
+    private captureSessionId;
+    private emitResponseBody;
+    /**
+     * Recover the session a request was sent on — once, no matter how many of its
+     * siblings come back stale. A second handshake for the same invalidation would
+     * discard a session that is already working and leave the first one orphaned on
+     * the server, where it shows up as another stranded client.
+     */
+    private ensureRecovered;
+    /**
+     * Replay the cached handshake against the restarted server. Its responses are
+     * swallowed — the client already completed its handshake and would reject a
+     * second `initialize` result for an id it no longer has outstanding.
+     */
+    private recover;
+    private runRecovery;
+    private refreshLaunchTarget;
+    /**
+     * Ask the recovered session which deck it actually acts on. A session deck
+     * override is gone after a restart, so this is the answer to compare a pending
+     * request against — and the launch header is only the fallback for a server
+     * that does not expose the binding tool.
+     */
+    private resolveSessionDeck;
+    private failRequest;
+    /**
+     * Server→client stream (`GET /mcp`). Reconnects on drop; a 404 here is the same
+     * restart signal as on POST, so it recovers through the same path.
+     */
+    private startServerStream;
+    private consumeServerStream;
+}
+export {};
+//# sourceMappingURL=mcp-bridge.d.ts.map

package/dist/mcp-bridge.d.ts.map

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