@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,119 @@
+export { SseFrameParser, type SseFrame } from './sse-frame-parser.js';
+export { probeDaemon, waitForDaemon } from './proxy/proxy-daemon-probe.js';
+/**
+ * Re-exported so every existing caller (and every spec) keeps importing the proxy's log from the
+ * proxy. Where the code lives is a file-size decision; where it is imported from is an API.
+ */
+export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, recoverOversizedProxyLog, setProxyLogPort, } from './proxy/proxy-log.js';
+export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy/proxy-backoff.js';
+export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, type PostFailure, } from './proxy/mcp-post-transport.js';
+/**
+ * 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;
+/** 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";
+/**
+ * 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, nextStep?: string): string[];
+/**
+ * How long a request may sit in the queue, unsent, before the proxy answers it itself.
+ *
+ * The second population the stress test found. A request that was FORWARDED and lost is failed when
+ * the stream drops; one that never got forwarded — queued while dormant or reconnecting — was
+ * waiting for a session that, with a squatter holding the port, never arrives. It then hung until
+ * the client's own timeout, or forever if the client has none.
+ *
+ * Comfortably longer than a daemon restart (~1-2s) so a normal blip still flushes and succeeds, and
+ * well under the 60s an MCP client typically allows, so the answer comes from us with a reason
+ * rather than from their timer with none.
+ */
+export declare const QUEUE_WAIT_MS = 20000;
+/** Retry a first connect, or report it? Pure, so the window can be held against the queue's. */
+export declare function shouldRetryFirstConnect(error: unknown, elapsedMs: number): boolean;
+/**
+ * What to do about it, carried on the reply the queue expiry sends.
+ *
+ * A bare -32001 on the first call after an install says nothing a user can act on: not whether to
+ * wait, not whether to retry, not whether the install itself is broken.
+ */
+export declare function queueExpiryNextStep(port: number): 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;
+}
+/**
+ * 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;
+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>, 
+/** Observe the real shutdown boundary in transport tests without terminating their worker. */
+exitProcess?: (code: number) => void, 
+/**
+ * Tell the resilience layer this session proved itself usable.
+ *
+ * The same `endpoint` frame that earns a fresh retry budget below also clears the disconnect-storm
+ * counter, and for the same reason: response headers are produced by a daemon that accepts SSE and
+ * drops it, and an `endpoint` frame is not. Optional, because a transport test drives this
+ * function with no resilience installed.
+ */
+onUsableSession?: () => void): Promise<never>;