@reticlehq/server 2.14.0 → 3.2.0

package/dist/mcp/mcp-outage.js

@@ -1,55 +0,0 @@
-/**
- * Reporting that the agent lost its Reticle tools.
- *
- * The proxy already writes a full account of an outage to ~/.reticle/mcp-proxy.log, which is exactly
- * where nobody looks and nothing aggregates. So the one question the transport must answer — how
- * often does a real user's MCP server go down, and does it come back — had no answer outside the
- * machine it happened on.
- *
- * Capped at two events per proxy process, and the cap is the design rather than a limitation. One
- * measured afternoon produced 547 proxy reconnects; an event per reconnect would bill for the
- * pathology instead of measuring it, which is the same mistake the per-call `tool` event made before
- * it was removed. What a dashboard needs is the SHARE OF SESSIONS that lose MCP at all (the first
- * outage) and the share where it never came back on its own (the budget being spent).
- */
-import { OutageReason, OutageStage, TelemetryEventKind } from '@reticlehq/core/telemetry';
-import { getTelemetry } from '../telemetry/telemetry.js';
-/**
- * `OutageStage` and `OutageReason` are core's — this re-export only saves the proxy an import. They
- * cross the wire, so the vocabulary lives in the contract package and is never re-listed here.
- */
-export { OutageReason, OutageStage };
-/**
- * The proxy's reason strings are free text: they also feed `proxyLog`, where prose is fine, and the
- * wire refuses anything unbounded. Unrecognised reports as `other` rather than being forwarded, so a
- * new drop path can appear in the proxy without an unclassified string leaving the machine.
- */
-const KNOWN_REASONS = new Set(Object.values(OutageReason));
-function outageReason(raw) {
-    return KNOWN_REASONS.has(raw) ? raw : OutageReason.OTHER;
-}
-const reported = new Set();
-/** Reset between tests; a real process reports each stage at most once. */
-export function resetOutageReporting() {
-    reported.clear();
-}
-/**
- * Report one stage of an outage, at most once per process. Fire-and-forget on purpose: this runs on
- * the transport's recovery path, and a telemetry POST must never be the thing that delays — or
- * fails — the reconnect it is describing.
- */
-export function reportMcpOutage(stage, facts) {
-    if (reported.has(stage))
-        return;
-    reported.add(stage);
-    void getTelemetry().emit(TelemetryEventKind.MCP_CONNECTION_LOST, {
-        outage: {
-            stage,
-            reason: outageReason(facts.reason),
-            attempts: facts.attempts,
-            // Always sent, including zero: zero is the finding — a drop no agent could feel. See
-            // McpOutageSchema.pendingLost.
-            pendingLost: facts.pendingLost ?? 0,
-        },
-    });
-}

package/dist/mcp/mcp-post-transport.js

