@reticlehq/server 3.5.0 → 3.7.0

package/dist/language/flows/flow-step-runners.js

@@ -7,15 +7,17 @@
  * or a step's events land in the wrong window depending on how it was addressed.
  */
 import { expectedElementTestid } from '@reticlehq/core';
-import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, PredicateKind, QueryBy, ReticleCommand, } from '@reticlehq/core';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, PredicateKind, QueryBy, ReplayStatus, ReticleCommand, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { replayActionArgs } from './replay.js';
 import { isStaleRefError } from '../../surface/tools/act/act-sequence-retry.js';
 import { waitForReaction } from '../../surface/tools/act/react-grace.js';
 import { anchorFieldName } from './flows.js';
-import { anchorLabel, componentLabel, componentQueryArgs, expectElementDrift, resolveQuery, testidDrift, } from './flow-anchor.js';
+import { ambiguityDrift, refFor, anchorLabel, componentLabel, componentQueryArgs, expectElementDrift, reresolved, resolveQuery, testidDrift, } from './flow-anchor.js';
 import { nearestRoleName } from './role-anchor-nearest.js';
 import { roleDriftReason } from '../../judgement/outcome/role-drift-reason.js';
+/** The live act_sequence tool gives each step this transport budget when none was supplied. */
+export const DEFAULT_SEQUENCE_STEP_TIMEOUT_MS = 8_000;
 /** Query args for a NAMED role anchor — the handle that identifies an instance, not a JSX site. */
 function roleQueryArgs(anchor) {
     return {
@@ -63,7 +65,25 @@ async function nearestRoleNameOnPage(session, anchor) {
 export async function runRoleStep(session, step, index, anchor, confirmDangerous, sleep) {
     const label = `${anchor.role} "${String(anchor.name)}"`;
     const { refs } = await resolveQuery(session, roleQueryArgs(anchor), sleep);
-    const ref = refs[0];
+    /*
+     * More than one match is DRIFT, not a guess. This path took `refs[0]`, dispatched, and returned
+     * `ok: true`, so a flow recorded against "View result" on row 3 of a table replayed by clicking row
+     * 1 and PASSED whenever every row shared the consequence (the same GET returning 200). The verdict
+     * reads `drift` and `ok` and nothing else, so a green here is indistinguishable from a replay that
+     * did what it did before.
+     *
+     * A role+name anchor is MORE likely to land here than a testid is: `button "View result"` is
+     * user-visible text, and a table repeats it by nature, so several matches is the expected shape of
+     * a recorded row action rather than an accident.
+     *
+     * The check itself lives in `ambiguityDrift`, shared with the testid and component runners: written
+     * per-runner, this rule got applied to two anchor kinds and forgotten for the third.
+     */
+    const ambiguous = ambiguityDrift(anchor, refs);
+    if (ambiguous !== null) {
+        return { step: index, tool: step.tool, anchor: label, ok: false, drift: ambiguous };
+    }
+    const ref = refFor(anchor, refs);
     if (ref === undefined) {
         // `nearest` used to be the literal null, so heal answered "no nearest match cleared the
         // confidence floor" for EVERY role-anchored drift — a structural limit reported as a judgement
@@ -86,8 +106,15 @@ export async function runRoleStep(session, step, index, anchor, confirmDangerous
         };
     }
     return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous, anchorFieldName(anchor), 
-    // The retry's whole point: run the SAME locator against the DOM as it is now.
-    async () => (await resolveQuery(session, roleQueryArgs(anchor), sleep)).refs[0]);
+    /*
+     * The retry's whole point: run the SAME locator against the DOM as it is now.
+     *
+     * It reports WHAT it found, not just a ref. A re-render can turn an unambiguous anchor into an
+     * ambiguous one between the two dispatches, and dispatching at the first of the new matches would
+     * re-make the guess the check above exists to refuse — one layer deeper, where the caller cannot
+     * see it. `reresolved` is the same rule as that check, so the two cannot disagree.
+     */
+    async () => reresolved(anchor, (await resolveQuery(session, roleQueryArgs(anchor), sleep)).refs));
 }
 /**
  * `assertActionAllowed`'s refusal — "potentially destructive action blocked; retry with
@@ -109,11 +136,8 @@ function replayDestructiveActionHint(rawError) {
     return (`${rawError} — this is a flow REPLAY: a step's own args.confirmDangerous is stripped before ` +
         'dispatch and never persists, so editing the flow file does nothing. Pass it at the call level ' +
         `instead: ${ReticleTool.FLOW_REPLAY} { confirmDangerous: true } acknowledges every flagged step ` +
-        // `reticle_verify{action:"flows"}` (the batch suite runner) has no such argument today — naming
-        // it here would repeat the exact defect this message exists to fix, so the honest statement is
-        // that a flow with a flagged step currently has to be replayed on its own to pass it.
-        'for this run. The batch reticle_verify{action:"flows"} has no equivalent option yet, so a flow ' +
-        'with a flagged step has to be replayed on its own to acknowledge it.');
+        'for this run, as do reticle_verify{action:"flows", confirmDangerous: true} for a suite and ' +
+        '`reticle verify <url> --confirm-dangerous` from the command line.');
 }
 /**
  * Dispatch one already-resolved step. Shared so every anchor kind runs the action the same way —
@@ -131,6 +155,9 @@ field,
  * found, and the retry below is worthless without it: re-dispatching the SAME dead ref fails
  * identically. What changed between the two attempts is the DOM, so the locator has to be run
  * against it again.
+ *
+ * It reports WHAT it found, not just a ref: see `Reresolved`. A re-render that turns one match into
+ * three is a drift, and the caller is the only layer that can say so with the right anchor in hand.
  */
 reresolve) {
     const dispatch = async (at) => {
@@ -167,8 +194,24 @@ reresolve) {
             sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         });
         const fresh = await reresolve();
