@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/session/output-budget.js

@@ -0,0 +1,108 @@
+import { CHURN_TYPES } from '@reticlehq/core';
+/**
+ * Above this, a timeline is big enough that re-reading it unscoped is a real token tax. Observed
+ * live: a single login flooded 319 events / ~37KB because the dashboard's count-up animations emit
+ * a dom.text per frame — the agent only dodged the cost by knowing to pass filters. The hint now
+ * tells it.
+ */
+const LARGE_TIMELINE_EVENTS = 80;
+const LARGE_TIMELINE_BYTES = 8000;
+/**
+ * Default cap for reticle_network / reticle_console when the caller passes no `limit`. Those tools
+ * default `since` to 0 (the whole session), so a long-lived or event-flooded session produced an
+ * UNBOUNDED result — a measured 1-hour flood is ~72,000 calls / ~1M tokens in a single tool result.
+ * Capping to the most-recent N (with `total`/`droppedOldest` disclosed, so nothing is hidden and the
+ * agent can page with since/until or a higher explicit limit) bounds the cost without changing the
+ * window. 200 comfortably covers a real flow's traffic while killing the pathological case.
+ */
+export const DEFAULT_QUERY_LIMIT = 200;
+/**
+ * Default cap for `reticle_observe`'s timeline when the caller passes no `max_events`.
+ *
+ * Without one, the whole window is returned. That is fine for a quiet page and pathological for a
+ * busy one: a page with count-up animations emits an event per frame, and a single observe result
+ * was measured at ~60KB. The sibling tools (`reticle_network`, `reticle_console`) have had a default
+ * for exactly this reason; observe was simply missed.
+ *
+ * Capping is safe for accuracy — and that is the only reason it is allowed. Contradiction detection
+ * runs over the FILTERED-BUT-UNBUDGETED window (see `observe-tools.ts`), so a finding can never
+ * disappear because the timeline was trimmed for tokens. What the cap changes is how much of the
+ * timeline is printed, never what was examined.
+ *
+ * Nothing is hidden: whenever the cap bites, `cost.droppedOldest` says how many older events fell
+ * outside it, and the caller can pass a larger `max_events` to see them.
+ */
+export const DEFAULT_OBSERVE_EVENT_LIMIT = 200;
+/**
+ * Trim a timeline to `maxEvents`, sacrificing noise before evidence.
+ *
+ * The obvious rule -- keep the most recent N -- is wrong here, and a live session showed why. A page
+ * emits a health heartbeat every few seconds forever, so on any idle app the most recent events are
+ * all heartbeats. A real observe call came back with 200 events and 46 KB whose own summary read:
+ * zero network, zero DOM changes, zero route changes, zero console errors, zero signals. The budget
+ * had been spent entirely on heartbeats, and the click the caller was asking about had been dropped
+ * for being older.
+ *
+ * So evidence is kept first, and `CHURN_TYPES` -- which core already defines as the high-volume,
+ * low-signal events that are "the ONLY thing that should be sacrificed when a buffer is full" -- is
+ * used to fill whatever room is left. That rule already governed buffer eviction; it governs this
+ * budget now too, so both agree on what is worth keeping.
+ *
+ * Order is preserved: the result reads oldest-first, like the timeline it came from.
+ */
+export function applyEventBudget(events, maxEvents) {
+    if (maxEvents === undefined || maxEvents < 0 || events.length <= maxEvents) {
+        return { events, droppedOldest: 0 };
+    }
+    const isNoise = (event) => CHURN_TYPES.has(event.type);
+    const evidence = events.filter((event) => !isNoise(event));
+    // Evidence alone can overflow the budget; then it is the most recent evidence that survives.
+    const keptEvidence = evidence.slice(Math.max(0, evidence.length - maxEvents));
+    const roomLeft = maxEvents - keptEvidence.length;
+    const keptNoise = roomLeft <= 0 ? [] : events.filter(isNoise).slice(-roomLeft);
+    const keep = new Set([...keptEvidence, ...keptNoise]);
+    return {
+        events: events.filter((event) => keep.has(event)),
+        droppedOldest: events.length - keep.size,
+    };
+}
+/** Build a cost hint from a payload + the event count it carries. */
+export function costHint(payload, events, droppedOldest = 0) {
+    const json = JSON.stringify(payload) ?? '';
+    // Actual UTF-8 wire bytes, not json.length (UTF-16 code units) — the field is labeled `bytes` and
+    // drives the large-timeline recommendation, so a multibyte-heavy payload was under-counted.
+    const bytes = Buffer.byteLength(json, 'utf8');
+    const base = droppedOldest > 0 ? { events, bytes, droppedOldest } : { events, bytes };
+    if (events >= LARGE_TIMELINE_EVENTS || bytes >= LARGE_TIMELINE_BYTES) {
+        base.recommendation = `large timeline (${String(events)} events, ~${String(estimateTokens(json))} tokens) — pass filters:[...] (e.g. ["signal","net"]) or max_events to scope your next call and cut tokens`;
+    }
+    return base;
+}
+/**
+ * Rough token estimate for a string. The exact count is model/tokenizer-specific, but ~4 characters
+ * per token is the well-known heuristic for English-ish text (and JSON) across GPT/Claude
+ * tokenizers — accurate enough for the only decision it drives: "is this response big enough that I
+ * should re-scope before reading it?" Deliberately a cheap, dependency-free approximation, NOT a
+ * billing-grade count.
+ */
+const CHARS_PER_TOKEN = 4;
+export function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+export function sizeCost(payload) {
+    const json = JSON.stringify(payload) ?? '';
+    // Actual UTF-8 wire bytes, not json.length (UTF-16 code units) — the field is labeled `bytes`
+    // and drives the large-snapshot recommendation, so a multibyte-heavy payload was under-counted.
+    const bytes = Buffer.byteLength(json, 'utf8');
+    return { bytes, tokens: estimateTokens(json) };
+}
+/**
+ * Attach a `cost` size preview to a read result. Pure: the cost is computed over the result BEFORE
+ * the cost field is added (so it measures the body the agent will actually read), then merged in.
+ * Non-object results (e.g. a thrown-error envelope) pass through unchanged.
+ */
+export function withSizeCost(result) {
+    if (typeof result !== 'object' || null === result)
+        return result;
+    return { ...result, cost: sizeCost(result) };
+}

