@reticlehq/server 2.0.0

package/dist/session/session.js

@@ -0,0 +1,408 @@
+import { EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+import { RingBuffer } from '../events/ring-buffer.js';
+import { ReviewStore } from './review-store.js';
+import { buildSessionRecommendation } from './session-recommendation.js';
+import { buildPresenterArgs } from './presenter-args.js';
+const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
+/** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
+const COMMAND_ID_PREFIX = 'c';
+/** ws readyState for an OPEN socket — guard fire-and-forget pushes against a closing tab. */
+const WS_OPEN = 1;
+/**
+ * One connected browser tab. Owns its socket, a ring buffer of observations, and the
+ * in-flight command map. `clock` is injected so elapsed-time logic stays testable.
+ */
+export class Session {
+    id;
+    /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
+    projectId;
+    url;
+    title;
+    adapters;
+    hasCapabilities;
+    #socket;
+    #clock;
+    #startedAt;
+    #buffer = new RingBuffer();
+    #pending = new Map();
+    #listeners = new Set();
+    #seq = 0;
+    #lastSeenAt;
+    #hidden = false;
+    #focused = true;
+    #state = SessionState.ACTIVE;
+    #lastActCursor;
+    /** Liveness: wall-clock of the last AGENT command (distinct from browser chatter / lastSeen). */
+    #lastAgentActivityAt;
+    /** Server-side mirror of the agent-tuned idle window, so the reaper honors reticle_session. */
+    #idleEndMs = SESSION_LIFECYCLE.IDLE_END_MS;
+    /** True when the reaper/disconnect ended this session — such an end is revivable; explicit ends are not. */
+    #autoEnded = false;
+    #inbox = [];
+    /** Human review marks: mistakes the human pinned to elements, for the agent to drain and fix. */
+    #review = new ReviewStore();
+    /** Whether the session_lease has already been returned (fire-once per session). */
+    #firstCommandDone = false;
+    constructor(hello, socket, clock) {
+        this.id = hello.sessionId;
+        this.projectId = hello.projectId;
+        this.url = hello.url;
+        this.title = hello.title;
+        this.adapters = hello.adapters;
+        this.hasCapabilities = hello.hasCapabilities ?? false;
+        this.#socket = socket;
+        this.#clock = clock;
+        this.#startedAt = clock();
+        this.#lastSeenAt = clock();
+        this.#lastAgentActivityAt = clock();
+    }
+    /** Milliseconds since this session connected — the authoritative buffer clock. */
+    elapsed() {
+        return this.#clock() - this.#startedAt;
+    }
+    /** Mark that the SDK was just heard from. Called on every inbound message. */
+    touch() {
+        this.#lastSeenAt = this.#clock();
+    }
+    /** ms since the SDK last reported anything (distinct from elapsed-since-connect). */
+    lastSeenMs() {
+        return this.#clock() - this.#lastSeenAt;
+    }
+    /** Record the latest page visibility/focus state from a PAGE_HEALTH event. */
+    applyHealth(hidden, focused) {
+        this.#hidden = hidden;
+        this.#focused = focused;
+    }
+    /** Throttled if the tab is hidden OR we have not heard from it recently. */
+    throttled() {
+        return this.#hidden || this.lastSeenMs() > SESSION_HEALTH.STALE_THRESHOLD_MS;
+    }
+    /** The attachable health block — single source of truth for the tools. */
+    health() {
+        const base = {
+            lastSeenMs: this.lastSeenMs(),
+            throttled: this.throttled(),
+            focused: this.#focused,
+        };
+        // attach the escape-hatch hint only when un-scriptable (keeps field absent otherwise).
+        const recommendation = buildSessionRecommendation({
+            hidden: this.#hidden,
+            throttled: base.throttled,
+            focused: base.focused,
+        });
+        return recommendation === undefined ? base : { ...base, recommendation };
+    }
+    info() {
+        const base = {
+            sessionId: this.id,
+            url: this.url,
+            ...(this.projectId === undefined ? {} : { projectId: this.projectId }),
+            title: this.title,
+            adapters: this.adapters,
+            hasCapabilities: this.hasCapabilities,
+            hidden: this.#hidden,
+            ...this.health(),
+        };
+        if (this.staleMs() > SESSION_LEASE.STALE_AFTER_MS) {
+            base.stale = true;
+            base.cleanup_suggestion =
+                'Call reticle_end_session to free this session before starting new work.';
+        }
+        // Surface human bug reports in reticle_sessions (only when > 0, so a clean session adds nothing).
+        const marks = this.#review.pendingCount();
+        if (marks > 0) {
+            base.pendingMarks = marks;
+            const s = marks === 1 ? '' : 's';
+            base.review_suggestion = `The human flagged ${String(marks)} issue${s} on this tab — call reticle_review to see and fix ${marks === 1 ? 'it' : 'them'}.`;
+        }
+        return base;
+    }
+    /** Wall-clock age of the session in milliseconds. */
+    staleMs() {
+        return this.#clock() - this.#startedAt;
+    }
+    /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
+    pushEvent(event) {
+        if (event.type === EventType.PAGE_HEALTH) {
+            const data = event.data;
+            const hidden = typeof data['hidden'] === 'boolean' ? data['hidden'] : this.#hidden;
+            const focused = typeof data['focused'] === 'boolean' ? data['focused'] : this.#focused;
+            this.applyHealth(hidden, focused);
+        }
+        if (event.type === EventType.HUMAN_CONTROL) {
+            // Narrow unknown at the boundary; an invalid/unknown control is ignored (never thrown).
+            const parsed = HumanControlDataSchema.safeParse(event.data);
+            if (parsed.success)
+                this.applyHumanControl(parsed.data);
+        }
+        if (event.type === EventType.HUMAN_MARK) {
+            // A human pinned a mistake to an element. Narrow at the boundary; an invalid mark is ignored.
+            const parsed = HumanMarkDataSchema.safeParse(event.data);
+            if (parsed.success)
+                this.#review.add(parsed.data, this.elapsed());
+        }
+        if (event.type === EventType.ROUTE_CHANGE) {
+            // Keep the reported URL live across SPA navigation. The SDK already emits route.change on
+            // pushState/replaceState/popstate; without this the URL stays frozen at the hello value, and
+            // URL-based CDP correlation (real input) silently breaks after the first client-side nav.
+            const to = event.data['to'];
+            if (typeof to === 'string' && to.length > 0)
+                this.url = to;
+        }
+        const t = this.elapsed();
+        const stamped = { ...event, t, sessionId: this.id };
+        this.#buffer.push(stamped, t);
+        for (const listener of this.#listeners)
+            listener(stamped);
+    }
+    eventsSince(cursor) {
+        return this.#buffer.since(cursor);
+    }
+    /**
+     * Honesty: remember the event cursor of the most recent act so wait_for/assert can default their
+     * evaluation floor to it — a signal buffered before this act can never fake a later pass.
+     */
+    markActCursor(cursor) {
+        this.#lastActCursor = cursor;
+    }
+    /** The cursor of the last act, or undefined if nothing has acted yet. */
+    lastActCursor() {
+        return this.#lastActCursor;
+    }
+    // ── Server-authoritative liveness (immune to browser-tab throttling) ──────────────
+    /**
+     * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
+     * If the reaper had auto-ended the session, a fresh command means the agent is alive again, so the
+     * session is REVIVED to ACTIVE. An EXPLICIT end (human/agent reticle_end_session) is terminal and is
+     * never revived here.
+     */
+    markAgentActivity() {
+        this.#lastAgentActivityAt = this.#clock();
+        if (this.#state === SessionState.ENDED && this.#autoEnded) {
+            this.#autoEnded = false;
+            this.setState(SessionState.ACTIVE);
+        }
+    }
+    /** ms since the agent last issued a command against this session (the reaper's idle signal). */
+    agentIdleMs() {
+        return this.#clock() - this.#lastAgentActivityAt;
+    }
+    /** The agent-idle window after which the reaper ends this session. */
+    idleEndMs() {
+        return this.#idleEndMs;
+    }
+    /** Tune the idle window (reticle_session). Floored so an agent can't disable the safety net. */
+    setIdleEndMs(ms) {
+        this.#idleEndMs = Math.max(SESSION_LIFECYCLE.IDLE_END_MIN_MS, Math.floor(ms));
+    }
+    /**
+     * Reaper/disconnect end: terminal like a normal end (pushes PRESENTER ended to the browser, which a
+     * throttled tab still receives) but flagged auto-ended so a returning agent revives it. No-op if
+     * already ended.
+     */
+    autoEnd(text, tone = PresenterTone.WARN) {
+        if (this.#state === SessionState.ENDED)
+            return;
+        this.#autoEnded = true;
+        this.setState(SessionState.ENDED, text, tone);
+    }
+    eventsInWindow(windowMs) {
+        return this.#buffer.window(windowMs, this.elapsed());
+    }
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    /** Send a command to the browser and await its reply (or time out). */
+    command(name, args = {}, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
+        this.#seq += 1;
+        const id = `${COMMAND_ID_PREFIX}${String(this.#seq)}`;
+        const payload = JSON.stringify({
+            kind: MessageKind.COMMAND,
+            id,
+            sessionId: this.id,
+            name,
+            args,
+        });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error(`command '${name}' timed out after ${String(timeoutMs)}ms`));
+            }, timeoutMs);
+            this.#pending.set(id, { resolve, reject, timer });
+            this.#socket.send(payload);
+        });
+    }
+    handleResult(result) {
+        const pending = this.#pending.get(result.id);
+        if (pending === undefined)
+            return;
+        clearTimeout(pending.timer);
+        this.#pending.delete(result.id);
+        pending.resolve(result);
+    }
+    /** Reject everything still in flight — used on disconnect. */
+    rejectAll(reason) {
+        for (const [id, pending] of this.#pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(reason));
+            this.#pending.delete(id);
+        }
+    }
+    /** End this transport without letting a stale socket remove its replacement session. */
+    disconnect(reason) {
+        this.rejectAll(reason);
+        try {
+            this.#socket.close(1008, reason);
+        }
+        catch {
+            // A fake or already-closed socket needs no further cleanup.
+        }
+    }
+    // ── Live-control: state machine + human→agent inbox (server-owned) ───────────────
+    getState() {
+        return this.#state;
+    }
+    isPaused() {
+        return this.#state === SessionState.PAUSED;
+    }
+    isEnded() {
+        return this.#state === SessionState.ENDED;
+    }
+    /**
+     * Set the lifecycle state and echo it to the panel in ONE PRESENTER push. The SOLE pusher of
+     * PRESENTER for a transition. Optional `text` rides the same push (e.g. an end-of-session
+     * summary) so a transition never emits two PRESENTER commands.
+     */
+    setState(next, text, tone) {
+        this.#state = next;
+        this.pushPresenter(this.#state, text, tone);
+    }
+    /** Push a human note onto the inbox; empty/whitespace-only text is ignored. Stamped with elapsed t. */
+    pushMessage(text) {
+        const trimmed = text.trim();
+        if (trimmed.length === 0)
+            return;
+        this.#inbox.push({ text: trimmed, t: this.elapsed() });
+    }
+    /** Return the queued human notes AND clear the inbox (delivered-once). */
+    drainInbox() {
+        return this.#inbox.splice(0, this.#inbox.length);
+    }
+    /** Diagnostic read of the inbox depth (does not clear). */
+    inboxSize() {
+        return this.#inbox.length;
+    }
+    // ── Human review marks: the "annotate the bug where you see it" inbox (server-owned) ──────────
+    /** Human marks still awaiting a fix (oldest first). Reading does not consume — resolveMark() does. */
+    pendingMarks() {
+        return this.#review.pending();
+    }
+    /** Full mark history (pending + resolved), oldest first. */
+    allMarks() {
+        return this.#review.all();
+    }
+    /** Count of pending marks — surfaced as the panel badge / a session-health hint. */
+    pendingMarkCount() {
+        return this.#review.pendingCount();
+    }
+    /** Retire a mark the agent fixed. True on a real pending → resolved transition; false otherwise. */
+    resolveMark(id) {
+        return this.#review.resolve(id);
+    }
+    /**
+     * Apply a narrowed human control. `setState` is called only on a GENUINE change, so each real
+     * transition pushes exactly one PRESENTER command; no-ops (e.g. resume on active, pause after
+     * end) push nothing. `ended` is terminal — pause/resume after end are no-ops.
+     */
+    applyHumanControl(data) {
+        if (this.#state === SessionState.ENDED) {
+            // Terminal: end is idempotent; pause/resume are no-ops.
+            return;
+        }
+        switch (data.kind) {
+            case HumanControlKind.PAUSE:
+                if (this.#state !== SessionState.PAUSED)
+                    this.setState(SessionState.PAUSED);
+                return;
+            case HumanControlKind.RESUME:
+                if (this.#state !== SessionState.ACTIVE)
+                    this.setState(SessionState.ACTIVE);
+                return;
+            case HumanControlKind.END:
+                this.setState(SessionState.ENDED);
+                return;
+            case HumanControlKind.MESSAGE:
+                if (data.text !== undefined)
+                    this.pushMessage(data.text);
+                return;
+            default:
+                return;
+        }
+    }
+    /**
+     * Push a lifecycle state to the panel with optional human-facing `text`. State changes still flow
+     * through `setState`; an auto-ended session rides a `warn` tone so the panel can shout "agent stopped".
+     */
+    pushPresenter(state, text, tone) {
+        this.#post(ReticleCommand.PRESENTER, buildPresenterArgs(state, text, tone));
+    }
+    /** Fire-and-forget a narration row to the live panel (so a resolved mark shows "✓ fixed"). */
+    pushNarration(text) {
+        this.#post(ReticleCommand.NARRATE, { text, level: 'info' });
+    }
+    /**
+     * Returns the one-time session lease block on the very first agent command, then undefined
+     * forever after. The lease carries an IMPORTANT reminder to call reticle_end_session. Coding agents
+     * (Claude Code, Codex) read tool results — they will see this and remember to clean up.
+     */
+    takeSessionLease() {
+        if (this.#firstCommandDone)
+            return undefined;
+        this.#firstCommandDone = true;
+        return {
+            sessionId: this.id,
+            opened_at: this.#startedAt,
+            IMPORTANT: 'MANDATORY: the moment you stop driving — finishing a reply or waiting on the human — call reticle_yield (mode:"waiting", or "ask" with your question) so the panel never falsely reads "live". Call reticle_end_session only when the whole task is done. The session revives on your next action.',
+        };
+    }
+    /**
+     * Returns a human-readable age warning after SESSION_LEASE.WARN_AFTER_MS (10 min), else undefined.
+     * Spliced onto every session-bound tool result so the agent is passively reminded to clean up
+     * without needing an explicit polling loop.
+     */
+    ageWarning() {
+        const ageMs = this.#clock() - this.#startedAt;
+        if (ageMs < SESSION_LEASE.WARN_AFTER_MS)
+            return undefined;
+        const minutes = Math.floor(ageMs / 60_000);
+        return `Session ${this.id} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_end_session now.`;
+    }
+    /** Fire-and-forget command send — NOT registered in #pending (no correlated result expected). */
+    #post(name, args) {
+        if (this.#socket.readyState !== WS_OPEN)
+            return;
+        this.#seq += 1;
+        const id = `${COMMAND_ID_PREFIX}${String(this.#seq)}`;
+        const payload = JSON.stringify({
+            kind: MessageKind.COMMAND,
+            id,
+            sessionId: this.id,
+            name,
+            args,
+        });
+        try {
+            this.#socket.send(payload);
+        }
+        catch {
+            // A closing/closed tab must never break event routing for the session.
+        }
+    }
+}
+/**
+ * Re-exported from session-manager.ts so the public import path (`./session.js`) is unchanged for
+ * the many call sites that resolve a target session. The class lives in its own file to keep both
+ * units under the file-size cap.
+ */
+export { SessionManager } from './session-manager.js';
+//# sourceMappingURL=session.js.map

package/dist/session/session.js.map

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

package/dist/session/state-select.d.ts

@@ -0,0 +1,8 @@
+/**
+ * reticle_state path selection + depth capping. The pure implementation now lives in
+ * `@reticlehq/core` so the BROWSER SDK can apply it BEFORE the transport (scoping a huge store
+ * without paying the truncation tax); the server re-exports it for its back-compat fallback path
+ * (an older browser that returns the whole store) and for the predicate engine's `state` assertion.
+ */
+export { selectPath, capDepth, type PathSelection } from '@reticlehq/core';
+//# sourceMappingURL=state-select.d.ts.map

package/dist/session/state-select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-select.d.ts","sourceRoot":"","sources":["../../src/session/state-select.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/session/state-select.js

@@ -0,0 +1,8 @@
+/**
+ * reticle_state path selection + depth capping. The pure implementation now lives in
+ * `@reticlehq/core` so the BROWSER SDK can apply it BEFORE the transport (scoping a huge store
+ * without paying the truncation tax); the server re-exports it for its back-compat fallback path
+ * (an older browser that returns the whole store) and for the predicate engine's `state` assertion.
+ */
+export { selectPath, capDepth } from '@reticlehq/core';
+//# sourceMappingURL=state-select.js.map

package/dist/session/state-select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-select.js","sourceRoot":"","sources":["../../src/session/state-select.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAsB,MAAM,iBAAiB,CAAC"}

package/dist/token-auth.d.ts

@@ -0,0 +1,24 @@
+import type { IncomingMessage } from 'node:http';
+/**
+ * Timing-safe pairing-token comparison. Length-guards first because `timingSafeEqual` throws on a
+ * length mismatch — and the guard itself is not a timing oracle (length is not the secret).
+ */
+export declare function tokensMatch(expected: string, received: string | undefined): boolean;
+/** Pull a request's pairing token from `Authorization: Bearer <t>` first, then a `?token=` query param. */
+export declare function requestToken(req: IncomingMessage, url: URL): string | undefined;
+/** True when the request peer is a loopback address — the local-trust tier that needs no token. */
+export declare function isLoopbackPeer(remoteAddress: string | undefined): boolean;
+/**
+ * True when the `Host` header names a loopback host. This is the anti-DNS-rebinding guard: a rebound
+ * page reaches us as a loopback *peer* but its browser still sends the attacker's original `Host`
+ * (`evil.com`), so a non-loopback Host means "not actually a local client" even when the socket is.
+ * Missing Host is untrusted — every real HTTP/1.1 client (incl. `reticle status`, the stdio proxy) sends it.
+ */
+export declare function isLoopbackHost(hostHeader: string | undefined): boolean;
+/**
+ * True when neither `Origin` nor `Referer` betrays a non-loopback web origin. Absent headers pass —
+ * non-browser local clients (the stdio MCP proxy, `reticle status`) send neither. Any present-but-
+ * non-loopback value fails, which is what kills a rebound `http://evil.com` page reading the plane.
+ */
+export declare function isLocalWebOrigin(origin: string | undefined, referer: string | undefined): boolean;
+//# sourceMappingURL=token-auth.d.ts.map

package/dist/token-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-auth.d.ts","sourceRoot":"","sources":["../src/token-auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AASjD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOnF;AAED,2GAA2G;AAC3G,wBAAgB,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAO/E;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGzE;AAYD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAItE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOjG"}

package/dist/token-auth.js

@@ -0,0 +1,71 @@
+import { timingSafeEqual } from 'node:crypto';
+import { isLoopbackHostname } from '@reticlehq/core';
+/** `Authorization: Bearer <token>` prefix and the query-param fallback for clients that can't set headers. */
+const BEARER_PREFIX = 'Bearer ';
+const TOKEN_QUERY_PARAM = 'token';
+/** Node reports IPv4 loopback over a dual-stack socket as this mapped form; strip it before classifying. */
+const IPV4_MAPPED_PREFIX = /^::ffff:/i;
+/**
+ * Timing-safe pairing-token comparison. Length-guards first because `timingSafeEqual` throws on a
+ * length mismatch — and the guard itself is not a timing oracle (length is not the secret).
+ */
+export function tokensMatch(expected, received) {
+    if (received === undefined)
+        return false;
+    const expectedBytes = Buffer.from(expected);
+    const receivedBytes = Buffer.from(received);
+    return (expectedBytes.length === receivedBytes.length && timingSafeEqual(expectedBytes, receivedBytes));
+}
+/** Pull a request's pairing token from `Authorization: Bearer <t>` first, then a `?token=` query param. */
+export function requestToken(req, url) {
+    const header = req.headers.authorization;
+    if (header !== undefined && header.startsWith(BEARER_PREFIX)) {
+        return header.slice(BEARER_PREFIX.length);
+    }
+    const queryToken = url.searchParams.get(TOKEN_QUERY_PARAM);
+    return queryToken !== null ? queryToken : undefined;
+}
+/** True when the request peer is a loopback address — the local-trust tier that needs no token. */
+export function isLoopbackPeer(remoteAddress) {
+    if (remoteAddress === undefined)
+        return false;
+    return isLoopbackHostname(remoteAddress.replace(IPV4_MAPPED_PREFIX, ''));
+}
+/** Extract the hostname from a `Host` value (`127.0.0.1:9000`) or a full origin/referer URL. */
+function hostnameOf(value) {
+    const direct = value.includes('://') ? value : `http://${value}`;
+    try {
+        return new URL(direct).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when the `Host` header names a loopback host. This is the anti-DNS-rebinding guard: a rebound
+ * page reaches us as a loopback *peer* but its browser still sends the attacker's original `Host`
+ * (`evil.com`), so a non-loopback Host means "not actually a local client" even when the socket is.
+ * Missing Host is untrusted — every real HTTP/1.1 client (incl. `reticle status`, the stdio proxy) sends it.
+ */
+export function isLoopbackHost(hostHeader) {
+    if (hostHeader === undefined)
+        return false;
+    const hostname = hostnameOf(hostHeader);
+    return hostname !== undefined && isLoopbackHostname(hostname);
+}
+/**
+ * True when neither `Origin` nor `Referer` betrays a non-loopback web origin. Absent headers pass —
+ * non-browser local clients (the stdio MCP proxy, `reticle status`) send neither. Any present-but-
+ * non-loopback value fails, which is what kills a rebound `http://evil.com` page reading the plane.
+ */
+export function isLocalWebOrigin(origin, referer) {
+    for (const value of [origin, referer]) {
+        if (value === undefined)
+            continue;
+        const hostname = hostnameOf(value);
+        if (hostname === undefined || !isLoopbackHostname(hostname))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=token-auth.js.map

package/dist/token-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-auth.js","sourceRoot":"","sources":["../src/token-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,8GAA8G;AAC9G,MAAM,aAAa,GAAG,SAAS,CAAC;AAChC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAClC,4GAA4G;AAC5G,MAAM,kBAAkB,GAAG,WAAW,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,QAA4B;IACxE,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACzC,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,CACL,aAAa,CAAC,MAAM,KAAK,aAAa,CAAC,MAAM,IAAI,eAAe,CAAC,aAAa,EAAE,aAAa,CAAC,CAC/F,CAAC;AACJ,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,YAAY,CAAC,GAAoB,EAAE,GAAQ;IACzD,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC7D,OAAO,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3D,OAAO,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,cAAc,CAAC,aAAiC;IAC9D,IAAI,aAAa,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,kBAAkB,CAAC,aAAa,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,gGAAgG;AAChG,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,KAAK,EAAE,CAAC;IACjE,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,UAA8B;IAC3D,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC3C,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,QAAQ,KAAK,SAAS,IAAI,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA0B,EAAE,OAA2B;IACtF,KAAK,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QACtC,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;IAC5E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tools/act-tools.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDef } from './tool-kit.js';
+export declare const ACT_TOOLS: ToolDef[];
+//# sourceMappingURL=act-tools.d.ts.map

package/dist/tools/act-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act-tools.d.ts","sourceRoot":"","sources":["../../src/tools/act-tools.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,KAAK,OAAO,EAAiD,MAAM,eAAe,CAAC;AAgI5F,eAAO,MAAM,SAAS,EAAE,OAAO,EA0O9B,CAAC"}