@reticlehq/server 2.12.0 → 2.13.1

package/dist/tools/act-preflight.js

@@ -0,0 +1,98 @@
+/**
+ * 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 { SessionReplacedError } from '../session/pending-commands.js';
+import { assertNativeInputSupported } from './act-danger.js';
+import { unevaluablePredicateReason } from '../events/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 only asks that every step names one of the
+ * two, and 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".
+ *
+ * A sub-step reads `ref`/`target`/`action`/`args` and nothing else, and the schema is a permissive
+ * record, so any of these was accepted and dropped. `until` is the likeliest of them 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. act_sequence cannot grade one; refusing and naming the tool that can is
+ * the same answer given to an unsupported native click, and for the same reason.
+ */
+const CONSEQUENCE_KEYS = ['until', 'expect', 'assert', 'waitFor'];
+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}\`, and reticle_act_sequence cannot grade it. ` +
+                'Sub-steps are dispatched, never asserted — the key would be dropped and the sequence ' +
+                'would report success having checked nothing. Drive the steps here, then prove the ' +
+                'consequence with reticle_act_and_wait on the LAST action (its `until` is graded), or ' +
+                'with reticle_assert after this call. Nothing was acted on.');
+        }
+        if ('string' === typeof step['ref'] && step['ref'].length > 0)
+            return;
+        if (step['target'] !== undefined)
+            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. ' +
+            '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);
+}
+/**
+ * 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/tools/act-sequence-retry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The two things a sequence step needs beyond a plain act: a retry when the ref goes stale under a
+ * re-render, and a result shaped for the per-step report.
+ *
+ * ── THE RETRY ─────────────────────────────────────────────────────────────────────────────────
+ *
+ * Refs are invalidated by a re-render, and `reticle_act_sequence` exists precisely because the
+ * caller cannot re-snapshot between steps. So `fill -> fill -> submit` fails on step two the moment
+ * step one causes React to re-render — and the SAME refs then work when the caller retries the whole
+ * sequence by hand, which is the tell: this is a race with the render, not a dead element. Losing
+ * the sequence to it makes the tool unusable for the exact shape it was built for.
+ *
+ * The fix is one retry, after the app has been given the grace period it already gets elsewhere, and
+ * ONLY for staleness. A genuinely gone element fails again immediately, and a step that failed for
+ * any other reason is never retried — a tool that quietly re-runs actions would turn one click into
+ * two, which is worse than the failure it was papering over.
+ */
+import { waitForReaction } from './react-grace.js';
+export declare const isStaleRefError: (error: string | undefined) => boolean;
+/** The shape a step attempt returns. Structural so this file needs nothing from the tool layer. */
+export interface StepOutcome {
+    ok: boolean;
+    error?: string | undefined;
+    result?: unknown;
+}
+/** Just enough of a session for the grace period. Same structural contract react-grace.ts uses. */
+type ReactionSource = Parameters<typeof waitForReaction>[0];
+/**
+ * Run one step, and retry it once if — and only if — its ref went stale under a re-render.
+ *
+ * `attempt` is called at most twice with identical arguments, so it must be the same idempotent
+ * dispatch the caller would have made itself.
+ */
+export declare function runStepWithStaleRetry(attempt: () => Promise<StepOutcome>, session: ReactionSource, since: number, budgetMs: number, opts?: {
+    sleep(ms: number): Promise<void>;
+}): Promise<StepOutcome>;
+/**
+ * One step's entry in the per-step report.
+ *
+ * Only the fields the underlying act actually produced. Copying them conditionally keeps a clean step
+ * from carrying a row of nulls that read as "we looked and found nothing" rather than "there was
+ * nothing to look for".
+ */
+export declare function describeStepResult(step: Record<string, unknown>, result: Record<string, unknown>): Record<string, unknown>;
+export {};

package/dist/tools/act-sequence-retry.js

