@reticlehq/server 2.3.0 → 2.4.0

package/dist/mcp-proxy.js

@@ -1,6 +1,9 @@
 import * as http from 'node:http';
 import * as net from 'node:net';
-import { LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { LOOPBACK_HOST, MCP_SSE_PATH, ReticleDir } from '@reticlehq/core';
 import { log } from './log.js';
 const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
 /**
@@ -16,6 +19,99 @@ const DAEMON_POLL_INTERVAL_MS = 100;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/** Reconnect backoff: linear, capped, so a briefly-restarting daemon is picked up fast. */
+const RECONNECT_BASE_MS = 250;
+const RECONNECT_CAP_MS = 5_000;
+/**
+ * How many consecutive failed reconnects before the proxy gives up and exits. At the capped backoff
+ * this is a few minutes — long enough to ride out a daemon restart, short enough that a genuinely
+ * dead daemon lets the agent host respawn the proxy (which spawns a fresh daemon) instead of hanging.
+ */
+export const MAX_RECONNECT_ATTEMPTS = 60;
+export function reconnectDelayMs(attempt) {
+    return Math.min(RECONNECT_BASE_MS * attempt, RECONNECT_CAP_MS);
+}
+/** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
+export const RECONNECT_INITIALIZE_ID = '__reticle_proxy_reinit';
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export function proxyLogPath() {
+    return join(homedir(), ReticleDir.ROOT, 'mcp-proxy.log');
+}
+/**
+ * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/mcp-proxy.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.
+ */
+function proxyLog(event, fields = {}) {
+    log(event, fields);
+    try {
+        const dir = join(homedir(), ReticleDir.ROOT);
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(proxyLogPath(), `${JSON.stringify({ event, ...fields })}\n`, 'utf8');
+    }
+    catch {
+        // Logging must never be the thing that kills the proxy.
+    }
+}
+function parseJsonRpc(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+const INITIALIZE_METHOD = 'initialize';
+const INITIALIZED_METHOD = 'notifications/initialized';
+/**
+ * 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 class HandshakeReplay {
+    #initialize = null;
+    #initialized = null;
+    #pendingReplayId = null;
+    /** Record one outbound client line. Cheap enough to call for every stdin message. */
+    observeOutbound(line) {
+        const msg = parseJsonRpc(line);
+        if (msg === null)
+            return;
+        // The first initialize is the session's identity; a client re-issuing one does not change it.
+        if (msg.method === INITIALIZE_METHOD && this.#initialize === null)
+            this.#initialize = line;
+        else if (msg.method === INITIALIZED_METHOD)
+            this.#initialized = line;
+    }
+    /** Lines to POST into a freshly-established session, before any queued client traffic. */
+    replayLines() {
+        if (this.#initialize === null)
+            return [];
+        const msg = parseJsonRpc(this.#initialize);
+        if (msg === null)
+            return [];
+        this.#pendingReplayId = RECONNECT_INITIALIZE_ID;
+        const reinit = { ...msg, id: RECONNECT_INITIALIZE_ID };
+        return this.#initialized === null
+            ? [JSON.stringify(reinit)]
+            : [JSON.stringify(reinit), this.#initialized];
+    }
+    /** True when this inbound daemon line is the echo of our replayed handshake and must not be forwarded. */
+    shouldSuppressInbound(line) {
+        if (this.#pendingReplayId === null)
+            return false;
+        const msg = parseJsonRpc(line);
+        if (msg === null || msg.id !== this.#pendingReplayId)
+            return false;
+        this.#pendingReplayId = null; // one response per replay — anything later is not ours to swallow
+        return true;
+    }
+}
 /**
  * Incremental SSE frame parser for the MCP front door.
  *
@@ -126,46 +222,92 @@ export function buildSessionUrl(rawData, port) {
 }
 /**
  * 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 or the SSE stream ends (at which point the process exits so
- * Claude Code restarts the proxy fresh).
+ * 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 function startMcpProxy(port) {
     return new Promise((_resolve, reject) => {
         let postUrl = null;
         const stdinQueue = [];
-        // ── SSE reader ──────────────────────────────────────────────────────────
-        const req = http.get({ host: LOOPBACK_HOST, port, path: MCP_SSE_PATH }, (res) => {
-            res.setEncoding('utf8');
-            const sse = new SseFrameParser();
-            res.on('data', (chunk) => {
-                for (const frame of sse.push(chunk))
-                    onSseEvent(frame.event, frame.data, port);
-            });
-            res.on('end', () => {
-                log('reticle_mcp_proxy_sse_ended', { port });
-                process.exit(0);
-            });
-            res.on('error', (err) => {
-                log('reticle_mcp_proxy_sse_error', { error: err.message });
-                process.exit(1);
-            });
-        });
-        req.on('error', (err) => reject(err));
+        const replay = new HandshakeReplay();
+        let stopped = false;
+        let attempts = 0;
         function onSseEvent(event, data, p) {
             if (event === 'endpoint') {
                 const url = buildSessionUrl(data, p);
                 postUrl = url;
-                // Flush messages that arrived before the session URL was known
-                for (const queued of stdinQueue.splice(0)) {
+                // The new session's McpServer has never seen the client's initialize — replay it first, then
+                // flush whatever the client sent while we were reconnecting.
+                for (const line of replay.replayLines())
+                    void postToSession(url, line);
+                for (const queued of stdinQueue.splice(0))
                     void postToSession(url, queued);
-                }
                 return;
             }
-            if (event === 'message') {
+            if (event === 'message' && !replay.shouldSuppressInbound(data)) {
                 process.stdout.write(`${data}\n`);
             }
         }
+        function scheduleReconnect(reason, detail) {
+            if (stopped)
+                return;
+            postUrl = null;
+            attempts++;
+            if (attempts > MAX_RECONNECT_ATTEMPTS) {
+                proxyLog('reticle_mcp_proxy_gave_up', {
+                    port,
+                    reason,
+                    attempts,
+                    ...(detail !== undefined ? { detail } : {}),
+                });
+                process.exit(1);
+            }
+            const wait = reconnectDelayMs(attempts);
+            proxyLog('reticle_mcp_proxy_reconnecting', {
+                port,
+                reason,
+                attempt: attempts,
+                retryInMs: wait,
+                ...(detail !== undefined ? { detail } : {}),
+            });
+            setTimeout(() => connect(false), wait).unref();
+        }
+        function connect(first) {
+            const req = http.get({ host: LOOPBACK_HOST, port, path: MCP_SSE_PATH }, (res) => {
+                attempts = 0; // a stream we actually established resets the budget
+                if (!first)
+                    proxyLog('reticle_mcp_proxy_reconnected', { port });
+                res.setEncoding('utf8');
+                // `end` and `error` can both fire on one response; only the first should drive a reconnect.
+                let settled = false;
+                const drop = (reason, detail) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    scheduleReconnect(reason, detail);
+                };
+                const sse = new SseFrameParser();
+                res.on('data', (chunk) => {
+                    for (const frame of sse.push(chunk))
+                        onSseEvent(frame.event, frame.data, port);
+                });
+                res.on('end', () => drop('sse_ended'));
+                res.on('error', (err) => drop('sse_error', err.message));
+                // A socket dying under us (daemon killed, network stack reset) emits NEITHER `end` nor
+                // `error` — only `aborted`/`close`. Listening for just the first two is why the proxy sat
+                // there afterwards holding a dead stream. `settled` keeps the clean case single-fire.
+                res.on('aborted', () => drop('sse_aborted'));
+                res.on('close', () => drop('sse_closed'));
+            });
+            // The very first connect failing means there is no daemon to talk to — that is a startup
+            // failure the caller handles. Later ones are just the daemon bouncing: keep retrying.
+            req.on('error', (err) => (first ? reject(err) : scheduleReconnect('connect_error', err.message)));
+        }
+        connect(true);
         // ── stdin reader ─────────────────────────────────────────────────────────
         process.stdin.setEncoding('utf8');
         let stdinBuffer = '';
@@ -177,6 +319,7 @@ export function startMcpProxy(port) {
                 const trimmed = line.trim();
                 if (trimmed === '')
                     continue;
+                replay.observeOutbound(trimmed);
                 if (postUrl === null) {
                     stdinQueue.push(trimmed);
                 }
@@ -185,6 +328,10 @@ export function startMcpProxy(port) {
                 }
             }
         });
-        process.stdin.on('end', () => process.exit(0));
+        // The client going away is the one clean shutdown — stop reconnecting and exit.
+        process.stdin.on('end', () => {
+            stopped = true;
+            process.exit(0);
+        });
     });
 }

package/dist/session/session-manager.js

@@ -1,4 +1,5 @@
 import { NO_SESSION_CONNECTED_ERROR } from '@reticlehq/core';
+import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
@@ -59,12 +60,17 @@ export class SessionManager {
     add(session) {
         const previous = this.#sessions.get(session.id);
         this.#sessions.set(session.id, session);
+        // Publish what this app declared sensitive to the driven-path rule. Here rather than in the
+        // bridge because EVERY path that registers a session goes through this method, and a declaration
+        // that silently fails to register is a leak nothing would report.
+        declareDrivenRedactionKeys(session.id, session.redactKeys);
         return previous;
     }
     remove(session) {
         if (this.#sessions.get(session.id) !== session)
             return false;
         session.rejectAll('session disconnected');
+        forgetDrivenRedactionKeys(session.id);
         return this.#sessions.delete(session.id);
     }
     get(sessionId) {

package/dist/session/session.d.ts

@@ -27,6 +27,12 @@ export declare class Session {
     title: string;
     adapters: string[];
     hasCapabilities: boolean;
+    /**
+     * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
+     * DRIVEN path can redact them too — a request body the daemon captures from the network stack
+     * never passes through the SDK, so nothing else would.
+     */
+    readonly redactKeys: readonly string[];
     constructor(hello: HelloMessage, socket: WebSocket, clock: Clock);
     /** Milliseconds since this session connected — the authoritative buffer clock. */
     elapsed(): number;

package/dist/session/session.js

@@ -32,6 +32,12 @@ export class Session {
     title;
     adapters;
     hasCapabilities;
+    /**
+     * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
+     * DRIVEN path can redact them too — a request body the daemon captures from the network stack
+     * never passes through the SDK, so nothing else would.
+     */
+    redactKeys;
     #socket;
     #clock;
     #startedAt;
@@ -70,6 +76,7 @@ export class Session {
         this.title = hello.title;
         this.adapters = hello.adapters;
         this.hasCapabilities = hello.hasCapabilities ?? false;
+        this.redactKeys = hello.redactKeys ?? [];
         this.#socket = socket;
         this.#clock = clock;
         this.#startedAt = clock();

package/dist/tools/read-tools.js

@@ -270,6 +270,10 @@ export const READ_TOOLS = [
             store: z.string().optional(),
             path: z.string().optional(),
             availableKeys: z.array(z.string()).optional(),
+            // Present only when `availableKeys` is a SAMPLE. Declared for the same reason as the truncation
+            // report below: a capped list of 50 keys with no count reads as a complete one, so an agent
+            // concludes the key it wants is absent when it is merely past the cap.
+            totalKeys: z.number().optional(),
             component: z
                 .object({ ok: z.boolean(), reason: z.string().optional(), state: z.unknown().optional() })
                 .optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Reticle bridge + MCP server. Hosts the browser WS endpoint and exposes MCP tools to the coding agent.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "@modelcontextprotocol/sdk": "^1.13.0",
     "ws": "^8.18.0",
     "zod": "^3.24.1",
-    "@reticlehq/core": "2.3.0"
+    "@reticlehq/core": "2.4.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",