@reticlehq/server 3.9.0 → 3.10.1

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

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { PredicateKind } from '@reticlehq/core';
+import { routePathOf } from '@reticlehq/engine/question/predicate/predicate-route.js';
 /**
  * One journey, however many times it was driven.
  *
@@ -104,17 +105,108 @@ export function routeClaims(startPath, steps) {
 /**
  * The preconditions only another flow can establish.
  *
- * A route claim on the page the flow starts on is not one of them: replay navigates there itself, so
- * it neither opts the flow out of the reset nor gates the run. That is the claim a saved drive writes
- * for the map (see routeClaims) — reading it as "starts from leftover state" would stop every
- * auto-saved flow from ever being reset.
+ * A route claim with a `pathname` is not one of them: replay navigates to a declared route itself
+ * (see `declaredRoute`), and checks the claim, its `contains` too, once the tab is there (see
+ * `unmetRouteClaim`). So a route claim neither opts the flow out of the reset nor gates the run
+ * here. The claim on the page the flow starts on is the one a saved drive writes for the map (see
+ * routeClaims) — reading it as "starts from leftover state" would stop every auto-saved flow from
+ * ever being reset. A route claim on ANOTHER page was read that way, and a suite then ran the flow
+ * on whatever page the previous flow left open (#2034).
  */
 export function establishedState(flow) {
+    return (flow.requires ?? []).filter((claim) => !(PredicateKind.ROUTE === claim.kind && claim.pathname !== undefined));
+}
+/**
+ * The route claims in `requires` that say more than the flow's `startPath`, in order.
+ *
+ * A claim on the `startPath` itself is left out: that is the claim every saved drive writes, and
+ * replay already arrives there. Every other claim names a page the flow needs (#2034).
+ */
+function pageClaims(flow) {
     const start = flow.startPath;
-    return (flow.requires ?? []).filter((claim) => !(start !== undefined &&
-        PredicateKind.ROUTE === claim.kind &&
-        claim.pathname !== undefined &&
-        samePath(claim.pathname, start)));
+    const claims = [];
+    for (const claim of flow.requires ?? []) {
+        if (PredicateKind.ROUTE !== claim.kind || claim.pathname === undefined) {
+            continue;
+        }
+        if (0 === claim.pathname.length) {
+            continue;
+        }
+        if (start !== undefined && samePath(claim.pathname, start)) {
+            continue;
+        }
+        claims.push({
+            pathname: claim.pathname,
+            ...(claim.contains === undefined ? {} : { contains: claim.contains }),
+        });
+    }
+    return claims;
+}
+/**
+ * The route a flow declares in `requires` when that says more than its `startPath`: the first
+ * such claim, in any order of the claims. Undefined when there is none, and replay then arrives
+ * at `startPath` as before. Replay puts the tab on this route before step 1 (#2034).
+ */
+export function declaredRoute(flow) {
+    return pageClaims(flow)[0]?.pathname;
+}
+/**
+ * The first declared route claim that the page `observed` does not satisfy, said for a reader.
+ * Undefined when they all hold. Each claim is checked whole: its `pathname` by `onRoute`, and its
+ * `contains` against the whole route, as the `route` predicate checks it.
+ */
+export function unmetRouteClaim(flow, observed) {
+    for (const claim of pageClaims(flow)) {
+        if (!onRoute(observed, claim.pathname)) {
+            return `it is not on ${claim.pathname}`;
+        }
+        if (claim.contains !== undefined && !observed.includes(claim.contains)) {
+            return `its address does not contain "${claim.contains}"`;
+        }
+    }
+    return undefined;
+}
+/** The mark of a route segment that stands for any one entity id: `:id` in `/cases/:id/notes`. */
+const ROUTE_PARAM_MARK = ':';
+/** Whether a route segment is a placeholder such as `:id`. */
+function isRouteParam(segment) {
+    return segment.startsWith(ROUTE_PARAM_MARK) && ROUTE_PARAM_MARK.length < segment.length;
+}
+/** The segments of the path the router is on, without a query or a trailing slash. */
+function routerSegments(path) {
+    let parsed;
+    try {
+        parsed = new URL(path, 'http://localhost');
+    }
+    catch {
+        return undefined;
+    }
+    return routePathOf(parsed.pathname, parsed.hash).replace(/\/$/, '').split('/');
+}
+/** Whether a declared route names an entity id with a `:name` segment, for example `/cases/:id/notes`. */
+export function isRoutePattern(route) {
+    return (routerSegments(route) ?? []).some(isRouteParam);
+}
+/**
+ * Is the tab on a declared route?
+ *
+ * A plain route is compared as `samePath` compares a `startPath`. A pattern is compared segment by
+ * segment on the router's path, and a `:name` segment matches any one non-empty segment. The query
+ * is not compared for a pattern: the pattern says which page, and the id says which record.
+ */
+export function onRoute(observed, route) {
+    if (!isRoutePattern(route)) {
+        return samePath(observed, route);
+    }
+    const here = routerSegments(observed);
+    const wanted = routerSegments(route);
+    if (here === undefined || wanted === undefined || here.length !== wanted.length) {
+        return false;
+    }
+    return wanted.every((segment, i) => {
+        const at = here[i] ?? '';
+        return isRouteParam(segment) ? 0 < at.length : segment === at;
+    });
 }
 /**
  * Is the tab where the flow asked to start? Up to a trailing slash, and up to the query the flow
@@ -150,3 +242,41 @@ export function startPathBudgetMs(flow) {
     const first = flow.steps[0]?.timeoutMs ?? flow.signalTimeoutMs ?? 0;
     return Math.max(START_PATH_ARRIVAL_TIMEOUT_MS, first);
 }
+/**
+ * A pattern route with its `:name` segments filled from the page `observed`.
+ *
+ * A segment is taken only when every segment before it in the route agrees with the page: from
+ * `/cases/c-42/files`, the route `/cases/:id/notes` becomes `/cases/c-42/notes`. So another section
+ * of the same case keeps the case, and the recorded id, which can be a deleted record, is not used.
+ * Undefined when the page has no id to give (`/settings`), or the route has no `:name` segment.
+ */
+export function fillRouteParams(route, observed) {
+    const wanted = routerSegments(route);
+    const here = routerSegments(observed);
+    if (wanted === undefined || here === undefined) {
+        return undefined;
+    }
+    const values = [];
+    for (const [i, segment] of wanted.entries()) {
+        if (!isRouteParam(segment)) {
+            continue;
+        }
+        const agrees = wanted
+            .slice(0, i)
+            .every((before, j) => isRouteParam(before) || before === here[j]);
+        const value = here[i] ?? '';
+        if (!agrees || 0 === value.length) {
+            return undefined;
+        }
+        values.push(value);
+    }
+    if (0 === values.length) {
+        return undefined;
+    }
+    let next = 0;
+    return route.replace(/(?<=\/):[^/?#]+/g, (param) => {
+        const value = values[next] ?? param;
+        next += 1;
+        return value;
+    });
+}

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

@@ -6,22 +6,6 @@ export declare function latestRecordedFlow(events: ReticleEvent[]): {
     flow: import('@reticlehq/core').FlowFile;
 } | undefined;
 export { flowErrorMessage } from './flow-result.js';
-/**
- * The honest answer when the document replay was driving went away mid-run.
- *
- * Not a pass: nothing graded the journey, and the steps in hand are only the ones the departed
- * document answered. Not a failure either — the app was never observed doing anything wrong, and
- * reporting one would be the false red that sends a reader into product code that is fine. So it
- * lands in the bucket this engine already has for "nothing was proved", the same one an unmet
- * precondition uses, with the steps that DID answer attached and no row invented for the one that
- * did not.
- *
- * Why replay reports rather than follows: the successor cannot be identified at the moment the
- * socket closes. `SessionManager.remove` runs from the close handler, writes the tombstone a
- * successor is later matched against, and has nothing to match yet — so the rejection is a plain
- * 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.
- */
 export declare function lostDocumentResult(name: string, lost: DocumentLostDuringReplay): FlowReplayResult;
 export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unknown>, 
 /** Wraps the session the steps run on, so a caller can watch what they resolved. */

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;