package/dist/portal/session/page-commands/undeclared-command.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Should this page be asked for this command at all?
+ *
+ * A pure decision, kept out of `Session` so it can be argued with directly: the interesting part
+ * is not the sending, it is the rule about when not to send, and that rule has a case each way.
+ *
+ * The protocol says an implementation declares what it can do and refuses everything else, and
+ * the whole value of refusing is that it happens BEFORE the action is spent. Without a
+ * declaration the only way to discover an unsupported command was to send it and wait: eight
+ * seconds, then a timeout whose message is about the page being slow. For a command the page was
+ * never going to answer, that reads as an unhealthy application rather than a request it does not
+ * serve, and it sends whoever is reading to debug the wrong thing.
+ *
+ * **The other half matters more.** `commands` is optional, and an SDK too old to declare sends
+ * nothing at all. Silence must read as UNKNOWN and never as an empty list -- treating it as
+ * "serves nothing" would refuse every command from every older page in the field, which is a far
+ * larger failure than the one being prevented. Absence is the reason this is a function with two
+ * answers rather than a set lookup at the call site.
+ */
+import { type CommandResult } from '@reticlehq/core';
+/** Why nothing was sent, in a sentence, or undefined when the command should go. */
+export declare function refusalForUndeclared(name: string, declared: readonly string[] | undefined): string | undefined;
+/**
+ * The refusal as a finished result, or undefined when the command should be sent.
+ *
+ * Returns the whole `CommandResult` rather than the sentence, so the caller is two lines and
+ * cannot get the envelope subtly wrong -- an `ok: true` refusal would be read as a command that
+ * worked, which is the one shape this must never produce.
+ */
+export declare function refusedResult(name: string, declared: readonly string[] | undefined, id: string): CommandResult | undefined;

package/dist/portal/session/page-commands/undeclared-command.js

