@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,330 @@
+/**
+ * `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 './args/numeric-bounds.js';
+import { compileSequenceStep } from '../../language/flows/replay.js';
+import { sequenceStepArgs } from './act/act-preflight.js';
+import { ReticleTool } from '@reticlehq/core';
+import { healthEnvelope } from '../../portal/session/session-health.js';
+import { pausedShortCircuit, pausedOutputShape, withControl, } from '../../portal/session/control-envelope.js';
+import { asRecord } from '@reticlehq/core';
+import { sessionIdFromArgs } from './tools-helpers.js';
+import { describeStepResult, runStepWithStaleRetry } from './act/act-sequence-retry.js';
+import { assertSequenceSteps } from './act/act-preflight.js';
+import { sessionIdShape } from './tool-kit.js';
+import { actCommand } from './act-tools.js';
+import { PredicateSchema, waitForPredicate, } from '@reticlehq/engine/question/predicate/predicate.js';
+import { DeviationMode, gradeSequence, offerToKeep, } from './act/sequence-grade.js';
+import { stepEffect } from '@reticlehq/engine/evidence/step-effect.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/act-target.js';
+/**
+ * The step's effect record, best-effort.
+ *
+ * An observation must never be able to fail the action it describes. This repo already states that
+ * rule for progress reporters -- "a reporter must never be able to fail the thing it is reporting
+ * on" -- and it holds harder here: a session shape without an event reader would otherwise throw
+ * INSIDE the step loop, be caught as a step failure, and abort the rest of a journey that was
+ * running perfectly. The drive is the product; the description of it is not.
+ */
+function effectOf(session, since) {
+    try {
+        return stepEffect(session.eventsSince(since), { since, until: session.elapsed() });
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Ceiling for a burst gap. Past this it is not a burst, it is a paced walk.
+ *
+ * HOW TO PICK A GAP, because both edges are real and neither is guessable. It must outlast the
+ * handler committing and dispatching its request, and undercut the response it is racing.
+ * Measured against a superseded-filter race (the superseded query 700ms, the one replacing it 90ms):
+ * at 0ms the first request was never issued at all, and at the ordinary settle (~500ms in a
+ * throttled tab, where rAF never fires and the frame budget always times out) the two clicks
+ * serialised and never overlapped. 50ms sat in the window. A different app needs a different
+ * number: read its own slow endpoint.
+ */
+const BURST_MAX_GAP_MS = 500;
+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: "Drive a WHOLE journey in ONE round-trip, with NO snapshot first. Name each step's element by {testid} | {label} | {role,name} | {text} in `target` and Reticle resolves it AT THE MOMENT THAT STEP RUNS — so a control that does not exist yet (a modal an earlier step opens, a row it creates) is still addressable, and waits up to timeout_ms to appear. This is the fast path: snapshot -> act -> snapshot -> act costs a model turn per step and is the slowest thing an agent can do. Give each step an `expect` and the sequence stops at the first one that does not hold, returning the un-run `tail` verbatim so you re-plan only the failure. Returns per-step effects[] (see reticle_act).",
+    inputSchema: {
+        steps: z
+            .array(z.record(z.unknown()))
+            .describe('Ordered list of { ref | target, action, args?, expect? } objects. Each step is equivalent to one reticle_act call, and takes its arguments either way: `{ ref, action: "fill", value: "…" }` flat, as reticle_act does, or nested as `args: { value }`. 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. `expect` is the same predicate shape as reticle_act_and_wait `until`, and it is what makes a step PROVE something: a step without one is driven, not verified, and the result says so. Naming the consequence is also FASTER — a named consequence is detected the instant it fires, where waiting for the page to settle can only conclude by waiting for silence.'),
+        // A plain number, not boolean|number: a zod union serialises to a JSON-Schema `anyOf` that
+        // cost 174 B on a surface re-sent every turn, against 81 B of headroom. One spelling is also
+        // the better API — `burst: 50` says what it does, where `burst: true` hides a magic default.
+        burst: z
+            .number()
+            .min(0)
+            .max(BURST_MAX_GAP_MS)
+            .optional()
+            .describe('ms gap between dispatches, to provoke an ordering race (try 50). Omit to settle.'),
+        onDeviation: z
+            .enum([DeviationMode.HALT, DeviationMode.CONTINUE])
+            .optional()
+            .describe('What to do when a step\'s `expect` does not hold. "halt" (default) stops there and returns the un-run tail — right for a dependent chain, where continuing past a broken login produces meaningless failures. "continue" drives every step and reports all misses — right for a sweep of independent controls.'),
+        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(),
+        /** Index of the step whose declared consequence did not hold, when one did not. */
+        stopped_at: z.number().optional(),
+        /** THE field to gate on: "yes" | "no" | "unknown" — see `because`. */
+        verified: z.string().optional(),
+        because: z.string().optional(),
+        /**
+         * Present only when the plan PROVED something — see `offerToKeep`. A plan that declared nothing
+         * replays green whatever the app does, so offering to keep it would manufacture regression
+         * coverage that cannot go red.
+         */
+        keep: z.string().optional(),
+        /** How many steps declared a consequence, of how many were driven. Never averaged away. */
+        coverage: z.object({ declared: z.number(), total: z.number() }).optional(),
+        /** Steps never run, verbatim, so a caller re-plans the failure rather than the whole journey. */
+        tail: z.array(z.record(z.unknown())).optional(),
+        /**
+         * Each step carries the same effect record a REPLAYED step carries: `window` (the
+         * `reticle_observe { since, until }` drill address), `digest` (what the app did, as counts) and
+         * `contradictions` (channels that disagree, present even when the step passed). Declared here
+         * because an undeclared field is stripped from structuredContent and would be silently lost.
+         */
+        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 = [];
+            const expectations = [];
+            // `true` means the default window; a number means that window exactly. 0 is legal and means
+            // "no settle at all" — useful only when the app issues its request synchronously.
+            const burstArg = args['burst'];
+            const burstGapMs = 
+            // The schema declares the same bounds, so this clamp is belt-and-braces — it matters for
+            // the replay path, which reaches this handler without the advertised schema in front of it.
+            'number' === typeof burstArg && Number.isFinite(burstArg)
+                ? Math.max(0, Math.min(burstArg, BURST_MAX_GAP_MS))
+                : undefined;
+            const onDeviation = DeviationMode.CONTINUE === args['onDeviation']
+                ? DeviationMode.CONTINUE
+                : DeviationMode.HALT;
+            let stalledAt;
+            let stoppedAt;
+            // 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]);
+                const stepSince = session.elapsed();
+                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, perStepTimeout);
+                        if ('error' === resolved.kind)
+                            return { ok: false, error: resolved.message };
+                        // In burst mode every step carries a zero settle budget, so step N+1 is dispatched
+                        // while step N is still in flight. That overlap IS the test — see `burst` above.
+                        return actCommand(deps, session, {
+                            ref: resolved.ref,
+                            action: step['action'],
+                            // `sequenceStepArgs` reads a step's arguments flat OR nested — keep it, it is the
+                            // fix for `{ ref, action: "fill", value }` silently losing `value`. Burst only
+                            // LAYERS on top: return as soon as the dispatch is in, because the gap below, not
+                            // the settle, is what paces the sequence. Leaving the default settle here would
+                            // race rAF and return early anyway — a budget is a CEILING, not a floor, which is
+                            // why an earlier attempt to pace with `settleMs` alone produced a 12ms step and
+                            // no race at all.
+                            args: burstGapMs === undefined
+                                ? sequenceStepArgs(step)
+                                : { ...sequenceStepArgs(step), settleMs: 0 },
+                        }, perStepTimeout);
+                    }, session, since, perStepTimeout);
+                    // Hold the gap BEFORE the next dispatch, measured from this step's own start so the
+                    // pacing is the interval between ACTIONS, not the interval plus however long this step
+                    // happened to take. The last step needs no gap: nothing follows it to race.
+                    if (burstGapMs !== undefined && i < inputSteps.length - 1) {
+                        const elapsed = session.elapsed() - stepSince;
+                        const remaining = burstGapMs - elapsed;
+                        if (remaining > 0)
+                            await new Promise((r) => setTimeout(r, remaining));
+                    }
+                    if (!outcome.ok) {
+                        stalledAt = i;
+                        stepResults.push({
+                            ref: step['ref'],
+                            action: step['action'],
+                            dispatched: false,
+                            error: outcome.error ?? 'step failed',
+                        });
+                        expectations.push({
+                            declared: undefined !== step['expect'],
+                            held: false,
+                            observed: outcome.error ?? 'the step could not be performed',
+                        });
+                        break;
+                    }
+                    /*
+                     * The SAME effect record a replayed step carries, from the same builder.
+                     *
+                     * A planned step driven now and the identical step replayed tomorrow have to describe what
+                     * happened in one vocabulary, or the before/after comparison this product exists for
+                     * cannot be read. Sharing the builder is what makes that true by construction rather than
+                     * by two implementations agreeing today.
+                     */
+                    const described = {
+                        ...describeStepResult(step, asRecord(outcome.result)),
+                        ...effectOf(session, stepSince),
+                    };
+                    /*
+                     * Evaluate what the step SAID it would cause, in the window this step opened.
+                     *
+                     * `stepSince` is taken before the dispatch so the predicate reads only this step's
+                     * consequences -- sharing the sequence's opening cursor would let step one's signal
+                     * satisfy step four's assertion, which is a false green built out of correct parts.
+                     */
+                    const parsed = PredicateSchema.safeParse(step['expect']);
+                    if (!parsed.success) {
+                        expectations.push({ declared: false });
+                        stepResults.push(described);
+                    }
+                    else {
+                        const verdict = await waitForPredicate(session, parsed.data, perStepTimeout, stepSince);
+                        const held = true === verdict.pass;
+                        expectations.push({
+                            declared: true,
+                            held,
+                            ...(verdict.observed === undefined ? {} : { observed: verdict.observed }),
+                            ...(verdict.expected === undefined ? {} : { expected: verdict.expected }),
+                        });
+                        stepResults.push({
+                            ...described,
+                            expected: verdict.expected ?? true,
+                            held,
+                            ...(held ? {} : { observed: verdict.observed ?? verdict.failureReason }),
+                        });
+                        if (!held) {
+                            stoppedAt ??= i;
+                            if (DeviationMode.HALT === onDeviation)
+                                break;
+                        }
+                    }
+                }
+                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;
+                }
+            }
+            /*
+             * Steps that actually ran — which is not the same as the length of the plan.
+             *
+             * This was `stalledAt ?? inputSteps.length`, from when a stall was the only way to stop early.
+             * Halting on an unmet `expect` came later and this never learned about it, so a sequence that
+             * stopped at step 2 of 3 answered `completed: 3` while `tail` carried the step it had not run:
+             * two accounts of one drive in the response an agent gates on, and the optimistic one was the
+             * round number. Measured on a live daemon.
+             *
+             * The halted step counts: it WAS dispatched, and only the consequence it declared failed
+             * afterwards. A stalled step never ran, which is why that index stays exclusive.
+             */
+            const completed = stoppedAt !== undefined ? stoppedAt + 1 : (stalledAt ?? inputSteps.length);
+            if (completed > 0) {
+                session.lastAct.markActed(since, undefined, undefined);
+            }
+            // Same as captureAct: no `active()` gate, so a sequence driven with nothing open still lands
+            // in the ambient tape. A stalled plan is still excluded — those steps never ran.
+            if (stalledAt === undefined) {
+                deps.recordings.capture(compileSequenceStep(args, { count: inputSteps.length, steps: stepResults }));
+            }
+            /*
+             * The grade, and the coverage it is never allowed to hide.
+             *
+             * A plan of twelve steps where three declared a consequence and all three held is verified FOR
+             * THOSE THREE and silent about nine. Reporting that as a pass is the arithmetic that buries the
+             * nine, so `coverage` rides on every answer and `because` says it in words.
+             */
+            const grade = gradeSequence(expectations, {
+                planned: inputSteps.length,
+                dispatched: completed > 0,
+            });
+            const ran = stoppedAt ?? stalledAt ?? inputSteps.length;
+            const tail = inputSteps.slice(ran + (stoppedAt === undefined ? 0 : 1));
+            return withControl(session, {
+                since,
+                dispatched: completed > 0,
+                completed,
+                ...(stalledAt !== undefined ? { stalled_at: stalledAt } : {}),
+                ...(stoppedAt !== undefined ? { stopped_at: stoppedAt } : {}),
+                verified: grade.verified,
+                because: grade.because,
+                // Offered at the one moment the compiled program is in hand and free to keep.
+                ...(() => {
+                    const keep = offerToKeep(grade);
+                    return keep === undefined ? {} : { keep };
+                })(),
+                coverage: { declared: grade.declared, total: grade.total },
+                // Verbatim and unmodified: the steps after the break are usually still correct, and handing
+                // them back edited invites a caller to re-plan work that was never wrong.
+                ...(tail.length > 0 ? { tail: tail.map((raw) => asRecord(raw)) } : {}),
+                steps: stepResults,
+                ...healthEnvelope(session),
+            });
+        }
+        finally {
+            session.finishAction();
+        }
+    },
+};

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

@@ -0,0 +1,24 @@
+/**
+ * Action tools — reticle_act and 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.
+ *
+ * `reticle_act_sequence` is a sibling file and is assembled by `tools.ts` directly. It used to be
+ * re-exported through this list, which made a cycle out of nothing: that file needs `actCommand` from
+ * here, and a registry is the right place to collect a definition from.
+ */
+import type { Session } from '../../portal/session/session.js';
+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 ACT_TOOLS: ToolDef[];