@reticlehq/server 2.0.0

package/dist/flows/recordings.d.ts

@@ -0,0 +1,46 @@
+import type { FlowExpect } from '@reticlehq/core';
+/** One captured agent action, normalized for replay. */
+export interface RecordedStep {
+    /** ReticleTool.ACT | ReticleTool.ACT_SEQUENCE */
+    tool: string;
+    /** Normalized args: refs replaced by { by:'testid', value } where resolvable. */
+    args: Record<string, unknown>;
+    /** false if any ref could not be normalized to a testid (replay only valid in-session). */
+    stable: boolean;
+    /** Optional post-condition annotation carried into the on-disk flow's expect. */
+    expect?: FlowExpect;
+}
+interface ActiveRecording {
+    cursor: number;
+    steps: RecordedStep[];
+}
+/** A finished, replayable program compiled from a recording. */
+export interface CompiledProgram {
+    name: string;
+    version: number;
+    steps: RecordedStep[];
+}
+/**
+ * Tracks in-flight recordings (name -> { buffer cursor at record_start, captured steps })
+ * and the last compiled program per name (for reticle_replay).
+ */
+export declare class RecordingStore {
+    #private;
+    start(name: string, cursor: number): void;
+    isRecording(name: string): boolean;
+    /**
+     * Number of steps captured so far in the named ACTIVE recording (0 if it
+     * exists but is empty, undefined if there is no active recording by that name). Lets the annotate
+     * compiler target the LAST captured step without exposing the mutable step array.
+     */
+    stepCount(name: string): number | undefined;
+    /** Append a captured step to every active recording (steps belong to all in-flight spans). */
+    capture(step: RecordedStep): void;
+    /** Returns the active recording (cursor + steps) and clears it, or undefined if not recording. */
+    stop(name: string): ActiveRecording | undefined;
+    saveCompiled(program: CompiledProgram): void;
+    getCompiled(name: string): CompiledProgram | undefined;
+    active(): string[];
+}
+export {};
+//# sourceMappingURL=recordings.d.ts.map

package/dist/flows/recordings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordings.d.ts","sourceRoot":"","sources":["../../src/flows/recordings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,2FAA2F;IAC3F,MAAM,EAAE,OAAO,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,cAAc;;IAIzB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAIzC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI3C,8FAA8F;IAC9F,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAIjC,kGAAkG;IAClG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAM/C,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAI5C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAItD,MAAM,IAAI,MAAM,EAAE;CAGnB"}

package/dist/flows/recordings.js