+        /*
+         * The re-render turned one match into SEVERAL, so there is nothing to dispatch at and the answer
+         * is a drift — the same `anchor_ambiguous` the first resolution would have given, reported for the
+         * same reason.
+         *
+         * The staleness this retry exists to absorb is a different diagnosis with a different fix, and
+         * this used to be the only one reported: the step came back as `{ok: false, error: "ref 'e-orig'
+         * no longer resolves to an element"}` — a sentence about an element that is GONE, sent for an
+         * element that is now three. An agent reading it goes hunting for a rename, or re-records the
+         * flow, when the actual fix is a narrower anchor. Telling the two apart is what `Reresolved` is
+         * for, and the reason `ANCHOR_AMBIGUOUS` exists as its own kind rather than folding into "not
+         * found".
+         */
+        if (fresh !== undefined && 'drift' in fresh) {
+            return { step: index, tool: step.tool, anchor: label, ok: false, drift: fresh.drift };
+        }
         if (fresh !== undefined)
-            act = await dispatch(fresh);
+            act = await dispatch(fresh.ref);
     }
     const result = { step: index, tool: step.tool, anchor: label, ok: act.ok };
     if (!act.ok)
@@ -195,10 +238,28 @@ export async function runComponentStep(session, step, index, anchor, confirmDang
             },
         };
     }
+    /*
+     * Several matches is DRIFT here too, and this runner is where the rule was MISSING.
+     *
+     * The other two runners check it (through `ambiguityDrift`); this one took `refs[0]`, dispatched and
+     * returned `ok: true`. `by: QueryBy.COMPONENT` matches by component NAME, and a component rendered
+     * once per row — a table's action button, a card's menu — matches as many times as there are rows.
+     * So the guessed-green shape is not an edge case for this anchor kind, it is its ordinary one, and
+     * it is the exact defect #1227 describes: a click on the wrong element reported as a pass because
+     * the verdict reads `drift` and `ok` and never reads which element was hit.
+     */
+    const ambiguous = ambiguityDrift(anchor, refs);
+    if (ambiguous !== null) {
+        return { step: index, tool: step.tool, anchor: label, ok: false, drift: ambiguous };
+    }
     const ref = refs[0] ?? '';
     // Shared with the role path so both get the same action window AND the same stale-ref retry —
     // this used to dispatch inline, which is how one anchor kind could gain a fix the other lacked.
