@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/tools/act/act-helpers.js

@@ -0,0 +1,40 @@
+/**
+ * Pure coercion + grading helpers behind the act tools.
+ *
+ * Split out when act-tools.ts crossed the 600-line cap. The seam is that nothing here touches a
+ * session, a command, or a tool definition — these are total functions over their arguments, which
+ * is why they can be tested without a browser and why they were the right thing to move.
+ */
+import { ActionType, ConsequenceKind } from '@reticlehq/core';
+import { HonestyGrade } from '@reticlehq/engine/evidence/honesty.js';
+import { asNumber, asRecord, asString } from '@reticlehq/core';
+/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
+export function gradeOf(links) {
+    if (links.some((l) => ConsequenceKind.SIGNAL === l.kind))
+        return HonestyGrade.SIGNAL;
+    if (links.some((l) => ConsequenceKind.NET === l.kind))
+        return HonestyGrade.NET;
+    if (links.some((l) => ConsequenceKind.STATE === l.kind))
+        return HonestyGrade.STATE;
+    return HonestyGrade.PRESENCE;
+}
+/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
+export function asBox(value) {
+    const b = asRecord(asRecord(value)['box']);
+    const x = asNumber(b['x']);
+    const y = asNumber(b['y']);
+    const w = asNumber(b['width']);
+    const h = asNumber(b['height']);
+    if (x === undefined || y === undefined || w === undefined || h === undefined)
+        return undefined;
+    if (w <= 0 || h <= 0)
+        return undefined; // zero-area (display:none) ⇒ native click would miss
+    return { x, y, width: w, height: h };
+}
+/** Outcome of a real-input attempt — real success (result set) or synthetic with a reason. */
+export function asActionType(value) {
+    const raw = asString(value);
+    if (raw === undefined)
+        return undefined;
+    return Object.values(ActionType).includes(raw) ? raw : undefined;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * What to do when the observer left in the middle of an act.
+ *
+ * A full-document navigation — often the very thing the act CAUSED — tears the SDK down. The page
+ * re-announces, and whatever this call still had in flight is gone. That is a fact about the
+ * observer, never about the application, and the difference matters: every honest verdict this
+ * engine can give depends on not converting "I stopped watching" into "your app is broken".
+ *
+ * Its own module because it is one idea — follow the document that took over, and re-ask there —
+ * used from the two points where observation can be lost: a write rejected at dispatch, and a wait
+ * cut off mid-predicate.
+ */
+import type { Session } from '../../../portal/session/session.js';
+import { type SuccessorRegistry } from '../../../portal/session/session-successor.js';
+import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate-eval.js';
+interface FollowSuccessor {
+    sessions: SuccessorRegistry;
+    session: Session;
+    verdict: EvalResult;
+    /** Total budget the CALLER granted, in ms. */
+    timeout: number;
+    /** `session.elapsed()` at the moment the predicate started. */
+    predicateStarted: number;
+    /** Re-ask the declared consequence on `next`, with whatever budget is left. */
+    reevaluate: (next: Session, budgetMs: number) => Promise<EvalResult>;
+}
+interface FollowedOutcome {
+    session: Session;
+    verdict: EvalResult;
+    /** True when the wait moved to a new document, so the caller must reset its event cursor. */
+    followed: boolean;
+}
+/**
+ * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
+ *
+ * `navigate` already waits for the HELLO and returns the new id; this path used to grade
+ * `observation_lost` and leave the agent holding a DEAD id, so the next assert failed even though
+ * the new page had loaded perfectly. Two live tabs at that origin is still a guess, and
+ * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
+ */
+export declare function followLostObservation(input: FollowSuccessor): Promise<FollowedOutcome>;
+export {};

package/dist/surface/tools/act/act-observation.js

@@ -0,0 +1,36 @@
+/**
+ * What to do when the observer left in the middle of an act.
+ *
+ * A full-document navigation — often the very thing the act CAUSED — tears the SDK down. The page
+ * re-announces, and whatever this call still had in flight is gone. That is a fact about the
+ * observer, never about the application, and the difference matters: every honest verdict this
+ * engine can give depends on not converting "I stopped watching" into "your app is broken".
+ *
+ * Its own module because it is one idea — follow the document that took over, and re-ask there —
+ * used from the two points where observation can be lost: a write rejected at dispatch, and a wait
+ * cut off mid-predicate.
+ */
+import { awaitDocumentSuccessor, } from '../../../portal/session/session-successor.js';
+/**
+ * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
+ *
+ * `navigate` already waits for the HELLO and returns the new id; this path used to grade
+ * `observation_lost` and leave the agent holding a DEAD id, so the next assert failed even though
+ * the new page had loaded perfectly. Two live tabs at that origin is still a guess, and
+ * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
+ */
+export async function followLostObservation(input) {
+    const { sessions, session, verdict, timeout, predicateStarted, reevaluate } = input;
+    if (true !== verdict.observationLost || 0 >= timeout)
+        return { session, verdict, followed: false };
+    const remaining = timeout - (session.elapsed() - predicateStarted);
+    const next = remaining > 0 ? await awaitDocumentSuccessor(sessions, session, remaining) : null;
+    if (null === next)
+        return { session, verdict, followed: false };
+    // Computed on the DEPARTED session, before the caller points at the successor: the new session's
+    // elapsed() starts at 0 and would silently refund the whole budget the caller had already spent.
+    const leftover = timeout - (session.elapsed() - predicateStarted);
+    if (leftover <= 0)
+        return { session: next, verdict, followed: true };
+    return { session: next, verdict: await reevaluate(next, leftover), followed: true };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * The action arguments of one step, from either spelling.
+ *
+ * An explicit `args` wins key by key: it is the form the schema documents, so a caller who wrote it
+ * meant it.
+ */
+export declare function sequenceStepArgs(step: Record<string, unknown>): Record<string, unknown>;
+export declare function assertSequenceSteps(steps: readonly unknown[]): void;
+/**
+ * Throws if this call cannot honestly be driven. Call it after the args are parsed and before the
+ * first dispatch — anything that depends on what is actually rendered belongs after the action.
+ */
+export declare function preflightAct(actArgs: Record<string, unknown>, until: unknown): void;
+/**
+ * Dispatch a write, or report that its outcome went unobserved.
+ *
+ * Returns null — never throws — when the transport was displaced by a newer connection claiming the
+ * same id. That happens on any full-document navigation the act itself causes: the page unloads,
+ * re-announces, and the write in flight is rejected by the handle that just died.
+ *
+ * The write is deliberately NOT re-sent. Re-asking a READ on the successor is free; re-sending a
+ * WRITE is not, because nothing can prove the first one did not reach the page — and a duplicated
+ * click on a button that charges a card is a far worse outcome than a verdict of "I could not see".
+ * Every other failure propagates unchanged: only a replacement is an observation problem, and
+ * treating a timeout or a refusal as one would launder a real failure into a shrug.
+ */
+export declare function dispatchAct<T>(send: () => Promise<T>): Promise<T | null>;

package/dist/surface/tools/act/act-preflight.js

@@ -0,0 +1,168 @@
+/**
+ * Everything refused BEFORE the action window opens.
+ *
+ * Both checks here share one property, and it is the reason they belong together: each is decidable
+ * without touching the page, and each would otherwise be discovered only after the click had landed
+ * — when the action is spent, the page has moved, and the honest answer has already been lost.
+ *
+ * Refusing early is not a convenience. `reticle_act_and_wait` promises a verdict, and a verdict that
+ * blames the app for the caller's own mistake is the most damaging thing a verification tool can
+ * produce: it sends somebody to fix code that is not broken. "Nothing was acted on" is a far better
+ * outcome than "unknown".
+ */
+import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate-schema.js';
+import { isGlobalPressCall } from '@reticlehq/core';
+import { SessionReplacedError } from '../../../portal/session/page-commands/pending-commands.js';
+import { assertNativeInputSupported } from './act-danger.js';
+import { unevaluablePredicateReason, vacuousPredicateReason, } from '@reticlehq/engine/question/predicate/predicate-precheck.js';
+/**
+ * Refuse a sequence whose steps cannot be addressed.
+ *
+ * `steps` is a bare array of objects, so a step with neither `ref` nor `target` used to travel on
+ * and dispatch as `ref: ''`. The browser then threw `ref '' no longer resolves to an element` —
+ * a stale-ref diagnosis for a missing locator — and the caller went looking for a re-render.
+ *
+ * `target` is the same locator `reticle_act` / `reticle_act_and_wait` take; the handler resolves it
+ * with `resolveActTarget` before dispatch. This check asks that every step names one of the two,
+ * except a document-key press (Escape, Tab, a modifier shortcut), which is not aimed at an element.
+ * It runs before the first step, so a typo in step three cannot leave one and two applied.
+ */
+/**
+ * Keys an agent reaches for when it means "and prove this happened", and that this tool does not read.
+ *
+ * A sub-step reads `ref`/`target`/`action`/`args`/`expect` and nothing else, and the schema is a
+ * permissive record, so any other spelling is accepted and dropped. `until` is the likeliest by a
+ * distance: it is what act_and_wait — the tool immediately next to this one — calls its assertion.
+ *
+ * Silently ignoring one manufactures a false green. A sequence carrying an impossible `until` came
+ * back `completed: 1` with no error and nothing said about the predicate, which reads as the
+ * consequence having held.
+ *
+ * `expect` is deliberately NOT here. It used to be, from when a sub-step genuinely could not be
+ * graded — and it stayed after that changed, so the tool's own schema advertised `expect` as "what
+ * makes a step PROVE something" while this check refused every step carrying one. An agent following
+ * the documentation got a hard refusal, and the entire graded path was unreachable. Found by driving
+ * a three-step plan against a live daemon; no unit test could see it, because they all call the
+ * grader and the handler internals directly and never pass through this door.
+ */
+const CONSEQUENCE_KEYS = ['until', 'assert', 'waitFor'];
+/**
+ * What a step says about ITSELF rather than about the action: everything else is an action argument.
+ *
+ * A step is one `reticle_act` call, and `reticle_act` takes its arguments flat — so
+ * `{ ref, action: "fill", value: "…" }` is the obvious way to write one, and the sequence dropped
+ * `value` silently. The browser then refused ("fill requires a string `value` — pass it nested"),
+ * which is the RIGHT refusal for a missing value: filling with nothing wipes the field, dispatches a
+ * real input event so the framework commits the empty string, and reports ok. But the value was not
+ * missing, it was discarded here, so a correct-looking call cost a round trip. Measured driving a
+ * real install.
+ */
+const STEP_STRUCTURE_KEYS = new Set([
+    'ref',
+    'target',
+    'action',
+    'args',
+    'timeout_ms',
+    'label',
+    ...CONSEQUENCE_KEYS,
+    'expect',
+]);
+/**
+ * The action arguments of one step, from either spelling.
+ *
+ * An explicit `args` wins key by key: it is the form the schema documents, so a caller who wrote it
+ * meant it.
+ */
+export function sequenceStepArgs(step) {
+    const flat = {};
+    for (const [key, value] of Object.entries(step)) {
+        if (!STEP_STRUCTURE_KEYS.has(key))
+            flat[key] = value;
+    }
+    const nested = step['args'];
+    return { ...flat, ...(null !== nested && 'object' === typeof nested ? nested : {}) };
+}
+export function assertSequenceSteps(steps) {
+    if (0 === steps.length) {
+        throw new Error('reticle_act_sequence was given no steps. Pass steps: [{ ref, action, args? }] or [{ target, action, args? }] — nothing was acted on.');
+    }
+    steps.forEach((raw, i) => {
+        const step = 'object' === typeof raw && null !== raw ? raw : {};
+        const claimed = CONSEQUENCE_KEYS.find((k) => step[k] !== undefined);
+        if (claimed !== undefined) {
+            throw new Error(`step ${String(i)} carries \`${claimed}\`, which reticle_act_sequence does not read. ` +
+                'The key would be dropped and the sequence would report success having checked nothing. ' +
+                'Rename it to `expect` — this tool grades that per step, halts there when it does not ' +
+                'hold, and returns the un-run tail. Nothing was acted on.');
+        }
+        /*
+         * An `expect` this tool cannot parse is refused, never counted as nothing declared.
+         *
+         * The handler parses with the same schema and, on failure, recorded the step as having declared
+         * nothing. So `expect: { signal: "order:placed" }` — a plausible spelling, and wrong — came back
+         * as "all 3 steps declared nothing, so the app was driven but not verified". The agent HAD
+         * declared; nothing told it the declaration was discarded, and that sentence invites it to add
+         * the very thing it just wrote. Same false green as an unreadable key, through a key this tool
+         * does read.
+         */
+        if (step['expect'] !== undefined && !PredicateSchema.safeParse(step['expect']).success) {
+            throw new Error(`step ${String(i)} carries an \`expect\` this tool cannot parse. ` +
+                'A consequence is a predicate object with a `kind` — e.g. { kind: "signal", name: ' +
+                '"order:placed" }, { kind: "element", by: "testid", value: "receipt" }, or ' +
+                '{ kind: "settled" } — the same shape reticle_act_and_wait takes as `until`. ' +
+                'Refused rather than dropped, because a step whose declaration was discarded reports ' +
+                'as a step that declared nothing. Nothing was acted on.');
+        }
+        if ('string' === typeof step['ref'] && step['ref'].length > 0)
+            return;
+        if (step['target'] !== undefined)
+            return;
+        if (isGlobalPressCall(step))
+            return;
+        throw new Error(`step ${String(i)} has no \`ref\` or \`target\`. ` +
+            'Sequence steps take `ref` (from reticle_query/reticle_snapshot) or `target` ' +
+            '(e.g. { testid } or { label }), the same locator reticle_act accepts. ' +
+            'A press of Escape, Tab, or a modifier shortcut is a document key and needs neither. ' +
+            'Nothing was acted on — the whole sequence is refused so a bad step cannot leave the earlier ones half-applied.');
+    });
+}
+/**
+ * Throws if this call cannot honestly be driven. Call it after the args are parsed and before the
+ * first dispatch — anything that depends on what is actually rendered belongs after the action.
+ */
+export function preflightAct(actArgs, until) {
+    // This path cannot honour a native-input request, and taking the argument and ignoring it told
+    // the agent its trusted click had happened. See act-danger.
+    assertNativeInputSupported(actArgs);
+    const unevaluable = unevaluablePredicateReason(until);
+    if (unevaluable !== undefined)
+        throw new Error(unevaluable);
+    // A predicate that was already true when it was written answered `no-fault` / `already_true` —
+    // verdict-shaped, and carrying no proof of anything the action did. See vacuousPredicateReason.
+    const vacuous = vacuousPredicateReason(until);
+    if (vacuous !== undefined)
+        throw new Error(vacuous);
+}
+/**
+ * Dispatch a write, or report that its outcome went unobserved.
+ *
+ * Returns null — never throws — when the transport was displaced by a newer connection claiming the
+ * same id. That happens on any full-document navigation the act itself causes: the page unloads,
+ * re-announces, and the write in flight is rejected by the handle that just died.
+ *
+ * The write is deliberately NOT re-sent. Re-asking a READ on the successor is free; re-sending a
+ * WRITE is not, because nothing can prove the first one did not reach the page — and a duplicated
+ * click on a button that charges a card is a far worse outcome than a verdict of "I could not see".
+ * Every other failure propagates unchanged: only a replacement is an observation problem, and
+ * treating a timeout or a refusal as one would launder a real failure into a shrug.
+ */
+export async function dispatchAct(send) {
+    try {
+        return await send();
+    }
+    catch (error) {
+        if (error instanceof SessionReplacedError)
+            return null;
+        throw error;
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { Session } from '../../../portal/session/session.js';
+import { type TargetResolution } from './resolve-target.js';
+export declare function resolveActTarget(session: Session, args: Record<string, unknown>, 
+/**
+ * How long a named element may take to appear. Passed in rather than read from `args`, because
+ * the budget belongs to the CALL and the args here are one STEP of it — reading it from the step
+ * silently defaulted every batched step to the full budget while the caller's `timeout_ms: 0`
+ * was ignored.
+ */
+appearanceMs?: number): Promise<TargetResolution>;

package/dist/surface/tools/act/act-target.js

@@ -0,0 +1,100 @@
+/**
+ * Turn what the caller named into a ref: `ref` outright, or `target` via one page query.
+ *
+ * Split out of act-tools.ts when it crossed the 1000-line cap. Chosen deliberately over the ACT
+ * dispatcher, which looks like the more obvious seam and is not: `dispatch-attribution` asserts
+ * file-by-file that anything sending an ACT also opens an attribution window, so moving the
+ * dispatch out of the file that opens the window would have weakened a real invariant to satisfy a
+ * line count. This resolves a TARGET and dispatches only QUERY, so that guard is untouched.
+ */
+import { ReticleCommand, isGlobalPressCall } from '@reticlehq/core';
+import { normalizeQueryArgs } from '../read/query-shape.js';
+import { resolveTargetRef } from './resolve-target.js';
+import { asRecord, asString, asNumber } from '@reticlehq/core';
+import { appearanceDecision } from '@reticlehq/engine/window/appearance-budget.js';
+/**
+ * A press of Escape, Tab, or a modifier shortcut is a document key. Requiring a locator for it
+ * forced a snapshot just to name an element the keystroke is not about.
+ */
+const MISSING_ACT_TARGET = 'pass `ref` (from reticle_query/reticle_snapshot) or `target` (e.g. { testid } or { role, name }). ' +
+    'A press of Escape, Tab, or a modifier shortcut is a document key and needs neither.';
+/**
+ * Resolve an action's element: an explicit `ref`, or a `target` query resolved in the SAME call.
+ *
+ * Requiring a ref meant every verification paid a `reticle_query` turn first just to learn one
+ * string, and the advertised tool surface is re-sent on every turn — measured on the wire, a
+ * two-turn verification spent 10,756 of 11,235 tokens on schema and 479 on the actual answers. The
+ * lookup still happens; it just stops costing a round trip through the model.
+ *
+ * `ref` wins when both are given, because it is the more specific instruction and silently
+ * preferring the query would act on something the caller did not name.
+ *
+ * A document-key press (Escape, Tab, a modifier shortcut) is the one action that is not aimed at
+ * an element. It resolves to `{ kind: 'global' }` rather than refusing, so dismissing a dialog
+ * does not cost a snapshot.
+ */
+/**
+ * How long a named element may take to appear before the step gives up.
+ *
+ * Matches `act_and_wait`'s own settle budget: a step that waits for its element and then waits for
+ * its consequence should not be slow twice for two different reasons.
+ */
+const DEFAULT_APPEARANCE_MS = 8_000;
+export async function resolveActTarget(session, args, 
+/**
+ * How long a named element may take to appear. Passed in rather than read from `args`, because
+ * the budget belongs to the CALL and the args here are one STEP of it — reading it from the step
+ * silently defaulted every batched step to the full budget while the caller's `timeout_ms: 0`
+ * was ignored.
+ */
+appearanceMs) {
+    const ref = asString(args['ref']);
+    if (ref !== undefined && ref.length > 0)
+        return { kind: 'ref', ref };
+    const target = args['target'];
+    if (target === undefined) {
+        if (isGlobalPressCall(args))
+            return { kind: 'global', ref: '' };
+        return { kind: 'error', message: MISSING_ACT_TARGET };
+    }
+    const q = normalizeQueryArgs(asRecord(target));
+    /*
+     * Look again while the step's own budget lasts, instead of once.
+     *
+     * A batched journey names every step's element up front, and the element a later step acts on
+     * often does not exist when the batch is submitted — the modal step 1 opens, the row step 2
+     * creates. One query fails those instantly, and that single behaviour is why an agent gives up on
+     * batching and pays a model turn per step: snapshot, act, snapshot, act.
+     *
+     * `appearanceDecision` holds the safety rule and holds it FIRST: zero matches may be waited for,
+     * because nothing else could be acted on meanwhile, but MORE THAN ONE is refused immediately and
+     * is never waited out. Given time an ambiguous name can resolve to whichever element the race
+     * settled on, and that is a coin toss the caller never saw.
+     *
+     * `budgetMs` of 0 means the caller asked never to wait, and that still holds.
+     */
+    const budgetMs = Math.max(0, appearanceMs ?? asNumber(args['timeout_ms']) ?? DEFAULT_APPEARANCE_MS);
+    const startedAt = Date.now();
+    for (;;) {
+        const out = await session.command(ReticleCommand.QUERY, {
+            by: q['by'],
+            value: q['value'],
+            name: q['name'],
+            scope: q['scope'],
+        });
+        if (!out.ok)
+            return { kind: 'error', message: out.error ?? 'target query failed' };
+        const elements = asRecord(out.result)['elements'];
+        const found = Array.isArray(elements) ? elements : [];
+        const decision = appearanceDecision({
+            matches: found.length,
+            elapsedMs: Date.now() - startedAt,
+            budgetMs,
+        });
+        // One match, or an ambiguity: both are answered by the existing resolver, which already ranks
+        // candidates inside its refusal so the next turn needs no snapshot.
+        if ('wait' !== decision.do)
+            return resolveTargetRef(found);
+        await new Promise((resolve) => setTimeout(resolve, decision.waitMs));
+    }
+}

package/dist/surface/tools/act/navigation/navigate-arrival.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Wait, briefly, for the SDK to reconnect after a navigation — so `confirmed` can mean something.
+ *
+ * `window.location.assign(url)` destroys the SDK that would report on the new document, so the
+ * navigation itself cannot be confirmed from inside the page. But the SDK reconnects TO THE DAEMON,
+ * which makes the daemon the only party that can see arrival happen. Before this, it did not look,
+ * and told the agent to poll `reticle_sessions` instead — a tool call on every navigation, on the
+ * least reliable tool we ship.
+ *
+ * Bounded and best-effort by construction: a navigation to a page that is not instrumented, or not
+ * there at all, must still return promptly with `confirmed:false` rather than hanging. The clock and
+ * the sleep are injected so this is testable without waiting on a real one.
+ *
+ * The bound is the CALLER'S to set. It was a fixed 5s that `reticle_navigate` did not expose, and a
+ * Nuxt SPA reattaching under HMR was measured coming back in 30–60s — so every navigation to it
+ * answered `confirmed:false` while the app was still on its way, and nothing the agent could pass
+ * would make the daemon wait. `assert` / `wait_for` / `act_and_wait` all spend the caller's
+ * `timeout_ms` (resolve-within.ts); this is the same budget applied to the same wait.
+ */
+import type { SessionManager } from '../../../../portal/session/session-manager.js';
+import type { NavigateArrival } from './navigate-result.js';
+/**
+ * The default when the caller gives no `timeout_ms`: long enough for a dev server to serve a page
+ * and the SDK to dial back; short enough to not hang. A caller who knows the app is slower says so.
+ */
+export declare const ARRIVAL_TIMEOUT_MS = 5000;
+/**
+ * Which session an arrival may be attributed to.
+ *
+ * Arrival means a session is at the target BECAUSE OF THIS NAVIGATION. The scan had no notion of
+ * that: it returned the first session whose page matched, whoever it belonged to. A stale row parked
+ * on the origin — in the field report, one belonging to a different app that had previously held the
+ * same port — therefore answered for a navigation it had nothing to do with, and `reticle_navigate`
+ * reported ITS id as the session the caller had arrived at. Targeting was never wrong; the result
+ * was (#785).
+ *
+ * `sessions.all()` is Map insertion order, so the older stale row is scanned FIRST. That made the
+ * wrong id the likely answer rather than a coin flip.
+ */
+export interface ArrivalScope {
+    /**
+     * The session the navigation was dispatched to.
+     *
+     * Exempt from the exclusion below, because it is legitimately at the target both before and after
+     * a navigation that keeps the document — a reload, or a same-page route change. Excluding it would
+     * report `confirmed: false` for the navigations most likely to have worked.
+     */
+    navigatedId: string;
+    /** Sessions already on the target BEFORE dispatch. They cannot be evidence of this arrival. */
+    priorIds: ReadonlySet<string>;
+}
+/**
+ * The sessions already on `target` — the set `ArrivalScope.priorIds` is built from, sampled before
+ * the navigation is dispatched.
+ *
+ * Shares `samePage` with the arrival scan on purpose: "was it already there" and "is it there now"
+ * are the same question asked at two moments, and two spellings of it would eventually disagree.
+ */
+export declare function idsAtTarget(sessions: SessionManager, target: string): ReadonlySet<string>;
+export interface ArrivalClock {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * Poll until a session is present at `target`, or the budget runs out. Returns `null` on timeout —
+ * never throws, because a failure to confirm is a legitimate answer, not an error.
+ */
+export declare function awaitArrival(sessions: SessionManager, target: string, scope: ArrivalScope, timeoutMs?: number, clock?: ArrivalClock): Promise<NavigateArrival | null>;

package/dist/surface/tools/act/resolve-target.js

@@ -0,0 +1,115 @@
+import { asRecord, ElementState } from '@reticlehq/core';
+/**
+ * Roles that usually name the control an agent meant, ahead of a wrapping `generic` that
+ * happened to inherit the same accessible name (header CTA vs empty-state CTA).
+ */
+const ROLE_RANK = {
+    button: 0,
+    link: 1,
+    menuitem: 2,
+    tab: 3,
+    checkbox: 4,
+    radio: 5,
+    switch: 6,
+    option: 7,
+    combobox: 8,
+    textbox: 9,
+    searchbox: 10,
+};
+function roleRank(role) {
+    if ('string' !== typeof role)
+        return 100;
+    return ROLE_RANK[role] ?? 50;
+}
+function statesOf(c) {
+    return Array.isArray(c.states) ? c.states.filter((s) => 'string' === typeof s) : [];
+}
+function inViewport(c) {
+    return statesOf(c).includes(ElementState.IN_VIEWPORT);
+}
+/**
+ * Stable ranking for the refusal message only. Never used to pick — an action must not guess.
+ *
+ * Order: in-viewport over off-screen, then more-specific roles over `generic`. Visibility is
+ * already applied before this runs (hidden duplicates are filtered), so it is not a sort key here.
+ */
+function compareCandidates(a, b) {
+    const viewport = Number(inViewport(b)) - Number(inViewport(a));
+    if (0 !== viewport)
+        return viewport;
+    return roleRank(a.role) - roleRank(b.role);
+}
+/**
+ * Annotate where the candidate sits. `anyInViewport` is true when at least one sibling carried
+ * `inViewport` — only then is absence meaningful as off-screen. Without that signal, saying
+ * "off-screen" would invent a fact the descriptor never reported.
+ */
+function formatCandidate(c, anyInViewport) {
+    const role = 'string' === typeof c.role ? c.role : '?';
+    const name = 'string' === typeof c.name ? c.name : '';
+    const ref = 'string' === typeof c.ref ? c.ref : '?';
+    const visible = false !== c.visible;
+    let where;
+    if (!visible)
+        where = 'hidden';
+    else if (inViewport(c))
+        where = 'in-viewport';
+    else if (anyInViewport)
+        where = 'off-screen';
+    else
+        where = 'visible';
+    const head = name.length > 0 ? `${ref} (${role} "${name}"` : `${ref} (${role}`;
+    return `${head}; ${where})`;
+}
+/**
+ * Turn a target QUERY into the single ref an action can be performed on.
+ *
+ * `act_and_wait` took only a `ref`, so every verification cost a `reticle_query` turn first just to
+ * learn one string. The advertised tool surface is re-sent on every turn, so that extra turn was not
+ * a small cost: measured on the wire, a two-turn verification spent 10,756 of its 11,235 tokens on
+ * schema and 479 on the actual answers. Removing the turn removes half the schema bill.
+ *
+ * Ambiguity is an ERROR, never a pick. Choosing "the first match" would let a verification act on a
+ * different element than the author meant and still report success, which is the false green this
+ * product exists to prevent — and the failure is invisible, because the verdict describes the
+ * element it DID act on. The message names the candidates so the caller can narrow rather than guess.
+ *
+ * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
+ * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
+ * the two-turn path for no gain.
+ *
+ * When several remain, they are ranked (in-viewport, then role) inside the refusal only — so the
+ * agent can pass the top ref on the next turn without a snapshot. Ranking is never acted on here.
+ */
+export function resolveTargetRef(candidates) {
+    const all = candidates.map((c) => asRecord(c));
+    const visible = all.filter((c) => c.visible !== false);
+    const usable = visible.length > 0 ? visible : all;
+    if (0 === usable.length) {
+        return {
+            kind: 'error',
+            message: 'target matched no element. Nothing was acted on and no verdict is possible — widen the ' +
+                'query, or take a reticle_snapshot to see what is actually on the page.',
+        };
+    }
+    if (usable.length > 1) {
+        const ranked = [...usable].sort(compareCandidates);
+        const anyInViewport = ranked.some(inViewport);
+        const named = ranked
+            .slice(0, 5)
+            .map((c) => formatCandidate(c, anyInViewport))
+            .join(', ');
+        return {
+            kind: 'error',
+            message: `target matched ${String(usable.length)} elements and an action must not guess between ` +
+                `them (ranked: in-viewport, then role): ${named}. Narrow the query (add role/name/testid ` +
+                'or a scope), or pass an explicit `ref` from reticle_query.',
+        };
+    }
+    const only = usable[0];
+    const ref = only === undefined ? undefined : only.ref;
+    if ('string' !== typeof ref || 0 === ref.length) {
+        return { kind: 'error', message: 'target matched an element with no usable ref.' };
+    }
+    return { kind: 'ref', ref };
+}