@reticlehq/server 3.7.0 → 3.8.1

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

@@ -7,13 +7,14 @@
  * 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, ReplayStatus, ReticleCommand, } from '@reticlehq/core';
-import { ReticleTool } from '@reticlehq/core';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, DOCUMENT_ANCHOR_ROLE, DriftReason, PredicateKind, QueryBy, ReplayStatus, ReticleCommand, } from '@reticlehq/core';
+import { ReticleTool, isGlobalPressCall } 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 { unreachableTargetNote } from '../../surface/tools/act/act-observation.js';
 import { anchorFieldName } from './flows.js';
-import { ambiguityDrift, refFor, anchorLabel, componentLabel, componentQueryArgs, expectElementDrift, reresolved, resolveQuery, testidDrift, } from './flow-anchor.js';
+import { ambiguityDrift, refFor, anchorLabel, componentLabel, componentQueryArgs, expectElementDrift, queryOnce, 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. */
@@ -168,7 +169,7 @@ reresolve) {
                 action: step.action ?? '',
                 args: replayActionArgs(step.args, confirmDangerous, field),
             });
-            return { ok: r.ok, error: r.error };
+            return { ok: r.ok, error: r.error, result: r.result };
         }
         finally {
             session.finishAction?.();
@@ -216,6 +217,19 @@ reresolve) {
     const result = { step: index, tool: step.tool, anchor: label, ok: act.ok };
     if (!act.ok)
         result.error = replayDestructiveActionHint(act.error ?? 'command failed');
+    // A click no person could have made decides nothing, on replay as on a live act.
+    const unreachable = act.ok ? unreachableTargetNote(act.result) : undefined;
+    if (unreachable !== undefined)
+        return {
+            ...result,
+            ok: false,
+            drift: {
+                reasonKind: DriftReason.TARGET_UNREACHABLE,
+                reason: unreachable,
+                anchor: label,
+                nearest: null,
+            },
+        };
     return result;
 }
 /** How long to let the app finish re-rendering before the one retry. Matches the sequence path. */
@@ -279,6 +293,26 @@ export function isDegradedAnchor(anchor) {
         anchor.role === DEGRADED_ANCHOR_ROLE &&
         anchor.name === undefined);
 }
+/**
+ * A saved document-key press (#1559): the nameless `document` ROLE anchor on a press of a document
+ * key. It is dispatched with no ref, the way `act` ran it live, and never QUERIED: there is no
+ * element with that role to find, and the page's root would be the wrong target if there were.
+ *
+ * The press is checked as well as the anchor, so the same anchor on any other action stays an
+ * anchor that addresses nothing.
+ */
+export function isDocumentPressStep(step) {
+    return (step.anchor.kind === AnchorKind.ROLE &&
+        step.anchor.role === DOCUMENT_ANCHOR_ROLE &&
+        step.anchor.name === undefined &&
+        isGlobalPressCall({ action: step.action, args: step.args }));
+}
+/** A `document` ROLE anchor names no element, whatever the step's action. */
+function isDocumentAnchor(anchor) {
+    return (anchor.kind === AnchorKind.ROLE &&
+        anchor.role === DOCUMENT_ANCHOR_ROLE &&
+        anchor.name === undefined);
+}
 /** What a step with no resolvable anchor reports, instead of a missing-element story. */
 const DEGRADED_STEP_REASON = 'recorded without a resolvable anchor (no data-testid, no accessible role+name), so it can never ' +
     'resolve on replay — add a data-testid to the element and record this flow again';