@@ -0,0 +1,58 @@
+/**
+ * The two things a sequence step needs beyond a plain act: a retry when the ref goes stale under a
+ * re-render, and a result shaped for the per-step report.
+ *
+ * ── THE RETRY ─────────────────────────────────────────────────────────────────────────────────
+ *
+ * Refs are invalidated by a re-render, and `reticle_act_sequence` exists precisely because the
+ * caller cannot re-snapshot between steps. So `fill -> fill -> submit` fails on step two the moment
+ * step one causes React to re-render — and the SAME refs then work when the caller retries the whole
+ * sequence by hand, which is the tell: this is a race with the render, not a dead element. Losing
+ * the sequence to it makes the tool unusable for the exact shape it was built for.
+ *
+ * The fix is one retry, after the app has been given the grace period it already gets elsewhere, and
+ * ONLY for staleness. A genuinely gone element fails again immediately, and a step that failed for
+ * any other reason is never retried — a tool that quietly re-runs actions would turn one click into
+ * two, which is worse than the failure it was papering over.
+ */
+import { waitForReaction } from './react-grace.js';
+/** Matches the daemon's own wording, which error-recovery.ts also keys its STALE_REF hint off. */
+const STALE_REF = /no longer resolves to an element/i;
+export const isStaleRefError = (error) => error !== undefined && STALE_REF.test(error);
+const realSleep = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * Run one step, and retry it once if — and only if — its ref went stale under a re-render.
+ *
+ * `attempt` is called at most twice with identical arguments, so it must be the same idempotent
+ * dispatch the caller would have made itself.
+ */
+export async function runStepWithStaleRetry(attempt, session, since, budgetMs, opts = realSleep) {
+    const first = await attempt();
+    if (first.ok || !isStaleRefError(first.error))
+        return first;
+    await waitForReaction(session, since, budgetMs, opts);
+    return attempt();
+}
+/**
+ * One step's entry in the per-step report.
+ *
+ * Only the fields the underlying act actually produced. Copying them conditionally keeps a clean step
+ * from carrying a row of nulls that read as "we looked and found nothing" rather than "there was
+ * nothing to look for".
+ */
+export function describeStepResult(step, result) {
+    const out = {
+        ref: result['ref'] ?? step['ref'],
+        action: result['action'] ?? step['action'],
+        dispatched: result['dispatched'] ?? true,
+        settled: result['settled'] ?? null,
+        settleReason: result['settleReason'] ?? null,
+    };
+    for (const key of ['testid', 'component', 'role', 'name', 'source', 'warning']) {
+        if (result[key] !== undefined)
+            out[key] = result[key];
+    }
+    return out;
+}

package/dist/tools/act-sequence-tool.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `reticle_act_sequence` — several actions compiled into one round trip.
+ *
+ * Split out of `act-tools.ts` when that file passed the 1000-line backstop. A tool seam rather than
+ * an arbitrary one: its two neighbours drive ONE action and grade its consequence, while this one
+ * compiles a list of steps and runs them inside a single action window, reporting per step.
+ *
+ * It keeps its own `beginAction` — the dispatch and the attribution window that must wrap it stay in
+ * the same file, which is the property `dispatch-attribution.test.ts` enforces. An earlier attempt
+ * split the shared `actCommand` helper out instead, which separated the two and that guard caught it.
+ */
+import { type ToolDef } from './tool-kit.js';
+export declare const ACT_SEQUENCE_TOOL: ToolDef;

package/dist/tools/act-sequence-tool.js