@@ -0,0 +1,44 @@
+/**
+ * Should this page be asked for this command at all?
+ *
+ * A pure decision, kept out of `Session` so it can be argued with directly: the interesting part
+ * is not the sending, it is the rule about when not to send, and that rule has a case each way.
+ *
+ * The protocol says an implementation declares what it can do and refuses everything else, and
+ * the whole value of refusing is that it happens BEFORE the action is spent. Without a
+ * declaration the only way to discover an unsupported command was to send it and wait: eight
+ * seconds, then a timeout whose message is about the page being slow. For a command the page was
+ * never going to answer, that reads as an unhealthy application rather than a request it does not
+ * serve, and it sends whoever is reading to debug the wrong thing.
+ *
+ * **The other half matters more.** `commands` is optional, and an SDK too old to declare sends
+ * nothing at all. Silence must read as UNKNOWN and never as an empty list -- treating it as
+ * "serves nothing" would refuse every command from every older page in the field, which is a far
+ * larger failure than the one being prevented. Absence is the reason this is a function with two
+ * answers rather than a set lookup at the call site.
+ */
+import { MessageKind } from '@reticlehq/core';
+/** Why nothing was sent, in a sentence, or undefined when the command should go. */
+export function refusalForUndeclared(name, declared) {
+    // Too old to say. Unknown, never "nothing".
+    if (declared === undefined)
+        return undefined;
+    if (declared.includes(name))
+        return undefined;
+    return (`this page does not serve "${name}". It declared ${String(declared.length)} command(s) when ` +
+        `it connected, and this is not one of them: ${declared.join(', ')}. Nothing was sent, so ` +
+        'nothing happened -- this is a refusal, not a failure of the app.');
+}
+/**
+ * The refusal as a finished result, or undefined when the command should be sent.
+ *
+ * Returns the whole `CommandResult` rather than the sentence, so the caller is two lines and
+ * cannot get the envelope subtly wrong -- an `ok: true` refusal would be read as a command that
+ * worked, which is the one shape this must never produce.
+ */
+export function refusedResult(name, declared, id) {
+    const error = refusalForUndeclared(name, declared);
+    return error === undefined
+        ? undefined
+        : { kind: MessageKind.COMMAND_RESULT, id, ok: false, error };
+}

package/dist/portal/session/presence/session-recommendation.js

@@ -0,0 +1,29 @@
+import { realmOf, DESKTOP_WINDOW_BACKGROUNDED, HIDDEN_TAB_RECOMMENDATION, THROTTLED_TAB_RECOMMENDATION, } from '@reticlehq/core';
+/**
+ * A human-readable hint when a tab is hidden or throttled. Returns undefined for a healthy tab so
+ * the field stays ABSENT (not empty). A merely-unfocused but live tab is still scriptable, so blur
+ * alone does not trigger it. Pure.
+ *
+ * HIDDEN and THROTTLED get DIFFERENT answers, which is the fix. They used to share one message that
+ * said "may be un-focusable; acquire a guaranteed scriptable context" — correct for a background
+ * tab, and actively harmful for a visible one. A visible throttled tab is driveable; measured in the
+ * field, one took a sign-in and two clean net-grade verdicts with no retries, while that message had
+ * already sent the agent into a lease the watching human could not see. One flag, advice that cost
+ * the product's main trust surface, and nothing bought.
+ *
+ * Hidden outranks throttled when both are set: a background tab is the stronger fact, and its
+ * failure mode (events landing on a page that never advances) is the one worth warning about.
+ */
+export function buildSessionRecommendation(inputs) {
+    if (!inputs.hidden && !inputs.throttled)
+        return undefined;
+    // A desktop window gets the one answer it can act on. Checked BEFORE hidden/throttled are told
+    // apart, because the distinction between them is about browser tab lifecycle and neither of its
+    // two answers exists for an app whose window is the client. See DESKTOP_WINDOW_BACKGROUNDED.
+    if (realmOf(inputs.runtime).isDesktopShell) {
+        return DESKTOP_WINDOW_BACKGROUNDED;
+    }
+    if (inputs.hidden)
+        return HIDDEN_TAB_RECOMMENDATION;
+    return THROTTLED_TAB_RECOMMENDATION;
+}

package/dist/portal/session/rebind.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Commands that may be re-issued against the connection that replaced this session.
+ *
+ * Reads only, and the boundary is the point. Re-reading a page costs nothing and answers the same
+ * question the caller asked. An act cannot be replayed: it may already have been dispatched in the
+ * page that went away, and performing it a second time behind the caller's back is a double submit
+ * nobody asked for. A replaced act still errors, and the caller's own retry — with the same id,
+ * which is still the right one — is the safe path.
+ */
+export declare const REBINDABLE_COMMANDS: ReadonlySet<string>;
+/**
+ * How far to walk a chain of replacements before giving up.
+ *
+ * Generous for the real case (a page reloading a handful of times while a call is in flight) and
+ * small enough that a cycle costs nothing. The number is a backstop, not a policy: a chain longer
+ * than this means something is re-dialling in a loop, and that is a different problem.
+ */
+export declare const MAX_SUCCESSOR_HOPS = 32;