@@ -310,8 +344,9 @@ export function anchorQueryArgs(anchor) {
         return { by: QueryBy.TESTID, value: anchor.value };
     if (anchor.kind === AnchorKind.COMPONENT)
         return componentQueryArgs(anchor);
-    if (anchor.kind === AnchorKind.ROLE && !isDegradedAnchor(anchor))
+    if (anchor.kind === AnchorKind.ROLE && !isDegradedAnchor(anchor) && !isDocumentAnchor(anchor)) {
         return roleQueryArgs(anchor);
+    }
     return null;
 }
 /**
@@ -324,7 +359,7 @@ export function anchorPrecondition(anchor) {
     if (anchor.kind === AnchorKind.TESTID) {
         return { kind: PredicateKind.ELEMENT, query: { testid: anchor.value } };
     }
-    if (anchor.kind === AnchorKind.ROLE && !isDegradedAnchor(anchor)) {
+    if (anchor.kind === AnchorKind.ROLE && !isDegradedAnchor(anchor) && !isDocumentAnchor(anchor)) {
         return { kind: PredicateKind.ELEMENT, query: { role: anchor.role, name: anchor.name } };
     }
     return undefined;
@@ -373,6 +408,10 @@ function staleSubStep(error, live, from, to) {
  * drift whatever else happened, and a failure that is not staleness is a failure.
  */
 export function staleTargetResult(name, steps) {
+    // A target no person could reach is the same kind of answer: nothing about the app was decided.
+    const unreachable = unreachableTargetResult(name, steps) ?? unreachedStepResult(name, steps);
+    if (unreachable !== undefined)
+        return unreachable;
     if (steps.some((step) => step.drift !== undefined))
         return undefined;
     const failed = steps.filter((step) => !step.ok);
@@ -386,6 +425,64 @@ export function staleTargetResult(name, steps) {
         unverifiable: { reason: staleTargetReason(only.step) },
     };
 }
