@reticlehq/server 2.3.0 → 2.5.0

package/dist/session/session-reconnect.js

@@ -0,0 +1,42 @@
+/**
+ * Block until a reloaded page has re-announced itself under the same session id.
+ *
+ * A reload tears the SDK down. The id survives (see session-continuity), and the daemon replaces the
+ * old Session with a new one when the page says HELLO again — so "is it back?" is exactly "does a
+ * DIFFERENT object hold this id now?". Identity, not a flag: the returning page always constructs a
+ * new Session, and nothing else can claim an id it already owns.
+ *
+ * Polls a live getter rather than subscribing, because there is no reconnect event to subscribe to
+ * and inventing one for this would be a wire change for a two-second wait.
+ */
+/**
+ * How often to look for the reconnected session.
+ *
+ * 25ms, not 100. What is being polled is an in-memory map lookup — no I/O, no browser round-trip —
+ * while the thing being waited for is an EVENT (the reloaded page's HELLO). At 100ms the agent paid
+ * up to a full interval of dead time after the page was already back, on every navigate-with-reload.
+ * Measured across the fixture fleet, `reticle_navigate` clustered at 105 / 202-206 / 308 / 407ms —
+ * the poll grid, visible in the data. Four times the checks of something this cheap costs nothing
+ * anyone can measure.
+ */
+const DEFAULT_POLL_MS = 25;
+/**
+ * How long a reload is worth waiting for before answering "not confirmed".
+ *
+ * A production build is back in well under a second; a cold dev-server route rebuild is the slow
+ * case this budget is sized for. It is a CEILING, not a delay — the common path returns on the first
+ * or second poll.
+ */
+export const RELOAD_RECONNECT_TIMEOUT_MS = 5000;
+export async function waitForReconnect(opts) {
+    const poll = opts.pollMs ?? DEFAULT_POLL_MS;
+    const start = opts.now();
+    for (;;) {
+        const live = opts.current();
+        if (live !== undefined && live !== opts.previous)
+            return true;
+        if (opts.now() - start >= opts.timeoutMs)
+            return false;
+        await opts.sleep(poll);
+    }
+}

package/dist/session/session.d.ts

@@ -3,7 +3,7 @@ import { LastAct } from './last-act.js';
 import { type PageRuntime } from './command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type CommandResult, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
 import type { JournalReader, JournalRecorder } from '../journal/journal-recorder.js';
 import { type EventQueryOptions } from '../journal/journal-query.js';
 import { type AmbientCounts } from '../journal/ambient.js';
