@reticlehq/server 3.8.2 → 3.10.0

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

@@ -3,13 +3,15 @@ import { withLeaseKeyboard } from '../../surface/tools/real-input-attempt.js';
 import { learnFromRun } from '@reticlehq/engine/evidence/learned-guards.js';
 import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, ReplayStatus, RunKind, RunStatus, } from '@reticlehq/core';
 import { haltedFrom } from './recording/replay-halt.js';
-import { establishedState } from './flow-journey.js';
+import { establishedState, startPathBudgetMs } from './flow-journey.js';
+import { resolveSessionWithin } from '../../portal/session/timing/resolve-within.js';
+import { WALL_CLOCK } from '../../portal/session/timing/wall-clock.js';
 import { asString } from '@reticlehq/core';
 import { partialStatus, replayFlow, replayWindow } from './flow-replay.js';
 import { staleTargetResult } from './flow-step-runners.js';
 import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
 import { buildDecision, unverifiableReason } from './decision.js';
-import { unsuppliedSecrets } from './fields/flow-secret-field.js';
+import { secretEnvKey, secretValue, unsuppliedSecrets } from './fields/flow-secret-field.js';
 import { assertStepExpect, DocumentLostDuringReplay, resumeArg, unresolvedResume, } from './flow-replay.js';
 import { isDocumentGoneError } from '../../portal/session/facts/session-replaced.js';
 import { classifyFlowAssertions, flattenSteps } from './flow-classify.js';
@@ -33,7 +35,8 @@ import { replayStepShooter } from '../../features/visual/step-shots.js';
 import { flowsForSession } from './flow-store-for-session.js';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { CROSS_STEP_INDEX, crossStepOnly, declaredIn } from './flow-cross-step.js';