@@ -0,0 +1,43 @@
+/**
+ * Tracks in-flight recordings (name -> { buffer cursor at record_start, captured steps })
+ * and the last compiled program per name (for reticle_replay).
+ */
+export class RecordingStore {
+    #active = new Map();
+    #compiled = new Map();
+    start(name, cursor) {
+        this.#active.set(name, { cursor, steps: [] });
+    }
+    isRecording(name) {
+        return this.#active.has(name);
+    }
+    /**
+     * Number of steps captured so far in the named ACTIVE recording (0 if it
+     * exists but is empty, undefined if there is no active recording by that name). Lets the annotate
+     * compiler target the LAST captured step without exposing the mutable step array.
+     */
+    stepCount(name) {
+        return this.#active.get(name)?.steps.length;
+    }
+    /** Append a captured step to every active recording (steps belong to all in-flight spans). */
+    capture(step) {
+        for (const rec of this.#active.values())
+            rec.steps.push(step);
+    }
+    /** Returns the active recording (cursor + steps) and clears it, or undefined if not recording. */
+    stop(name) {
+        const rec = this.#active.get(name);
+        this.#active.delete(name);
+        return rec;
+    }
+    saveCompiled(program) {
+        this.#compiled.set(program.name, program);
+    }
+    getCompiled(name) {
+        return this.#compiled.get(name);
+    }
+    active() {
+        return [...this.#active.keys()];
+    }
+}
+//# sourceMappingURL=recordings.js.map

package/dist/flows/recordings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordings.js","sourceRoot":"","sources":["../../src/flows/recordings.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,MAAM,OAAO,cAAc;IAChB,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAC7C,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;IAExD,KAAK,CAAC,IAAY,EAAE,MAAc;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,WAAW,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC;IAC9C,CAAC;IAED,8FAA8F;IAC9F,OAAO,CAAC,IAAkB;QACxB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,CAAC;IAED,kGAAkG;IAClG,IAAI,CAAC,IAAY;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,YAAY,CAAC,OAAwB;QACnC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED,WAAW,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/flows/replay.d.ts

@@ -0,0 +1,23 @@
+import type { RecordedStep, CompiledProgram } from './recordings.js';
+import type { Session } from '../session/session.js';
+/** A destructive-action confirmation is one-shot and must never persist into a recording. */
+export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean): Record<string, unknown>;
+/**
+ * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor
+ * priority mirrors synthesizeAnchor: a data-testid is the gold standard; failing that, the element's
+ * component identity / source location (the AUTO-ANCHOR) keeps the step STABLE instead of degrading to
+ * a volatile ref. Only when neither is available is the step ref-bound (in-session only).
+ */
+export declare function compileActStep(args: Record<string, unknown>, res: unknown): RecordedStep;
+/** Compile an reticle_act_sequence invocation, normalizing each sub-step to its testid where resolvable. */
+export declare function compileSequenceStep(args: Record<string, unknown>, res: unknown): RecordedStep;
+interface ReplayStepResult {
+    tool: string;
+    ok: boolean;
+    error?: string;
+    note?: string;
+}
+/** Re-execute every step of a compiled program in order, stopping at the first failure. */
+export declare function replayProgram(session: Session, program: CompiledProgram, confirmDangerous?: boolean): Promise<ReplayStepResult[]>;
+export {};
+//# sourceMappingURL=replay.d.ts.map

package/dist/flows/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/flows/replay.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAUrD,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,gBAAgB,UAAQ,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB;AAWD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,YAAY,CAyBxF;AAUD,4GAA4G;AAC5G,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,YAAY,CAkB7F;AA2BD,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,2FAA2F;AAC3F,wBAAsB,aAAa,CACjC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,eAAe,EACxB,gBAAgB,UAAQ,GACvB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyC7B"}

package/dist/flows/replay.js

@@ -0,0 +1,160 @@
+import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy } from '@reticlehq/core';
+import { ReticleTool } from '../tools/tool-names.js';
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+/** A destructive-action confirmation is one-shot and must never persist into a recording. */
+export function replayActionArgs(value, confirmDangerous = false) {
+    const args = { ...asRecord(value) };
+    delete args[DANGEROUS_ACTION_CONFIRM_ARG];
+    if (confirmDangerous)
+        args[DANGEROUS_ACTION_CONFIRM_ARG] = true;
+    return args;
+}
+/** The element's source location from an action result, when the framework stamped one. */
+function sourceFromResult(res) {
+    const source = asRecord(res['source']);
+    if (typeof source['file'] !== 'string' || typeof source['line'] !== 'number')
+        return undefined;
+    const out = { file: source['file'], line: source['line'] };
+    if (typeof source['column'] === 'number')
+        out['column'] = source['column'];
+    return out;
+}
+/**
+ * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor
+ * priority mirrors synthesizeAnchor: a data-testid is the gold standard; failing that, the element's
+ * component identity / source location (the AUTO-ANCHOR) keeps the step STABLE instead of degrading to
+ * a volatile ref. Only when neither is available is the step ref-bound (in-session only).
+ */
+export function compileActStep(args, res) {
+    const r = asRecord(res);
+    const testid = asString(r['testid']);
+    const action = asString(args['action']) ?? '';
+    const actArgs = replayActionArgs(args['args']);
+    if (testid !== undefined) {
+        return {
+            tool: ReticleTool.ACT,
+            stable: true,
+            args: { by: QueryBy.TESTID, value: testid, action, args: actArgs },
+        };
+    }
+    const component = asString(r['component']);
+    const source = sourceFromResult(r);
+    if (component !== undefined || source !== undefined) {
+        const componentArgs = { by: QueryBy.COMPONENT, action, args: actArgs };
+        if (component !== undefined)
+            componentArgs['component'] = component;
+        if (source !== undefined)
+            componentArgs['source'] = source;
+        return { tool: ReticleTool.ACT, stable: true, args: componentArgs };
+    }
+    return {
+        tool: ReticleTool.ACT,
+        stable: false,
+        args: { ref: asString(args['ref']) ?? '', action, args: actArgs },
+    };
+}
+/** Compile an reticle_act_sequence invocation, normalizing each sub-step to its testid where resolvable. */
+export function compileSequenceStep(args, res) {
+    const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
+    const resolved = Array.isArray(asRecord(res)['steps'])
+        ? asRecord(res)['steps']
+        : [];
+    let stable = inputSteps.length > 0;
+    const subSteps = inputSteps.map((raw, i) => {
+        const step = asRecord(raw);
+        const action = asString(step['action']) ?? '';
+        const stepArgs = replayActionArgs(step['args']);
+        const testid = asString(asRecord(resolved[i])['testid']);
+        if (testid !== undefined) {
+            return { by: QueryBy.TESTID, value: testid, action, args: stepArgs };
+        }
+        stable = false;
+        return { ref: asString(step['ref']) ?? '', action, args: stepArgs };
+    });
+    return { tool: ReticleTool.ACT_SEQUENCE, stable, args: { steps: subSteps } };
+}
+/** Resolve a recorded sub-step's element to a live ref via testid query, else fall back to its stored ref. */
+async function resolveRef(session, step) {
+    const by = asString(step.by);
+    const value = asString(step.value);
+    if (by === QueryBy.TESTID && value !== undefined) {
+        const result = await session.command(ReticleCommand.QUERY, { by, value });
+        if (!result.ok)
+            throw new Error(result.error ?? 'query failed');
+        const elements = Array.isArray(asRecord(result.result)['elements'])
+            ? asRecord(result.result)['elements']
+            : [];
+        const ref = asString(asRecord(elements[0])['ref']);
+        if (ref === undefined)
+            throw new Error(`testid '${value}' did not resolve in current page`);
+        return elements.length > 1
+            ? { ref, note: `ambiguous testid '${value}', used first match` }
+            : { ref };
+    }
+    const ref = asString(step.ref);
+    if (ref === undefined || ref.length === 0)
+        throw new Error('step has no testid or ref to resolve');
+    return { ref, note: 'replayed by stale ref (not portable across sessions)' };
+}
+/** Re-execute every step of a compiled program in order, stopping at the first failure. */
+export async function replayProgram(session, program, confirmDangerous = false) {
+    const results = [];
+    for (const step of program.steps) {
+        try {
+            if (step.tool === ReticleTool.ACT_SEQUENCE) {
+                const subs = Array.isArray(step.args['steps']) ? step.args['steps'] : [];
+                const notes = [];
+                const liveSteps = [];
+                for (const raw of subs) {
+                    const sub = asRecord(raw);
+                    const { ref, note } = await resolveRef(session, sub);
+                    if (note !== undefined)
+                        notes.push(note);
+                    liveSteps.push({
+                        ref,
+                        action: asString(sub['action']) ?? '',
+                        args: replayActionArgs(sub['args'], confirmDangerous),
+                    });
+                }
+                const r = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: liveSteps });
+                results.push(buildResult(step.tool, r.ok, r.error, notes));
+                if (!r.ok)
+                    break;
+            }
+            else {
+                const { ref, note } = await resolveRef(session, step.args);
+                const r = await session.command(ReticleCommand.ACT, {
+                    ref,
+                    action: asString(step.args['action']) ?? '',
+                    args: replayActionArgs(step.args['args'], confirmDangerous),
+                });
+                results.push(buildResult(step.tool, r.ok, r.error, note !== undefined ? [note] : []));
+                if (!r.ok)
+                    break;
+            }
+        }
+        catch (e) {
+            results.push({
+                tool: step.tool,
+                ok: false,
+                error: e instanceof Error ? e.message : String(e),
+            });
+            break;
+        }
+    }
+    return results;
+}
+function buildResult(tool, ok, error, notes) {
+    const base = { tool, ok };
+    if (!ok)
+        base.error = error ?? 'command failed';
+    if (notes.length > 0)
+        base.note = notes.join('; ');
+    return base;
+}
+//# sourceMappingURL=replay.js.map

