@reticlehq/server 2.11.0 → 2.13.0

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[];