-import { arriveAtStartPath, startPathMismatchHint, withStartPageWait } from './flow-start-path.js';
+import { arriveAtStartPath, navigateAndAwait, noteReplayEnded, routeClaimsWhereTheTabIs, startPathMismatchHint, withStartPageWait, } from './flow-start-path.js';
+import { requestSender } from './steps/page-steps.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
@@ -226,6 +229,15 @@ async function firstUnmetPrecondition(session, flow, since) {
  * transport failure by design, and a step in the middle of a journey has no budget to sit and poll
  * with. `navigateAndAwait` CAN wait, because it knows it asked for the navigation, and it does.
  */
+/** The path a `navigate` step expects to land on: `/u07` for `/u07?x=1` or `http://host/u07`. */
+function pathOfUrl(url) {
+    try {
+        return new URL(url, 'http://localhost').pathname;
+    }
+    catch {
+        return url;
+    }
+}
 export function lostDocumentResult(name, lost) {
     return {
         name,
@@ -244,6 +256,20 @@ export function lostDocumentResult(name, lost) {
 export async function replayNamedFlow(deps, args, 
 /** Wraps the session the steps run on, so a caller can watch what they resolved. */
 observe = (s) => s) {
+    try {
+        return await replayOnce(deps, args, observe);
+    }
+    finally {
+        // Where this flow left the tab, so the next flow's reset does not keep its query.
+        try {
+            noteReplayEnded(deps.sessions.resolve(asString(args['sessionId'])));
+        }
+        catch {
+            /* no tab is left to note */
+        }
+    }
+}
+async function replayOnce(deps, args, observe) {
     const startedAt = deps.now();
     const name = asString(args['flowName']) ?? '';
     // Resolve within the connecting app's scope so a shared daemon replays THIS project's flow, not a
@@ -274,7 +300,9 @@ observe = (s) => s) {
     const replayRoot = sessionRoot(deps, asString(args['sessionId']));
     const intents = new IntentStore(deps.fs, replayRoot, { now: deps.now });
     const intentSaid = await flowIntentStatement(intents, loaded.value);
-    const connected = deps.sessions.resolve(asString(args['sessionId']));
+    // `verify` reloads the page between flows. A flow that starts in the reconnect gap waits for the
+    // page, up to the start-page budget, instead of ending unknown at once (#2168).
+    const connected = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), startPathBudgetMs(loaded.value), { now: deps.now, sleep: WALL_CLOCK.sleep });
     // The FlowFile contract: replay navigates to the flow's startPath before step 1, and the steps run
     // on the session the SDK reconnects as. When arrival can't be confirmed, replay proceeds on the
     // connected session — and the hint below turns the wrong-page drift into an actionable next move.
@@ -285,10 +313,11 @@ observe = (s) => s) {
     const stillLoading = pool === undefined ? undefined : () => pool.leaseLoading(connected.id);
     const arrival = continueAt === undefined
         ? await arriveAtStartPath(deps.sessions, connected, loaded.value, undefined, undefined, stillLoading)
-        : {};
+        : routeClaimsWhereTheTabIs(loaded.value, connected);
     // Continuing on `connected` after the tab left timed every step out on a dead handle (#1129).
-    if (arrival.lost !== undefined) {
-        const reason = arrival.lost;
+    // A declared route that replay could not reach is the same: the steps would run on another page.
+    const reason = arrival.lost ?? arrival.unreached;
+    if (reason !== undefined) {
         return withStartPageWait({
             name: loaded.value.name,
             status: ReplayStatus.UNVERIFIABLE,
@@ -303,6 +332,29 @@ observe = (s) => s) {
     // Floor the success oracle at the start of THIS replay so a stale signal from a prior run
     // in the same session can't fake a pass.
     const replayFloor = session.elapsed();
+    /*
+     * A `navigate` step loads another page, and the page that asked for the load is gone. The journey
+     * goes on with the session of the page that loaded, and so does everything judged after the last
+     * step: the cross-step pass, the success oracle and the deviation report. That page's clock starts
+     * at its own connect, so its floor is 0.
+     */
+    let live = session;
+    let liveFloor = replayFloor;
+    const openPage = async (url) => {
+        const outcome = await navigateAndAwait(deps.sessions, live, url, pathOfUrl(url), startPathBudgetMs(loaded.value), undefined, { acceptRedirect: true });
+        if ('arrived' === outcome.kind || 'redirected' === outcome.kind) {
+            live = outcome.session;
+            liveFloor = 0;
+            return { session: observe(withLeaseKeyboard(deps, live)) };
+        }
+        if ('refused' === outcome.kind) {
+            return { error: `the page refused to open ${url}` };
+        }
+        return {
+            error: `no page of this app answered in ${String(outcome.waitedMs)} ms after opening ${url}; ` +
+                'the page may have left the app, which a flow cannot follow',
+        };
+    };
     // An upload path becomes bytes once, before step 1, against the app's project (#1769).
     const uploadDeps = { fs: deps.fs, reticleRoot: replayRoot };
     const replayable = await resolveFlowUploads(uploadDeps, loaded.value);
@@ -382,9 +434,14 @@ observe = (s) => s) {
             // Bug-sweep mode: keep going past a step whose action ran and whose consequence merely did
             // not hold, so one flow reports one verdict per step instead of stopping at the first defect.
             sweep: true === args['sweep'],
+            navigate: openPage,
+            request: requestSender(() => live.url, deps.realInput, (account) => secretValue(secretEnvKey(account), process.env)),
             ...(from === undefined ? {} : { from }),
             ...(to === undefined ? {} : { to }),
             ...(continueAt === undefined ? {} : { at: continueAt }),
+            // Replay loaded the start page, so the load is part of the journey. The successor session
+            // began with that load, at time 0.
+            ...(arrival.session === undefined ? {} : { loadSince: 0 }),
             // The HUD's replay chip, when the human pressed ▶. In-process only: an agent's arguments
             // arrive as JSON and can never carry a function.
             onStepResult: replayStepShooter(deps, session.id),
@@ -412,9 +469,9 @@ observe = (s) => s) {
      */
     const crossStep = (() => {
         try {
-            const span = { since: replayFloor, until: session.elapsed() };
-            const events = session.eventsSince(replayFloor).filter((e) => e.t >= replayFloor);
-            const scope = { ...appScope(session), declared: declaredIn(loaded.value.steps) };
+            const span = { since: liveFloor, until: live.elapsed() };
+            const events = live.eventsSince(liveFloor).filter((e) => e.t >= liveFloor);
+            const scope = { ...appScope(live), declared: declaredIn(loaded.value.steps) };
             return crossStepOnly(stepEffect(events, span, scope).contradictions ?? [], steps);
         }
         catch {
@@ -426,11 +483,11 @@ observe = (s) => s) {
     // even though all locators resolved — the regression a healed-but-wrong locator ships green.
     const stepsClean = steps.length > 0 && steps.every((s) => s.ok && s.drift === undefined);
     if (stepsClean && loaded.value.success !== undefined) {
-        const verdict = await assertSuccess(session, loaded.value.success, dynamicTestids(loaded.value), waitForPredicate, 
+        const verdict = await assertSuccess(live, loaded.value.success, dynamicTestids(loaded.value), waitForPredicate, 
         // The flow's own declaration, not the built-in floor: an app slow enough to need a longer
         // step wait is slow enough that its OUTCOME lands late too, and greening every step only to
         // fail the success oracle at 4s is the same false red one layer down.
-        loaded.value.signalTimeoutMs ?? FLOW_SIGNAL_TIMEOUT_MS, replayFloor);
+        loaded.value.signalTimeoutMs ?? FLOW_SIGNAL_TIMEOUT_MS, liveFloor);
         const row = {
             step: steps.length,
             tool: SUCCESS_STEP_TOOL,
@@ -440,7 +497,12 @@ observe = (s) => s) {
         };
         steps.push(row);
     }
-    const staleTarget = staleTargetResult(name, steps);
+    // The caller's request counts only when replay itself loaded the start page and stayed there.
+    const startControlRequired = true === args['requireStartControl'] &&
+        arrival.session !== undefined &&
+        arrival.redirected === undefined &&
+        arrival.resetCost === undefined;
+    const staleTarget = staleTargetResult(name, steps, { startControlRequired });
     if (staleTarget !== undefined) {
         return withStartPageWait(staleTarget, arrival);
     }
@@ -480,7 +542,7 @@ observe = (s) => s) {
         }
     }
     // Push-default: the deviation report over this drive's segments, learned across runs. Best-effort.
-    const deviation = await computeReplayDeviation(deps, session, replayFloor, replayRoot);
+    const deviation = await computeReplayDeviation(deps, live, liveFloor, replayRoot);
     /*
      * What the team already knows about this flow, fetched on the agent's behalf.
      *

package/dist/language/flows/flow-replay-types.d.ts

@@ -1,6 +1,6 @@
 import type { CommandResult, ReticleEvent } from '@reticlehq/core';
 import type { Predicate } from '@reticlehq/engine/question/predicate/predicate-schema.js';
-import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate.js';
+import type { Baselines, EvalResult } from '@reticlehq/engine/question/predicate/predicate.js';
 /**
  * The shapes a replay needs from whatever is driving it.
  *
@@ -41,6 +41,8 @@ export interface FlowReplaySession {
  * `since` is the event-time floor (default 0 = whole buffer): pass the cursor captured before a
  * replay so the success oracle can't be satisfied by a stale signal from a prior replay/run.
  */
-export type WaitForSignal = (session: FlowReplaySession, predicate: Predicate, timeoutMs: number, since?: number) => Promise<EvalResult>;
+export type WaitForSignal = (session: FlowReplaySession, predicate: Predicate, timeoutMs: number, since?: number, 
+/** Readings taken before the action, for `unchanged` and the other comparing properties. */
+baselines?: Baselines) => Promise<EvalResult>;
 /** Injected sleeper so tests drive replay with a no-op clock; production waits on a real timer. */
 export type Sleep = (ms: number) => Promise<void>;

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

@@ -2,6 +2,8 @@ export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.j
 import type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
 export type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
 import { type Drift, type FlowFile, type FlowStep, type FlowStepResult, ReplayStatus } from '@reticlehq/core';
+import { type Baselines } from '@reticlehq/engine/evidence/baseline.js';
+import { type OpenPage, type SendRequest } from './steps/page-steps.js';
 /**
  * The document this replay was driving went away mid-run.
  *
@@ -42,7 +44,7 @@ export declare function runTestidStep(session: FlowReplaySession, step: FlowStep
  * quietly stop agreeing, and the disagreement would land as a flow that replays green against a
  * state it was never meant to run in.
  */
-export declare function assertStepExpect(session: FlowReplaySession, expect: NonNullable<FlowStep['expect']>, waitForSignal: WaitForSignal, timeoutMs: number, since: number): Promise<Drift | undefined>;
+export declare function assertStepExpect(session: FlowReplaySession, expect: NonNullable<FlowStep['expect']>, waitForSignal: WaitForSignal, timeoutMs: number, since: number, baselines?: Baselines): Promise<Drift | undefined>;
 /**
  * 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
@@ -62,6 +64,13 @@ export declare function withCaseOnly(reason: string, verdict: {
  * How a replay is loaded, where it starts reporting, and how far it goes.
  */
 export interface ReplayFromOptions {
+    /**
+     * Opens the page a `navigate` step names and returns the session of the page that loaded. Supplied
+     * by the caller that owns the sessions. Absent: a `navigate` step fails, never skips.
+     */
+    navigate?: OpenPage<FlowReplaySession>;
+    /** Sends the request a `request` step names. Absent: a `request` step fails, never skips. */
+    request?: SendRequest;
     /**
      * Told after every step it reports: how many are done, of how many, and whether this one held.
      * The HUD's replay chip draws its progress from this; it must never throw into the replay.
@@ -102,6 +111,15 @@ export interface ReplayFromOptions {
      * replayer had honoured invocations for an hour by then. Two replay paths; one was wired.
      */
     resolveFlow?: (name: string) => Promise<FlowFile | undefined>;
+    /**
+     * Set when replay loaded the start page itself: the session time the load began.
+     *
+     * The load is then part of the journey. An error the page logged while it loaded lands before
+     * step 1 opens its window, so a "no console errors" on step 1 passed over it. Only console-absent
+     * clauses look back to here. A `net` or `text` clause that did so could be satisfied by the load
+     * and not by the step, which is a false pass.
+     */
+    loadSince?: number;
     /** The invocation chain that reached this flow, nearest caller first. Empty at the top. */
     via?: readonly {
         flow: string;