@reticlehq/server 2.0.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Reticle Labs
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,17 @@
+# @reticlehq/server
+
+The [Reticle](https://github.com/reticlehq/reticle) bridge + MCP server. It hosts a localhost WebSocket endpoint your app's `@reticlehq/browser` SDK connects to, and exposes MCP tools your coding agent uses to look at, act on, observe, and assert against the live app.
+
+```bash
+npx @reticlehq/server        # bridge on ws://localhost:4400, MCP over stdio
+```
+
+Point your agent at it (e.g. Claude Code `.mcp.json`):
+
+```jsonc
+{ "mcpServers": { "reticle": { "command": "npx", "args": ["@reticlehq/server", "mcp"] } } }
+```
+
+Tools: `reticle_snapshot`, `reticle_query`, `reticle_inspect`, `reticle_act`, `reticle_act_sequence`, `reticle_observe`, `reticle_wait_for`, `reticle_assert`, `reticle_network`, `reticle_console`, `reticle_animations`, `reticle_baseline_save`/`_list`, `reticle_diff`, `reticle_record_start`/`_stop`, `reticle_explore`, `reticle_sessions`.
+
+See the [main README](https://github.com/reticlehq/reticle). MIT.

package/dist/bridge-security.d.ts

@@ -0,0 +1,23 @@
+import type { StartOptions } from './index.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[];
+}
+/**
+ * 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 {};
+//# sourceMappingURL=bridge-security.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-security.d.ts","sourceRoot":"","sources":["../src/bridge-security.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,2GAA2G;AAC3G,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,cAAc,CAiB3E;AAED;;;;;;GAMG;AACH,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,cAAc,CAAC,CAUzB"}

package/dist/bridge-security.js

@@ -0,0 +1,44 @@
+import { ReticleEnv } from '@reticlehq/core';
+import { defaultPairingTokenDir, nodePairingTokenDeps, readOrCreatePairingToken, } 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 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 }),
+    };
+}
+/**
+ * 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) {
+        log('pairing_token_provision_failed', { dir });
+        return security;
+    }
+    return { ...security, token };
+}
+//# sourceMappingURL=bridge-security.js.map

package/dist/bridge-security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-security.js","sourceRoot":"","sources":["../src/bridge-security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAS/B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqB;IACzD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,KAAK,GACT,OAAO,CAAC,KAAK,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC1F,MAAM,cAAc,GAClB,OAAO,CAAC,cAAc;QACtB,UAAU;YACR,EAAE,KAAK,CAAC,GAAG,CAAC;aACX,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;aAC9B,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,OAAO;QACL,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACvC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;QACzC,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,OAAqB;IAErB,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC,eAAe,IAAI,sBAAsB,EAAE,CAAC;IAChE,MAAM,KAAK,GAAG,MAAM,wBAAwB,CAAC,GAAG,EAAE,oBAAoB,EAAE,CAAC,CAAC;IAC1E,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,GAAG,CAAC,gCAAgC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/C,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,CAAC;AAChC,CAAC"}

package/dist/bridge.d.ts

@@ -0,0 +1,42 @@
+import * as http from 'node:http';
+import { Session, SessionManager } from './session/session.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;
+interface BridgeOptions {
+    port: number;
+    host?: string;
+    token?: string;
+    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 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 (to push it the replayable flows). */
+    attachSessionReady(handler: SessionReadyHandler): void;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAalC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI/D,qGAAqG;AACrG,KAAK,oBAAoB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;AAC1E,kGAAkG;AAClG,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAqBtD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC;CACtB;AAkBD;;;;GAIG;AACH,qBAAa,MAAM;;IACjB,QAAQ,CAAC,QAAQ,iBAAwB;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;gBAapB,OAAO,EAAE,aAAa;IAyMlC,mFAAmF;IACnF,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAIjD,mGAAmG;IACnG,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAItD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQvB"}

package/dist/bridge.js

@@ -0,0 +1,281 @@
+import * as http from 'node:http';
+import { WebSocketServer } from 'ws';
+import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOOPBACK_HOST, MessageKind, TRANSPORT_LIMITS, isLoopbackHostname, } from '@reticlehq/core';
+import { Session, SessionManager } from './session/session.js';
+import { tokensMatch } from './token-auth.js';
+import { log } from './log.js';
+/** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
+const WS_CLOSE = {
+    TOO_MANY_HANDSHAKES: [1013, 'too many pending handshakes'],
+    HELLO_TIMEOUT: [1008, 'hello timeout'],
+    RATE_EXCEEDED: [1008, 'message rate exceeded'],
+    INVALID_MESSAGE: [1008, 'invalid message'],
+    HELLO_DUPLICATE: [1008, 'hello already received'],
+    AUTH_FAILED: [1008, 'authentication failed'],
+    SESSION_LIMIT: [1013, 'session limit reached'],
+};
+/** The flow name if this event is a panel ▶ replay request, else undefined. Pure boundary narrowing. */
+function replayRequest(event) {
+    if (event.type !== EventType.HUMAN_CONTROL)
+        return undefined;
+    if (event.data['kind'] !== HumanControlKind.REPLAY)
+        return undefined;
+    const name = event.data['text'];
+    return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+function normalizeOrigin(origin) {
+    try {
+        return new URL(origin).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/** Normalize ws RawData (string | Buffer | Buffer[] | ArrayBuffer) into a UTF-8 string. */
+function rawToString(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (Array.isArray(raw))
+        return Buffer.concat(raw).toString('utf8');
+    if (raw instanceof ArrayBuffer)
+        return Buffer.from(raw).toString('utf8');
+    return raw.toString('utf8');
+}
+/**
+ * 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 class Bridge {
+    sessions = new SessionManager();
+    /** Resolves with the actually-bound port once the server is listening. */
+    ready;
+    #wss;
+    #clock;
+    #token;
+    #allowedOrigins;
+    #maxMessagesPerSecond;
+    #maxSessions;
+    #maxPendingConnections;
+    #helloTimeoutMs;
+    #pendingConnections = 0;
+    #onReplay;
+    #onSessionReady;
+    constructor(options) {
+        const host = options.host ?? LOOPBACK_HOST;
+        if ((options.token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
+            throw new Error(`Reticle pairing token exceeds ${String(TRANSPORT_LIMITS.MAX_TOKEN_LENGTH)} characters`);
+        }
+        if (!isLoopbackHostname(host) && (options.token === undefined || options.token.length === 0)) {
+            throw new Error('a pairing token is required when the Reticle bridge binds beyond localhost');
+        }
+        this.#clock = options.clock ?? (() => Date.now());
+        this.#token =
+            options.token !== undefined && options.token.length > 0 ? options.token : undefined;
+        this.#allowedOrigins = new Set((options.allowedOrigins ?? [])
+            .map(normalizeOrigin)
+            .filter((origin) => origin !== null));
+        this.#maxMessagesPerSecond =
+            options.maxMessagesPerSecond ?? TRANSPORT_LIMITS.MAX_MESSAGES_PER_SECOND;
+        this.#maxSessions = options.maxSessions ?? TRANSPORT_LIMITS.MAX_SESSIONS;
+        this.#maxPendingConnections =
+            options.maxPendingConnections ?? TRANSPORT_LIMITS.MAX_PENDING_CONNECTIONS;
+        this.#helloTimeoutMs = options.helloTimeoutMs ?? TRANSPORT_LIMITS.HELLO_TIMEOUT_MS;
+        if (options.server !== undefined) {
+            const srv = options.server;
+            this.#wss = new WebSocketServer({
+                server: srv,
+                path: RETICLE_WS_PATH,
+                maxPayload: TRANSPORT_LIMITS.MAX_MESSAGE_BYTES,
+                verifyClient: ({ origin }, done) => {
+                    const allowed = this.#originAllowed(origin);
+                    if (!allowed)
+                        log('origin_rejected', { origin: origin ?? 'missing' });
+                    done(allowed, 403, 'Forbidden');
+                },
+            });
+            // In shared-server mode the daemon owns listen(); but a WebSocketServer bound to a server that
+            // fails to listen (EADDRINUSE) surfaces the error on the WS instance too. Without a listener
+            // that is an unhandled 'error' that can crash/hang the process — so absorb it here and reject
+            // `ready`, mirroring the standalone branch. The daemon's own listen handler reports the failure.
+            this.ready = new Promise((resolve, reject) => {
+                this.#wss.once('error', reject);
+                if (srv.listening) {
+                    this.#wss.removeListener('error', reject);
+                    resolve(srv.address().port);
+                }
+                else {
+                    srv.once('listening', () => {
+                        this.#wss.removeListener('error', reject);
+                        resolve(srv.address().port);
+                    });
+                }
+            });
+        }
+        else {
+            this.#wss = new WebSocketServer({
+                port: options.port,
+                host,
+                path: RETICLE_WS_PATH,
+                maxPayload: TRANSPORT_LIMITS.MAX_MESSAGE_BYTES,
+                verifyClient: ({ origin }, done) => {
+                    const allowed = this.#originAllowed(origin);
+                    if (!allowed)
+                        log('origin_rejected', { origin: origin ?? 'missing' });
+                    done(allowed, 403, 'Forbidden');
+                },
+            });
+            // Reject on 'error' as well as resolve on 'listening'. A port collision (EADDRINUSE) emits
+            // 'error'; with no listener that becomes an unhandled 'error' (process crash) AND leaves
+            // `ready` pending forever. Surfacing it lets the CLI print "port already in use" cleanly.
+            this.ready = new Promise((resolve, reject) => {
+                this.#wss.once('error', reject);
+                this.#wss.on('listening', () => {
+                    this.#wss.removeListener('error', reject);
+                    resolve(this.#wss.address().port);
+                });
+            });
+        }
+        this.#wss.on('connection', (socket) => {
+            this.#onConnection(socket);
+        });
+    }
+    #onConnection(socket) {
+        if (this.#pendingConnections >= this.#maxPendingConnections) {
+            socket.close(...WS_CLOSE.TOO_MANY_HANDSHAKES);
+            return;
+        }
+        this.#pendingConnections += 1;
+        let awaitingHello = true;
+        let session;
+        let messageWindowStartedAt = this.#clock();
+        let messagesInWindow = 0;
+        const releasePending = () => {
+            if (!awaitingHello)
+                return;
+            awaitingHello = false;
+            this.#pendingConnections -= 1;
+        };
+        const helloTimer = setTimeout(() => {
+            if (!awaitingHello)
+                return;
+            releasePending();
+            socket.close(...WS_CLOSE.HELLO_TIMEOUT);
+        }, this.#helloTimeoutMs);
+        socket.on('message', (raw) => {
+            const now = this.#clock();
+            if (now - messageWindowStartedAt >= 1000) {
+                messageWindowStartedAt = now;
+                messagesInWindow = 0;
+            }
+            messagesInWindow += 1;
+            if (messagesInWindow > this.#maxMessagesPerSecond) {
+                log('message_rate_exceeded', {});
+                socket.close(...WS_CLOSE.RATE_EXCEEDED);
+                return;
+            }
+            const parsed = this.#parse(rawToString(raw));
+            if (parsed === null) {
+                socket.close(...WS_CLOSE.INVALID_MESSAGE);
+                return;
+            }
+            if (parsed.kind === MessageKind.HELLO) {
+                if (session !== undefined) {
+                    socket.close(...WS_CLOSE.HELLO_DUPLICATE);
+                    return;
+                }
+                if (this.#token !== undefined && !tokensMatch(this.#token, parsed.token)) {
+                    log('authentication_failed', {});
+                    socket.close(...WS_CLOSE.AUTH_FAILED);
+                    return;
+                }
+                const existing = this.sessions.get(parsed.sessionId);
+                if (existing === undefined && this.sessions.count() >= this.#maxSessions) {
+                    socket.close(...WS_CLOSE.SESSION_LIMIT);
+                    return;
+                }
+                clearTimeout(helloTimer);
+                releasePending();
+                session = new Session(parsed, socket, this.#clock);
+                const replaced = this.sessions.add(session);
+                replaced?.disconnect('session replaced by a newer connection');
+                log('session_connected', { sessionId: session.id, url: session.url });
+                this.#onSessionReady?.(session); // daemon pushes the replayable-flow list to the panel
+                return;
+            }
+            if (session === undefined)
+                return;
+            session.touch();
+            if (parsed.kind === MessageKind.EVENT) {
+                // A panel ▶ replay needs the daemon's flow store, which the Session can't reach — route it to
+                // the daemon-wired handler instead of the in-session control path. Everything else is normal.
+                const replay = replayRequest(parsed.event);
+                if (replay !== undefined)
+                    this.#onReplay?.(session.id, replay);
+                else
+                    session.pushEvent(parsed.event);
+            }
+            else if (parsed.kind === MessageKind.COMMAND_RESULT) {
+                session.handleResult(parsed);
+            }
+        });
+        socket.on('close', () => {
+            clearTimeout(helloTimer);
+            releasePending();
+            if (session !== undefined) {
+                if (this.sessions.remove(session)) {
+                    log('session_disconnected', { sessionId: session.id });
+                }
+            }
+        });
+        socket.on('error', (err) => {
+            log('socket_error', { error: err.message });
+        });
+    }
+    #originAllowed(origin) {
+        // A real browser SDK connection always carries an Origin. A missing Origin means a non-browser
+        // local process (another app, a malicious npm postinstall, an extension's native host) — untrusted
+        // unless a pairing token is required, in which case the HELLO token check is the real gate.
+        if (origin === undefined)
+            return this.#token !== undefined;
+        const normalized = normalizeOrigin(origin);
+        if (normalized === null)
+            return false;
+        if (this.#allowedOrigins.has(normalized))
+            return true;
+        return isLoopbackHostname(new URL(normalized).hostname);
+    }
+    #parse(text) {
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        const result = ReticleMessageSchema.safeParse(json);
+        if (!result.success) {
+            log('bad_message', { issues: result.error.issues.length });
+            return null;
+        }
+        return result.data;
+    }
+    /** Register the daemon's handler for a panel ▶ replay (it owns the flow store). */
+    attachReplay(handler) {
+        this.#onReplay = handler;
+    }
+    /** Register a callback fired when a browser session connects (to push it the replayable flows). */
+    attachSessionReady(handler) {
+        this.#onSessionReady = handler;
+    }
+    close() {
+        return new Promise((resolve) => {
+            for (const client of this.#wss.clients)
+                client.terminate();
+            this.#wss.close(() => {
+                resolve();
+            });
+        });
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}