package/dist/flows/replay.js.map

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

package/dist/http-server.d.ts

@@ -0,0 +1,39 @@
+import * as http from 'node:http';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const MCP_SSE_PATH = "/mcp/sse";
+export declare const MCP_MESSAGE_PATH = "/mcp/message";
+/** Local-only daemon introspection — `reticle status` GETs this to show sessions + health at a glance. */
+export declare const STATUS_PATH = "/status";
+export interface SharedServer {
+    readonly httpServer: http.Server;
+    /**
+     * Register a factory that creates a fresh McpServer per SSE connection.
+     * The MCP SDK's Protocol layer only supports one transport per Server instance,
+     * so each concurrent Claude Code client needs its own McpServer.
+     * Must be called before listen().
+     */
+    attachMcp(factory: () => McpServer): void;
+    /** Register the JSON the daemon returns from GET /status (live sessions + health for `reticle status`). */
+    attachStatus(provider: () => unknown): void;
+    /**
+     * Register a callback fired when the AGENT presence changes — true when the first MCP client (any
+     * agent: Codex/OpenCode/Claude/Hermes) connects, false when the last one disconnects. Agent-
+     * independent: the MCP connection lives exactly as long as the agent session, so its presence IS
+     * "is an agent attached?". The daemon uses this to tell the panel "agent live" vs "agent stopped".
+     */
+    attachAgentPresence(cb: (connected: boolean) => void): void;
+    close(): Promise<void>;
+}
+/**
+ * Creates a shared HTTP server that handles both the WebSocket bridge (browser SDK) and the
+ * SSE MCP transport (Claude/agent). Does NOT call listen() — caller controls that.
+ *
+ * Routes:
+ *   GET  /mcp/sse       → establishes SSE MCP session
+ *   POST /mcp/message   → routes MCP messages to an active SSE session
+ *   WS   /reticle          → browser SDK connections (via WebSocketServer)
+ */
+export declare function createSharedServer(options?: {
+    token?: string;
+}): SharedServer;
+//# sourceMappingURL=http-server.d.ts.map