package/dist/portal/session/rebind.js

@@ -0,0 +1,38 @@
+/**
+ * Whether a command in flight may be re-issued against the connection that REPLACED this session,
+ * and how far a chain of replacements is worth walking.
+ *
+ * One question, so one file. It left `session.ts` when that file crossed the thousand-line cap on a
+ * merge: two branches had each grown it by a few lines and the sum went over, which is the moment
+ * the rule says to split rather than to raise the number. These two constants and the reasoning
+ * behind them are the most self-contained thing in there — `session.ts` reads them twice and owns
+ * nothing else about rebinding.
+ */
+import { ReticleCommand } from '@reticlehq/core';
+/**
+ * Commands that may be re-issued against the connection that replaced this session.
+ *
+ * Reads only, and the boundary is the point. Re-reading a page costs nothing and answers the same
+ * question the caller asked. An act cannot be replayed: it may already have been dispatched in the
+ * page that went away, and performing it a second time behind the caller's back is a double submit
+ * nobody asked for. A replaced act still errors, and the caller's own retry — with the same id,
+ * which is still the right one — is the safe path.
+ */
+export const REBINDABLE_COMMANDS = new Set([
+    ReticleCommand.SNAPSHOT,
+    ReticleCommand.QUERY,
+    ReticleCommand.MATCH,
+    ReticleCommand.INSPECT,
+    ReticleCommand.STATE_READ,
+    ReticleCommand.STORAGE_READ,
+    ReticleCommand.CAPABILITIES,
+    ReticleCommand.ANIMATIONS,
+]);
+/**
+ * How far to walk a chain of replacements before giving up.
+ *
+ * Generous for the real case (a page reloading a handful of times while a call is in flight) and
+ * small enough that a cycle costs nothing. The number is a backstop, not a policy: a chain longer
+ * than this means something is re-dialling in a loop, and that is a different problem.
+ */
+export const MAX_SUCCESSOR_HOPS = 32;

package/dist/portal/session/session-health.d.ts

