@reticlehq/server 2.14.0 → 3.2.0

package/dist/session/observed-state.js

@@ -1,121 +0,0 @@
-import { BlindSpotKind, EventType } from '@reticlehq/core';
-import { ambientKeyOf } from '../journal/ambient.js';
-/**
- * The two things a session learns by watching its own event stream, as opposed to storing.
- *
- * Both are LEVELS derived from a stream, and both have to outlive the ring buffer — which is what
- * separates them from the buffer's job and earns them their own unit:
- *
- *   ambient    — which regions of the page move on their own (chat, tickers, live counters). Used by
- *                the settle oracle to ignore background motion, so an action isn't held open forever
- *                by churn it did not cause.
- *   blindSpots — how much of the page the SDK cannot observe (cross-origin frames, closed shadow
- *                roots). The SDK reports these only when the count CHANGES, so a page that mounts
- *                two frames at load announces them once and is silent forever after. Anything that
- *                infers coverage from a window of events therefore sees nothing and concludes the
- *                page was fully observed — a positive claim to have seen what we cannot see. Holding
- *                the level here makes coverage something to ask rather than infer.
- */
-export class ObservedState {
-    /** What THIS session observed. Never contains seeded history — see seedAmbient. */
-    #ownAmbient = {};
-    /** What previous sessions learned, kept separate so it is never re-persisted as if newly seen. */
-    #seededAmbient = {};
-    #blindSpots = {};
-    /** Fold one already-attributed event into the learned state. */
-    observe(event) {
-        // Only UNATTRIBUTED events count as ambient: an event caused by an action is the action's work,
-        // and learning it as background would teach the settle oracle to ignore real effects.
-        if (event.actionId === undefined) {
-            const key = ambientKeyOf(event);
-            if (key !== undefined)
-                this.#ownAmbient[key] = (this.#ownAmbient[key] ?? 0) + 1;
-        }
-        if (event.type === EventType.BLIND_SPOT) {
-            const kind = event.data['kind'];
-            const count = event.data['count'];
-            if ('string' === typeof kind && 'number' === typeof count)
-                this.#blindSpots[kind] = count;
-        }
-    }
-    /**
-     * Learned ambient-churn counts — seeded history PLUS this session — for the settle oracle, which
-     * wants the sharpest available picture of what moves on its own.
-     */
-    ambientCounts() {
-        const merged = { ...this.#seededAmbient };
-        for (const [key, count] of Object.entries(this.#ownAmbient)) {
-            merged[key] = (merged[key] ?? 0) + count;
-        }
-        return merged;
-    }
-    /**
-     * ONLY what this session observed — the correct input to persistence.
-     *
-     * Teardown accumulates by adding the session's counts onto the file it loaded. When the session's
-     * counts still contained the seeded ones, that addition wrote `2 x persisted + own` every run, so
-     * the map doubled per session: the file committed in this repo had reached ~9.1e23 (about 2^80,
-     * i.e. ~80 sessions of doubling). Keeping the seed separate makes the accumulation what it always
-     * claimed to be — history plus what is new.
-     */
-    ownAmbientCounts() {
-        return this.#ownAmbient;
-    }
-    /**
-     * Seed from the persisted per-app map so the picture sharpens across sessions.
-     * In-session counts win: they describe this page as it is now.
-     */
-    seedAmbient(counts) {
-        this.#seededAmbient = { ...counts };
-    }
-    /** Latest reported count per blind-spot kind, for the whole session. */
-    /**
-     * Refs the agent has driven, for the exercised/untouched split `reticle_coverage` reports.
-     *
-     * Kept here beside the blind-spot counts because both are per-session observed facts that must
-     * SURVIVE buffer eviction. Deriving "what did I touch" from the event buffer instead would mean an
-     * action fifty steps ago silently stops counting, so "untouched" would quietly come to mean
-     * "recently untouched" — a number that reads as thorough while drifting toward the opposite.
-     */
-    #actedRefs = new Set();
-    /**
-     * The same drives, keyed by something that SURVIVES a re-render.
-     *
-     * A ref is invalidated whenever the DOM changes, so on a framework that replaces nodes rather than
-     * reconciling in place (Next's app router, for one) every driven ref is stale by the time coverage
-     * is asked and the number reads 0 forever. The snapshot label — `button "Deploy"` — names the same
-     * control on both sides of a re-render.
-     */
-    #actedLabels = new Set();
-    /** Record a driven ref. Idempotent. */
-    recordActedRef(ref) {
-        if (ref.length > 0)
-            this.#actedRefs.add(ref);
-    }
-    /** Record a driven control's re-render-surviving label. Idempotent; empty labels are not identities. */
-    recordActedLabel(label) {
-        if (label.length > 0)
-            this.#actedLabels.add(label);
-    }
-    /** Every ref driven so far this session. */
-    actedRefs() {
-        return this.#actedRefs;
-    }
-    /** Every driven control's label, for matching across re-renders. */
-    actedLabels() {
-        return this.#actedLabels;
-    }
-    /**
-     * Record bridge-side sampling as a blind spot.
-     *
-     * Every other blind spot is reported BY the SDK, which cannot report this one: the events were
-     * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
-     * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
-     */
-    noteRateLimited(dropped) {
-        this.#blindSpots[BlindSpotKind.RATE_LIMITED] = dropped;
-    }
-    blindSpots() {
-        return this.#blindSpots;
-    }
-}

package/dist/session/output-budget.d.ts

@@ -1,49 +0,0 @@
-import type { ReticleEvent } from '@reticlehq/core';
-/**
- * A self-budgeting hint returned on event-bearing tool results so the agent can decide whether to
- * narrow its next call (the report flagged 60KB+ results as a real token tax). `bytes` is the JSON
- * size of the payload; `droppedOldest` is present only when a cap actually truncated the timeline —
- * never a silent cap.
- */
-interface CostHint {
-    events: number;
-    bytes: number;
-    droppedOldest?: number;
-    /** Present when the timeline is large — tells the agent to scope its NEXT call (cut tokens). */
-    recommendation?: string;
-}
-/**
- * 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 declare const DEFAULT_QUERY_LIMIT = 200;
-/** Keep only the most recent `maxEvents` events; report how many older ones were dropped. */
-export declare function applyEventBudget(events: ReticleEvent[], maxEvents: number | undefined): {
-    events: ReticleEvent[];
-    droppedOldest: number;
-};
-/** Build a cost hint from a payload + the event count it carries. */
-export declare function costHint(payload: unknown, events: number, droppedOldest?: number): CostHint;
-export declare function estimateTokens(text: string): number;
-/**
- * A size preview for non-event read results (snapshot, query). Same intent as CostHint but for
- * payloads measured by size rather than event count: the agent can bail and re-scope (mode:status,
- * a tighter scope, a more specific query) before spending context on a large body. The token
- * figure is an estimate (see estimateTokens).
- */
-interface SizeCost {
-    bytes: number;
-    tokens: number;
-}
-export declare function sizeCost(payload: unknown): SizeCost;
-/**
- * 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 declare function withSizeCost<T>(result: T): T;
-export {};

package/dist/session/output-budget.js

@@ -1,67 +0,0 @@
-/**
- * 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;
-/** Keep only the most recent `maxEvents` events; report how many older ones were dropped. */
-export function applyEventBudget(events, maxEvents) {
-    if (maxEvents === undefined || maxEvents < 0 || events.length <= maxEvents) {
-        return { events, droppedOldest: 0 };
-    }
-    return {
-        events: events.slice(events.length - maxEvents),
-        droppedOldest: events.length - maxEvents,
-    };
-}
-/** 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/session/session-health.d.ts

@@ -1,138 +0,0 @@
-import { BrowserBrand, type ReticleEvent } from '@reticlehq/core';
-import type { Session } from './session.js';
-/**
- * The health block spliced onto act/assert results. Defined here rather than in session.ts: this is
- * the module that builds it, and session.ts was over the file-size cap.
- */
-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. Both
-     * reporters on the hung-server issue said this alone would have been enough for them: one sat on
-     * an RSC fetch stuck pending for 170+ seconds across many calls, the other on a dev server that
-     * accepted connections and never sent a body. Reticle held the evidence both times and the truth
-     * was eventually established with `curl`.
-     */
-    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. Reported from the field: `act_and_wait`
-     * returning `dispatched: true, settled: true, domMutatedWithin: 12-40ms` while React state never
-     * changed, across eight attempts and three interaction strategies. The banner existed the whole
-     * time — on `reticle_sessions` and `reticle_lease`, which is not the surface an agent reads on
-     * 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: Session): 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: Session): 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: Session, 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 sentence FOLLOWS the 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; it stamps
- * `THROTTLED_STARVED_NOTE` when it was. Deciding again here got two answers to one question:
- * an `absent: true` assertion that MATCHED 13 elements was graded honestly in the field an agent
- * gates on, and told in prose that the tab may never have rendered. It also doubled up on a failure
- * that already carried a more specific reason (an unreadable locator, a superseded window), where
- * the concrete diagnosis is the one that should lead.
- */
-export declare function annotateStarvedFailure<V extends {
-    pass?: boolean;
-    failureReason?: string;
-    inconclusive?: string;
-}>(session: Session, 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/session/session-health.js

@@ -1,154 +0,0 @@
-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 sentence FOLLOWS the 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; it stamps
- * `THROTTLED_STARVED_NOTE` when it was. Deciding again here got two answers to one question:
- * an `absent: true` assertion that MATCHED 13 elements was graded honestly in the field an agent
- * gates on, and told in prose that the tab may never have rendered. It also doubled up on a failure
- * that already carried a more specific reason (an unreadable locator, a superseded window), where
- * the concrete diagnosis is the one that should lead.
- */
-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/session/session-manager.d.ts

@@ -1,76 +0,0 @@
-import type { NoSessionReason } from '@reticlehq/core/telemetry';
-import { Session, type SessionInfo } from './session.js';
-import { AttachmentHistory } from './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;
-    /**
-     * 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;
-    /**
-     * 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 {};