@reticlehq/server 2.4.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "2.4.0",
+  "version": "2.6.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.4.0"
+    "@reticlehq/core": "2.6.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -45,7 +45,9 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE-ENTERPRISE"
+    "LICENSE-ENTERPRISE",
+    "SKILL.md",
+    "docs"
   ],
   "keywords": [
     "mcp",
@@ -54,7 +56,7 @@
     "cli"
   ],
   "reticle": {
-    "changelog": "Smart MCP proxy with auto-start daemon, auto-update, and rollback support. Agents can call reticle_version_info, reticle_apply_update, and reticle_rollback.",
+    "changelog": "An MCP server that stays up when the daemon dies, one tool surface instead of five profiles (`RETICLE_TOOL_PROFILE` retired for `RETICLE_ADVERTISE_ALL_TOOLS`), and tools that refuse instead of answering wrongly.",
     "breakingChanges": []
   },
   "publishConfig": {
@@ -68,6 +70,7 @@
     "dev": "tsc -b --watch",
     "typecheck": "tsc -b",
     "lint": "eslint src",
-    "test:unit": "vitest run src --passWithNoTests"
+    "test:unit": "vitest run src --passWithNoTests",
+    "test:coverage": "vitest run src --passWithNoTests --coverage.enabled --coverage.provider=v8 --coverage.reporter=text-summary --coverage.include='src/**/*.ts' --coverage.exclude='src/**/*.test.ts'"
   }
 }

package/dist/cli-doctor.d.ts

@@ -1,6 +0,0 @@
-/**
- * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
- * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
- * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
- */
-export declare function handleDoctor(port: number): Promise<void>;

package/dist/cli-doctor.js

@@ -1,60 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { readPid, isAlive } from './daemon.js';
-import { diagnoseDesktop, isDesktopProject } from './init/desktop-doctor.js';
-/**
- * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
- * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
- * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
- */
-export async function handleDoctor(port) {
-    const line = (s) => {
-        process.stdout.write(`${s}\n`);
-    };
-    line('reticle doctor');
-    line(`  node         ${process.version}`);
-    try {
-        const { chromium } = await import('playwright');
-        const path = chromium.executablePath();
-        line(existsSync(path)
-            ? '  chromium     ✓ installed'
-            : '  chromium     ✗ missing — run: npx playwright install chromium');
-    }
-    catch {
-        line('  chromium     ✗ missing — run: npx playwright install chromium');
-    }
-    const pid = readPid(port);
-    if (pid !== null && isAlive(pid)) {
-        line(`  daemon       ✓ running on :${port} (pid ${pid})`);
-    }
-    else {
-        line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
-    }
-    line(`  bridge port  ${port}  (your app must dial THIS port — not your dev-server port)`);
-    // Desktop setup RCA. Every one of these fails SILENTLY — a Tauri app with the default CSP runs
-    // perfectly and never connects; an Electron app without the preload line reports zero network
-    // activity forever, which reads as "makes no backend calls" rather than "you are blind to them".
-    const readProjectFile = (relative) => {
-        try {
-            return readFileSync(join(process.cwd(), relative), 'utf8');
-        }
-        catch {
-            return undefined;
-        }
-    };
-    const desktop = diagnoseDesktop(readProjectFile, port);
-    if (desktop.length > 0) {
-        line('');
-        line(`  desktop      ✗ ${String(desktop.length)} issue(s) — the app will look fine and not work:`);
-        for (const finding of desktop) {
-            line(`                 ${finding.file}`);
-            line(`                   ${finding.problem}`);
-            line(`                   fix: ${finding.fix}`);
-        }
-    }
-    else if (isDesktopProject(readProjectFile)) {
-        // Say so explicitly. Silence would read as "not checked", which is the same ambiguity the
-        // findings above exist to remove.
-        line('  desktop      ✓ desktop wiring looks right');
-    }
-}

package/dist/cli-launch.js