+/**
+ * The honest answer when a step acted on a target no person could have clicked (covered, of no
+ * size, off screen). The replay stopped there, and nothing about the app was decided: undecided as a
+ * whole, with the cause and the fix, as a live act answers it. Read as a drift, the suite counted it
+ * as a failed flow ("Reticle result: failed") on an app that may be fine.
+ */
+export function unreachableTargetResult(name, steps) {
+    const step = steps.find((s) => DriftReason.TARGET_UNREACHABLE === s.drift?.reasonKind);
+    if (step?.drift === undefined)
+        return undefined;
+    return {
+        name,
+        status: ReplayStatus.UNVERIFIABLE,
+        steps: [...steps],
+        unverifiable: { reason: `step ${String(step.step)}: ${step.drift.reason}` },
+    };
+}
+/** Drifts where the step's own control was never resolved, so the step never acted. */
+const ANCHOR_MISSES = new Set([
+    DriftReason.TESTID_NOT_FOUND,
+    DriftReason.COMPONENT_NOT_FOUND,
+    DriftReason.ANCHOR_AMBIGUOUS,
+    DriftReason.ANCHOR_DEGRADED,
+]);
+/**
+ * The honest answer when a replay stopped before it acted on anything: its first failing step's
+ * control was not on the page, often because the page lacks a state the recording had (a task added
+ * before recording started). Nothing ran, so nothing was proved. Read as drift, the run synced as
+ * FAIL, and the dashboard showed a failure for a journey that was never tested.
+ *
+ * Only when no earlier step ran. A control that is missing after earlier steps acted is on a page
+ * those steps made, so it stays drift, and heal reads it. A step that acted and whose expectation
+ * did not hold is a consequence drift and stays a failure. The failing step keeps its index and
+ * its `drift.reasonKind`, which the synced run carries in `stepResults`.
+ */
+function unreachedStepResult(name, steps) {
+    const at = steps.findIndex((s) => !s.ok);
+    const step = steps[at];
+    const drift = step?.drift;
+    if (step === undefined || drift === undefined || !ANCHOR_MISSES.has(drift.reasonKind))
+        return undefined;
+    if (steps.slice(0, at).some((s) => s.ok))
+        return undefined;
+    // ponytail: one close, unambiguous survivor reads as a rename (heal's case), so it stays drift. A
+    // page with exactly one sibling of the missing control (`toggle-1` for `toggle-3`) reads the same.
+    if (drift.nearest !== null && true !== drift.ambiguous)
+        return undefined;
+    return {
+        name,
+        status: ReplayStatus.UNVERIFIABLE,
+        steps: [...steps],
+        unverifiable: {
+            reason: `did not reach step ${String(step.step + 1)} (${drift.reason}), so nothing was acted ` +
+                `on and nothing was proved. Start the replay from the state this step needs, or record the ` +
+                `steps that make it.`,
+        },
+    };
+}
 /**
  * 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
@@ -398,7 +495,12 @@ export function staleTargetResult(name, steps) {
  */
 export async function runSequenceStep(session, step, index, subs, confirmDangerous, sleep, 
 /** Testids whose presence is deliberately NOT asserted — the LLM-output case. */
-dynamic = new Set()) {
+dynamic = new Set(), 
+/**
+ * Judge one sub-step's `expect` over the window from `since`, which opens just before that
+ * sub-step's dispatch. Omitted for a setup step, whose consequences are not checked.
+ */
+judge) {
     /**
      * 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.
@@ -407,19 +509,36 @@ dynamic = new Set()) {
      * 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.
+     *
+     * `ahead` is a look at a sub-step before its turn. It is one query with no settle. An anchor that is
+     * not on the page yet is `pending`, not drift, because an earlier sub-step can render it.
      */
-    const resolveSub = async (sub, subIndex, afterRerender = false) => {
+    const resolveSub = async (sub, subIndex, afterRerender = false, ahead = false) => {
         const label = `${anchorLabel(sub.anchor)} (sub-step ${String(subIndex)})`;
+        if (isDocumentPressStep(sub)) {
+            // Dispatched as it ran live, at the document with no ref (#1559).
+            return {
+                live: {
+                    ref: '',
+                    action: sub.action ?? '',
+                    args: replayActionArgs(sub.args, confirmDangerous, undefined),
+                },
+            };
+        }
         const queryArgs = anchorQueryArgs(sub.anchor);
         if (null === queryArgs)
             return { stop: degradedStepResult(step, index, label) };
-        const { refs, hint } = await resolveQuery(session, queryArgs, sleep);
+        const { refs, hint } = ahead
+            ? await queryOnce(session, queryArgs)
+            : await resolveQuery(session, queryArgs, sleep);
         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) {
+            if (ahead)
+                return { pending: true };
             return {
                 stop: {
                     step: index,
@@ -447,15 +566,31 @@ dynamic = new Set()) {
             },
         };
     };
-    // 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);
-    }
+    /**
+     * Resolve sub-steps from `from`, as far as the page allows now. Return the index where the run must
+     * dispatch before it can look further.
+     *
+     * Sub-step `from` is the one whose turn it is. It gets the full settle, and it drifts if it is
+     * missing. At 0, that is before anything acted. Each later sub-step gets one look before its turn.
+     * The first one that is not on the page yet ends the stretch. Live, a later sub-step can target
+     * what an earlier one renders, for example the "Cancel" of a form that "Edit" opens (#1523). A
+     * sequence whose anchors are all on the page at the start is one stretch, so it is one batch.
+     */
+    const resolveFrom = async (from) => {
+        for (let at = from; at < subs.length; at += 1) {
+            const sub = subs[at];
+            if (sub === undefined)
+                continue;
+            const resolved = await resolveSub(sub, at, false, at > from);
+            if ('pending' in resolved)
+                return { end: at };
+            if ('stop' in resolved)
+                return resolved;
+            live[at] = resolved.live;
+        }
+        return { end: subs.length };
+    };
     const result = {
         step: index,
         tool: step.tool,
@@ -482,7 +617,7 @@ dynamic = new Set()) {
     /**
      * 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
+     * The refs were resolved before their stretch 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.
      *
@@ -531,7 +666,9 @@ dynamic = new Set()) {
                         result.drift = resolved.stop.drift;
                     return false;
                 }
-                live[at] = resolved.live;
+                // A second look settles, so it is never `pending`.
+                if ('live' in resolved)
+                    live[at] = resolved.live;
             }
             start = staleAt;
         }
@@ -567,19 +704,41 @@ dynamic = new Set()) {
      *
      * The walk costs a round trip per sub-step, so only a flow that declared something pays for it.
      */
-    const declaring = subs.some((sub) => declaredBy(sub) !== undefined);
-    if (!declaring) {
-        await dispatchFrom(0, live.length);
-        return result;
-    }
-    for (const [subIndex, sub] of subs.entries()) {
-        if (live[subIndex] === undefined)
-            continue;
-        if (!(await dispatchFrom(subIndex, subIndex + 1)))
-            return result;
-        const testid = declaredBy(sub);
-        if (testid !== undefined && !(await assertDeclared(testid)))
-            return result;
+    const judged = (sub) => judge !== undefined && sub.expect !== undefined;
+    const declaring = subs.some((sub) => declaredBy(sub) !== undefined || judged(sub));
+    for (let next = 0; next < subs.length;) {
+        const stretch = await resolveFrom(next);
+        if ('stop' in stretch)
+            return stretch.stop;
+        const { end } = stretch;
+        if (!declaring) {
+            if (!(await dispatchFrom(next, end)))
+                return result;
+        }
+        else {
+            for (let at = next; at < end; at += 1) {
+                const sub = subs[at];
+                if (sub === undefined)
+                    continue;
+                const since = session.elapsed();
+                if (!(await dispatchFrom(at, at + 1)))
+                    return result;
+                const testid = declaredBy(sub);
+                if (testid !== undefined && !(await assertDeclared(testid)))
+                    return result;
+                // The claim is about THIS sub-step: a later one has not run, and an earlier one is before
+                // `since`. Judged at the end, a middle route expect failed and a late claim passed early.
+                const drift = judge !== undefined && sub.expect !== undefined
+                    ? await judge(sub.expect, since)
+                    : undefined;
+                if (drift !== undefined) {
+                    result.ok = false;
+                    result.drift = drift;
+                    return result;
+                }
+            }
+        }
+        next = end;
     }
     return result;
 }

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

@@ -24,9 +24,16 @@
  * returned unchanged.
  */
 import { FlowStore } from './flows.js';
-import type { ProjectTarget } from '../../memory/project/session-root.js';
+import { type ProjectTarget } from '../../memory/project/session-root.js';
+import type { ProjectId } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 export declare function flowsForSession(deps: ToolDeps, target: ProjectTarget): {
     flows: FlowStore;
     root: string;
 };
+/** `flowsForSession` for a session id, with the project id to scope the store by. Same refusals. */
+export declare function flowsForSessionId(deps: ToolDeps, sessionId: string | undefined): {
+    flows: FlowStore;
+    root: string;
+    projectId: ProjectId | undefined;
+};

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

@@ -24,6 +24,7 @@
  * returned unchanged.
  */
 import { FlowStore } from './flows.js';
+import { sessionTarget } from '../../memory/project/session-root.js';
 export function flowsForSession(deps, target) {
     const resolved = deps.artifactRootFor?.(target.projectId, target.origin);
     if (resolved === undefined || resolved.root === deps.reticleRoot) {
@@ -35,3 +36,8 @@ export function flowsForSession(deps, target) {
         root: resolved.root,
     };
 }
+/** `flowsForSession` for a session id, with the project id to scope the store by. Same refusals. */
+export function flowsForSessionId(deps, sessionId) {
+    const target = sessionTarget(deps, sessionId);
+    return { ...flowsForSession(deps, target), projectId: target.projectId };
+}

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

@@ -1,25 +1,4 @@
-import { type FlowReplayResult } from '@reticlehq/core';
-import type { ToolDef, ToolDeps } from '../../surface/tools/tool-kit.js';
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
 export { replayNamedFlow } from './flow-replay-run.js';
-/**
- * The URL a leased context should open: the app's ORIGIN, not the live tab's current location.
- *
- * The live tab drifts — every replay navigates it — so using its full URL made each lease start wherever
- * the previous run happened to finish (observed: leases opening /deployments and failing to find the
- * login control that only exists at the root). A lease must be a FRESH visit to a deterministic entry
- * 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 { leasableAppUrl, leaseFailureReplay, sessionUrlOf } from './flow-lease.js';
 export declare const FLOW_TOOLS: ToolDef[];