@@ -27,6 +27,14 @@ export declare class Session {
     title: string;
     adapters: string[];
     hasCapabilities: boolean;
+    /** Set when the page's SDK version differs from the daemon's (see version-skew.ts). */
+    versionSkew?: string;
+    /**
+     * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
+     * DRIVEN path can redact them too — a request body the daemon captures from the network stack
+     * never passes through the SDK, so nothing else would.
+     */
+    readonly redactKeys: readonly string[];
     constructor(hello: HelloMessage, socket: WebSocket, clock: Clock);
     /** Milliseconds since this session connected — the authoritative buffer clock. */
     elapsed(): number;
@@ -40,10 +48,12 @@ export declare class Session {
      * `runtime` is optional so an older SDK (which does not report it) still works — it simply loses
      * the desktop-specific timeout diagnosis rather than breaking.
      */
-    applyHealth(hidden: boolean, focused: boolean, runtime?: string, engine?: string): void;
+    applyHealth(hidden: boolean, focused: boolean, runtime?: string, engine?: string, brand?: BrowserBrand): void;
     /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
     get runtime(): PageRuntime | undefined;
     get engine(): string | undefined;
+    /** The browser brand the SDK reported. Absent (never guessed) when the page did not say. */
+    get brand(): BrowserBrand | undefined;
     /** Throttled if the tab is hidden OR we have not heard from it recently. */
     throttled(): boolean;
     /** The attachable health block — single source of truth for the tools. */
@@ -54,6 +64,14 @@ export declare class Session {
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
+    actedLabels(): ReadonlySet<string>;
+    /**
+     * Derive the snapshot-shaped label (`button "Deploy"`) from an act reply and remember it.
+     *
+     * Same shape the interactive snapshot emits, so coverage can match a control the agent drove
+     * against the same control after a re-render gave it a different ref.
+     */
+    private recordActedLabelFrom;
     actedRefs(): ReadonlySet<string>;
     noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;

package/dist/session/session.js

@@ -2,7 +2,8 @@ import { LastAct } from './last-act.js';
 import { commandTimeoutMessage } from './command-timeout.js';
 import { readHealthEvent } from './session-health.js';
 import { PendingCommands } from './pending-commands.js';
-import { EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+import { span } from '../trace.js';
+import { AppRuntime, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '../events/ring-buffer.js';
 import { filterEvents, mergeEventsBySeq, } from '../journal/journal-query.js';
 import {} from '../journal/ambient.js';
@@ -13,6 +14,7 @@ import { ReviewStore } from './review-store.js';
 import { buildSessionRecommendation } from './session-recommendation.js';
 import { buildPresenterArgs } from './presenter-args.js';
 import { buildSessionLease } from './session-lease.js';
+import { buildSessionInfo } from './session-info.js';
 const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
 /** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
 const COMMAND_ID_PREFIX = 'c';
@@ -32,6 +34,14 @@ export class Session {
     title;
     adapters;
     hasCapabilities;
+    /** Set when the page's SDK version differs from the daemon's (see version-skew.ts). */
+    versionSkew;
+    /**
+     * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
+     * DRIVEN path can redact them too — a request body the daemon captures from the network stack
+     * never passes through the SDK, so nothing else would.
+     */
+    redactKeys;
     #socket;
     #clock;
     #startedAt;
@@ -44,6 +54,8 @@ export class Session {
     /** Which shell the page reported (PAGE_HEALTH). Undefined until the first report lands. */
     #runtime;
     #engine;
+    /** Which browser the page said it is (chrome/edge/arc/…). Undefined on an SDK too old to report one. */
+    #brand;
     #focused = true;
     /** Liveness: wall-clock of the last AGENT command (distinct from browser chatter / lastSeen). */
     #lastAgentActivityAt;
@@ -70,6 +82,7 @@ export class Session {
         this.title = hello.title;
         this.adapters = hello.adapters;
         this.hasCapabilities = hello.hasCapabilities ?? false;
+        this.redactKeys = hello.redactKeys ?? [];
         this.#socket = socket;
         this.#clock = clock;
         this.#startedAt = clock();
@@ -94,14 +107,18 @@ export class Session {
      * `runtime` is optional so an older SDK (which does not report it) still works — it simply loses
      * the desktop-specific timeout diagnosis rather than breaking.
      */
-    applyHealth(hidden, focused, runtime, engine) {
+    applyHealth(hidden, focused, runtime, engine, brand) {
         this.#hidden = hidden;
         this.#focused = focused;
-        if (runtime === 'electron' || runtime === 'tauri' || runtime === 'web') {
+        if (AppRuntime.ELECTRON === runtime ||
+            AppRuntime.TAURI === runtime ||
+            AppRuntime.WEB === runtime) {
             this.#runtime = runtime;
         }
         if (engine !== undefined)
             this.#engine = engine;
+        if (brand !== undefined)
+            this.#brand = brand;
     }
     /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
     get runtime() {
@@ -110,6 +127,10 @@ export class Session {
     get engine() {
         return this.#engine;
     }
+    /** The browser brand the SDK reported. Absent (never guessed) when the page did not say. */
+    get brand() {
+        return this.#brand;
+    }
     /** 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;
@@ -130,29 +151,19 @@ export class Session {
         return recommendation === undefined ? base : { ...base, recommendation };
     }
     info() {
-        const base = {
-            sessionId: this.id,
+        return buildSessionInfo({
+            id: this.id,
             url: this.url,
-            ...(this.projectId === undefined ? {} : { projectId: this.projectId }),
+            projectId: this.projectId,
             title: this.title,
             adapters: this.adapters,
             hasCapabilities: this.hasCapabilities,
+            versionSkew: this.versionSkew,
             hidden: this.#hidden,
-            ...this.health(),
-        };
-        if (this.staleMs() > SESSION_LEASE.STALE_AFTER_MS) {
-            base.stale = true;
-            base.cleanup_suggestion =
-                'Call reticle_session{action:"end"} 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_session{action:"review"} to see and fix ${marks === 1 ? 'it' : 'them'}.`;
-        }
-        return base;
+            health: () => this.health(),
+            staleMs: () => this.staleMs(),
+            pendingMarkCount: () => this.#review.pendingCount(),
+        });
     }
     /** Wall-clock age of the session in milliseconds. */
     staleMs() {
@@ -162,7 +173,7 @@ export class Session {
     pushEvent(event, byteSize) {
         if (event.type === EventType.PAGE_HEALTH) {
             const r = readHealthEvent(event.data);
-            this.applyHealth(r.hidden ?? this.#hidden, r.focused ?? this.#focused, r.runtime, r.engine);
+            this.applyHealth(r.hidden ?? this.#hidden, r.focused ?? this.#focused, r.runtime, r.engine, r.brand);
         }
         // The in-page half of Reticle reporting its own failure — recorded like a tool error
         // (fingerprinted, variables stripped) so a broken observer is as visible as a broken tool.
@@ -188,7 +199,7 @@ export class Session {
             // 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)
+            if ('string' === typeof to && to.length > 0)
                 this.url = to;
         }
         const t = this.elapsed();
@@ -211,6 +222,35 @@ export class Session {
     recordActedRef(ref) {
         this.#observed.recordActedRef(ref);
     }
+    actedLabels() {
+        return this.#observed.actedLabels();
+    }
+    /**
+     * Derive the snapshot-shaped label (`button "Deploy"`) from an act reply and remember it.
+     *
+     * Same shape the interactive snapshot emits, so coverage can match a control the agent drove
+     * against the same control after a re-render gave it a different ref.
+     */
+    recordActedLabelFrom(result) {
+        const payload = result.result;
+        if (typeof payload !== 'object' || null === payload)
+            return;
+        const record = payload;
+        // The TESTID first: it is the strongest identity a control has and it survives any re-render.
+        // Coverage previously matched only on `role "name"`, so a control with a testid but no accessible
+        // name — or on a stack where the act reply carried neither — was unrecognisable after a
+        // re-render, and coverage read `exercised: 0` however much work had been done.
+        const testid = record['testid'];
+        if ('string' === typeof testid && testid.length > 0)
+            this.#observed.recordActedLabel(testid);
+        const role = record['role'];
+        const name = record['name'];
+        if (typeof role !== 'string' || typeof name !== 'string')
+            return;
+        if (0 === role.length || 0 === name.length)
+            return;
+        this.#observed.recordActedLabel(`${role} "${name}"`);
+    }
     actedRefs() {
         return this.#observed.actedRefs();
     }
@@ -341,7 +381,7 @@ export class Session {
         // still wrong, and it made the number depend on which tool the agent happened to use.
         if (name === ReticleCommand.ACT) {
             const ref = args['ref'];
-            if (typeof ref === 'string')
+            if ('string' === typeof ref)
                 this.recordActedRef(ref);
         }
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);
@@ -362,7 +402,17 @@ export class Session {
         }));
         this.#socket.send(payload);
         const sentAt = Date.now(); // browser-leg timing; see recordBrowserLatency for why it is split out
-        return awaited.finally(() => recordBrowserLatency(Date.now() - sentAt));
+        // Traced because this is the boundary that decides whether a slow tool call is OUR overhead or
+        // the app taking its time — the split telemetry reports in aggregate, made visible per call.
+        return span('browser.command', { command: name, sessionId: this.id }, () => awaited)
+            .then((result) => {
+            // The label is only knowable from the REPLY — the request carries a ref, and a ref dies with
+            // the next re-render. Recorded here so coverage survives frameworks that replace nodes.
+            if (name === ReticleCommand.ACT)
+                this.recordActedLabelFrom(result);
+            return result;
+        })
+            .finally(() => recordBrowserLatency(Date.now() - sentAt));
     }
     handleResult(result) {
         this.#pending.settle(result);
@@ -483,7 +533,7 @@ export class Session {
         // still wrong, and it made the number depend on which tool the agent happened to use.
         if (name === ReticleCommand.ACT) {
             const ref = args['ref'];
-            if (typeof ref === 'string')
+            if ('string' === typeof ref)
                 this.recordActedRef(ref);
         }
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);

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

@@ -4,4 +4,4 @@
  * 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';
+export { selectPath, capDepth, projectComponentState, type PathSelection } from '@reticlehq/core';

package/dist/session/state-select.js

@@ -4,4 +4,4 @@
  * 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';
+export { selectPath, capDepth, projectComponentState } from '@reticlehq/core';

package/dist/status-payload.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What `GET /status` answers — the daemon describing itself.
+ *
+ * Carries the daemon's OWN version, because a daemon outlives every agent attached to it: after an
+ * upgrade the new CLI attaches to the old daemon and serves its code, and until this field existed
+ * there was no surface anywhere — not /status, not `reticle status` — naming the version actually
+ * answering requests. See describeDaemonSkew.
+ */
+import type { SessionInfo } from './session/session-info.js';
+interface StatusPayload {
+    running: true;
+    version: string;
+    /** The wire contract this daemon speaks — what another process compares against, not the version. */
+    contract: string;
+    sessionCount: number;
+    sessions: SessionInfo[];
+}
+export declare function statusPayload(sessionCount: number, sessions: SessionInfo[]): StatusPayload;
+export {};

package/dist/status-payload.js

@@ -0,0 +1,11 @@
+import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
+import { SERVER_VERSION } from './version/server-version.js';
+export function statusPayload(sessionCount, sessions) {
+    return {
+        running: true,
+        version: SERVER_VERSION,
+        contract: CONTRACT_FINGERPRINT,
+        sessionCount,
+        sessions,
+    };
+}

package/dist/telemetry/argument-shape.js

@@ -57,10 +57,19 @@ export function describeParam(name, value) {
         return name;
     return `${name}:${allowed.has(value) ? value : OTHER_VALUE}`;
 }
+/**
+ * Parameters that carry no information about how the tool is USED, and so are not counted.
+ *
+ * `sessionId` is accepted by nearly every tool and passed on nearly every call, so counting it
+ * produced a row per tool saying only "the agent addressed a session" — in one real day's export it
+ * was a third of the toolParams block. This histogram exists to answer "is anyone using the argument
+ * we shipped last release", and a parameter every call carries can never answer it.
+ */
+const UNINFORMATIVE_PARAMS = new Set(['sessionId']);
 /** Every parameter an agent actually passed to one tool call, reduced to names (+ safe enums). */
 export function describeToolParams(args) {
     return Object.keys(args)
-        .filter((key) => args[key] !== undefined)
+        .filter((key) => args[key] !== undefined && !UNINFORMATIVE_PARAMS.has(key))
         .map((key) => describeParam(key, args[key]))
         .sort();
 }

package/dist/telemetry/browser-mode.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Was this verification watched by a person, or run by a machine?
+ *
+ * A verification's cost and its meaning both depend on it. A headless run is CI or an unattended
+ * agent loop — it should be fast, and there is nobody to notice a wrong answer. A headed run has a
+ * human in front of it. And the most common case of all is neither: the SDK in somebody's own dev
+ * server, in their own browser, which Reticle never launched at all.
+ *
+ * Recorded once at daemon start, because that is when the decision is made and it does not change
+ * for the daemon's life. Defaults to ATTACHED, which is the honest answer when Reticle launched
+ * nothing: claiming "headless" for a browser we did not open would be a guess about somebody's
+ * machine.
+ */
+export declare const BrowserMode: {
+    /** Reticle launched the browser with no display — CI, or an unattended agent loop. */
+    readonly HEADLESS: "headless";
+    /** Reticle launched a visible browser — a human is watching. */
+    readonly HEADED: "headed";
+    /** Reticle launched nothing: the SDK connected from a browser somebody else opened. */
+    readonly ATTACHED: "attached";
+};
+export type BrowserMode = (typeof BrowserMode)[keyof typeof BrowserMode];
+/** Record how this daemon drives a browser. Called once, at start. */
+export declare function setBrowserMode(mode: BrowserMode): void;
+export declare function getBrowserMode(): BrowserMode;
+/** Tests only — restore the default so cases do not leak into each other. */
+export declare function resetBrowserMode(): void;

package/dist/telemetry/browser-mode.js

@@ -0,0 +1,33 @@
+/**
+ * Was this verification watched by a person, or run by a machine?
+ *
+ * A verification's cost and its meaning both depend on it. A headless run is CI or an unattended
+ * agent loop — it should be fast, and there is nobody to notice a wrong answer. A headed run has a
+ * human in front of it. And the most common case of all is neither: the SDK in somebody's own dev
+ * server, in their own browser, which Reticle never launched at all.
+ *
+ * Recorded once at daemon start, because that is when the decision is made and it does not change
+ * for the daemon's life. Defaults to ATTACHED, which is the honest answer when Reticle launched
+ * nothing: claiming "headless" for a browser we did not open would be a guess about somebody's
+ * machine.
+ */
+export const BrowserMode = {
+    /** Reticle launched the browser with no display — CI, or an unattended agent loop. */
+    HEADLESS: 'headless',
+    /** Reticle launched a visible browser — a human is watching. */
+    HEADED: 'headed',
+    /** Reticle launched nothing: the SDK connected from a browser somebody else opened. */
+    ATTACHED: 'attached',
+};
+let current = BrowserMode.ATTACHED;
+/** Record how this daemon drives a browser. Called once, at start. */
+export function setBrowserMode(mode) {
+    current = mode;
+}
+export function getBrowserMode() {
+    return current;
+}
+/** Tests only — restore the default so cases do not leak into each other. */
+export function resetBrowserMode() {
+    current = BrowserMode.ATTACHED;
+}

package/dist/telemetry/bug-found.d.ts

@@ -1,20 +1,3 @@
-/**
- * Counting the defects Reticle actually finds.
- *
- * Every other metric in this product measures whether Reticle is USED. This one measures whether it
- * WORKS — and it is the only number that can honestly be put in front of an investor or published,
- * because it counts outcomes for users rather than activity by them.
- *
- * It is read off tool RESULTS at the single chokepoint every tool already crosses, rather than
- * emitted from the four places that produce findings. That is deliberate: the detectors are pure
- * functions and should stay that way, and reading results means a fifth source of findings is covered
- * the day it starts returning one of these shapes, instead of the day someone remembers to instrument
- * it.
- *
- * What is sent is the KIND from Reticle's own findings vocabulary — `signal-contradicted`,
- * `console-error`, `duplicate-request`. Never a selector, a URL, an element, or a description of
- * anyone's app: that a class of defect was found, never what it was found in.
- */
 import { type BugFound } from '@reticlehq/core';
 /**
  * A defect as the CLASSIFIER sees it — everything except `repeat`.
@@ -24,10 +7,23 @@ import { type BugFound } from '@reticlehq/core';
  */
 export type BugCandidate = Omit<BugFound, 'repeat'>;
 /**
- * The defects in one tool result.
+ * `bug.attribution` was REMOVED, deliberately, and this note is here so it is not re-added casually.
+ *
+ * It shipped twice and was wrong both times. First it stamped `app` on every contradiction, including
+ * `request-never-settled` — which Reticle raises from the ABSENCE of a settle event, so a dev-overlay
+ * poll manufactured it with the app doing nothing wrong. That was fixed, and a real drive then found
+ * it still inverted: across two full runs, EVERY `attribution: 'app'` was a misattribution, while the
+ * one defect that genuinely was a bad agent predicate carried none. One session would have published
+ * "2 defects in the app" against a true count of 0.
+ *
+ * A metric that is confidently wrong about WHOSE fault a defect is, is worse than no metric: it is
+ * the number a founder steers on, and it points at the customer. Counting nothing is recoverable;
+ * publishing a false accusation about somebody's product is not.
  *
- * Ordering matters for the false-green flag: a contradiction found alongside a PASSING assertion is
- * the case the product exists for — the screen looked right, the write failed, and every other tool
- * on the market would have called it green. That pairing is what `falseGreen` marks.
+ * Bringing it back needs evidence that actually separates the cases. It does not exist in the payload
+ * today: `element.present` covers "the button is missing", "the API is down" and "the agent mistyped
+ * a testid" identically, and `signal.absent` covers both a signal the app never fired and a ref
+ * Reticle drove into nothing. Until a verdict carries the reason it came out that way, the honest
+ * output is no owner at all.
  */
 export declare function bugsInResult(toolName: string, result: Record<string, unknown>): BugCandidate[];