@reticlehq/server 3.7.0 → 3.8.1

package/dist/surface/http-server.js

@@ -1,8 +1,8 @@
 import * as http from 'node:http';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, STATUS_HOLD_QUERY, DRIVE_PATH, } from '@reticlehq/core';
+import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, STATUS_HOLD_QUERY, DRIVE_PATH, SHUTDOWN_PATH, PROXY_ID_PARAM, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
-import { agentPeerSkew, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, } from '../command/version/peer-announce.js';
+import { agentPeerSkew, agentSessionOf, AGENT_SESSION_PARAM, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, } from '../command/version/peer-announce.js';
 import { log } from '../log.js';
 import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensMatch, } from '../portal/bridge/token-auth.js';
 import { clientDirectoryFromPeer, runWithClientDirectory } from '../hooks/client-directory.js';
@@ -18,8 +18,10 @@ import { LOOPBACK_IDLE_MS } from './loopback-agent.js';
  */
 export function createSharedServer(options = {}) {
     let mcpFactory;
+    let pageSdkVersions = () => [];
     let statusProvider;
     let driveProvider;
+    let shutdownHandler;
     let agentPresence;
     const transports = new Map();
     /**
@@ -47,10 +49,12 @@ export function createSharedServer(options = {}) {
         const localClient = isLoopbackPeer(req.socket.remoteAddress) &&
             isLoopbackHost(req.headers.host) &&
             isLocalWebOrigin(req.headers.origin, req.headers.referer);
-        if (localClient)
+        if (localClient) {
             return true;
-        if (token === undefined)
+        }
+        if (token === undefined) {
             return false;
+        }
         return tokensMatch(token, requestToken(req, url));
     };
     const httpServer = http.createServer((req, res) => {
@@ -90,6 +94,30 @@ export function createSharedServer(options = {}) {
             res.end(body);
             return;
         }
+        if ('POST' === req.method && path === SHUTDOWN_PATH) {
+            // Stricter than the routes above: loopback alone is not enough to stop a daemon that serves
+            // every agent on this machine. The caller must also show the pairing token.
+            if (!isLoopbackPeer(req.socket.remoteAddress) || token === undefined) {
+                res.writeHead(403, { 'Content-Type': 'text/plain' });
+                res.end('forbidden');
+                return;
+            }
+            if (!tokensMatch(token, requestToken(req, url))) {
+                res.writeHead(401, { 'Content-Type': 'text/plain' });
+                res.end('unauthorized');
+                return;
+            }
+            const handler = shutdownHandler;
+            if (handler === undefined) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('not found');
+                return;
+            }
+            // Answer first: the shutdown closes this server.
+            res.writeHead(202, { 'Content-Type': 'text/plain' });
+            res.end('stopping', () => handler());
+            return;
+        }
         if ('POST' === req.method && path === DRIVE_PATH) {
             if (driveProvider === undefined) {
                 res.writeHead(404, { 'Content-Type': 'text/plain' });
@@ -148,7 +176,7 @@ export function createSharedServer(options = {}) {
             // own check (a stderr line no agent reads), a nudge queued here rides out on the agent's next
             // tool result. That is the pair the user hits after `npm update`: a cached npx MCP package
             // talking to a daemon from a different build.
-            const peerSkew = agentPeerSkew(url.searchParams.get(PEER_VERSION_PARAM), url.searchParams.get(PEER_CONTRACT_PARAM));
+            const peerSkew = agentPeerSkew(url.searchParams.get(PEER_VERSION_PARAM), url.searchParams.get(PEER_CONTRACT_PARAM), pageSdkVersions());
             if (mcpFactory === undefined) {
                 res.writeHead(503, { 'Content-Type': 'text/plain' });
                 res.end('MCP server not ready');
@@ -158,16 +186,19 @@ export function createSharedServer(options = {}) {
             // one active transport per Server instance, so concurrent clients each need
             // their own instance backed by the same shared ToolDeps.
             // Handed to THIS connection's server only: the skew is about this agent, not the daemon (#1136).
-            const mcpServer = mcpFactory(peerSkew);
+            // The agent's own session id, so this connection's episode joins the agent hooks' records.
+            const mcpServer = mcpFactory(peerSkew, proxyIdOf(url.searchParams.get(PROXY_ID_PARAM)), agentSessionOf(url.searchParams.get(AGENT_SESSION_PARAM)));
             const transport = new SSEServerTransport(MCP_MESSAGE_PATH, res);
             const sid = transport.sessionId;
             transports.set(sid, transport);
             sseStreams.set(sid, res);
             const peerVersion = url.searchParams.get(PEER_VERSION_PARAM);
-            if (null !== peerVersion && 0 < peerVersion.length)
+            if (null !== peerVersion && 0 < peerVersion.length) {
                 peerVersions.set(sid, peerVersion);
-            if (1 === transports.size)
-                agentPresence?.(true); // first agent attached
+            }
+            if (1 === transports.size) {
+                agentPresence?.(true);
+            } // first agent attached
             res.on('close', () => {
                 transports.delete(sid);
                 sseStreams.delete(sid);
@@ -183,8 +214,9 @@ export function createSharedServer(options = {}) {
                 catch {
                     /* a counter must never affect a disconnect path */
                 }