@@ -0,0 +1,135 @@
+/**
+ * `reticle_act_sequence` — several actions compiled into one round trip.
+ *
+ * Split out of `act-tools.ts` when that file passed the 1000-line backstop. A tool seam rather than
+ * an arbitrary one: its two neighbours drive ONE action and grade its consequence, while this one
+ * compiles a list of steps and runs them inside a single action window, reporting per step.
+ *
+ * It keeps its own `beginAction` — the dispatch and the attribution window that must wrap it stay in
+ * the same file, which is the property `dispatch-attribution.test.ts` enforces. An earlier attempt
+ * split the shared `actCommand` helper out instead, which separated the two and that guard caught it.
+ */
+import { z } from 'zod';
+import { timeoutMsSchema } from './numeric-bounds.js';
+import { compileSequenceStep } from '../flows/replay.js';
+import { ReticleTool } from './tool-names.js';
+import { healthEnvelope } from '../session/session-health.js';
+import { pausedShortCircuit, pausedOutputShape, withControl } from '../session/control-envelope.js';
+import { asRecord, sessionIdFromArgs } from './tools-helpers.js';
+import { describeStepResult, runStepWithStaleRetry } from './act-sequence-retry.js';
+import { assertSequenceSteps } from './act-preflight.js';
+import { sessionIdShape } from './tool-kit.js';
+import { actCommand } from './act-tools.js';
+// resolveActTarget moved out of act-tools into its own module on this branch; #706 was written
+// against the older layout where act-tools re-exported it.
+import { resolveActTarget } from './act-target.js';
+export const ACT_SEQUENCE_TOOL = {
+    name: ReticleTool.ACT_SEQUENCE,
+    // The example is required for a core tool, and this one carries weight: the measured loop it
+    // replaces is literally a login form driven as three separate reticle_act calls (98 clicks and
+    // 21 fills inside looping sessions, 2026-08-10/11). Showing fill -> fill -> click is showing the
+    // exact shape an agent otherwise spends three round trips on.
+    example: {
+        steps: [
+            { ref: 'e12', action: 'fill', args: { value: 'a@b.com' } },
+            { ref: 'e13', action: 'fill', args: { value: 'hunter2' } },
+            { ref: 'e14', action: 'click' },
+        ],
+    },
+    description: 'Run multiple actions in order (fill -> fill -> submit) in ONE round-trip. Prefer this over repeating reticle_act for a multi-step journey, then assert its consequence once. Returns per-step effects[] (see reticle_act).',
+    inputSchema: {
+        steps: z
+            .array(z.record(z.unknown()))
+            .describe('Ordered list of { ref | target, action, args? } objects. Each step is equivalent to one reticle_act call — give `ref` from a snapshot/query, or `target` ({ testid } | { label } | { role, name } | { text }) to resolve in this call. Put confirmDangerous:true in a destructive step args object.'),
+        timeout_ms: timeoutMsSchema
+            .optional()
+            .describe('Per-step timeout in milliseconds. Default: 8000. Each step gets this budget independently.'),
+        ...sessionIdShape,
+    },
+    outputSchema: {
+        since: z.number(),
+        dispatched: z.boolean(),
+        completed: z.number(),
+        stalled_at: z.number().optional(),
+        steps: z.array(z.record(z.unknown())).optional(),
+        result: z.unknown().optional(),
+        session: z
+            .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
+            .optional(),
+        // Short-circuits to pausedShortCircuit while paused — declare its fields (drained-once guidance).
+        ...pausedOutputShape,
+    },
+    handler: async (deps, args) => {
+        const session = deps.sessions.resolve(sessionIdFromArgs(args));
+        const paused = pausedShortCircuit(session);
+        if (paused !== undefined)
+            return paused;
+        const since = session.elapsed();
+        session.beginAction(ReticleTool.ACT_SEQUENCE, asRecord(args));
+        try {
+            const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
+            assertSequenceSteps(inputSteps);
+            const perStepTimeout = 'number' === typeof args['timeout_ms'] ? args['timeout_ms'] : 8000;
+            const stepResults = [];
+            let stalledAt;
+            // DIVERGENCE: live sends N individual ACT commands (for per-step timeout + progress);
+            // replay sends one batched ACT_SEQUENCE command (flows/replay.ts:294). A bug in either is
+            // invisible from the other — cover both when changing sequence semantics.
+            for (let i = 0; i < inputSteps.length; i++) {
+                const step = asRecord(inputSteps[i]);
+                try {
+                    // One retry when the ref went stale under a re-render — see act-sequence-retry.ts.
+                    // Resolve `target` with the same helper reticle_act uses, then dispatch by ref. Passing
+                    // the unresolved step through used to send `ref: undefined` and the browser blamed a
+                    // stale empty ref — the caller went looking for a re-render instead of a missing locator.
+                    const outcome = await runStepWithStaleRetry(async () => {
+                        const resolved = await resolveActTarget(session, step);
+                        if ('error' === resolved.kind)
+                            return { ok: false, error: resolved.message };
+                        return actCommand(deps, session, { ref: resolved.ref, action: step['action'], args: step['args'] ?? {} }, perStepTimeout);
+                    }, session, since, perStepTimeout);
+                    if (!outcome.ok) {
+                        stalledAt = i;
+                        stepResults.push({
+                            ref: step['ref'],
+                            action: step['action'],
+                            dispatched: false,
+                            error: outcome.error ?? 'step failed',
+                        });
+                        break;
+                    }
+                    stepResults.push(describeStepResult(step, asRecord(outcome.result)));
+                }
+                catch (err) {
+                    stalledAt = i;
+                    stepResults.push({
+                        ref: step['ref'],
+                        action: step['action'],
+                        dispatched: null,
+                        timedOut: true,
+                        error: err instanceof Error ? err.message : 'step timed out',
+                    });
+                    break;
+                }
+            }
+            const completed = stalledAt ?? inputSteps.length;
+            if (completed > 0) {
+                session.lastAct.markActed(since, undefined, undefined);
+            }
+            if (deps.recordings.active().length > 0 && stalledAt === undefined) {
+                deps.recordings.capture(compileSequenceStep(args, { count: inputSteps.length, steps: stepResults }));
+            }
+            return withControl(session, {
+                since,
+                dispatched: completed > 0,
+                completed,
+                ...(stalledAt !== undefined ? { stalled_at: stalledAt } : {}),
+                steps: stepResults,
+                ...healthEnvelope(session),
+            });
+        }
+        finally {
+            session.finishAction();
+        }
+    },
+};

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