package/dist/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWzE,eAAO,MAAM,YAAY,aAAa,CAAC;AACvC,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAC/C,0GAA0G;AAC1G,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;IACjC;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,SAAS,GAAG,IAAI,CAAC;IAC1C,2GAA2G;IAC3G,YAAY,CAAC,QAAQ,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IAC5C;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAC5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAqIjF"}

package/dist/http-server.js

@@ -0,0 +1,145 @@
+import * as http from 'node:http';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { log } from './log.js';
+import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensMatch, } from './token-auth.js';
+// These paths form the agent↔server wire contract. Keep in sync with skill/SKILL.md.
+export const MCP_SSE_PATH = '/mcp/sse';
+export const MCP_MESSAGE_PATH = '/mcp/message';
+/** Local-only daemon introspection — `reticle status` GETs this to show sessions + health at a glance. */
+export const STATUS_PATH = '/status';
+/**
+ * Creates a shared HTTP server that handles both the WebSocket bridge (browser SDK) and the
+ * SSE MCP transport (Claude/agent). Does NOT call listen() — caller controls that.
+ *
+ * Routes:
+ *   GET  /mcp/sse       → establishes SSE MCP session
+ *   POST /mcp/message   → routes MCP messages to an active SSE session
+ *   WS   /reticle          → browser SDK connections (via WebSocketServer)
+ */
+export function createSharedServer(options = {}) {
+    let mcpFactory;
+    let statusProvider;
+    let agentPresence;
+    const transports = new Map();
+    const token = options.token;
+    // The agent control plane (MCP transport) and /status carry the same trust as the browser WS: a
+    // loopback peer is trusted (the local stdio proxy and `reticle status` always dial 127.0.0.1), but any
+    // non-loopback peer must present the pairing token. Without this, binding the daemon beyond loopback
+    // (RETICLE_HOST) would expose reticle_act/reticle_navigate and session enumeration to the whole network even
+    // though the WS demanded a token. When no token is configured the bind is loopback-only anyway.
+    //
+    // Loopback-peer trust alone is not enough: a DNS-rebound webpage reaches us AS a loopback peer while
+    // its browser sends the attacker's original Host/Origin. So the loopback-trust tier additionally
+    // requires a loopback Host header and a loopback-or-absent Origin/Referer — the same rebinding
+    // defense the WS bridge has (#originAllowed). A rebound page fails those and falls through to the
+    // token check (which it cannot satisfy). Legitimate remote clients on a RETICLE_HOST bind present the
+    // token instead of relying on loopback trust, so this never breaks them.
+    const authorized = (req, url) => {
+        const localClient = isLoopbackPeer(req.socket.remoteAddress) &&
+            isLoopbackHost(req.headers.host) &&
+            isLocalWebOrigin(req.headers.origin, req.headers.referer);
+        if (localClient)
+            return true;
+        if (token === undefined)
+            return false;
+        return tokensMatch(token, requestToken(req, url));
+    };
+    const httpServer = http.createServer((req, res) => {
+        const rawUrl = req.url ?? '/';
+        const url = new URL(rawUrl, 'http://localhost');
+        const path = url.pathname;
+        if (path === STATUS_PATH || path === MCP_SSE_PATH || path === MCP_MESSAGE_PATH) {
+            if (!authorized(req, url)) {
+                res.writeHead(401, { 'Content-Type': 'text/plain' });
+                res.end('unauthorized');
+                return;
+            }
+        }
+        if (req.method === 'GET' && path === STATUS_PATH) {
+            const body = JSON.stringify(statusProvider?.() ?? { running: true });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(body);
+            return;
+        }
+        if (req.method === 'GET' && path === MCP_SSE_PATH) {
+            if (mcpFactory === undefined) {
+                res.writeHead(503, { 'Content-Type': 'text/plain' });
+                res.end('MCP server not ready');
+                return;
+            }
+            // Fresh McpServer per connection: the MCP SDK's Protocol layer only supports
+            // one active transport per Server instance, so concurrent clients each need
+            // their own instance backed by the same shared ToolDeps.
+            const mcpServer = mcpFactory();
+            const transport = new SSEServerTransport(MCP_MESSAGE_PATH, res);
+            const sid = transport.sessionId;
+            transports.set(sid, transport);
+            if (transports.size === 1)
+                agentPresence?.(true); // first agent attached
+            res.on('close', () => {
+                transports.delete(sid);
+                transport.close().catch(() => undefined);
+                mcpServer.close().catch(() => undefined);
+                log('mcp_client_disconnected', { sessionId: sid });
+                if (transports.size === 0)
+                    agentPresence?.(false); // last agent detached → it's the human's turn
+            });
+            mcpServer
+                .connect(transport)
+                .then(() => {
+                log('mcp_client_connected', { sessionId: sid });
+            })
+                .catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                log('mcp_connect_error', { error: message });
+            });
+            return;
+        }
+        if (req.method === 'POST' && path === MCP_MESSAGE_PATH) {
+            const sessionId = url.searchParams.get('sessionId');
+            if (sessionId === null) {
+                res.writeHead(400, { 'Content-Type': 'text/plain' });
+                res.end('missing sessionId');
+                return;
+            }
+            const transport = transports.get(sessionId);
+            if (transport === undefined) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('session not found');
+                return;
+            }
+            transport.handlePostMessage(req, res).catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                log('mcp_message_error', { error: message });
+            });
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('not found');
+    });
+    function attachStatus(provider) {
+        statusProvider = provider;
+    }
+    function attachAgentPresence(cb) {
+        agentPresence = cb;
+    }
+    function attachMcp(factory) {
+        mcpFactory = factory;
+    }
+    async function close() {
+        for (const transport of transports.values()) {
+            await transport.close();
+        }
+        transports.clear();
+        await new Promise((resolve, reject) => {
+            httpServer.close((err) => {
+                if (err !== undefined && err !== null)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    return { httpServer, attachMcp, attachStatus, attachAgentPresence, close };
+}
+//# sourceMappingURL=http-server.js.map

package/dist/http-server.js.map

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

package/dist/idle-shutdown.d.ts

@@ -0,0 +1,34 @@
+export interface IdleShutdownOptions {
+    /** True when nothing is using the daemon: no agent connected, no browser session, no pool lease. */
+    isIdle: () => boolean;
+    /** Clean teardown + process exit. Called at most once. */
+    onShutdown: () => void;
+    /** Continuous-idle window before shutdown. `0` (or negative) disables the watcher entirely. */
+    graceMs: number;
+    /** How often to re-check idleness. */
+    checkIntervalMs?: number;
+    /** Injected clock — never read wall-clock time in logic (repo rule). */
+    clock?: () => number;
+}
+/**
+ * Self-terminates an idle daemon so Reticle never lingers eating a user's resources (the daemon process,
+ * any headless Chromium the pool launched, and the bound port) after the editor closes. The `reticle mcp`
+ * proxy spawns the daemon DETACHED so it survives between turns — which means nothing else will ever
+ * stop it; this watcher is that missing stop. Idle = `isIdle()` true continuously for `graceMs` (long
+ * enough to ride out brief agent reconnects between turns). On fire it calls `onShutdown` exactly once.
+ * The interval is `unref`'d, so it never keeps the process alive on its own; `start()` is idempotent.
+ */
+export declare class IdleShutdown {
+    #private;
+    constructor(opts: IdleShutdownOptions);
+    /** Run one idle check. Exposed so a test can drive it deterministically with an injected clock. */
+    check(): void;
+    start(): void;
+    stop(): void;
+}
+/**
+ * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of milliseconds,
+ * `0` to disable. Anything missing/invalid falls back to the default. Pure.
+ */
+export declare function resolveIdleShutdownMs(raw: string | undefined): number;
+//# sourceMappingURL=idle-shutdown.d.ts.map

package/dist/idle-shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle-shutdown.d.ts","sourceRoot":"","sources":["../src/idle-shutdown.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,mBAAmB;IAClC,oGAAoG;IACpG,MAAM,EAAE,MAAM,OAAO,CAAC;IACtB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;;gBAUX,IAAI,EAAE,mBAAmB;IAQrC,mGAAmG;IACnG,KAAK,IAAI,IAAI;IAeb,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,IAAI;CAKb;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKrE"}

package/dist/idle-shutdown.js

@@ -0,0 +1,68 @@
+import { SESSION_LIFECYCLE } from '@reticlehq/core';
+import { log } from './log.js';
+/**
+ * Self-terminates an idle daemon so Reticle never lingers eating a user's resources (the daemon process,
+ * any headless Chromium the pool launched, and the bound port) after the editor closes. The `reticle mcp`
+ * proxy spawns the daemon DETACHED so it survives between turns — which means nothing else will ever
+ * stop it; this watcher is that missing stop. Idle = `isIdle()` true continuously for `graceMs` (long
+ * enough to ride out brief agent reconnects between turns). On fire it calls `onShutdown` exactly once.
+ * The interval is `unref`'d, so it never keeps the process alive on its own; `start()` is idempotent.
+ */
+export class IdleShutdown {
+    #timer;
+    #idleSince = null;
+    #fired = false;
+    #isIdle;
+    #onShutdown;
+    #graceMs;
+    #checkMs;
+    #clock;
+    constructor(opts) {
+        this.#isIdle = opts.isIdle;
+        this.#onShutdown = opts.onShutdown;
+        this.#graceMs = opts.graceMs;
+        this.#checkMs = opts.checkIntervalMs ?? SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
+        this.#clock = opts.clock ?? (() => Date.now());
+    }
+    /** Run one idle check. Exposed so a test can drive it deterministically with an injected clock. */
+    check() {
+        if (this.#fired || this.#graceMs <= 0)
+            return; // graceMs <= 0 ⇒ disabled (never self-shut-down)
+        if (!this.#isIdle()) {
+            this.#idleSince = null;
+            return;
+        }
+        const now = this.#clock();
+        this.#idleSince ??= now;
+        if (now - this.#idleSince >= this.#graceMs) {
+            this.#fired = true;
+            log('reticle_daemon_idle_shutdown', { idleMs: now - this.#idleSince });
+            this.#onShutdown();
+        }
+    }
+    start() {
+        if (this.#graceMs <= 0 || this.#timer !== undefined)
+            return; // 0 = disabled
+        this.#timer = setInterval(() => this.check(), this.#checkMs);
+        this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer === undefined)
+            return;
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+}
+/**
+ * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of milliseconds,
+ * `0` to disable. Anything missing/invalid falls back to the default. Pure.
+ */
+export function resolveIdleShutdownMs(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
+    return Math.floor(n);
+}
+//# sourceMappingURL=idle-shutdown.js.map

package/dist/idle-shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle-shutdown.js","sourceRoot":"","sources":["../src/idle-shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAe/B;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACvB,MAAM,CAA6C;IACnD,UAAU,GAAkB,IAAI,CAAC;IACjC,MAAM,GAAG,KAAK,CAAC;IACN,OAAO,CAAgB;IACvB,WAAW,CAAa;IACxB,QAAQ,CAAS;IACjB,QAAQ,CAAS;IACjB,MAAM,CAAe;IAE9B,YAAY,IAAyB;QACnC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,eAAe,IAAI,iBAAiB,CAAC,oBAAoB,CAAC;QAC/E,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,mGAAmG;IACnG,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC;YAAE,OAAO,CAAC,iDAAiD;QAChG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;YACpB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,OAAO;QACT,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC1B,IAAI,CAAC,UAAU,KAAK,GAAG,CAAC;QACxB,IAAI,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,GAAG,CAAC,8BAA8B,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YACvE,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,eAAe;QAC5E,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACtC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAuB;IAC3D,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,iBAAiB,CAAC,uBAAuB,CAAC;IAC7F,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,iBAAiB,CAAC,uBAAuB,CAAC;IACnF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC"}