@reticlehq/server 3.8.2 → 3.10.0

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

@@ -1,4 +1,5 @@
-import { asRecord, ElementState } from '@reticlehq/core';
+import * as z from 'zod';
+import { asRecord, ElementState, NearestTargetSchema } 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).
@@ -17,8 +18,9 @@ const ROLE_RANK = {
     searchbox: 10,
 };
 function roleRank(role) {
-    if ('string' !== typeof role)
+    if ('string' !== typeof role) {
         return 100;
+    }
     return ROLE_RANK[role] ?? 50;
 }
 function statesOf(c) {
@@ -35,8 +37,9 @@ function inViewport(c) {
  */
 function compareCandidates(a, b) {
     const viewport = Number(inViewport(b)) - Number(inViewport(a));
-    if (0 !== viewport)
+    if (0 !== viewport) {
         return viewport;
+    }
     return roleRank(a.role) - roleRank(b.role);
 }
 /**
@@ -50,14 +53,18 @@ function formatCandidate(c, anyInViewport) {
     const ref = 'string' === typeof c.ref ? c.ref : '?';
     const visible = false !== c.visible;
     let where;
-    if (!visible)
+    if (!visible) {
         where = 'hidden';
-    else if (inViewport(c))
+    }
+    else if (inViewport(c)) {
         where = 'in-viewport';
-    else if (anyInViewport)
+    }
+    else if (anyInViewport) {
         where = 'off-screen';
-    else
+    }
+    else {
         where = 'visible';
+    }
     const head = name.length > 0 ? `${ref} (${role} "${name}"` : `${ref} (${role}`;
     return `${head}; ${where})`;
 }
@@ -76,6 +83,42 @@ function nearNamesClause(hint) {
         'Use that name, or — when the name carries a part that changes, like a time — target it by ' +
         '`testid` or by `text` (a contained match).');
 }
+/**
+ * What a result says when every match was hidden and the action used the hidden one. It does not
+ * say that a person could not reach it: a hidden input with a visible label is reached through the
+ * label, and the reach check after the action decides that.
+ */
+export function hiddenTargetNote(ref) {
+    return (`every element that matched the target is hidden, so the action used the hidden match ${ref}. ` +
+        'If a person reaches it through a visible label, this is correct. If not, target the control ' +
+        'a person can see.');
+}
+/** The `hiddenTarget` field for a tool result, or nothing when the action used a visible match. */
+export function hiddenTargetField(resolution) {
+    if ('ref' !== resolution.kind || resolution.hiddenTarget === undefined) {
+        return {};
+    }
+    return { hiddenTarget: resolution.hiddenTarget };
+}
+const NearestTargetsSchema = z.array(NearestTargetSchema).min(1);
+/** The words before the nearest-target list in a no_match refusal. The repeat hint reads after it. */
+export const NEAREST_TARGETS_LEAD = ' The nearest targets on the page, most similar first: ';
+/**
+ * The browser's `nearest` hint as a sentence: the targets most like the one asked for, with refs,
+ * so the retry is one call and not a snapshot loop. Empty when there is no list. It is advice
+ * only: the action stays refused, and nothing here picks a target.
+ */
+function nearestClause(hint) {
+    const parsed = NearestTargetsSchema.safeParse(asRecord(hint)['nearest']);
+    if (!parsed.success) {
+        return '';
+    }
+    const listed = parsed.data
+        .map((t) => `${t.ref} (${t.role} "${t.name}${true === t.nameTruncated ? '…' : ''}")`)
+        .join(', ');
+    return (`${NEAREST_TARGETS_LEAD}${listed}. If one of them is the ` +
+        'element you meant, pass its ref as `ref`.');
+}
 /**
  * Turn a target QUERY into the single ref an action can be performed on.
  *
@@ -91,7 +134,9 @@ function nearNamesClause(hint) {
  *
  * 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.
+ * the two-turn path for no gain. When every match is hidden, the one hidden match is used and the
+ * resolution names it in `hiddenTarget`. It is not refused: a hidden input is often clicked through
+ * its visible label.
  *
  * 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.
@@ -104,7 +149,8 @@ export function resolveTargetRef(candidates, hint) {
         return {
             kind: 'error',
             message: 'target matched no element. Nothing was acted on and no verdict is possible — ' +
-                nearNamesClause(hint),
+                nearNamesClause(hint) +
+                nearestClause(hint),
         };
     }
     if (usable.length > 1) {
@@ -126,5 +172,9 @@ export function resolveTargetRef(candidates, hint) {
     if ('string' !== typeof ref || 0 === ref.length) {
         return { kind: 'error', message: 'target matched an element with no usable ref.' };
     }
+    // Every match was hidden, so the action uses a hidden one. Rule 11: say so, never silently.
+    if (0 === visible.length) {
+        return { kind: 'ref', ref, hiddenTarget: hiddenTargetNote(ref) };
+    }
     return { kind: 'ref', ref };
 }

package/dist/surface/tools/act/sequence-grade.d.ts

@@ -14,7 +14,7 @@
  * is verified FOR THOSE THREE and silent about nine, and `because` says so — reporting it as "25%
  * verified" would be the arithmetic that hides the nine.
  */
-import { Verified } from '@reticlehq/core';
+import { Verified, VerifiedReason } from '@reticlehq/core';
 /**
  * What to do when a step's declared consequence does not hold.
  *
@@ -46,9 +46,21 @@ export interface StepExpectation {
      * step is undecided, never a miss — `unknown`, as act_and_wait says.
      */
     undecided?: string;
+    /** The step's action (`click`, `fill`), so a plan that could not judge a step can name it. */
+    action?: string;
+    /** A real frame flushed after this step's action, as `settled` on its act result says. */
+    settled?: boolean;
+    /**
+     * Absence-derived contradiction kinds seen in this step's window (a request that never settled,
+     * for example). They do not decide a miss, but they stop a plan from claiming no channel saw a
+     * problem.
+     */
+    doubted?: readonly string[];
 }
 export interface SequenceGrade {
     verified: Verified;
+    /** The deciding clause, from core's list, so a sequence verdict is counted by reason like any other. */
+    reason: VerifiedReason;
     /** Steps that declared a consequence. */
     declared: number;
     total: number;
@@ -67,6 +79,8 @@ interface SequencePlan {
     readonly planned: number;
     /** Whether anything actually reached the page. */
     readonly dispatched: boolean;
+    /** The capture lost events inside the plan's window, so no channel saw all of it. */
+    readonly captureLost?: boolean;
 }
 export declare function gradeSequence(steps: readonly StepExpectation[], plan?: SequencePlan): SequenceGrade;
 /**

package/dist/surface/tools/act/sequence-grade.js

@@ -14,7 +14,7 @@
  * is verified FOR THOSE THREE and silent about nine, and `because` says so — reporting it as "25%
  * verified" would be the arithmetic that hides the nine.
  */
-import { Verified } from '@reticlehq/core';
+import { Verified, VerifiedReason } from '@reticlehq/core';
 /**
  * What to do when a step's declared consequence does not hold.
  *
@@ -23,6 +23,23 @@ import { Verified } from '@reticlehq/core';
  * sweep of independent controls, where stopping at the first would hide the other thirteen.
  */
 export const DeviationMode = { HALT: 'halt', CONTINUE: 'continue' };
+/** The sentence for a plan whose steps declared nothing. */
+function undeclaredBecause(total, dispatched) {
+    if (0 === total) {
+        return 'the plan had no steps, so nothing was driven and nothing was proved';
+    }
+    // A step refused before dispatch is a malformed call: telling its author to add an `expect`
+    // sends them to the wrong thing.
+    if (!dispatched) {
+        return `nothing was dispatched, so none of the ${String(total)} step(s) ran — read the per-step \`error\` for the one that was refused, and fix that before adding an \`expect\``;
+    }
+    return `all ${String(total)} step(s) declared nothing, so the app was driven but not verified — give each step an \`expect\` naming the consequence it causes`;
+}
+/** A step as a sentence names it: its number, counted from 1, and its action when it has one. */
+function stepName(index, action) {
+    const number = `step ${String(index + 1)}`;
+    return action === undefined ? number : `${number} (${action})`;
+}
 export function gradeSequence(steps, plan = { planned: steps.length, dispatched: true }) {
     const total = Math.max(plan.planned, steps.length);
     const declaring = steps.filter((step) => step.declared);
@@ -36,6 +53,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
         const observed = missed.observed ?? 'nothing that matched';
         return {
             verified: Verified.NO,
+            reason: VerifiedReason.ASSERTION_FAILED,
             declared,
             total,
             because: `a declared consequence did not hold — observed ${observed}`,
@@ -47,47 +65,43 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
         const kinds = (steps[contradictedAt]?.contradicted ?? []).join(', ');
         return {
             verified: Verified.NO,
+            reason: VerifiedReason.CONTRADICTED,
             declared,
             total,
             because: `step ${String(contradictedAt + 1)}: channels disagree about this action (${kinds}) even though it went on`,
         };
     }
-    // Nothing failed that was seen: a step nobody could judge leaves the plan undecided, saying why.
-    const unjudged = steps.find((step) => step.undecided !== undefined);
-    if (unjudged !== undefined)
+    // Nothing failed that was seen: a step nobody could judge leaves the plan undecided. The sentence
+    // names the step and what was missing, so the agent knows which step to change (#2204).
+    const unjudgedAt = steps.findIndex((step) => step.undecided !== undefined);
+    if (unjudgedAt >= 0) {
+        const unjudged = steps[unjudgedAt];
         return {
             verified: Verified.UNKNOWN,
+            reason: VerifiedReason.INCONCLUSIVE,
             declared,
             total,
-            because: `a step could not be judged — ${unjudged.undecided ?? ''}`,
+            because: `${stepName(unjudgedAt, unjudged?.action)} could not be judged: ${unjudged?.undecided ?? ''}`,
         };
+    }
     /*
-     * `unknown` rather than `no-fault`, and the distinction is load-bearing.
-     *
-     * "Nothing was declared" is what `no-fault` means for a single action -- but the engine only says
-     * it over a SETTLED window, because no-fault claims the whole window was observed. Nothing on
-     * this path observes settledness: the caller tracks dispatch and stalls, never settle. Saying
-     * `no-fault` here would claim evidence nobody collected, in the one place this product cannot
-     * afford to overclaim.
-     *
-     * So the enum stays conservative and the SENTENCE carries the whole answer: it names declaring a
-     * consequence as the next move, which is what an agent reading `no-fault` would have done.
-     * Upgrading means plumbing `settled` from the act results through `SequencePlan`.
+     * Nothing declared is `no-fault` over a quiet plan and `unknown` otherwise. This is the rule a
+     * single action follows (`engine/src/evidence/verified.ts`): no-fault claims the whole window was
+     * observed, so every step must report a settled frame, no step may carry an absence-derived
+     * finding, and the capture must be whole. `unknown` sends an agent to look again with better
+     * coverage. When the plan was quiet, that cannot help: the fix is to declare a consequence.
      */
     if (0 === declared) {
+        const quiet = plan.dispatched &&
+            true !== plan.captureLost &&
+            steps.length > 0 &&
+            steps.every((step) => true === step.settled && 0 === (step.doubted ?? []).length);
         return {
-            verified: Verified.UNKNOWN,
+            verified: quiet ? Verified.NO_FAULT : Verified.UNKNOWN,
+            reason: VerifiedReason.NOTHING_DECLARED,
             declared,
             total,
-            because: 0 === total
-                ? 'the plan had no steps, so nothing was driven and nothing was proved'
-                : // "the app was driven" was said unconditionally, including on a call whose own
-                    // `dispatched` was false in the same object. A step refused before dispatch is a
-                    // malformed call, and telling its author to add an `expect` sends them at the wrong
-                    // thing entirely.
-                    plan.dispatched
-                        ? `all ${String(total)} step(s) declared nothing, so the app was driven but not verified — give each step an \`expect\` naming the consequence it causes`
-                        : `nothing was dispatched, so none of the ${String(total)} step(s) ran — read the per-step \`error\` for the one that was refused, and fix that before adding an \`expect\``,
+            because: undeclaredBecause(total, plan.dispatched),
         };
     }
     // A journey is proved at its END. Declaring only early steps checks that it started, and a yes
@@ -95,6 +109,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     if (steps.length < total) {
         return {
             verified: Verified.UNKNOWN,
+            reason: VerifiedReason.EVIDENCE_INCOMPLETE,
             declared,
             total,
             because: `only ${String(steps.length)} of ${String(total)} steps ran, so the journey never reached its end`,
@@ -103,6 +118,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     if (true !== steps.at(-1)?.declared) {
         return {
             verified: Verified.UNKNOWN,
+            reason: VerifiedReason.EVIDENCE_INCOMPLETE,
             declared,
             total,
             because: `the last step, where the journey ends, declared nothing — give it an \`expect\` naming the end state (${String(declared)} of ${String(total)} steps declared one)`,
@@ -110,6 +126,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     }
     return {
         verified: Verified.YES,
+        reason: VerifiedReason.PROVED,
         declared,
         total,
         because: declared === total
@@ -137,8 +154,9 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
 /** The stopped recording a proved journey is held under, so the `keep` offer can be taken. */
 export const JOURNEY_RECORDING = 'last-journey';
 export function offerToKeep(grade) {
-    if (grade.verified !== Verified.YES || 0 === grade.declared)
+    if (grade.verified !== Verified.YES || 0 === grade.declared) {
         return undefined;
+    }
     return (`this plan proved something (${String(grade.declared)} of ${String(grade.total)} steps declared a ` +
         'consequence and every one held) — keep it as a regression flow with ' +
         `reticle_flow_save { flowName: "${JOURNEY_RECORDING}", saveAs: "<name>" }, and the steps that declared nothing will replay ` +

package/dist/surface/tools/act/settle-in-flight.js

@@ -27,7 +27,7 @@
  *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
  *     limit instead of an early exit.
  */
-import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic, urlForMatch, } from '@reticlehq/core';
+import { EventType, isDevToolingUrl, isForeignTraffic, neverAnswered, urlForMatch, } from '@reticlehq/core';
 /**
  * What a URL is matched against, as opposed to what is shown.
  *
@@ -81,10 +81,11 @@ const isForeign = (data, appOrigin, background) => isForeignTraffic(matchUrlOf(d
  * NET_REQUEST, so counting it as outstanding would mean no page containing an outbound link or a
  * download button ever settles again. See `NetInitiator.NAVIGATION`.
  *
- * The `settled` predicate asks the same question in `evalSettled`; it spells it against this same
- * constant rather than against a string, which is what keeps the two answers one vocabulary.
+ * The `settled` predicate asks the same question in `evalSettled`. Both read core's `neverAnswered`,
+ * which keeps the two answers one rule. It also covers a request whose page unloaded before its
+ * answer arrived (#1944).
  */
-const isDeparture = (data) => data['initiator'] === NetInitiator.NAVIGATION;
+const isDeparture = neverAnswered;
 /** How often to re-read the buffer. Short enough to return promptly, long enough not to spin. */
 const POLL_MS = 50;
 const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
@@ -98,21 +99,26 @@ const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
 export function inFlightRequestIds(events, appOrigin, background = []) {
     const settled = new Set();
     for (const e of events) {
-        if (e.type !== EventType.NET_REQUEST)
+        if (e.type !== EventType.NET_REQUEST) {
             continue;
+        }
         const id = idOf(e.data);
-        if (id !== undefined)
+        if (id !== undefined) {
             settled.add(id);
+        }
     }
     const open = [];
     for (const e of events) {
-        if (e.type !== EventType.NET_PENDING || isDevTooling(e.data) || isDeparture(e.data))
+        if (e.type !== EventType.NET_PENDING || isDevTooling(e.data) || isDeparture(e.data)) {
             continue;
-        if (isForeign(e.data, appOrigin, background))
+        }
+        if (isForeign(e.data, appOrigin, background)) {
             continue;
+        }
         const id = idOf(e.data);
-        if (id !== undefined && !settled.has(id) && !open.includes(id))
+        if (id !== undefined && !settled.has(id) && !open.includes(id)) {
             open.push(id);
+        }
     }
     return open;
 }
@@ -128,11 +134,13 @@ export function inFlightRequestLabels(events, appOrigin, background = []) {
     const open = new Set(inFlightRequestIds(events, appOrigin, background));
     const labels = [];
     for (const e of events) {
-        if (e.type !== EventType.NET_PENDING)
+        if (e.type !== EventType.NET_PENDING) {
             continue;
+        }
         const id = idOf(e.data);
-        if (id === undefined || !open.has(id))
+        if (id === undefined || !open.has(id)) {
             continue;
+        }
         open.delete(id); // one label per request, however many times its start was recorded
         const method = 'string' === typeof e.data['method'] ? e.data['method'] : 'request';
         const url = 'string' === typeof e.data['url'] ? e.data['url'] : 'an unreported url';
@@ -158,8 +166,9 @@ const MIN_REPEATS = 2;
 export function repeatedRequestLabels(events) {
     const counts = new Map();
     for (const e of events) {
-        if (e.type !== EventType.NET_REQUEST || isDevTooling(e.data))
+        if (e.type !== EventType.NET_REQUEST || isDevTooling(e.data)) {
             continue;
+        }
         const method = 'string' === typeof e.data['method'] ? e.data['method'] : 'request';
         const url = 'string' === typeof e.data['url'] ? e.data['url'] : 'an unreported url';
         const key = `${method} ${url}`;
@@ -182,17 +191,20 @@ export async function waitForInFlight(session, since, budgetMs, opts) {
     // The verdict's own scope: waiting on a request the verdict will not count is latency for nothing.
     const outstanding = () => inFlightRequestIds(session.eventsSince(since), session.url, session.background);
     let open = outstanding();
-    if (0 === open.length)
+    if (0 === open.length) {
         return { settled: true, stillInFlight: [] };
-    if (budgetMs <= 0)
+    }
+    if (budgetMs <= 0) {
         return { settled: false, stillInFlight: open };
+    }
     const deadline = session.elapsed() + budgetMs;
     while (session.elapsed() < deadline) {
         // Never overshoot the budget: the last sleep is trimmed to whatever is actually left.
         await opts.sleep(Math.min(POLL_MS, deadline - session.elapsed()));
         open = outstanding();
-        if (0 === open.length)
+        if (0 === open.length) {
             return { settled: true, stillInFlight: [] };
+        }
     }
     return { settled: false, stillInFlight: open };
 }

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

@@ -0,0 +1,23 @@
+/**
+ * The single dispatch point for every ACT and ACT_SEQUENCE command, extracted from
+ * act-tools.ts at the 1000-line cap.
+ *
+ * Attribution: this dispatch does NOT open its own window — the CALLER wraps it in
+ * `session.beginAction` / `finishAction` with the tool it serves (act, act_and_wait, act_sequence
+ * pass their own `command`), so the window covers the whole flow around the dispatch, not just
+ * the send.
+ */
+import { ReticleCommand } from '@reticlehq/core';
+import type { Session } from '../../portal/session/session.js';
+import type { ToolDeps } from './tool-kit.js';
+/**
+ * Single dispatch point for every ACT and ACT_SEQUENCE command.
+ *
+ * reticle_act, act_and_wait and act_sequence rewrite uploads here, once. The path resolves against
+ * the session's project, not the daemon's folder, so a worktree uploads its own fixture (#1769).
+ *
+ * captureAct is called AFTER this, so the flow-recording captures the pre-rewrite args (the path
+ * the agent actually wrote) rather than the base64 blob — replay would otherwise send 750 KiB of
+ * base64 to the browser as if it were an inline content call.
+ */
+export declare function actCommand(deps: ToolDeps, session: Session, command: ReticleCommand, rawActArgs: Record<string, unknown>, timeoutMs?: number, realTried?: boolean): Promise<import('@reticlehq/core').CommandResult>;

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

@@ -0,0 +1,50 @@
+/**
+ * The single dispatch point for every ACT and ACT_SEQUENCE command, extracted from
+ * act-tools.ts at the 1000-line cap.
+ *
+ * Attribution: this dispatch does NOT open its own window — the CALLER wraps it in
+ * `session.beginAction` / `finishAction` with the tool it serves (act, act_and_wait, act_sequence
+ * pass their own `command`), so the window covers the whole flow around the dispatch, not just
+ * the send.
+ */
+import { ActionType, ReticleCommand, asRecord, asString } from '@reticlehq/core';
+import { rewriteUploadArgs, tryRealInput, HOVER_NEEDS_POINTER_MSG } from './real-input-attempt.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { normalizeTypeSpelling } from './type-spelling.js';
+/**
+ * Single dispatch point for every ACT and ACT_SEQUENCE command.
+ *
+ * reticle_act, act_and_wait and act_sequence rewrite uploads here, once. The path resolves against
+ * the session's project, not the daemon's folder, so a worktree uploads its own fixture (#1769).
+ *
+ * captureAct is called AFTER this, so the flow-recording captures the pre-rewrite args (the path
+ * the agent actually wrote) rather than the base64 blob — replay would otherwise send 750 KiB of
+ * base64 to the browser as if it were an inline content call.
+ */
+export async function actCommand(deps, session, command, rawActArgs, timeoutMs, realTried = false) {
+    const actArgs = normalizeTypeSpelling(rawActArgs);
+    const rewritten = await rewriteUploadArgs({ fs: deps.fs, reticleRoot: sessionRoot(deps, session.id) }, 'string' === typeof actArgs['action'] ? actArgs['action'] : '', asRecord(actArgs['args']));
+    // Sequence and act_and_wait dispatch through here without the ACT handler's tryRealInput.
+    // A synthetic hover reports dispatched/settled while CSS :hover never applies — drive a real
+    // pointer when one is available, otherwise refuse rather than lie. A press on a lease takes its
+    // real keyboard, as reticle_act does: a synthetic Tab moves no focus.
+    const hover = ActionType.HOVER === actArgs['action'];
+    if (!realTried && (hover || ActionType.PRESS === actArgs['action'])) {
+        const ref = asString(actArgs['ref']);
+        if (hover && ref === undefined) {
+            throw new Error(HOVER_NEEDS_POINTER_MSG);
+        }
+        const action = hover ? ActionType.HOVER : ActionType.PRESS;
+        const real = await tryRealInput(deps, session, ref ?? '', action, actArgs);
+        if (hover && real.result === undefined) {
+            throw new Error(HOVER_NEEDS_POINTER_MSG);
+        }
+        if (real.result !== undefined) {
+            const result = { dispatched: true, settled: real.settled, ...asRecord(real.result) };
+            return { kind: 'command_result', id: action, ok: true, result };
+        }
+    }
+    const bridgeArgs = { ...actArgs, args: rewritten };
+    // What the acted element shows (test id, source) is noted in `Session.command`, Harness acts too.
+    return session.command(command, bridgeArgs, timeoutMs);
+}