@reticlehq/server 3.5.0 → 3.7.0

package/dist/language/flows/flow-replay.js

@@ -1,12 +1,13 @@
 import { formatStepAddress } from 'open-verification';
 import { assertsState, expectLabel, expectedElementTestid, withoutClauses } from '@reticlehq/core';
 import { span } from '../../trace.js';
-import { anchorLabel, expectElementDrift, resolveTestid, testidDrift, ambiguousAnchorDrift, } from './flow-anchor.js';
+import { ambiguityDrift, anchorLabel, expectElementDrift, reresolved, resolveTestid, testidDrift, } from './flow-anchor.js';
 export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
 import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
+import { evalConsole } from '@reticlehq/engine/question/predicate/predicate-console.js';
 import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
-import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, } from '@reticlehq/core';
-import { asString, isConsequenceDrift } from '@reticlehq/core';
+import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, ReplayStatus, } from '@reticlehq/core';
+import { asString, invokedFlowMissing, isConsequenceDrift } from '@reticlehq/core';
 import { anchorFieldName } from './fields/flow-secret-field.js';
 import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
 import { inFlightRequestLabels } from '../../surface/tools/act/settle-in-flight.js';
@@ -100,11 +101,48 @@ function summarizeConsequence(events) {
         const status = 'number' === typeof data['status'] ? ` ${data['status']}` : '';
         parts.push(`${method} ${path}${status}`.trim());
     }
-    const errors = events.filter((e) => e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT).length;
+    const errors = events.filter(isConsoleError).length;
     if (errors > 0)
         parts.push(`${errors} console error${errors > 1 ? 's' : ''}`);
     return parts.length > 0 ? parts.join('; ') : undefined;
 }
