@reticlehq/server 2.4.0 → 2.6.0

package/dist/mcp/mcp-proxy.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Overridable so the survival spec can reach exhaustion in seconds instead of minutes — the same
+ * reason the idle windows take an env override. A positive integer only; anything else falls back,
+ * so a typo cannot silently disable the retry loop.
+ */
+export declare const MAX_RECONNECT_ATTEMPTS: number;
+export declare function reconnectDelayMs(attempt: number): number;
+/** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
+export declare const RECONNECT_INITIALIZE_ID = "__reticle_proxy_reinit";
+/** Name the proxy log after the port it serves. Called before anything can log. */
+export declare function setProxyLogPort(port: number): void;
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export declare function proxyLogPath(port?: number | undefined): string;
+/**
+ * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
+ * does not. A dropped MCP connection is invisible from the agent's side — no message, no exit code —
+ * so the one thing that makes it diagnosable at all is a file somebody can read afterwards.
+ *
+ * EXPORTED because the crash handlers need it. `installProxyResilience` was wired to the bare stderr
+ * logger, so the proxy's own uncaught exceptions and unhandled rejections — the exact events that
+ * present to a human as "the MCP server disconnected" — were written to a stream the editor throws
+ * away. The handler ran, the process kept serving, and the reason went nowhere. Reported as "the
+ * proxy has no log file… when it dies the diagnostic dies with it", which was half right: the file
+ * existed, and the one path that most needed it was not using it.
+ */
+export declare function proxyLog(event: string, fields?: Record<string, unknown>): void;
+/**
+ * JSON-RPC requests forwarded on behalf of the client that have not been answered yet.
+ *
+ * Only used at shutdown, where it is the difference between "the client closed stdin" and "the client
+ * closed stdin and we dropped its `tools/list` on the floor while reporting exit 0". A request has an
+ * id AND a method; a notification has no id and is owed nothing; a response has an id and no method.
+ */
+export declare class PendingRequests {
+    #private;
+    observeOutbound(line: string): void;
+    observeInbound(line: string): void;
+    get unanswered(): string[];
+    /**
+     * Claim ONE unanswered id, so exactly one path may answer it. False means somebody already did —
+     * a duplicate response to one id is a protocol violation, not a belt-and-braces retry.
+     */
+    take(id: unknown): boolean;
+    /** Take every unanswered id and forget them, so the same request is failed at most once. */
+    drain(): string[];
+}
+/**
+ * JSON-RPC errors for every request that was in flight when the stream died.
+ *
+ * These are unrecoverable BY CONSTRUCTION: the daemon builds a fresh MCP session per SSE
+ * connection, so the reconnected session has never seen them. Re-sending them is not an option
+ * either — a `reticle_act` that already clicked would click twice, and inventing a second action in
+ * somebody's app is worse than reporting a failure.
+ *
+ * So the proxy answers them itself, under each request's own id. Found by brute force: killing the
+ * daemon under a live client left 20 of 20 concurrent calls hanging until the client's own timeout,
+ * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
+ */
+export declare function streamLossReplies(pending: PendingRequests, reason: string): string[];
+/** The one shape every "the transport ate your call" answer takes, whichever leg died. */
+export declare function transportLossReply(id: unknown, reason: string): string;
+/**
+ * Makes a reconnect invisible to the client.
+ *
+ * The daemon builds a FRESH `McpServer` per SSE connection, so a reconnected session has never seen
+ * the client's `initialize` — every subsequent `tools/call` would hit an uninitialized server. The
+ * proxy therefore remembers the handshake the client sent once and replays it into each new session.
+ * The replay is re-issued under a reserved id so the daemon's response to it can be dropped rather
+ * than reaching the client's stdout, where a duplicate JSON-RPC id would be a protocol violation.
+ */
+export declare class HandshakeReplay {
+    #private;
+    /** Record one outbound client line. Cheap enough to call for every stdin message. */
+    observeOutbound(line: string): void;
+    /** Lines to POST into a freshly-established session, before any queued client traffic. */
+    replayLines(): string[];
+    /** True when this inbound daemon line is the echo of our replayed handshake and must not be forwarded. */
+    shouldSuppressInbound(line: string): boolean;
+}
+/** One parsed Server-Sent-Events frame: the event name (defaulted to "message") and its data. */
+interface SseFrame {
+    event: string;
+    data: string;
+}
+/**
+ * Incremental SSE frame parser for the MCP front door.
+ *
+ * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
+ * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
+ * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
+ * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
+ * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
+ * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
+ */
+export declare class SseFrameParser {
+    #private;
+    push(chunk: string): SseFrame[];
+}
+/**
+ * Returns true if something is already listening on the reticle port.
+ * Uses a plain TCP probe so we don't create a side-effectful SSE session
+ * inside the daemon just to check reachability.
+ */
+export declare function probeDaemon(port: number): Promise<boolean>;
+/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
+export declare function waitForDaemon(port: number): Promise<void>;
+/**
+ * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
+ *
+ * An empty (or whitespace) data field is the shape a malformed daemon response takes, and it used to
+ * be accepted: `postUrl` became `''`, which is not `null`, so the proxy considered itself CONNECTED
+ * and posted every subsequent message to the empty string. Each one failed, the queue never armed
+ * its deadline because nothing was ever queued, and the agent held a session that could not carry a
+ * single call. Refusing the frame keeps the proxy in its disconnected path, which already knows how
+ * to reconnect and how to answer what it cannot send.
+ */
+export declare function buildSessionUrl(rawData: string, port: number): string | null;
+/**
+ * Bridge stdio ↔ SSE: connects to the running daemon's MCP endpoint and forwards
+ * Claude Code's stdin/stdout JSON-RPC through it. Never resolves — runs until stdin closes.
+ *
+ * A dropped SSE stream used to exit the process, which is what made the agent's `reticle_*` tools
+ * vanish mid-session with no message and no way for the agent to get them back — only a human running
+ * `/mcp` could. The daemon demonstrably stays up across these drops, so the stream ending is a
+ * transport event, not a shutdown: reconnect to it and replay the handshake instead of dying.
+ */
+export declare function startMcpProxy(port: number, 
+/**
+ * Bring a daemon back before reconnecting. Without it the proxy retried a DEAD port until the
+ * budget ran out and then killed itself, taking the agent's whole Reticle surface with it — the
+ * failure mode for a daemon that crashed, was stopped, or shut itself down as idle.
+ */
+ensureDaemon?: () => Promise<void>): Promise<never>;
+export {};