@@ -0,0 +1,14 @@
+import type { Session } from '../session/session.js';
+import { type TargetResolution } from './resolve-target.js';
+/**
+ * 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.
+ */
+export declare function resolveActTarget(session: Session, args: Record<string, unknown>): Promise<TargetResolution>;

package/dist/tools/act-target.js

@@ -0,0 +1,47 @@
+/**
+ * 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 } from '@reticlehq/core';
+import { normalizeQueryArgs } from './query-shape.js';
+import { resolveTargetRef } from './resolve-target.js';
+import { asRecord, asString } from './tools-helpers.js';
+/**
+ * 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.
+ */
+export async function resolveActTarget(session, args) {
+    const ref = asString(args['ref']);
+    if (ref !== undefined && ref.length > 0)
+        return { kind: 'ref', ref };
+    const target = args['target'];
+    if (target === undefined) {
+        return {
+            kind: 'error',
+            message: 'pass `ref` (from reticle_query/reticle_snapshot) or `target` (e.g. { testid } or { role, name }).',
+        };
+    }
+    const q = normalizeQueryArgs(asRecord(target));
+    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'];
+    return resolveTargetRef(Array.isArray(elements) ? elements : []);
+}

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

@@ -1,2 +1,22 @@
-import { type ToolDef } from './tool-kit.js';
+/**
+ * Action tools — reticle_act, reticle_act_sequence, reticle_act_and_wait. Split out of tools.ts to keep
+ * that file under the line cap and assembled back into the tool list there via ...ACT_TOOLS; the
+ * native-input attempt itself lives in real-input-attempt.ts for the same reason.
+ */
+import type { Session } from '../session/session.js';
+import { z } from 'zod';
+import { type ToolDef, type ToolDeps } from './tool-kit.js';
+/**
+ * Single dispatch point for every ACT and ACT_SEQUENCE command.
+ *
+ * This is the seam the reviewer asked for: instead of wiring rewriteUploadArgs at three separate
+ * call sites (reticle_act, reticle_act_and_wait, reticle_act_sequence) we intercept once here,
+ * which also covers flow-replay, crawl, and any future dispatch site that goes through this helper.
+ *
+ * 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, actArgs: Record<string, unknown>, timeoutMs?: number): Promise<import('@reticlehq/core').CommandResult>;
+export declare const actionTypeEnum: z.ZodEnum<[string, ...string[]]>;
 export declare const ACT_TOOLS: ToolDef[];