+const isConsoleError = (e) => e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT;
+/** At most this many console errors travel on one step; its `digest` still counts them all. */
+const CONSOLE_ERRORS_PER_STEP = 5;
+/** The console errors a step's window saw, for the run artifact's evidence. See FlowStepResult. */
+function consoleErrorsIn(events) {
+    const errors = events
+        .filter(isConsoleError)
+        .slice(0, CONSOLE_ERRORS_PER_STEP)
+        .map((e) => ({ level: e.type, message: asString(e.data['message']) ?? '', at: e.t }));
+    return errors.length > 0 ? errors : undefined;
+}
+/** The console-absent clauses an expect cannot pass without: itself, or any `allOf` member. */
+function requiredConsoleAbsences(expect) {
+    if (PredicateKind.ALL_OF === expect.kind)
+        return expect.predicates.flatMap(requiredConsoleAbsences);
+    return PredicateKind.CONSOLE === expect.kind && true === expect.absent ? [expect] : [];
+}
+/**
+ * A console-absent expect, read again over the step's WHOLE window.
+ *
+ * The wait that graded the expect ends before the window does, so an error landing between the two
+ * was counted by the step's consequence and missed by its verdict (#1344). The window wins.
+ */
+function lateConsoleDrift(expect, events) {
+    for (const clause of requiredConsoleAbsences(expect)) {
+        const read = evalConsole(events, clause);
+        if (read.pass)
+            continue;
+        return {
+            reasonKind: DriftReason.SIGNAL_NOT_OBSERVED,
+            reason: read.failureReason ?? "the step's declared consequence did not hold",
+            anchor: expectLabel(expect),
+            nearest: null,
+        };
+    }
+    return undefined;
+}
 /** Run one testid-anchored step: re-resolve via QUERY, then ACT on the live ref, else drift. */
 export async function runTestidStep(session, step, index, value, dynamic, confirmDangerous, sleep) {
     const { refs, hint } = await resolveTestid(session, value, sleep);
@@ -124,17 +162,13 @@ export async function runTestidStep(session, step, index, value, dynamic, confir
      * reads `drift` and `ok` and never reads a note, so "we guessed which element you meant" was
      * indistinguishable from "it did what it did before" -- the one claim a replay makes.
      *
-     * The action is NOT dispatched. Acting and then reporting drift would leave the app changed by
-     * a click nobody can attribute, which is worse than the ambiguity it reports.
+     * The record itself comes from `ambiguityDrift`, shared with the role and component runners: this
+     * anchor kind was the first to get the rule, and writing it inline is how the other two came to
+     * answer the same question differently.
      */
-    if (refs.length > 1) {
-        return {
-            step: index,
-            tool: step.tool,
-            anchor: value,
-            ok: false,
-            drift: ambiguousAnchorDrift(value, refs.length),
-        };
+    const ambiguous = ambiguityDrift(step.anchor, refs);
+    if (ambiguous !== null) {
+        return { step: index, tool: step.tool, anchor: value, ok: false, drift: ambiguous };
     }
     const ref = refs[0] ?? '';
     /*
@@ -146,15 +180,12 @@ export async function runTestidStep(session, step, index, value, dynamic, confir
      * so the kind most likely to appear in a real flow was the kind without the cure.
      *
      * The re-resolve keeps the ambiguity rule above: more than one match is drift, never a guess, so
-     * it hands back a ref only when the locator still names exactly one element.
+     * it reports an `anchor_ambiguous` drift rather than handing back the first of the new matches.
      */
     const result = await actOnResolvedRef(session, step, index, value, ref, confirmDangerous, 
     // The field this step types into — from the anchor, so a redacted fill can be supplied from
     // RETICLE_SECRET_<FIELD> without the flow carrying the secret.
-    anchorFieldName(step.anchor), async () => {
-        const again = await resolveTestid(session, value, sleep);
-        return 1 === again.refs.length ? again.refs[0] : undefined;
-    });
+    anchorFieldName(step.anchor), async () => reresolved(step.anchor, (await resolveTestid(session, value, sleep)).refs));
     if (!result.ok)
         return result;
     // assert the step's expect.element testid is present AFTER the action —
@@ -251,11 +282,22 @@ export async function assertStepExpect(session, expect, waitForSignal, timeoutMs
                 : DriftReason.SIGNAL_NOT_OBSERVED,
         reason: namedInFlight
             ? `${IN_FLIGHT_AT_BUDGET_END} (${openRequests.join(', ')})`
-            : (verdict.failureReason ?? "the step's declared consequence did not hold"),
+            : withCaseOnly(verdict.failureReason ?? "the step's declared consequence did not hold", verdict),
         anchor: expectLabel(expect),
         nearest: null,
     };
 }
+/**
+ * A text check that missed only on case says so, with what would hold. Text checks match case
+ * exactly now, so a flow saved when they did not goes red on capitalisation alone; the person
+ * reading its replay needs the fix (`ignoreCase: true`, or re-record), not a bare "did not hold".
+ */
+export function withCaseOnly(reason, verdict) {
+    if (true !== verdict.caseOnlyMiss)
+        return reason;
+    const shown = verdict.wouldHold === undefined ? '' : ` ("${verdict.wouldHold}")`;
+    return `${reason} — the page shows it in another case${shown}. Text checks match case exactly: if any case is meant, add ignoreCase: true to this check, or re-record the flow.`;
+}
 /** Run one signal-anchored step: wait for the signal predicate, else drift (no nearest for signals). */
 async function runSignalStep(session, step, index, name, waitForSignal, signalTimeoutMs, since) {
     // Scope to THIS replay's floor, not the whole buffer.
@@ -297,6 +339,22 @@ export function resumeIndex(from, steps) {
         return undefined;
     return steps.slice(0, at).some((step) => StepEffect.COMMITS === step.effect) ? 0 : at;
 }
+/**
+ * How far a replay drives: `to` stops before a step (positive), `at` picks up at one on the page as
+ * it is. `at: 0` is the whole flow continuing the page the flow before it left, with no reload.
+ */
+export function replayWindow(args) {
+    const index = (raw, least) => 'number' === typeof raw && Number.isInteger(raw) && least <= raw ? raw : undefined;
+    const to = index(args['to'], 1);
+    const at = index(args['at'], 0);
+    return { ...(to === undefined ? {} : { to }), ...(at === undefined ? {} : { at }) };
+}
+/** A part-way replay's status, from the steps it drove. */
+export function partialStatus(steps) {
+    if (steps.some((step) => step.drift !== undefined))
+        return ReplayStatus.DRIFT;
+    return steps.every((step) => step.ok) ? ReplayStatus.OK : ReplayStatus.ERROR;
+}
 /** The `from` argument, narrowed: a step index or a step id. */
 export function resumeArg(raw) {
     return 'number' === typeof raw || ('string' === typeof raw && raw.length > 0) ? raw : undefined;
@@ -337,12 +395,13 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
         return {
             ...base,
             ok: false,
-            error: `cannot replay "${name}": it was not found, so this journey would report green having never run it`,
+            error: invokedFlowMissing(name),
         };
     }
     // `from` is an offset into the CALLER's steps. A sub-journey invoked from the setup prefix runs
     // whole and unchecked (from = its length); one invoked at or after the resume point runs normally.
-    const { from: _outer, ...rest } = options;
+    // Nor the progress callback: a sub-flow's steps are one step of the flow the chip is drawing.
+    const { from: _outer, onStep: _progress, to: _to, at: _at, ...rest } = options;
     const carried = setup ? { ...rest, from: sub.steps.length } : rest;
     const nested = await replayFlow(session, sub, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, {
         ...carried,
@@ -377,13 +436,28 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     // wait for the slowest step would trade a false red for a slow suite. See FlowStep.timeoutMs.
     const waitFor = (step) => step.timeoutMs ?? flow.signalTimeoutMs ?? signalTimeoutMs;
     let index = 0;
+    const tell = (result) => {
+        try {
+            options.onStep?.(index + 1, flow.steps.length, true === result?.ok && result.drift === undefined);
+        }
+        catch {
+            /* progress is a picture of the replay, never a reason to stop it */
+        }
+    };
     try {
         for (const step of flow.steps) {
+            if (options.to !== undefined && index >= options.to)
+                break;
+            if (options.at !== undefined && index < options.at) {
+                index += 1;
+                continue;
+            }
             if (step.invoke !== undefined) {
                 results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options, index < from));
                 const last = results[results.length - 1];
                 if (last !== undefined && index < from && last.ok)
                     results.pop();
+                tell(last);
                 if (last !== undefined && false === last.ok)
                     break;
                 index += 1;
@@ -459,6 +533,18 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             const consequence = summarizeConsequence(windowEvents);
             if (consequence !== undefined)
                 result.consequence = consequence;
+            const consoleErrors = consoleErrorsIn(windowEvents);
+            if (consoleErrors !== undefined)
+                result.consoleErrors = consoleErrors;
+            for (const expectation of checked) {
+                if (!result.ok || result.drift !== undefined)
+                    break;
+                const late = lateConsoleDrift(expectation, windowEvents);
+                if (late !== undefined) {
+                    result.ok = false;
+                    result.drift = late;
+                }
+            }
             // Per-step wall time is NOT shipped: it is `window.until - window.since`, computed from two numbers
             // the next line already puts in the same object, under the same emission condition. A step used to
             // carry the subtraction AND both operands, on every step of every replay.
@@ -483,7 +569,9 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             }
             if (index < from)
                 result.note = `setup step for resuming at step ${String(from)} failed`;
+            await options.onStepResult?.(result, flow.name).catch(() => undefined);
             results.push(result);
+            tell(result);
             // Under `sweep`, a failure whose action still RAN does not stop the run — the page is where the
             // step left it, so the next step is as meaningful as it was going to be. Anything else halts.
             const sweepPast = true === options.sweep &&

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

@@ -1,4 +1,4 @@
-import { FlowErrorCode } from '@reticlehq/core';
+import { FlowErrorCode, ReplayStatus, Verified } from '@reticlehq/core';
 import { type ProjectId } from '@reticlehq/core';
 /** Discriminated result so callers never branch on free strings. */
 export type FlowResult<T> = {
@@ -35,3 +35,24 @@ export type FlowResult<T> = {
 export declare const safeProjectId: (projectId?: ProjectId) => ProjectId | undefined;
 /** Map a structured FlowErrorCode to a legible one-line message for the agent. */
 export declare function flowErrorMessage(code: FlowErrorCode, detail?: string): string;
+/**
+ * A replay as one check of the session that ran it: held when it replayed clean, failed when a step
+ * failed, undecided when it drifted or its flow asserts nothing. A session whose only work was a
+ * failing replay ended "nothing was checked" beside the replay's own failure.
+ */
+export declare function replayVerdictEffect(name: string, status: ReplayStatus, assertsNothing: boolean): {
+    claim: string;
+    verified: Verified;
+    declaredBeforeActing: true;
+    grade: string;
+};
+/** Record a replay as one check of the session that ran it. A session double without a journal is skipped. */
+export declare function noteReplayCheck(session: {
+    recordAction?: (tool: string, args: Record<string, unknown>, effect?: unknown) => string;
+}, name: string, status: ReplayStatus, assertsNothing: boolean): void;
+/**
+ * The active recording a refused `reticle_flow_save` was most likely about: the one it named, or
+ * the only one running when it named none and nothing is stopped yet.
+ */
+export declare function stillRecording(active: readonly string[], name: string, explicitName: string | undefined, held: readonly string[]): string | undefined;
+export declare function stillRecordingMessage(recording: string): string;

package/dist/language/flows/flow-result.js

@@ -1,6 +1,7 @@
-import { FlowErrorCode } from '@reticlehq/core';
+import { FlowErrorCode, NO_SUCH_FLOW, ReplayStatus, ReticleTool, Verified } from '@reticlehq/core';
 import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
 import { FlowParseNote } from './flow-expect-grammar.js';
+import { isAmbient } from './recording/tape/recordings.js';
 /**
  * A project id that is safe to put in a path, or nothing.
  *
@@ -36,7 +37,7 @@ export function flowErrorMessage(code, detail) {
         case FlowErrorCode.INVALID_NAME:
             return 'invalid flow name — use a single safe segment (letters/digits/-/_), no path separators';
         case FlowErrorCode.NOT_FOUND:
-            return 'no such flow on disk — run reticle_flow{action:"list"} to see saved flows';
+            return `${NO_SUCH_FLOW} — run reticle_flow{action:"list"} to see saved flows`;
         case FlowErrorCode.PARSE_FAILED:
             return FlowParseNote.MALFORMED;
         case FlowErrorCode.NO_RECORDING:
@@ -49,3 +50,47 @@ export function flowErrorMessage(code, detail) {
             return (detail ?? 'the step to resume at is not in this flow — pass a 0-based index or a step id');
     }
 }
+/**
+ * A replay as one check of the session that ran it: held when it replayed clean, failed when a step
+ * failed, undecided when it drifted or its flow asserts nothing. A session whose only work was a
+ * failing replay ended "nothing was checked" beside the replay's own failure.
+ */
+export function replayVerdictEffect(name, status, assertsNothing) {
+    const verified = ReplayStatus.OK === status && !assertsNothing
+        ? Verified.YES
+        : ReplayStatus.ERROR === status
+            ? Verified.NO
+            : Verified.UNKNOWN;
+    return {
+        claim: `the flow "${name}" replays and its checks hold`,
+        verified,
+        declaredBeforeActing: true,
+        grade: REPLAY_GRADE,
+    };
+}
+/** The grade a replay's check is recorded with. */
+const REPLAY_GRADE = 'flow';
+/** Record a replay as one check of the session that ran it. A session double without a journal is skipped. */
+export function noteReplayCheck(session, name, status, assertsNothing) {
+    session.recordAction?.(ReticleTool.FLOW_REPLAY, { flowName: name }, replayVerdictEffect(name, status, assertsNothing));
+}
+/**
+ * The active recording a refused `reticle_flow_save` was most likely about: the one it named, or
+ * the only one running when it named none and nothing is stopped yet.
+ */
+// A running recording has no compiled program yet, so a save refusal names it (#1551).
+export function stillRecording(active, name, explicitName, held) {
+    if (active.includes(name) && !isAmbient(name))
+        return name;
+    // The ambient tape is the daemon's own, never one the agent started, so it is neither named nor
+    // counted: with a named recording beside it, that one is still the only candidate.
+    const opened = active.filter((recording) => !isAmbient(recording));
+    if ((explicitName === undefined || 0 === explicitName.length) && 0 === held.length) {
+        return 1 === opened.length ? opened[0] : undefined;
+    }
+    return undefined;
+}
+export function stillRecordingMessage(recording) {
+    return (`'${recording}' is still recording, and flow_save only saves a stopped recording. ` +
+        `Stop it first with reticle_record{action:"stop", recordingName:"${recording}"}, then save again.`);
+}

package/dist/language/flows/flow-scope.js

@@ -27,7 +27,11 @@ export function buildFlowChips(flows, sessionProjectId) {
         const start = first !== undefined && first.anchor.kind === AnchorKind.TESTID
             ? first.anchor.value
             : undefined;
-        chips.push(start === undefined ? { name: flow.name } : { name: flow.name, start });
+        chips.push({
+            name: flow.name,
+            createdAt: flow.createdAt,
+            ...(start === undefined ? {} : { start }),
+        });
     }
     return chips;
 }

package/dist/language/flows/flow-step-runners.d.ts

@@ -1,5 +1,8 @@
-import { AnchorKind, type FlowAnchor, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
+import { AnchorKind, type FlowAnchor, type FlowReplayResult, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
 import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
+import { type Reresolved } from './flow-anchor.js';
+/** The live act_sequence tool gives each step this transport budget when none was supplied. */
+export declare const DEFAULT_SEQUENCE_STEP_TIMEOUT_MS = 8000;
 export declare function runRoleStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.ROLE;
 }>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
@@ -19,8 +22,11 @@ field?: string,
  * 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?: () => Promise<string | undefined>): Promise<FlowStepResult>;
+reresolve?: () => Promise<Reresolved | undefined>): Promise<FlowStepResult>;
 /** Run one component-anchored step: re-resolve via QUERY by:'component', ACT on the live ref, else drift. */
 export declare function runComponentStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.COMPONENT;
@@ -55,6 +61,20 @@ export declare function anchorQueryArgs(anchor: FlowAnchor): Record<string, unkn
  * flow's own `requires` holds. No tool writes `requires`, so the reset's hint hands over this line.
  */
 export declare function anchorPrecondition(anchor: FlowAnchor): Predicate | 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 declare function staleTargetResult(name: string, steps: readonly FlowStepResult[]): FlowReplayResult | undefined;
 /**
  * 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