@@ -0,0 +1,145 @@
+import { BrowserBrand, type ReticleEvent } from '@reticlehq/core';
+/**
+ * What these functions need from a session, named structurally rather than imported.
+ *
+ * `Session` imports this module for `readHealthEvent`/`pendingNavigationMs`, so naming the class
+ * here made a cycle out of three method signatures. The real `Session` satisfies this by having the
+ * methods, and a test can now pass a two-line stand-in instead of a whole session.
+ */
+interface HealthSubject {
+    bufferHealth(): {
+        total: number;
+        dropped: number;
+    };
+    health(): SessionHealth;
+    throttled(): boolean;
+}
+/** The health block spliced onto act/assert results. Defined here because this is what builds it. */
+export interface SessionHealth {
+    lastSeenMs: number;
+    throttled: boolean;
+    focused: boolean;
+    /** present only when hidden/throttled — points at the `reticle drive` escape hatch. */
+    recommendation?: string;
+    /**
+     * How long the OLDEST unanswered request has been in flight, when that is long enough to matter.
+     *
+     * Present only past `PENDING_NAVIGATION_NOTICE_MS`, so a healthy session costs nothing. Without
+     * it, a fetch stuck pending forever and a dev server that accepts connections and never sends a
+     * body both look exactly like an app that is merely slow — while the daemon holds the evidence.
+     */
+    pendingNavigationMs?: number;
+    /**
+     * Present only when the page's SDK version differs from the daemon's — see version-skew.ts.
+     *
+     * On the HEALTH block, not only on `reticle_sessions`, because skew causes SILENT action failures
+     * and the fields it contradicts ride on the act result: `act_and_wait` can report `dispatched`,
+     * `settled` and a DOM mutation while framework state never changed. A banner an agent only sees
+     * on `reticle_sessions` or `reticle_lease` is not on the surface it reads every call.
+     */
+    versionSkew?: string;
+}
+/**
+ * How long a request may be in flight before it is worth reporting on session health.
+ *
+ * A drive always has requests in the air, so a low bar puts a scary number on every healthy session
+ * and trains agents to ignore the field — the same way a guard that fires on routine controls trains
+ * them to pass `confirmDangerous` reflexively.
+ *
+ * 10s, and it is a HEURISTIC with no clean separation available: "a slow endpoint" and "a server
+ * that will never answer" are the same observation until one of them finishes. The number is chosen
+ * to sit between the two things actually measured, not derived from anything.
+ *
+ * Below it: this repo's own battery runs its API with `REFLECT_MS=6000` on purpose, and at the 5s
+ * this first shipped with, a healthy app with one slow route was permanently non-nominal and carried
+ * a scary number on every result.
+ *
+ * Above it: both reported wedges — 10.4s on one, 170s+ on the other. 10.4s clears this by 400ms,
+ * which is thin, and an app with an 8-second endpoint will not be warned about a wedge until 10s.
+ * That is the trade: an over-firing field gets ignored, and a field nobody reads catches nothing.
+ */
+export declare const PENDING_NAVIGATION_NOTICE_MS = 10000;
+/**
+ * The age of the oldest request that STARTED and never completed, or undefined when there is none
+ * worth reporting.
+ *
+ * Matched on request id, the way `detectHungRequests` and the route oracle's `unansweredIn` do: a
+ * NET_PENDING with no NET_REQUEST carrying the same id. Three readings of one fact is two too many,
+ * but they read different windows — this one is the whole session, which is the point: a wedge that
+ * began before the current action is exactly the case a per-window reading cannot see.
+ */
+export declare function pendingNavigationMs(events: readonly ReticleEvent[], nowMs: number): number | undefined;
+/** The evidence-completeness block spliced onto observe/network/console results. */
+interface BufferEnvelope {
+    buffer?: {
+        held: number;
+        dropped: number;
+        note: string;
+    };
+}
+/**
+ * Buffer-honesty envelope for observe/network/console. When the ring buffer has evicted anything
+ * (age/size cap), a "no such event" answer may be a false negative — so we attach the drop count and
+ * an actionable note. OMITTED entirely when nothing was dropped: silence means the buffer is intact,
+ * so a clean/empty result there is trustworthy and costs zero tokens.
+ */
+export declare function bufferEnvelope(session: HealthSubject): BufferEnvelope;
+/** The `session` (and optional throttled `warning`) block spliced onto act/assert results. */
+interface HealthEnvelope {
+    session?: SessionHealth;
+    warning?: string;
+}
+/**
+ * Build the health envelope for a tool result. When the session is **nominal** (focused, not
+ * throttled, no escape-hatch recommendation) the block is OMITTED entirely — a healthy session
+ * conveys nothing actionable, and emitting it on every act/observe/assert call is pure token
+ * overhead. The block (and a throttled `warning`) appears only when something is actually wrong,
+ * so no health signal is lost — absence means healthy.
+ */
+export declare function healthEnvelope(session: HealthSubject): HealthEnvelope;
+/**
+ * Opt-in hard stop. When `refuseWhenThrottled` is true and the tab is throttled, throw so the
+ * agent does not drive a tab where timers/rAF/pointer gestures may silently no-op. Default is
+ * warn-only so background testing never breaks.
+ */
+export declare function refuseIfThrottled(session: HealthSubject, refuse: unknown): void;
+/**
+ * Suffix the starvation note onto a FAILED predicate verdict when the tab is throttled. A pass is
+ * returned untouched — starvation is context for a failure, not a reason to doubt a hold. Pure and
+ * generic over the verdict shape so assert/wait_for/act_and_wait share one rule.
+ *
+ * The note FOLLOWS the stamped field and does not decide for itself. `annotateThrottledMiss`
+ * (predicate.ts) owns the question of whether this failure was reached by NOT HAVING SEEN
+ * something, which is the only reading a starved tab casts doubt on, and stamps
+ * `THROTTLED_STARVED_NOTE` when it was. Deciding again here gives two answers to one question: an
+ * `absent: true` assertion that failed because it MATCHED elements is not in doubt, and must not be
+ * told in prose that the tab may never have rendered. The same applies to a failure that already
+ * carries a more specific reason (an unreadable locator, a superseded window): the concrete
+ * diagnosis leads.
+ */
+export declare function annotateStarvedFailure<V extends {
+    pass?: boolean;
+    failureReason?: string;
+    inconclusive?: string;
+}>(session: HealthSubject, verdict: V): V;
+/** The page's own visibility/runtime report, narrowed out of an untrusted PAGE_HEALTH payload. */
+interface HealthReport {
+    hidden: boolean | undefined;
+    focused: boolean | undefined;
+    runtime: string | undefined;
+    /** Coarse rendering engine (blink/gecko/webkit) — context for a feedback report, not a health input. */
+    engine: string | undefined;
+    /**
+     * Which browser the page is. Narrowed to `BrowserBrand` HERE rather than trusted: the SDK already
+     * normalises, so anything else is a stale or hand-forged payload and is dropped — the point of the
+     * closed list is that an unbounded string can never reach telemetry through it.
+     */
+    brand: BrowserBrand | undefined;
+}
+/**
+ * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report
+ * `runtime` at all — so each is returned as undefined rather than defaulted here, letting the caller
+ * keep its previous value instead of silently flipping a session to "visible" on a partial report.
+ */
+export declare function readHealthEvent(data: Record<string, unknown>): HealthReport;
+export {};

