@reticlehq/server 2.3.0 → 2.5.0

package/dist/license/license.js

@@ -37,13 +37,13 @@ export function signLicenseKey(payload, privateKey) {
 }
 /** Verify a key against the issuer public key. Never throws — returns a structured status. */
 export function verifyLicenseKey(key, publicKey, now) {
-    if (key === undefined || key.length === 0)
+    if (key === undefined || 0 === key.length)
         return { status: LicenseStatus.MISSING };
     const parts = key.split(KEY_SEP);
     if (parts.length !== 2 ||
         parts[0] === undefined ||
         parts[1] === undefined ||
-        parts[0].length === 0) {
+        0 === parts[0].length) {
         return { status: LicenseStatus.MALFORMED };
     }
     let json;
@@ -85,7 +85,7 @@ export class EnterpriseLicenseError extends Error {
 /** The issuer public key from the environment (set at release / by the operator); undefined if unset. */
 function issuerPublicKey() {
     const pem = process.env[LICENSE_PUBLIC_KEY_ENV];
-    if (pem === undefined || pem.length === 0)
+    if (pem === undefined || 0 === pem.length)
         return undefined;
     try {
         return createPublicKey(pem);
@@ -122,20 +122,20 @@ export const LICENSE_PUBLIC_KEY_ENV = 'RETICLE_LICENSE_PUBLIC_KEY';
  * never setting RETICLE_LICENSE_PUBLIC_KEY, because the baked key takes precedence. The public key is
  * safe to ship openly — it can only verify licenses, never mint them (that needs the private key).
  */
-export const BAKED_ISSUER_PUBLIC_KEY_PEM = '';
+const BAKED_ISSUER_PUBLIC_KEY_PEM = '';
 /**
  * Resolve the issuer public-key PEM enforcement uses: the baked-in release key wins, so it can't be
  * turned off from the environment. Only when nothing is baked (dev/repo) does the env var apply — that
  * env path is the test/self-eval escape hatch, not the production switch.
  */
-export function resolveIssuerPublicKeyPem(env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
+function resolveIssuerPublicKeyPem(env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
     if (baked.length > 0)
         return baked;
     const envPem = env[LICENSE_PUBLIC_KEY_ENV];
     return envPem !== undefined && envPem.length > 0 ? envPem : undefined;
 }
 function loadPublicKey(pem) {
-    if (pem === undefined || pem.length === 0)
+    if (pem === undefined || 0 === pem.length)
         return undefined;
     try {
         return createPublicKey(pem);
@@ -151,7 +151,7 @@ function loadPublicKey(pem) {
  */
 export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
     const pem = resolveIssuerPublicKeyPem(env, baked);
-    if (pem === undefined || pem.length === 0) {
+    if (pem === undefined || 0 === pem.length) {
         // In a production runtime this is NOT a benign eval session — it is a mis-built release whose gate
         // is off, and assertEnterpriseFromEnv now denies rather than unlocking. Say so loudly here too.
         return isProductionEnv(env)
@@ -196,7 +196,7 @@ export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUB
 /** True in a production runtime (NODE_ENV=production) — where a missing issuer key is a mis-built
  *  release, not an eval session, so the gate must fail CLOSED rather than run features free. */
 function isProductionEnv(env) {
-    return env['NODE_ENV'] === 'production';
+    return 'production' === env['NODE_ENV'];
 }
 /**
  * Gate an enterprise feature using env-resolved activation. Enforcement is ON when the issuer public key

package/dist/log.d.ts

@@ -1,5 +1,15 @@
 /**
  * Structured logging to stderr. stdout is reserved for the MCP stdio transport — never
  * write logs there.
+ *
+ * Every line carries `t`, an ISO-8601 wall clock, FIRST.
+ *
+ * It did not, and that cost a real investigation its conclusion: `~/.reticle/daemon-4400.log` had
+ * grown to 24MB of events and not one of them could be placed in time, so "the daemon vanished right
+ * behind the proxy" could only ever be "points at" and never "is". Ordering the key first also means
+ * a huge log can be bisected by eye, and by `sort`, without parsing it.
+ *
+ * The clock is read here rather than injected: this is the I/O boundary, not pure logic, and a
+ * logger that needs its caller to supply the time is a logger callers will route around.
  */
 export declare function log(event: string, fields?: Record<string, unknown>): void;

package/dist/log.js

@@ -1,8 +1,18 @@
 /**
  * Structured logging to stderr. stdout is reserved for the MCP stdio transport — never
  * write logs there.
+ *
+ * Every line carries `t`, an ISO-8601 wall clock, FIRST.
+ *
+ * It did not, and that cost a real investigation its conclusion: `~/.reticle/daemon-4400.log` had
+ * grown to 24MB of events and not one of them could be placed in time, so "the daemon vanished right
+ * behind the proxy" could only ever be "points at" and never "is". Ordering the key first also means
+ * a huge log can be bisected by eye, and by `sort`, without parsing it.
+ *
+ * The clock is read here rather than injected: this is the I/O boundary, not pure logic, and a
+ * logger that needs its caller to supply the time is a logger callers will route around.
  */
 export function log(event, fields = {}) {
-    const line = JSON.stringify({ event, ...fields });
+    const line = JSON.stringify({ t: new Date().toISOString(), event, ...fields });
     process.stderr.write(`${line}\n`);
 }

package/dist/mcp/mcp-is-error.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Does a SUCCESSFUL tool result actually describe a refusal?
+ *
+ * `isError` used to be set only when a handler threw. Every tool that returns a well-formed
+ * `{ error, recovery }` object instead — and that is half the surface — came back as protocol
+ * success with the flag unset, so anything branching on `isError` read a refusal as a result.
+ * Reported from a field sweep that had to special-case each tool's shape to score a run at all.
+ *
+ * A top-level `error` STRING is this codebase's refusal convention (see buildErrorPayload), so that
+ * is the whole test. Deliberately top-level only: `error` appears inside console entries and network
+ * rows as ordinary data, and flipping the flag for those would make it useless in the other direction.
+ */
+export declare function resultIsError(result: unknown): boolean;

package/dist/mcp/mcp-is-error.js

@@ -0,0 +1,18 @@
+/**
+ * Does a SUCCESSFUL tool result actually describe a refusal?
+ *
+ * `isError` used to be set only when a handler threw. Every tool that returns a well-formed
+ * `{ error, recovery }` object instead — and that is half the surface — came back as protocol
+ * success with the flag unset, so anything branching on `isError` read a refusal as a result.
+ * Reported from a field sweep that had to special-case each tool's shape to score a run at all.
+ *
+ * A top-level `error` STRING is this codebase's refusal convention (see buildErrorPayload), so that
+ * is the whole test. Deliberately top-level only: `error` appears inside console entries and network
+ * rows as ordinary data, and flipping the flag for those would make it useless in the other direction.
+ */
+export function resultIsError(result) {
+    if (typeof result !== 'object' || null === result || Array.isArray(result))
+        return false;
+    const error = result.error;
+    return 'string' === typeof error && error.length > 0;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 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 } from '@reticlehq/core';
+/**
+ * `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 };
+/** Reset between tests; a real process reports each stage at most once. */
+export declare function resetOutageReporting(): void;
+/**
+ * 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 declare function reportMcpOutage(stage: OutageStage, facts: {
+    reason: string;
+    attempts: number;
+}): void;

package/dist/mcp/mcp-outage.js

@@ -0,0 +1,48 @@
+/**
+ * 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';
+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 },
+    });
+}

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

@@ -0,0 +1,124 @@
+/**
+ * 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>;
+export declare function buildSessionUrl(rawData: string, port: number): string;
+/**
+ * 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 {};