-                if (0 === transports.size)
-                    agentPresence?.(false); // last agent detached → it's the human's turn
+                if (0 === transports.size) {
+                    agentPresence?.(false);
+                } // last agent detached → it's the human's turn
             });
             mcpServer
                 .connect(transport)
@@ -233,12 +265,18 @@ export function createSharedServer(options = {}) {
     function attachDrive(provider) {
         driveProvider = provider;
     }
+    function attachShutdown(handler) {
+        shutdownHandler = handler;
+    }
     function attachAgentPresence(cb) {
         agentPresence = cb;
     }
     function attachMcp(factory) {
         mcpFactory = factory;
     }
+    function attachPageSdkVersions(provider) {
+        pageSdkVersions = provider;
+    }
     function announceShutdown() {
         for (const [sid, stream] of sseStreams) {
             try {
@@ -271,8 +309,9 @@ export function createSharedServer(options = {}) {
                     'ERR_SERVER_NOT_RUNNING' !== err.code) {
                     reject(err);
                 }
-                else
+                else {
                     resolve();
+                }
             });
         });
     }
@@ -290,8 +329,10 @@ export function createSharedServer(options = {}) {
     return {
         httpServer,
         attachMcp,
+        attachPageSdkVersions,
         attachStatus,
         attachDrive,
+        attachShutdown,
         attachAgentPresence,
         announceShutdown,
         close,
@@ -308,12 +349,18 @@ const MAX_DRIVE_BODY_BYTES = 8 * 1024;
  * because real clients send them.
  */
 const JSON_MEDIA_TYPE = 'application/json';
+/** A proxy id is a UUID. Anything else is not an id this daemon keys an agent by. */
+const PROXY_ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function proxyIdOf(raw) {
+    return null !== raw && PROXY_ID_SHAPE.test(raw) ? raw : undefined;
+}
 function isJsonRequest(req) {
     // Read through the typed accessor rather than indexing the header bag: the index signature is
     // `any`-shaped, and narrowing after an unsafe read is narrowing a lie.
     const value = req.headersDistinct['content-type']?.[0];
-    if (undefined === value)
+    if (undefined === value) {
         return false;
+    }
     return JSON_MEDIA_TYPE === value.split(';')[0]?.trim().toLowerCase();
 }
 function readBody(req) {
@@ -361,8 +408,9 @@ function schemeOf(url) {
 }
 function driveSchemeRefusal(url) {
     const scheme = schemeOf(url);
-    if (scheme !== undefined && DRIVEABLE_SCHEMES.includes(scheme))
+    if (scheme !== undefined && DRIVEABLE_SCHEMES.includes(scheme)) {
         return undefined;
+    }
     // Names what it got, because the caller is a CLI printing this to somebody who typed the url and
     // needs to see which part of it was the problem.
     return (`unsupported scheme ${scheme ?? '(unparseable url)'} — reticle drive opens a running web app, ` +
@@ -376,8 +424,9 @@ function urlFromDriveRequest(body) {
     catch {
         return undefined;
     }
-    if (typeof parsed !== 'object' || null === parsed)
+    if (typeof parsed !== 'object' || null === parsed) {
         return undefined;
+    }
     const url = parsed['url'];
     return 'string' === typeof url && url.length > 0 ? url : undefined;
 }

package/dist/surface/mcp/faults/mcp-outage.d.ts

@@ -13,12 +13,22 @@
  * 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 } from '@reticlehq/core/telemetry';
+import { OutageErrCode, OutageReason, OutageStage } from '@reticlehq/core/telemetry';
 /**
  * `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 };
+/**
+ * What the proxy knew about a drop besides its reason: the socket error, if one came with it, and
+ * whether the stream had got a response first.
+ */
+export interface DropCause {
+    readonly error?: unknown;
+    readonly responded: boolean;
+}
+/** The error's `code`, narrowed to the closed set. Never the message. */
+export declare function outageErrCode(error: unknown): OutageErrCode;
 /** Reset between tests; a real process reports each stage at most once. */
 export declare function resetOutageReporting(): void;
 /**
@@ -30,4 +40,4 @@ export declare function reportMcpOutage(stage: OutageStage, facts: {
     reason: string;
     attempts: number;
     pendingLost?: number;
-}): void;
+} & Partial<DropCause>): void;

package/dist/surface/mcp/faults/mcp-outage.js

@@ -13,8 +13,9 @@
  * 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 { OutageErrCode, OutageReason, OutageStage, TelemetryEventKind, } from '@reticlehq/core/telemetry';
 import { getTelemetry } from '../../../telemetry/telemetry.js';
+import { PROXY_ID } from '../../../telemetry/proxy-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.
@@ -29,6 +30,14 @@ const KNOWN_REASONS = new Set(Object.values(OutageReason));
 function outageReason(raw) {
     return KNOWN_REASONS.has(raw) ? raw : OutageReason.OTHER;
 }
+const KNOWN_ERR_CODES = new Set(Object.values(OutageErrCode));
+/** The error's `code`, narrowed to the closed set. Never the message. */
+export function outageErrCode(error) {
+    const raw = error?.code;
+    return 'string' === typeof raw && KNOWN_ERR_CODES.has(raw)
+        ? raw
+        : OutageErrCode.OTHER;
+}
 /**
  * The daemon retiring on schedule is not a fault, and it is by far the commonest drop.
  *
@@ -54,6 +63,11 @@ export function resetOutageReporting() {
  */
 export function reportMcpOutage(stage, facts) {
     const reason = outageReason(facts.reason);
+    // The idle exit is not an outage. The daemon retires on schedule, `daemon_stopped` says so, and
+    // a `first` row for it was most of this event's volume. A real fault keeps its own slot below.
+    if (OutageStage.FIRST === stage && isBenign(reason)) {
+        return;
+    }
     const slot = `${stage}:${isBenign(reason) ? 'benign' : 'fault'}`;
     if (reported.has(slot))
         return;
@@ -66,6 +80,10 @@ export function reportMcpOutage(stage, facts) {
             // Always sent, including zero: zero is the finding — a drop no agent could feel. See
             // McpOutageSchema.pendingLost.
             pendingLost: facts.pendingLost ?? 0,
+            ...(facts.error !== undefined ? { errCode: outageErrCode(facts.error) } : {}),
+            ...(facts.responded !== undefined ? { responded: facts.responded } : {}),
+            // The join key: this event has no `sessionId`, and `mcp_client_connected` carries this id.
+            proxyId: PROXY_ID,
         },
     });
 }

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

@@ -1,10 +1,15 @@
-export { SseFrameParser, type SseFrame } from './sse-frame-parser.js';
-export { probeDaemon, waitForDaemon, waitForDaemonBind } from './proxy/proxy-daemon-probe.js';
+export { HandshakeReplay, RECONNECT_INITIALIZE_ID } from './proxy/proxy-handshake.js';
+export { SseFrameParser, buildSessionUrl, type SseFrame } from './sse-frame-parser.js';
+export { daemonProcessAlive, probeDaemon, waitForDaemon, waitForDaemonBind, } from './proxy/proxy-daemon-probe.js';
+export { flushProxyExit, reportWakeRefused } from '../../telemetry/proxy-telemetry.js';
+import type { ProxyBoot } from './proxy/proxy-boot.js';
+export type { ProxyBoot } from './proxy/proxy-boot.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 { PendingRequests, streamLossReplies } from './proxy/drive-calls.js';
 export { reconnectDelayMs } from './proxy/proxy-backoff.js';
 export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, type PostFailure, } from './proxy/mcp-post-transport.js';
 /**
@@ -13,45 +18,6 @@ export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, typ
  * 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;
-    /** Whether this unanswered request asked for a Harness drive. */
-    isDrive(id: unknown): boolean;
-    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[];
-    /** Forget which requests were drives, once their replies are written. */
-    clearDrives(): void;
-}
-/**
- * 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.
  *
@@ -74,47 +40,19 @@ export declare function shouldRetryFirstConnect(error: unknown, elapsedMs: numbe
  * 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;
 /** The briefing's facts about this directory; a live session outweighs stale memory (#1138). */
 export declare function instructionStateAt(port: number, liveSessions?: number): {
     previouslyConnected: boolean;
     appHere: boolean;
 };
-export declare function startMcpProxy(port: number, 
+export declare function startMcpProxy(bootPort: 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.
+ * failure mode for a daemon that crashed, was stopped, or shut itself down as idle. A returned
+ * port is where the daemon now is; the proxy dials it from then on.
  */
-ensureDaemon?: () => Promise<void>, 
+ensureDaemon?: () => Promise<number | void>, 
 /** Observe the real shutdown boundary in transport tests without terminating their worker. */
 exitProcess?: (code: number) => void, 
 /**
@@ -125,4 +63,9 @@ exitProcess?: (code: number) => void,
  * drops it, and an `endpoint` frame is not. Optional, because a transport test drives this
  * function with no resilience installed.
  */
-onUsableSession?: () => void): Promise<never>;
+onUsableSession?: () => void, 
+/**
+ * The daemon start that runs while the proxy already reads stdin. A client that does not wait
+ * for MCP servers gets the handshake and the tool list before the daemon is up.
+ */
+boot?: ProxyBoot): Promise<never>;