package/dist/portal/session/session-health.js

@@ -0,0 +1,154 @@
+import { BrowserBrand, EventType, BUFFER_EVICTION_WARNING, THROTTLED_STARVED_NOTE, THROTTLED_WARNING, } from '@reticlehq/core';
+/**
+ * How long a request may be in flight before it is worth reporting on session health.
+ *
+ * A drive always has requests in the air, so a low bar puts a scary number on every healthy session
+ * and trains agents to ignore the field — the same way a guard that fires on routine controls trains
+ * them to pass `confirmDangerous` reflexively.
+ *
+ * 10s, and it is a HEURISTIC with no clean separation available: "a slow endpoint" and "a server
+ * that will never answer" are the same observation until one of them finishes. The number is chosen
+ * to sit between the two things actually measured, not derived from anything.
+ *
+ * Below it: this repo's own battery runs its API with `REFLECT_MS=6000` on purpose, and at the 5s
+ * this first shipped with, a healthy app with one slow route was permanently non-nominal and carried
+ * a scary number on every result.
+ *
+ * Above it: both reported wedges — 10.4s on one, 170s+ on the other. 10.4s clears this by 400ms,
+ * which is thin, and an app with an 8-second endpoint will not be warned about a wedge until 10s.
+ * That is the trade: an over-firing field gets ignored, and a field nobody reads catches nothing.
+ */
+export const PENDING_NAVIGATION_NOTICE_MS = 10_000;
+/**
+ * Said beside `dispatched` / `settled` on a skewed session, because those fields read as success.
+ *
+ * The reporter's own account of the cost: "the false-positive dispatch confirmation is what cost the
+ * most time — I trusted `dispatched: true, domMutatedWithin: Nms` as real signal for a long time
+ * before suspecting the skew banner." Stating the contradiction is the whole job here; the existing
+ * banner was accurate and simply never appeared where it was needed.
+ */
+const SKEW_VERDICT_WARNING = 'version skew: `dispatched` and `settled` on this session mean the event was sent, NOT that the ' +
+    'app acted on it — a skewed pair drops actions silently. Re-read the control (aria-checked, ' +
+    'data-state, its text) before trusting any verdict from this session, and converge the versions:';
+/**
+ * The age of the oldest request that STARTED and never completed, or undefined when there is none
+ * worth reporting.
+ *
+ * Matched on request id, the way `detectHungRequests` and the route oracle's `unansweredIn` do: a
+ * NET_PENDING with no NET_REQUEST carrying the same id. Three readings of one fact is two too many,
+ * but they read different windows — this one is the whole session, which is the point: a wedge that
+ * began before the current action is exactly the case a per-window reading cannot see.
+ */
+export function pendingNavigationMs(events, nowMs) {
+    const settled = new Set();
+    for (const e of events)
+        if (e.type === EventType.NET_REQUEST)
+            settled.add(e.data['id']);
+    let oldest;
+    for (const e of events) {
+        if (e.type !== EventType.NET_PENDING || settled.has(e.data['id']))
+            continue;
+        if (oldest === undefined || e.t < oldest)
+            oldest = e.t;
+    }
+    if (oldest === undefined)
+        return undefined;
+    const age = nowMs - oldest;
+    return age >= PENDING_NAVIGATION_NOTICE_MS ? age : undefined;
+}
+/**
+ * Buffer-honesty envelope for observe/network/console. When the ring buffer has evicted anything
+ * (age/size cap), a "no such event" answer may be a false negative — so we attach the drop count and
+ * an actionable note. OMITTED entirely when nothing was dropped: silence means the buffer is intact,
+ * so a clean/empty result there is trustworthy and costs zero tokens.
+ */
+export function bufferEnvelope(session) {
+    const { total, dropped } = session.bufferHealth();
+    if (0 === dropped)
+        return {};
+    return { buffer: { held: total, dropped, note: BUFFER_EVICTION_WARNING } };
+}
+/**
+ * Build the health envelope for a tool result. When the session is **nominal** (focused, not
+ * throttled, no escape-hatch recommendation) the block is OMITTED entirely — a healthy session
+ * conveys nothing actionable, and emitting it on every act/observe/assert call is pure token
+ * overhead. The block (and a throttled `warning`) appears only when something is actually wrong,
+ * so no health signal is lost — absence means healthy.
+ */
+export function healthEnvelope(session) {
+    const health = session.health();
+    // A request stuck in flight makes a session non-nominal even when the tab is fine, because it is
+    // the one condition where every observation is about to be about a page that is not moving.
+    const nominal = !health.throttled &&
+        health.focused &&
+        health.recommendation === undefined &&
+        health.pendingNavigationMs === undefined &&
+        health.versionSkew === undefined;
+    if (nominal)
+        return {};
+    // Skew outranks the throttle warning when both hold: a throttled tab makes a reading unreliable,
+    // a skewed link makes the ACTION unreliable, and there is no point warning about the quality of an
+    // observation of something that may never have happened.
+    if (health.versionSkew !== undefined) {
+        return { session: health, warning: `${SKEW_VERDICT_WARNING} ${health.versionSkew}` };
+    }
+    return health.throttled ? { session: health, warning: THROTTLED_WARNING } : { session: health };
+}
+/**
+ * Opt-in hard stop. When `refuseWhenThrottled` is true and the tab is throttled, throw so the
+ * agent does not drive a tab where timers/rAF/pointer gestures may silently no-op. Default is
+ * warn-only so background testing never breaks.
+ */
+export function refuseIfThrottled(session, refuse) {
+    if (true === refuse && session.throttled()) {
+        throw new Error(`refusing to act: ${THROTTLED_WARNING}`);
+    }
+}
+/**
+ * The sentence appended to a FAILED predicate verdict waited out on a throttled tab.
+ *
+ * A starved tab and a missing element read identically as a bare near-miss: after a hard reload a
+ * backgrounded tab can sit on its loading state forever (hydration starved, nothing painted), and
+ * `wait_for { text }` timing out there looks exactly like "the code did not render" (#521). The
+ * health envelope already rode alongside saying `throttled:true`, but nothing connected it to the
+ * verdict an agent actually gates on. Appended, not replacing: the original diagnosis still leads,
+ * and on a healthy tab the failure says exactly what it always said.
+ */
+const STARVED_WAIT_NOTE = ' (the tab was throttled during this wait, so starvation can look exactly like absence: bring it to the front and re-check before concluding this is genuinely missing)';
+/**
+ * Suffix the starvation note onto a FAILED predicate verdict when the tab is throttled. A pass is
+ * returned untouched — starvation is context for a failure, not a reason to doubt a hold. Pure and
+ * generic over the verdict shape so assert/wait_for/act_and_wait share one rule.
+ *
+ * The note FOLLOWS the stamped field and does not decide for itself. `annotateThrottledMiss`
+ * (predicate.ts) owns the question of whether this failure was reached by NOT HAVING SEEN
+ * something, which is the only reading a starved tab casts doubt on, and stamps
+ * `THROTTLED_STARVED_NOTE` when it was. Deciding again here gives two answers to one question: an
+ * `absent: true` assertion that failed because it MATCHED elements is not in doubt, and must not be
+ * told in prose that the tab may never have rendered. The same applies to a failure that already
+ * carries a more specific reason (an unreadable locator, a superseded window): the concrete
+ * diagnosis leads.
+ */
+export function annotateStarvedFailure(session, verdict) {
+    if (true === verdict.pass || verdict.failureReason === undefined)
+        return verdict;
+    if (true !== session.throttled())
+        return verdict;
+    if (THROTTLED_STARVED_NOTE !== verdict.inconclusive)
+        return verdict;
+    return { ...verdict, failureReason: `${verdict.failureReason}${STARVED_WAIT_NOTE}` };
+}
+/**
+ * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report
+ * `runtime` at all — so each is returned as undefined rather than defaulted here, letting the caller
+ * keep its previous value instead of silently flipping a session to "visible" on a partial report.
+ */
+export function readHealthEvent(data) {
+    return {
+        hidden: 'boolean' === typeof data['hidden'] ? data['hidden'] : undefined,
+        focused: 'boolean' === typeof data['focused'] ? data['focused'] : undefined,
+        runtime: 'string' === typeof data['runtime'] ? data['runtime'] : undefined,
+        engine: 'string' === typeof data['engine'] ? data['engine'] : undefined,
+        brand: Object.values(BrowserBrand).find((known) => known === data['brand']),
+    };
+}

