@reticlehq/server 2.14.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "2.14.0",
+  "version": "3.2.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",
@@ -14,16 +14,20 @@
       "default": "./dist/index.js"
     },
     "./cli": {
-      "types": "./dist/cli.d.ts",
-      "default": "./dist/cli.js"
+      "types": "./dist/command/cli.d.ts",
+      "default": "./dist/command/cli.js"
     }
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "ws": "^8.21.3",
     "zod": "^3.24.1",
-    "@reticlehq/core": "2.14.0",
-    "@reticlehq/init": "2.14.0"
+    "zod-to-json-schema": "^3.24.0",
+    "@reticlehq/browser": "3.2.0",
+    "@reticlehq/engine": "3.2.0",
+    "@reticlehq/init": "3.2.0",
+    "@reticlehq/core": "3.2.0",
+    "open-verification": "1.0.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -35,12 +39,12 @@
     "playwright": "^1.62.1",
     "pngjs": "^7.0.0"
   },
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "FSL-1.1-ALv2",
   "author": "Reticle contributors",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reticlehq/reticle.git",
-    "directory": "packages/server"
+    "directory": "server"
   },
   "homepage": "https://github.com/reticlehq/reticle#readme",
   "bugs": "https://github.com/reticlehq/reticle/issues",
@@ -59,22 +63,36 @@
     "cli"
   ],
   "reticle": {
-    "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": []
+    "changelog": "Reticle writes and tightens your regression flows for you: every drive is recorded automatically and replays with no model in the loop. The agent now sees nine tools instead of seventeen, `init` stops at a connected app and proving a flow is a separate first run, and Windows is supported. Upgrading from 2.x: see MIGRATION.md.",
+    "breakingChanges": [
+      "The default MCP surface is the merged nine. reticle_snapshot/query/inspect/state -> reticle_look { action }, reticle_network/console -> reticle_observe { action }, reticle_sessions/feedback -> reticle_session { action }, reticle_wait_for -> reticle_assert { action: \"wait\" }, reticle_act_sequence -> reticle_act { steps }. Old names redirect when CALLED, but an allowedTools allowlist or an MCP permission rule naming one refuses first -- update those by hand.",
+      "Twelve tools are unreachable on the default surface and have NO redirect: reticle_capabilities, reticle_clock, reticle_context, reticle_flow_replay, reticle_flow_save, reticle_intent, reticle_network_mock, reticle_record, reticle_run, reticle_screenshot, reticle_storage, reticle_visual_diff. The default surface ships no reticle_run hatch. Start the daemon with RETICLE_ADVERTISE_ALL_TOOLS=1 (read once at startup) and call them by name. Saved flows still replay via reticle_verify { action: \"flows\" }.",
+      "`reticle init` no longer drives: it ends at a connected session. --flow, --no-drive and --drive-model now exit non-zero, each naming its replacement. Prove a flow with reticle_verify { action: \"explore\", persona: \"<who does what>\" }, or npx @reticlehq/server verify <url> --explore --persona \"...\". init's exit code now means \"nothing connected\" rather than \"no verdict\". --files-only is unchanged.",
+      "@reticlehq/server now requires Node >=20.11 (was >=20.0.0).",
+      "@reticlehq/server, @reticlehq/init and @reticlehq/test declare license FSL-1.1-ALv2 instead of \"SEE LICENSE IN LICENSE\". The terms are identical; add the SPDX id to a licence allowlist."
+    ]
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.11"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.50"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
   },
   "scripts": {
-    "build": "tsc -b",
+    "build": "tsc -b && node ../scripts/alias-dist.mjs",
     "dev": "tsc -b --watch",
     "typecheck": "tsc -b",
     "lint": "eslint src",
-    "test:unit": "node ../../scripts/guard-tests.mjs unit",
-    "test:guards": "node ../../scripts/guard-tests.mjs guards",
+    "test:unit": "node ../scripts/guard-tests.mjs unit",
+    "test:guards": "node ../scripts/guard-tests.mjs guards",
     "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/bridge/auth-failure-reason.d.ts

@@ -1,23 +0,0 @@
-/**
- * Why the bridge refused a HELLO — the specific reason when there is one.
- *
- * A daemon left running by one project answers the next project's app and rejects it on token, and
- * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
- * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
- * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
- *
- * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
- * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
- * would report "different project" on every auth failure — the same confidently-wrong diagnostic
- * this exists to replace. What the daemon knows for certain is which projects it has ALREADY
- * accepted a session from; if it has served X and a HELLO arrives for Y, it demonstrably belongs to
- * someone else.
- *
- * A HELLO with no token at all is a third case, and a reload cannot fix it: the CDN snippet and a
- * Next config evaluated before any token existed froze an empty credential into the page. Naming
- * that is what stops the close reason from prescribing a recovery that cannot work.
- *
- * With no evidence — a fresh daemon, or a HELLO naming no project — nothing is inferred and the
- * plain reason stands, unless the page sent no token.
- */
-export declare function authFailureReason(servedProjects: ReadonlySet<string>, helloProject: string | undefined, helloToken?: string): string;

package/dist/bridge/auth-failure-reason.js

@@ -1,47 +0,0 @@
-/**
- * Why the bridge refused a HELLO — the specific reason when there is one.
- *
- * A daemon left running by one project answers the next project's app and rejects it on token, and
- * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
- * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
- * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
- *
- * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
- * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
- * would report "different project" on every auth failure — the same confidently-wrong diagnostic
- * this exists to replace. What the daemon knows for certain is which projects it has ALREADY
- * accepted a session from; if it has served X and a HELLO arrives for Y, it demonstrably belongs to
- * someone else.
- *
- * A HELLO with no token at all is a third case, and a reload cannot fix it: the CDN snippet and a
- * Next config evaluated before any token existed froze an empty credential into the page. Naming
- * that is what stops the close reason from prescribing a recovery that cannot work.
- *
- * With no evidence — a fresh daemon, or a HELLO naming no project — nothing is inferred and the
- * plain reason stands, unless the page sent no token.
- */
-const PLAIN = 'authentication failed';
-/** A paste-in snippet or a Next config that never saw a token. Reload cannot mint one. */
-const NO_TOKEN = 'authentication failed: no pairing token on the page';
-/** WebSocket close reasons are capped at 123 bytes; a longer one throws and closes with nothing. */
-const MAX_REASON_BYTES = 123;
-export function authFailureReason(servedProjects, helloProject, helloToken) {
-    // ONE served project, not merely some. A daemon that has accepted sessions from SEVERAL projects
-    // is demonstrably not owned by any one of them, so "that daemon is not yours, stop it" is the
-    // wrong story — and its advice is actively harmful there, because stopping it breaks the projects
-    // that are working. This is the normal shape for a globally-registered daemon, which several
-    // editors start from the user's home directory and point at everything.
-    //
-    // With one served project the inference holds and is worth making: the daemon belongs to that
-    // project and this HELLO is somebody else's. With several, the token is the suspect, and the plain
-    // reason says so without prescribing a recovery that costs other people their sessions.
-    if (helloProject !== undefined &&
-        1 === servedProjects.size &&
-        !servedProjects.has(helloProject)) {
-        const reason = `this daemon serves a different project — run \`reticle stop\` and retry`;
-        return Buffer.byteLength(reason, 'utf8') <= MAX_REASON_BYTES ? reason : PLAIN;
-    }
-    if (helloToken === undefined || 0 === helloToken.length)
-        return NO_TOKEN;
-    return PLAIN;
-}

package/dist/bridge/bridge-security.d.ts

@@ -1,30 +0,0 @@
-import type { StartOptions } from '../index.js';
-import { pairingTokenSource } from './pairing-token.js';
-/** The security contract the bridge/daemon enforce: bind host, pairing token, and WS origin allow-list. */
-interface BridgeSecurity {
-    host?: string;
-    token?: string;
-    allowedOrigins?: string[];
-    /**
-     * Which source supplied `token`, decided HERE because this is the only place that knows.
-     * By the time the Bridge sees it, an auto-provisioned token and one passed by a caller are the
-     * same field — so computing it downstream would report `explicit` for every daemon and describe
-     * nothing. See pairingTokenSource for why a refusal needs this at all.
-     */
-    tokenSource?: ReturnType<typeof pairingTokenSource>;
-}
-/**
- * Resolve the bridge's security options from explicit options first, then the environment. Shared by
- * both `start` and `startDaemon` so the token/host/origin contract is enforced identically on
- * every entrypoint — a past divergence let daemon mode silently run with auth disabled.
- */
-export declare function resolveBridgeSecurity(options: StartOptions): BridgeSecurity;
-/**
- * Same as `resolveBridgeSecurity`, but when no explicit/env token is set it auto-provisions one from
- * ~/.reticle/pairing-token so the bridge always requires a secret by default — this is what closes the
- * "any loopback origin is trusted" gap (a rogue localhost app can't read the file to present it). The
- * build plugins read the same file and inject it, so plugin-served apps stay zero-config. Best-effort:
- * if provisioning fails, the daemon degrades to the prior tokenless behavior rather than failing to start.
- */
-export declare function resolveBridgeSecurityWithAutoToken(options: StartOptions): Promise<BridgeSecurity>;
-export {};

package/dist/bridge/bridge-security.js

@@ -1,53 +0,0 @@
-import { ReticleEnv } from '@reticlehq/core';
-import { defaultPairingTokenDir, nodePairingTokenDeps, readOrCreatePairingToken, pairingTokenSource, } from './pairing-token.js';
-import { log } from '../log.js';
-/**
- * Resolve the bridge's security options from explicit options first, then the environment. Shared by
- * both `start` and `startDaemon` so the token/host/origin contract is enforced identically on
- * every entrypoint — a past divergence let daemon mode silently run with auth disabled.
- */
-export function resolveBridgeSecurity(options) {
-    const tokenSource = pairingTokenSource({
-        explicit: options.token !== undefined && 0 < options.token.length,
-        env: process.env,
-    });
-    const envToken = process.env[ReticleEnv.TOKEN];
-    const envOrigins = process.env[ReticleEnv.ALLOWED_ORIGINS];
-    const host = options.host ?? process.env[ReticleEnv.HOST];
-    const token = options.token ?? (envToken !== undefined && envToken.length > 0 ? envToken : undefined);
-    const allowedOrigins = options.allowedOrigins ??
-        envOrigins
-            ?.split(',')
-            .map((origin) => origin.trim())
-            .filter((origin) => origin.length > 0);
-    return {
-        ...(host === undefined ? {} : { host }),
-        ...(token === undefined ? {} : { token }),
-        ...(allowedOrigins === undefined ? {} : { allowedOrigins }),
-        tokenSource,
-    };
-}
-/**
- * Same as `resolveBridgeSecurity`, but when no explicit/env token is set it auto-provisions one from
- * ~/.reticle/pairing-token so the bridge always requires a secret by default — this is what closes the
- * "any loopback origin is trusted" gap (a rogue localhost app can't read the file to present it). The
- * build plugins read the same file and inject it, so plugin-served apps stay zero-config. Best-effort:
- * if provisioning fails, the daemon degrades to the prior tokenless behavior rather than failing to start.
- */
-export async function resolveBridgeSecurityWithAutoToken(options) {
-    const security = resolveBridgeSecurity(options);
-    if (security.token !== undefined)
-        return security;
-    const dir = options.pairingTokenDir ?? defaultPairingTokenDir();
-    const token = await readOrCreatePairingToken(dir, nodePairingTokenDeps());
-    if (token === undefined) {
-        // Fail-open is deliberate (never block a dev daemon on an unwritable $HOME), but it must be LOUD:
-        // the bridge is now trusting every loopback origin. Say so plainly, not just as a silent event.
-        log('pairing_token_provision_failed', {
-            dir,
-            warning: 'SECURITY: could not provision a pairing token — the bridge is running WITHOUT auth and will trust any localhost origin. Any local process/page can drive your browser sessions. Fix write access to this dir, or set RETICLE_TOKEN.',
-        });
-        return security;
-    }
-    return { ...security, token };
-}

package/dist/bridge/bridge.d.ts

@@ -1,95 +0,0 @@
-import * as http from 'node:http';
-import { Session, SessionManager } from '../session/session.js';
-import { pairingTokenSource } from './pairing-token.js';
-/** A human clicked ▶ on a saved flow in the panel — replay it with no agent. Wired by the daemon. */
-type ReplayRequestHandler = (sessionId: string, flowName: string) => void;
-/** Called once a browser session connects, so the daemon can push it the replayable-flow list. */
-type SessionReadyHandler = (session: Session) => void;
-/**
- * The close reasons worth telling an AGENT about, not just the SDK.
- *
- * The SDK prints these and stops retrying. The agent then calls a tool and is told "no browser
- * session connected" — which is indistinguishable from an app nobody started. An outdated SDK and a
- * stale pairing token were both invisible for that reason; these two carry their own remedy, so
- * surfacing them is strictly better than the generic answer.
- */
-export declare const WS_CLOSE_REASON: {
-    /**
-     * The generic form. The live path picks a DIRECTION-aware reason instead (see protocol-skew.ts);
-     * this stays as the close-code table's label and as the fallback when the skew cannot be read.
-     */
-    readonly PROTOCOL_MISMATCH: "protocol version mismatch — @reticlehq/browser and server disagree";
-    readonly AUTH_FAILED: "authentication failed — reload the page to pick up the current pairing token";
-    /**
-     * The daemon threw while handling a message. Closing is deliberate: an exception leaves the
-     * session in a state neither side can describe, and a socket left OPEN and unresponsive is the
-     * worst of the outcomes — the agent's next tool call reports "no browser session connected",
-     * which reads as an app nobody started. Closing at least makes the SDK reconnect and say so.
-     */
-    readonly HANDLER_FAILED: "the Reticle daemon failed handling a message — reload the page to reconnect";
-    /**
-     * The pool of half-open handshakes was full, so this dial was turned away before it could say
-     * anything. Every other refusal here records why and this one did not — it closed the socket and
-     * returned — so an app that was running, instrumented and actively dialling looked exactly like an
-     * app nobody had started, and the diagnosis went hunting a stopped dev server.
-     *
-     * Names the cause and the fact that it is transient, because the remedy differs from every other
-     * refusal on this path: nothing about the app is wrong and retrying is the correct response.
-     */
-    readonly HANDSHAKE_POOL_FULL: string;
-};
-interface BridgeOptions {
-    port: number;
-    host?: string;
-    token?: string;
-    /** Which source supplied `token`. Set by resolveBridgeSecurity; logged on a refusal, never sent. */
-    tokenSource?: ReturnType<typeof pairingTokenSource>;
-    allowedOrigins?: string[];
-    maxMessagesPerSecond?: number;
-    maxSessions?: number;
-    maxPendingConnections?: number;
-    helloTimeoutMs?: number;
-    clock?: () => number;
-    /**
-     * When set, the WebSocket server attaches to this HTTP server instead of binding standalone.
-     * Used in daemon mode where a single HTTP server handles both WS and SSE MCP traffic.
-     * `port` and `host` are ignored for binding when this is provided.
-     */
-    server?: http.Server;
-    /**
-     * The SDK-upgrade sentence to attach when a HELLO is skewed. Injected so the daemon can name
-     * this project's packages and package manager; tests that omit it get the no-project fallback.
-     */
-    sdkFix?: () => string;
-}
-/**
- * The browser-facing half of the relay: a localhost WebSocket server. Each connection
- * announces itself with HELLO (registering a Session), then streams EVENTs and replies to
- * COMMANDs.
- */
-export declare class Bridge {
-    #private;
-    readonly sessions: SessionManager;
-    /** Resolves with the actually-bound port once the server is listening. */
-    readonly ready: Promise<number>;
-    constructor(options: BridgeOptions);
-    /** Register the daemon's handler for a panel ▶ replay (it owns the flow store). */
-    attachReplay(handler: ReplayRequestHandler): void;
-    /**
-     * Register a callback fired when a browser session connects.
-     *
-     * ADDITIVE: every registered handler runs. Assigning to one slot meant the last caller silently
-     * won and every earlier one stopped firing — see the field declaration.
-     */
-    attachSessionReady(handler: SessionReadyHandler): void;
-    /** Register a callback fired the instant a session is created — used to attach the durable journal. */
-    /**
-     * Teardown handler fired when a session is removed (tab closed/disconnected). Without it the journal's
-     * batched tail (< one flush batch) never reaches disk and the learned ambient map is discarded.
-     */
-    attachSessionEnd(handler: (session: Session) => Promise<void>): void;
-    /** Register a handler to run when a session connects. Additive — every handler runs. */
-    attachSessionCreate(handler: (session: Session) => void): void;
-    close(): Promise<void>;
-}
-export {};