package/dist/bridge.test-harness.d.ts

@@ -0,0 +1,42 @@
+import { type ElementQuery } from '@reticlehq/core';
+import type { Bridge } from './bridge.js';
+import { type ToolDeps } from './tools/tools.js';
+/** The app-advertised testable surface a FakeBrowser reports for an reticle_capabilities round-trip. */
+export declare const FAKE_CAPABILITIES: {
+    testids: string[];
+    signals: string[];
+    stores: string[];
+    flows: {
+        name: string;
+        steps: string[];
+    }[];
+};
+/** A stand-in for the real @reticlehq/browser SDK: replies to commands and emits events. */
+export declare class FakeBrowser {
+    #private;
+    private readonly sessionId;
+    private readonly hasCapabilities;
+    matcher: (query: ElementQuery) => boolean;
+    /** When false, the browser pretends it has no CAPABILITIES handler (older build). */
+    handlesCapabilities: boolean;
+    /** When false, ACT results omit a testid (element has no data-testid → unstable step). */
+    actHasTestid: boolean;
+    /** when false, ACT reports settled:false + settleReason:'timeout' (throttled-tab path). */
+    actSettled: boolean;
+    /** When false, QUERY by testid returns no match (testid not in current DOM at replay). */
+    queryResolves: boolean;
+    /** Records every command the bridge sent (for replay assertions). */
+    readonly received: {
+        name: string;
+        args: Record<string, unknown>;
+    }[];
+    constructor(port: number, sessionId: string, hasCapabilities?: boolean);
+    open(): Promise<void>;
+    emit(type: string, data: Record<string, unknown>, ref?: string): void;
+    close(): void;
+}
+export declare function waitUntil(cond: () => boolean, timeoutMs?: number): Promise<void>;
+export declare const callTool: (deps: ToolDeps, name: string, args?: Record<string, unknown>) => Promise<unknown>;
+/** Builds the ToolDeps wired to a running bridge, with a frozen clock for deterministic tests. */
+export declare function makeDeps(bridge: Bridge): ToolDeps;
+//# sourceMappingURL=bridge.test-harness.d.ts.map

package/dist/bridge.test-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.test-harness.d.ts","sourceRoot":"","sources":["../src/bridge.test-harness.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAO1C,OAAO,EAAS,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAExD,wGAAwG;AACxG,eAAO,MAAM,iBAAiB;;;;;;;;CAK7B,CAAC;AAEF,4FAA4F;AAC5F,qBAAa,WAAW;;IAgBpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAflC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAe;IACxD,qFAAqF;IACrF,mBAAmB,UAAQ;IAC3B,0FAA0F;IAC1F,YAAY,UAAQ;IACpB,2FAA2F;IAC3F,UAAU,UAAQ;IAClB,0FAA0F;IAC1F,aAAa,UAAQ;IACrB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAM;gBAGxE,IAAI,EAAE,MAAM,EACK,SAAS,EAAE,MAAM,EACjB,eAAe,UAAQ;IAQ1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBrB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAOrE,KAAK,IAAI,IAAI;CAwFd;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,OAAO,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9E;AAED,eAAO,MAAM,QAAQ,GACnB,MAAM,QAAQ,EACd,MAAM,MAAM,EACZ,OAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,KACjC,OAAO,CAAC,OAAO,CAIjB,CAAC;AAEF,kGAAkG;AAClG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAcjD"}