@@ -1,109 +0,0 @@
-/**
- * The MCP proxy's POST leg: its own socket pool, and the one retry that is safe to make.
- *
- * Split out of `mcp-proxy.ts` when that file passed the 1000-line backstop after two independent
- * hardenings of this path met in a merge. It earns its own module rather than being an arbitrary
- * slice: everything here is about ONE thing — getting a single JSON-RPC line into the daemon, or
- * saying honestly that it never arrived — and the file it came from is about the SSE stream.
- */
-import * as http from 'node:http';
-import { log } from '../log.js';
-import { getSessionMetrics } from '../telemetry/session-metrics.js';
-import { reconnectDelayMs } from './proxy-backoff.js';
-/** One bounded pool for the short-lived POST side of each MCP SSE session. */
-export const MCP_PROXY_HTTP_AGENT_OPTIONS = {
-    keepAlive: true,
-    keepAliveMsecs: 30_000,
-    timeout: 60_000,
-    maxSockets: 8,
-    scheduling: 'lifo',
-};
-const MCP_PROXY_HTTP_AGENT = new http.Agent(MCP_PROXY_HTTP_AGENT_OPTIONS);
-/**
- * POST one JSON-RPC line into the daemon's session. Resolves null on success, or a structured
- * failure when the request never reached a server that will answer it.
- *
- * It used to resolve `void` in every case, logging the failure and moving on. That is the THIRD way
- * a call goes unanswered, and the only one neither `streamLossReplies` nor the queue timer can see:
- * the SSE stream is healthy (so nothing drops) and the request was forwarded (so nothing is queued),
- * but the POST leg is its own TCP connection and an ECONNRESET on it means the daemon never received
- * the call. Nobody was ever going to reply, and the caller waited for its own timeout.
- */
-const RETRYABLE_UNSENT_POST_ERRORS = new Set(['ENOBUFS', 'ERR_NO_BUFFER_SPACE', 'EADDRNOTAVAIL']);
-export function shouldRetryUnsentPost(error, bytesWritten, retryCount) {
-    const code = error?.code;
-    return 0 === retryCount && 0 === bytesWritten && RETRYABLE_UNSENT_POST_ERRORS.has(String(code));
-}
-export function postToSession(url, body, request = (options, callback) => http.request(options, callback)) {
-    const send = (retryCount) => new Promise((resolve) => {
-        const parsed = new URL(url);
-        const bodyBuf = Buffer.from(body, 'utf8');
-        const options = {
-            host: parsed.hostname,
-            port: parsed.port !== '' ? parseInt(parsed.port, 10) : 80,
-            path: `${parsed.pathname}${parsed.search}`,
-            method: 'POST',
-            agent: MCP_PROXY_HTTP_AGENT,
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': bodyBuf.byteLength,
-            },
-        };
-        // A keep-alive socket carries historical bytes; retry safety depends on this request's delta.
-        let socket;
-        let socketBytesBeforeRequest = 0;
-        let settled = false;
-        const req = request(options, (res) => {
-            if (settled)
-                return;
-            settled = true;
-            const status = res.statusCode ?? 0;
-            const rejected = status < 200 || status >= 300;
-            if (rejected) {
-                // A non-2xx from the daemon MCP endpoint used to be swallowed, hanging the JSON-RPC call
-                // client-side with no diagnostic. It is a refusal: no response is coming over the stream.
-                log('reticle_mcp_proxy_post_non2xx', { status, path: options.path });
-            }
-            else if (retryCount > 0) {
-                getSessionMetrics().recordPostRetrySaved();
-            }
-            res.resume(); // drain so the socket is reused
-            resolve(rejected
-                ? {
-                    reason: `daemon rejected the call with HTTP ${String(status)}`,
-                    transport: false,
-                    attempts: retryCount + 1,
-                }
-                : null);
-        });
-        req.once('socket', (assigned) => {
-            socket = assigned;
-            socketBytesBeforeRequest = assigned.bytesWritten;
-        });
-        req.on('error', (err) => {
-            if (settled)
-                return;
-            settled = true;
-            // Invisible to mcp_connection_lost (SSE is up) and to tool_refused (handler never ran).
-            getSessionMetrics().recordPostSocketFailure();
-            const bytesWritten = socket === undefined ? 0 : Math.max(0, socket.bytesWritten - socketBytesBeforeRequest);
-            if (shouldRetryUnsentPost(err, bytesWritten, retryCount)) {
-                const retryInMs = reconnectDelayMs(retryCount + 1);
-                log('reticle_mcp_proxy_post_retry', {
-                    code: err.code,
-                    retryInMs,
-                });
-                setTimeout(() => void send(retryCount + 1).then(resolve), retryInMs);
-                return;
-            }
-            log('reticle_mcp_proxy_post_error', { error: err.message });
-            resolve({
-                reason: `post failed: ${err.message}`,
-                transport: true,
-                attempts: retryCount + 1,
-            });
-        });
-        req.end(bodyBuf);
-    });
-    return send(0);
-}

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

@@ -1,110 +0,0 @@
-export { SseFrameParser, type SseFrame } from './sse-frame-parser.js';
-export { probeDaemon, waitForDaemon } from './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-log.js';
-export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy-backoff.js';
-export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, type PostFailure, } from './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): Promise<never>;