@@ -1,112 +0,0 @@
-import * as http from 'node:http';
-import { spawn } from 'node:child_process';
-import { isOpaqueOrigin, LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
-/**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
- */
-export function summarizeStatus(payload) {
-    if (typeof payload !== 'object' || payload === null)
-        return { sessionCount: 0, sessions: [] };
-    const obj = payload;
-    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
-    const sessions = raw
-        .map((s) => {
-        if (typeof s !== 'object' || s === null)
-            return null;
-        const r = s;
-        const sessionId = typeof r['sessionId'] === 'string' ? r['sessionId'] : '';
-        if (sessionId === '')
-            return null;
-        return {
-            sessionId,
-            url: typeof r['url'] === 'string' ? r['url'] : '',
-            throttled: r['throttled'] === true,
-            stale: r['stale'] === true,
-            pendingMarks: typeof r['pendingMarks'] === 'number' ? r['pendingMarks'] : 0,
-        };
-    })
-        .filter((s) => s !== null);
-    const sessionCount = typeof obj['sessionCount'] === 'number' ? obj['sessionCount'] : sessions.length;
-    return { sessionCount, sessions };
-}
-/** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
-const STATUS_PROBE_TIMEOUT_MS = 1000;
-/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
-export function fetchStatus(port) {
-    return new Promise((resolve) => {
-        const req = http.get({ host: LOOPBACK_HOST, port, path: STATUS_PATH, timeout: STATUS_PROBE_TIMEOUT_MS }, (res) => {
-            let body = '';
-            res.setEncoding('utf8');
-            res.on('data', (chunk) => (body += chunk));
-            res.on('end', () => {
-                try {
-                    resolve(JSON.parse(body));
-                }
-                catch {
-                    resolve(undefined);
-                }
-            });
-        });
-        req.on('error', () => resolve(undefined));
-        req.on('timeout', () => {
-            req.destroy();
-            resolve(undefined);
-        });
-    });
-}
-function sameOrigin(a, b) {
-    try {
-        const origin = new URL(a).origin;
-        // Two opaque origins (desktop webviews, file:// docs) BOTH stringify to "null", so comparing them
-        // would call every desktop app the same app and reuse the wrong session. Never match on opaque.
-        if (isOpaqueOrigin(origin))
-            return false;
-        return origin === new URL(b).origin;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
- * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
- * - no url + nothing connected → ask for one.
- * - url + a tab already on that origin → reuse it (idempotent — re-running never piles up tabs).
- * - url + no matching tab → open it.
- */
-export function decideOpen(sessions, url) {
-    if (url === undefined) {
-        const first = sessions[0];
-        return first !== undefined ? { action: 'reuse', url: first.url } : { action: 'need-url' };
-    }
-    const match = sessions.find((s) => s.url === url || sameOrigin(s.url, url));
-    return match !== undefined ? { action: 'reuse', url: match.url } : { action: 'open', url };
-}
-/**
- * Percent-encode the cmd.exe metacharacters that `start` re-parses so a URL can't break out into
- * command execution on Windows (`?next=x&calc` → command chaining). `%` is left untouched so an
- * already-encoded URL isn't double-encoded; the browser decodes the escapes back to the real URL.
- */
-function encodeForWindowsStart(url) {
-    return url.replace(/[&^|<>()"'!]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
-}
-/** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
-export function openCommand(url, platform) {
-    if (platform === 'darwin')
-        return { cmd: 'open', args: [url] };
-    if (platform === 'win32') {
-        return { cmd: 'cmd', args: ['/c', 'start', '', encodeForWindowsStart(url)] };
-    }
-    return { cmd: 'xdg-open', args: [url] };
-}
-/** Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic. */
-export function openInBrowser(url, platform = process.platform, run = defaultRun) {
-    const { cmd, args } = openCommand(url, platform);
-    run(cmd, args);
-}
-function defaultRun(cmd, args) {
-    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
-    child.unref();
-}

package/dist/daemon-resilience.d.ts

@@ -1,22 +0,0 @@
-/**
- * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
- * single stray error must not take the whole fleet down:
- *
- * - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
- * code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
- * - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
- * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
- * daemon, which beats crashing silently or limping along corrupt.
- */
-export interface ProcessLike {
-    on(event: string, listener: (arg: unknown) => void): unknown;
-}
-type LogFn = (event: string, data: Record<string, unknown>) => void;
-/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
-export declare const CrashKind: {
-    readonly UNHANDLED_REJECTION: "unhandled_rejection";
-    readonly UNCAUGHT_EXCEPTION: "uncaught_exception";
-};
-export type CrashKind = (typeof CrashKind)[keyof typeof CrashKind];
-export declare function installDaemonResilience(proc: ProcessLike, log: LogFn, onFatal: () => void): void;
-export {};

package/dist/daemon-resilience.js

@@ -1,85 +0,0 @@
-/**
- * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
- * single stray error must not take the whole fleet down:
- *
- * - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
- * code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
- * - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
- * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
- * daemon, which beats crashing silently or limping along corrupt.
- */
-import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
-import { errorSkeleton, errorTypeOf, fingerprintCrash, MAX_REPORTED_FRAMES, reticleFrames, } from './telemetry/error-fingerprint.js';
-import { getSessionMetrics } from './telemetry/session-metrics.js';
-import { machineSnapshot } from './telemetry/machine-snapshot.js';
-import { getTelemetry } from './telemetry/telemetry.js';
-function describe(value) {
-    return value instanceof Error ? value.message : String(value);
-}
-/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
-export const CrashKind = {
-    UNHANDLED_REJECTION: 'unhandled_rejection',
-    UNCAUGHT_EXCEPTION: 'uncaught_exception',
-};
-/**
- * Report a crash with enough detail to actually diagnose it.
- *
- * This is the only place in the product that learns about a crash at all. An uncaught exception in a
- * long-running daemon takes down every agent attached to it, and the only other record is a line in a
- * local log nobody sends us.
- *
- * The first version sent a hash and nothing else, which made crashes rankable and undiagnosable — you
- * could see that forty machines hit `a3f2c1d8e9b0` and had no way to learn what that was. So it now
- * carries the four things an RCA needs: WHERE (our own frames, with function names and line numbers),
- * WHAT (the message with every variable part stripped), WHEN (the tool in flight), and WHY-ish (the
- * agent's approach run before it). All of it is our code and our vocabulary; the user's stack frames,
- * their paths, and the contents of their message are removed before any of it is built.
- *
- * Best-effort and wrapped: reporting a crash must never be the reason a crash gets worse.
- */
-function reportCrash(kind, value) {
-    try {
-        const errorType = errorTypeOf(value);
-        const stack = value instanceof Error ? (value.stack ?? '') : '';
-        const message = describe(value);
-        const { breadcrumb, inFlight } = getSessionMetrics().trail;
-        const machine = machineSnapshot();
-        void getTelemetry().emit(TelemetryEventKind.RUNTIME_CRASHED, {
-            // A crash is ALWAYS reached through something the agent asked for — the daemon does nothing on
-            // its own — so attributing it to the agent is accurate rather than a guess.
-            actor: TelemetryActor.AGENT,
-            crash: {
-                kind,
-                errorType,
-                fingerprint: fingerprintCrash(errorType, stack, message),
-                // The skeleton, not the message: every quoted string, path, URL, id and number is replaced
-                // by `*` first. This is what makes the fingerprint mean something to a human reading a chart.
-                message: errorSkeleton(message).slice(0, 300),
-                // Our own frames, our own published code. The file, the line, and the function — which is the
-                // whole of "where did it break". Frames from the user's app never survive this.
-                frames: reticleFrames(stack).slice(0, MAX_REPORTED_FRAMES),
-                ...(inFlight !== undefined ? { tool: inFlight } : {}),
-                ...(breadcrumb.length > 0 ? { breadcrumb } : {}),
-                // Crashes cluster hard by runtime version and architecture, and we were recording neither.
-                nodeVersion: process.versions.node,
-                arch: process.arch,
-                // "Out of memory" and "our bug" look identical in a stack trace. This is what tells them apart.
-                ...(machine !== undefined ? { machine } : {}),
-            },
-        });
-    }
-    catch {
-        /* a crash report must never be the reason a crash gets worse */
-    }
-}
-export function installDaemonResilience(proc, log, onFatal) {
-    proc.on('unhandledRejection', (reason) => {
-        log('reticle_daemon_unhandled_rejection', { reason: describe(reason) });
-        reportCrash(CrashKind.UNHANDLED_REJECTION, reason);
-    });
-    proc.on('uncaughtException', (err) => {
-        log('reticle_daemon_uncaught_exception', { error: describe(err) });
-        reportCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
-        onFatal();
-    });
-}

package/dist/mcp-proxy.d.ts

@@ -1,67 +0,0 @@
-/**
- * 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 declare const MAX_RECONNECT_ATTEMPTS = 60;
-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";
-/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
-export declare function proxyLogPath(): 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. */
-export 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): Promise<never>;