package/dist/portal/session/session-manager.d.ts

@@ -0,0 +1,81 @@
+import type { NoSessionReason } from '@reticlehq/core/telemetry';
+import { Session, type SessionInfo } from './session.js';
+import { AttachmentHistory } from './presence/attachment-history.js';
+import type { NoSessionNextAction } from './no-session-next-action.js';
+import { type SessionIdentity } from './session-successor.js';
+/**
+ * The agent's active project, used to scope auto-selection. `projectId` is the stable build-stamped
+ * identity (authoritative when present); `url` is the app origin, a fallback hint for older SDKs that
+ * don't stamp a projectId. Both optional — an empty scope means "no project filter" (legacy behavior).
+ */
+interface ResolveScope {
+    projectId?: string;
+    url?: string;
+}
+/** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
+export declare function originOf(url: string | undefined): string | undefined;
+export declare class SessionManager {
+    #private;
+    /** Set the active project's default resolve scope (called once at daemon wiring). */
+    setDefaultScope(scope: ResolveScope | undefined): void;
+    setConnectionRecorder(record: ((projectId: string | undefined) => void) | undefined): void;
+    add(session: Session): Session | undefined;
+    remove(session: Session): boolean;
+    get(sessionId: string): Session | undefined;
+    list(): SessionInfo[];
+    /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
+    attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;
+    /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
+    all(): Session[];
+    count(): number;
+    /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
+    setNoSessionHint(hint: (() => string | undefined) | undefined): void;
+    /** Wire the short rendering. Registered from the same `explainNoSession` call as the hint. */
+    setNoSessionLead(lead: (() => string | undefined) | undefined): void;
+    /** The lead and the next action, for a surface a person reads. */
+    noSessionLead(): string | undefined;
+    /**
+     * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
+     *
+     * `reticle_sessions` is the first thing an agent reaches for and it returned a bare empty array —
+     * confidently, with nothing to act on. An agent cannot tell an empty list apart from a daemon that
+     * is down, an app with no SDK, or a tab that was closed, so it stops there. The diagnosis was
+     * already computed for the error path; this exposes it to the read path too.
+     */
+    noSessionHint(): string | undefined;
+    setNoSessionReason(reason: (() => NoSessionReason | undefined) | undefined): void;
+    noSessionReason(): NoSessionReason | undefined;
+    setNoSessionNextAction(next: (() => NoSessionNextAction | undefined) | undefined): void;
+    noSessionNextAction(): NoSessionNextAction | undefined;
+    everConnected(): boolean;
+    /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
+    noteClosure(reason: string, at: number): void;
+    /** The most recent bridge-initiated close, if any. */
+    lastClosure(): {
+        at: number;
+        reason: string;
+    } | undefined;
+    connectedSinceLastClosure(): boolean;
+    /**
+     * The id of the session that most recently went away, if any.
+     *
+     * Distinct from {@link lastClosure}, which only records closes the bridge itself initiated
+     * (handshake refusals, auth failures) — an ordinary disconnect never reaches it. This reads the
+     * tombstone ring `remove()` maintains, so it covers every departure.
+     *
+     * Read by the no-session diagnosis, which needs to say something about the session that actually
+     * vanished rather than about the daemon's lifetime history (#611).
+     */
+    lastDeparted(): string | undefined;
+    /**
+     * The session that most recently disappeared — id, last URL, project — or undefined.
+     *
+     * `lastDeparted` is the id alone, which is what lease-expiry attribution needs. This is the
+     * rest: a route that 500s tears the page down and the SDK never reconnects, and without the
+     * URL `reticle_sessions` is an empty list with no history (#808). Tombstones, not live rows:
+     * a connected tab is in `list()`, not here.
+     */
+    lastKnown(): SessionIdentity | undefined;
+    resolve(sessionId?: string, scope?: ResolveScope): Session;
+}
+export {};