@reticlehq/server 3.7.0 → 3.8.1

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

@@ -0,0 +1,59 @@
+/**
+ * What a flow needs from the live session to run in a leased context, and what it reports when the
+ * lease never came up.
+ */
+import { ReplayStatus } from '@reticlehq/core';
+import { AppRuntime } from '@reticlehq/core';
+/**
+ * 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 function leasableAppUrl(deps, sessionId) {
+    try {
+        const session = deps.sessions.resolve(sessionId);
+        if (AppRuntime.WEB !== (session.runtime ?? AppRuntime.WEB)) {
+            return undefined;
+        } // desktop: no IPC in a lease
+        const url = session.url;
+        if (typeof url !== 'string' || 0 === url.length) {
+            return undefined;
+        }
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined; // no live session (or an unparseable URL) → sequential path
+    }
+}
+/**
+ * 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 function sessionUrlOf(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).url;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A flow whose leased context never came up is a suite ERROR, never a silent pass. */
+export function leaseFailureReplay(name, error) {
+    return {
+        name,
+        status: ReplayStatus.ERROR,
+        steps: [],
+        error: {
+            code: ReplayStatus.ERROR,
+            message: `could not run in a leased context: ${error ?? 'unknown error'}`,
+        },
+    };
+}

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

@@ -1,7 +1,4 @@
-import { type CommandResult, type FlowFile, type FlowReplayResult, type ReticleEvent } from '@reticlehq/core';
-import type { ArrivalClock } from '../../surface/tools/act/navigation/navigate-arrival.js';
-import type { SessionManager } from '../../portal/session/session-manager.js';
-import type { Session } from '../../portal/session/session.js';
+import { type FlowReplayResult, type ReticleEvent } from '@reticlehq/core';
 import { DocumentLostDuringReplay, type FlowReplaySession } from './flow-replay.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 export declare function latestRecordedFlow(events: ReticleEvent[]): {
@@ -9,89 +6,6 @@ export declare function latestRecordedFlow(events: ReticleEvent[]): {
     flow: import('@reticlehq/core').FlowFile;
 } | undefined;
 export { flowErrorMessage } from './flow-result.js';
-/** The slice of a session the start-path logic reads: the live URL plus the event buffer. */
-interface StartPathSession {
-    url?: string;
-    eventsSince(cursor: number): ReticleEvent[];
-}
-/**
- * When a flow records the page its journey started on (`startPath`) and the tab is currently on a
- * different route, step 1 drifts for a reason that has nothing to do with the app regressing — the
- * anchor simply isn't on this page yet. Detect that so the decision says "navigate there first"
- * instead of a mystifying "a step no longer matches". Returns undefined when the routes agree or the
- * current route is unobservable — never a false alarm. Replay normally never gets here on a
- * wrong page (arriveAtStartPath navigates before step 1); this is the fallback when navigation
- * was refused. A page that never reconnected is reported as unverifiable before step 1.
- */
-export declare function startPathMismatchHint(flow: FlowFile, session: StartPathSession): string | undefined;
-/** What replay learned on its way to step 0. Both fields absent = the tab was left exactly as it was. */
-export interface StartPathArrival {
-    /** The successor session replay must continue on. Absent when nothing was navigated, or arrival timed out. */
-    session?: Session;
-    /** Set when the RESET itself is why step 1 cannot start — the reason a step-1 red is not drift. */
-    resetCost?: string;
-    /** Set when the tab was sent away and nothing reconnected: the old handle will never answer (#1129). */
-    lost?: string;
-    /** A live successor arrived on a different route, so replay must not use the dead old handle. */
-    redirected?: string;
-}
-/**
- * Replay's half of the FlowFile contract: put the tab on the flow's `startPath` before step 1, and
- * RELOAD it if it is already there.
- *
- * The reload is the state contract. Replaying "add a task" twice against a tab nobody reset gives
- * the second run a world the recording never saw, and its assertions then describe the first run
- * rather than the app. Our own `replay-determinism.mjs` has always refreshed before every run — the
- * determinism we measured was never the determinism a user got.
- *
- * `requires` is the declared opt-out, and its first caller. A flow that says it starts from state
- * another flow established is the one flow a page load would destroy, so it is never reset — here
- * or from the wrong page. Silence is not an opt-out: a flow that depends on leftovers without
- * saying so is a flow whose green means nothing on a fresh machine, and CI is a fresh machine.
- *
- * A full-page load tears down the session socket, so the navigation must happen here — before any
- * step runs — and the replay continues on the session the SDK reconnects as (found via the same
- * tombstone rebind that lets `resolve(oldId)` answer after any navigation). Best-effort by design:
- * when the flow carries no startPath, the current route is unobservable, or navigation is refused,
- * replay proceeds on the connected session. A missing successor stops before step 1; a redirect
- * continues on the live successor with a route-specific hint.
- */
-export declare function arriveAtStartPath(sessions: SessionManager, session: StartPathSession & {
-    id: string;
-    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock): Promise<StartPathArrival>;
-/**
- * Send a tab somewhere and wait for the session that comes back.
- *
- * A navigation is a full page load: the session that issued it DIES and a successor connects with a
- * new id. Every caller therefore has to wait for that successor rather than reuse the handle it
- * already holds, and getting this wrong does not error — it leaves the caller talking to a session
- * that will never answer again.
- *
- * Extracted so there is ONE of these rather than one per caller. `arriveAtStartPath` decides WHETHER
- * to move and this decides how, which is also why the deliberate short-circuits live up there and
- * not in here: a caller that has already decided it must move should not have to argue with them.
- */
-/** How a navigate ended: target, redirect, refusal (untouched tab), or no successor. */
-export type NavigateOutcome = {
-    kind: 'arrived';
-    session: Session;
-} | {
-    kind: 'redirected';
-    session: Session;
-} | {
-    kind: 'refused';
-} | {
-    kind: 'lost';
-};
-export declare function navigateAndAwait(sessions: SessionManager, session: {
-    id: string;
-    /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
-    url?: string;
-    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-}, destination: string, expectedPath: string, timeoutMs?: number, clock?: ArrivalClock, 
-/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
-isReload?: boolean): Promise<NavigateOutcome>;
 /**
  * The honest answer when the document replay was driving went away mid-run.
  *