-    return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous, anchorFieldName(anchor), async () => (await resolveQuery(session, componentQueryArgs(anchor), sleep)).refs[0]);
+    return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous, anchorFieldName(anchor), 
+    // Same rule one layer deeper, same helper: a re-render that turns one match into three must not
+    // be dispatched at either, and it must say so as a drift rather than as a dead ref. This callback
+    // used to return `refs[0]` unconditionally.
+    async () => reresolved(anchor, (await resolveQuery(session, componentQueryArgs(anchor), sleep)).refs));
 }
 /**
  * DEGRADED_ANCHOR_ROLE is a MARKER ("no anchor could be determined"), never a locator.
@@ -268,6 +329,63 @@ export function anchorPrecondition(anchor) {
     }
     return undefined;
 }
+/** What is added to a stale-ref error when it cannot be traced to one sub-step of the sequence. */
+const STALE_SUB_STEP_UNKNOWN = ' (which sub-step that was could not be told, so the ones before it may have run)';
+/** Where a ref that stayed stale sat in the sequence, and that every sub-step before it ran. */
+const staleSubStepPosition = (at, total) => ` (sub-step ${String(at)} of ${String(total)}; ${String(at)} before it ran)`;
+/**
+ * Why a step whose target kept going stale is unverifiable, as the replay result tells a reader.
+ * `step` is the index of the step that could not be acted on.
+ */
+const staleTargetReason = (step) => `step ${String(step)} could not be acted on: its target kept going stale, because the ` +
+    `page re-rendered between finding the element and using it, and the replay looked it up ` +
+    `again for as long as that got it further. The steps before it are reported and nothing ` +
+    `after it ran. Nothing here says the app failed. If an earlier step makes the page ` +
+    `re-render, record that step's consequence with \`expect\` so the replay waits for the new ` +
+    `render before it moves on.`;
+/**
+ * The sub-step, among live[from, to), whose ref the page said it could not find.
+ *
+ * The page echoes the ref in "ref 'x' no longer resolves to an element". A ref it shortened, or one
+ * that is not among these, gives no answer. Neither does a ref that two sub-steps share: the first of
+ * them may already have run, and may be what re-rendered the page, which makes the later one the stale
+ * one, and nothing in the message says so. The caller must not guess which actions already ran.
+ */
+function staleSubStep(error, live, from, to) {
+    const named = /ref '([^']*)'/.exec(error)?.[1];
+    if (named === undefined)
+        return undefined;
+    const sharing = live.flatMap((one, at) => at >= from && at < to && one.ref === named ? [at] : []);
+    const [only] = sharing;
+    return 1 === sharing.length ? only : undefined;
+}
+/**
+ * The honest answer when a step's target kept going stale.
+ *
+ * Replay looks the element up again and goes on while that gets it further, so a step still stale
+ * after that is one the page re-rendered around faster than it could be targeted. Reporting it as
+ * `error` with the browser's own sentence says "your app broke", which is a claim nothing observed
+ * and sends a reader into product code that is fine. It is the same bucket as a document that went
+ * away: the steps before it are real and are attached, the step that could not be acted on is among
+ * them with its index, and nothing after it ran.
+ *
+ * Left alone, so the ordinary verdict stands, when anything else is in the run: a drifted anchor is
+ * drift whatever else happened, and a failure that is not staleness is a failure.
+ */
+export function staleTargetResult(name, steps) {
+    if (steps.some((step) => step.drift !== undefined))
+        return undefined;
+    const failed = steps.filter((step) => !step.ok);
+    const [only] = failed;
+    if (failed.length !== 1 || only === undefined || !isStaleRefError(only.error))
+        return undefined;
+    return {
+        name,
+        status: ReplayStatus.UNVERIFIABLE,
+        steps: [...steps],
+        unverifiable: { reason: staleTargetReason(only.step) },
+    };
+}
 /**
  * Run an act_sequence step: resolve every sub-step's OWN anchor, then dispatch the whole thing as one
  * ACT_SEQUENCE — the same shape `replayProgram` already uses, so a recorded sequence and a saved one
@@ -281,37 +399,62 @@ export function anchorPrecondition(anchor) {
 export async function runSequenceStep(session, step, index, subs, confirmDangerous, sleep, 
 /** Testids whose presence is deliberately NOT asserted — the LLM-output case. */
 dynamic = new Set()) {
-    const live = [];
-    for (const [subIndex, sub] of subs.entries()) {
+    /**
+     * Find one sub-step's element as the page is NOW. Either the live step to dispatch, or the step
+     * result that ends the run: a degraded anchor, or one that is no longer on the page.
+     *
+     * `afterRerender` is the second look, taken because the page re-rendered under a sub-step. An anchor
+     * that now matches several elements is drift there, as it is for a single step's retry: the first of
+     * the new matches may be an element the recording did not mean, and acting on it would report a pass
+     * for a click nobody can attribute. The first look keeps taking the first match.
+     */
+    const resolveSub = async (sub, subIndex, afterRerender = false) => {
         const label = `${anchorLabel(sub.anchor)} (sub-step ${String(subIndex)})`;
         const queryArgs = anchorQueryArgs(sub.anchor);
         if (null === queryArgs)
-            return degradedStepResult(step, index, label);
+            return { stop: degradedStepResult(step, index, label) };
         const { refs, hint } = await resolveQuery(session, queryArgs, sleep);
-        const ref = refs[0];
+        const ambiguous = afterRerender ? ambiguityDrift(sub.anchor, refs) : null;
+        if (ambiguous !== null) {
+            return { stop: { step: index, tool: step.tool, anchor: label, ok: false, drift: ambiguous } };
+        }
+        const ref = afterRerender ? refFor(sub.anchor, refs) : refs[0];
         if (ref === undefined) {
             return {
-                step: index,
-                tool: step.tool,
-                anchor: label,
-                ok: false,
-                drift: sub.anchor.kind === AnchorKind.TESTID
-                    ? testidDrift(sub.anchor.value, hint)
-                    : {
-                        reasonKind: DriftReason.COMPONENT_NOT_FOUND,
-                        reason: `anchor ${label} not found`,
-                        anchor: label,
-                        nearest: null,
-                    },
+                stop: {
+                    step: index,
+                    tool: step.tool,
+                    anchor: label,
+                    ok: false,
+                    drift: sub.anchor.kind === AnchorKind.TESTID
+                        ? testidDrift(sub.anchor.value, hint)
+                        : {
+                            reasonKind: DriftReason.COMPONENT_NOT_FOUND,
+                            reason: `anchor ${label} not found`,
+                            anchor: label,
+                            nearest: null,
+                        },
+                },
             };
         }
-        live.push({
-            ref,
-            action: sub.action ?? '',
-            // Each sub-step carries its OWN anchor, so each gets its own field name. A sequence that ends
-            // in a login is the shape this was reported on, and the sub-step is where the fill lives.
-            args: replayActionArgs(sub.args, confirmDangerous, anchorFieldName(sub.anchor)),
-        });
+        return {
+            live: {
+                ref,
+                action: sub.action ?? '',
+                // Each sub-step carries its OWN anchor, so each gets its own field name. A sequence that ends
+                // in a login is the shape this was reported on, and the sub-step is where the fill lives.
+                args: replayActionArgs(sub.args, confirmDangerous, anchorFieldName(sub.anchor)),
+            },
+        };
+    };
+    // Every anchor is checked before anything runs, so a sub-step that has drifted away is reported as
+    // drift and not discovered half way through a sequence that has already acted.
+    const live = [];
+    for (const [subIndex, sub] of subs.entries()) {
+        const resolved = await resolveSub(sub, subIndex);
+        if ('stop' in resolved)
+            return resolved.stop;
+        live.push(resolved.live);
     }
     const result = {
         step: index,
@@ -320,20 +463,78 @@ dynamic = new Set()) {
         ok: true,
     };
     /** One dispatch through the SAME command either way, so batched and walked replay identically. */
-    const dispatch = async (steps) => {
+    const send = async (steps) => {
         session.beginAction?.(ReticleTool.FLOW_REPLAY, { steps: steps.length });
-        let act;
         try {
-            act = await session.command(ReticleCommand.ACT_SEQUENCE, { steps });
+            // A recorded zero means "do not wait for the element", not "abort the whole batch now".
+            // Keep the transport alive long enough for the sequence's default per-step budget, and give
+            // an omitted timeout the same aggregate budget as the live tool's independent step waits.
+            const perStepTimeout = undefined === step.timeoutMs || 0 === step.timeoutMs
+                ? DEFAULT_SEQUENCE_STEP_TIMEOUT_MS
+                : step.timeoutMs;
+            const timeoutMs = perStepTimeout * steps.length;
+            return await session.command(ReticleCommand.ACT_SEQUENCE, { steps }, timeoutMs);
         }
         finally {
             session.finishAction?.();
         }
-        if (act.ok)
-            return true;
-        result.ok = false;
-        result.error = replayDestructiveActionHint(act.error ?? 'command failed');
-        return false;
+    };
+    /**
+     * Run sub-steps [from, to), and survive the page re-rendering under them.
+     *
+     * The refs were resolved before anything ran, and the first action of a sequence is allowed to
+     * re-render the page, so by the time a later sub-step is reached its ref may be dead. The same
+     * anchor is almost always still there under a new ref; what was missing is a second look.
+     *
+     * The page names the ref it could not find, which says WHICH sub-step failed and so which ones
+     * already ran, as long as no other sub-step holds the same ref. Only the rest is resolved again and
+     * sent, so nothing acts twice: starting over is what turns one click into two. A stale ref is the
+     * only failure retried, and the retry goes on only while it gets further. A sub-step that is stale
+     * again at the same point is a target that does not hold still, and the run says so, with how far
+     * it got.
+     */
+    const dispatchFrom = async (from, to) => {
+        let start = from;
+        let staleBefore = -1;
+        for (;;) {
+            const act = await send(live.slice(start, to));
+            if (act.ok)
+                return true;
+            const error = act.error ?? 'command failed';
+            if (!isStaleRefError(error)) {
+                result.ok = false;
+                result.error = replayDestructiveActionHint(error);
+                return false;
+            }
+            const staleAt = staleSubStep(error, live, start, to);
+            if (staleAt === undefined) {
+                result.ok = false;
+                result.error = error + STALE_SUB_STEP_UNKNOWN;
+                return false;
+            }
+            if (staleAt <= staleBefore) {
+                result.ok = false;
+                result.error = error + staleSubStepPosition(staleAt, subs.length);
+                return false;
+            }
+            staleBefore = staleAt;
+            await waitForReaction(session, 0, STALE_REF_GRACE_MS, { sleep });
+            for (let at = staleAt; at < to; at += 1) {
+                const sub = subs[at];
+                if (sub === undefined)
+                    continue;
+                const resolved = await resolveSub(sub, at, true);
+                if ('stop' in resolved) {
+                    result.ok = false;
+                    result.anchor = resolved.stop.anchor;
+                    if (resolved.stop.drift !== undefined)
+                        result.drift = resolved.stop.drift;
+                    return false;
+                }
+                live[at] = resolved.live;
+            }
+            start = staleAt;
+        }
     };
     /** The sub-step's own expectation, unless its testid is deliberately unasserted. */
     const declaredBy = (sub) => {
@@ -368,14 +569,13 @@ dynamic = new Set()) {
      */
     const declaring = subs.some((sub) => declaredBy(sub) !== undefined);
     if (!declaring) {
-        await dispatch(live);
+        await dispatchFrom(0, live.length);
         return result;
     }
     for (const [subIndex, sub] of subs.entries()) {
-        const one = live[subIndex];
-        if (one === undefined)
+        if (live[subIndex] === undefined)
             continue;
-        if (!(await dispatch([one])))
+        if (!(await dispatchFrom(subIndex, subIndex + 1)))
             return result;
         const testid = declaredBy(sub);
         if (testid !== undefined && !(await assertDeclared(testid)))

package/dist/language/flows/flow-store-for-session.d.ts

@@ -24,9 +24,9 @@
  * returned unchanged.
  */
 import { FlowStore } from './flows.js';
-import type { ProjectId } from '@reticlehq/core';
+import type { ProjectTarget } from '../../memory/project/session-root.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
-export declare function flowsForSession(deps: ToolDeps, projectId: ProjectId | undefined): {
+export declare function flowsForSession(deps: ToolDeps, target: ProjectTarget): {
     flows: FlowStore;
     root: string;
 };

package/dist/language/flows/flow-store-for-session.js

@@ -24,10 +24,14 @@
  * returned unchanged.
  */
 import { FlowStore } from './flows.js';
-export function flowsForSession(deps, projectId) {
-    const resolved = deps.artifactRootFor?.(projectId);
+export function flowsForSession(deps, target) {
+    const resolved = deps.artifactRootFor?.(target.projectId, target.origin);
     if (resolved === undefined || resolved.root === deps.reticleRoot) {
         return { flows: deps.flows, root: deps.reticleRoot };
     }
-    return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
+    const onWrote = deps.onRunPersisted;
+    return {
+        flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }, onWrote === undefined ? {} : { onWrote }),
+        root: resolved.root,
+    };
 }

package/dist/language/flows/flow-tools.d.ts

@@ -10,6 +10,16 @@ export { replayNamedFlow } from './flow-replay-run.js';
  * point; flows that need another page carry their own startPath.
  */
 export declare function leasableAppUrl(deps: ToolDeps, sessionId: string | undefined): string | undefined;
+/**
+ * The live session's own URL — what the fixture port must be looked up by.
+ *
+ * NOT `leasableAppUrl`. That returns an ORIGIN, and the input provider finds a page by comparing
+ * full URLs, so an origin matched no page: `suiteFixtureSeed` answered `undefined` on every run and
+ * every leased flow booted cold while the code read as if it were seeded. Silent, because every
+ * refusal on that path is deliberately silent — a fixture is an optimisation, and a suite must not
+ * die when one is unavailable.
+ */
+export declare function sessionUrlOf(deps: ToolDeps, sessionId: string | undefined): string | undefined;
 /** A flow whose leased context never came up is a suite ERROR, never a silent pass. */
 export declare function leaseFailureReplay(name: string, error: string | undefined): FlowReplayResult;
 export declare const FLOW_TOOLS: ToolDef[];