@reticlehq/server 3.7.0 → 3.8.1

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

@@ -1,4 +1,5 @@
 import { CALL_SECRETS_ARG, callSecretsArg } from './fields/flow-secret-field.js';
+import { REPLAYABILITY_OUTPUT, SKIP_WRITES_ARG } from './flow-replayable.js';
 import { flowAuthor } from './flow-author.js';
 import { FLOW_MUTATE_TOOL } from './flow-mutate-tools.js';
 import { seedSchema, workerCountSchema } from '../../surface/tools/args/numeric-bounds.js';
@@ -8,9 +9,9 @@ import { emptyFlowRefusal } from './empty-flow.js';
 import { aliasParam, aliasUsed } from '../../surface/tools/args/alias-args.js';
 import { stillRecording, stillRecordingMessage } from './flow-result.js';
 import { resolveAnnotateTarget } from './annotate-notes/annotate-target.js';
-import { FlowErrorCode, RecordedSaveError, ReplayStatus, SuiteIsolation, } from '@reticlehq/core';
+import { FlowErrorCode, RecordedSaveError, SuiteIsolation, } from '@reticlehq/core';
 import { recordSuiteFlakes } from './suite/suite-flakes.js';
-import { AppRuntime, ReticleTool } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { log } from '../../log.js';
 import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../../memory/cloud/cloud-sync.js';
@@ -25,11 +26,11 @@ import { classifyFlowAssertions, flattenSteps } from './flow-classify.js';
 import { recordingBacktrackWarning } from './recording/recording-backtrack.js';
 import { isValidFlowName, flowPath } from '../../memory/project/dir/reticle-dir.js';
 import {} from './flows.js';
-import { flowsForSession } from './flow-store-for-session.js';
+import { flowsForSession, flowsForSessionId } from './flow-store-for-session.js';
 import { rootForTarget, sessionTarget } from '../../memory/project/session-root.js';
 import { originOf } from '../../portal/session/session-manager.js';
 import { resolveSuiteSelection } from './suite-selection.js';
-import { flowErrorMessage, latestRecordedFlow, sessionProjectId } from './flow-replay-run.js';
+import { flowErrorMessage, latestRecordedFlow } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun, } from '../../judgement/runs/verification-sync.js';
 import { runServerVerify } from './suite/server-verify.js';
 import { healFlow } from './heal-run.js';
@@ -37,6 +38,8 @@ import { RESULT_FIELD, resultField, suiteResult } from '../../surface/tools/reti
 import { replayOneFlow } from './single-replay.js';
 export { replayNamedFlow } from './flow-replay-run.js';
 import { replayAndLearn } from './flow-learning.js';
+import { leasableAppUrl, leaseFailureReplay, sessionUrlOf } from './flow-lease.js';
+export { leasableAppUrl, leaseFailureReplay, sessionUrlOf } from './flow-lease.js';
 /**
  * Best-effort mirror of a just-saved flow to Reticle (only when logged in — both cloud env vars
  * set). Fire-and-forget: resolves the config, POSTs via the platform fetch, and logs the outcome. Any
@@ -48,8 +51,9 @@ async function syncSavedFlowToCloud(deps, flow, target) {
     // `flowsForSession`, and reading the credential from a different tree is how one project's work
     // reaches another project's dashboard.
     const cloud = await resolveProjectCloud(deps.fs, rootForTarget(deps, target), homedir(), process.env);
-    if (null === cloud.config || !cloud.policy.flows)
-        return; // not attached / flows disabled → local only
+    if (null === cloud.config || !cloud.policy.flows) {
+        return;
+    } // not attached / flows disabled → local only
     const result = await syncFlowToCloud(flow, cloud.config, target.projectId, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-flow-sync-failed', { flow: flow.name, status: result.status, error: result.error });
@@ -57,57 +61,6 @@ async function syncSavedFlowToCloud(deps, flow, target) {
 }
 /** A step index no recorded flow reaches; bounds `to` and `at`. */
 const MAX_REPLAY_STEP = 10_000;
-/**
- * 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'}`,
-        },
-    };
-}
 /** Stand-in path for a flow whose name fails the path-segment guard — never a real join. */
 const INVALID_FLOW_NAME_PATH = '(invalid flow name — not a usable path)';
 /**
@@ -121,16 +74,18 @@ const INTENT_GAP_FIELD = z
     .unknown()
     .optional()
     .describe('Present ONLY when the flow was saved with nothing saying what it is for: { kind, missing, cost, fix }. The flow is on disk either way — this never blocks a save. Close it by saving again with `intent`, or by setting the flow file’s `intentId` to an intent already in the ledger. Nothing here is ever derived from the flow name, the steps or the assertions: a guessed goal reads as the author’s own words.');
+/** `flow`: the name reticle_annotate gives the field the flow tools call `flowName`. */
+const FLOW_NAME_ALIAS = z
+    .string()
+    .optional()
+    .describe('Alias for `flowName` (the name reticle_annotate uses).');
 export const FLOW_TOOLS = [
     FLOW_MUTATE_TOOL,
     {
         name: ReticleTool.FLOW_SAVE,
         description: 'Persist a STOPPED recording (by name) as a git-checked, anchor-resolved flow at .reticle/flows/<name>.json. A recording that is still running is refused: stop it first with reticle_record{action:"stop"}, and the refusal names the exact call. Each step is bound to a SEMANTIC anchor (testid/role/signal), never a volatile ref; steps without a resolvable testid are kept with degraded:true (a "add a data-testid here" marker) rather than dropped. Returns { name, stepCount, degraded, empty, assertions, warning? } — `assertions.grade` is asserted | presence-only | assertion-free: a flow that only acts (or only checks element presence) will pass even if the feature breaks, so when grade is not "asserted" follow assertions.warning and add a consequence assertion via reticle_annotate (assert-signal / assert-net / success-state). `warning` is present when the recording left a page and returned to it: replay has no navigation steps, so the next click will look for a control on a page the tab is no longer on.',
         inputSchema: {
-            flow: z
-                .string()
-                .optional()
-                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            flow: FLOW_NAME_ALIAS,
             name: z.string().optional().describe('Alias for `flowName`.'),
             flowName: z
                 .string()
@@ -244,8 +199,9 @@ export const FLOW_TOOLS = [
             // A zero-step recording is not a flow. Saving it wrote a file the suite reports "unverifiable"
             // forever while telling the agent it had saved a regression test — see empty-flow.
             const emptyRefusal = emptyFlowRefusal(program.steps.length, name);
-            if (emptyRefusal !== undefined)
+            if (emptyRefusal !== undefined) {
                 return Promise.resolve(emptyRefusal);
+            }
             const { flows, root } = flowsForSession(deps, target);
             const author = flowAuthor();
             const toSave = {
@@ -254,8 +210,9 @@ export const FLOW_TOOLS = [
                 ...(author === undefined ? {} : { author }),
             };
             return flows.save(toSave, annotations, projectId).then(async (res) => {
-                if (!res.ok)
+                if (!res.ok) {
                     return { error: flowErrorMessage(res.code, res.detail), code: res.code };
+                }
                 deps.annotations.clear(name);
                 // Grade the saved flow's assertions so the agent learns immediately if it just saved a flow
                 // that asserts nothing observable (passes even when the feature is broken).
@@ -327,10 +284,7 @@ export const FLOW_TOOLS = [
         name: ReticleTool.FLOW_LOAD,
         description: 'Read + validate a saved flow by flowName from .reticle/flows/<flowName>.json. Returns the FlowFile (version, flowName, createdAt, anchored steps) or a structured { error, code }. Step `expect` (and flow `success`) accepts the same allOf grammar as reticle_act_and_wait; a parse failure names the step and key rather than calling the file malformed.',
         inputSchema: {
-            flow: z
-                .string()
-                .optional()
-                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            flow: FLOW_NAME_ALIAS,
             flowName: z
                 .string()
                 .describe('Flow file name (without .json extension) from reticle_flow{action:"list"}.'),
@@ -340,21 +294,19 @@ export const FLOW_TOOLS = [
                 .describe('Active session ID — resolves the flow within that app’s scope.'),
         },
         outputSchema: {
-            flow: z
-                .string()
-                .optional()
-                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            flow: FLOW_NAME_ALIAS,
             flowName: z.string(),
             steps: z.array(z.unknown()),
             createdAt: z.number().optional(),
         },
         handler: (deps, args) => {
-            const projectId = sessionProjectId(deps, asString(args['sessionId']));
-            return deps.flows
+            const { flows, projectId } = flowsForSessionId(deps, asString(args['sessionId']));
+            return flows
                 .load(asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '', projectId)
                 .then((res) => {
-                if (!res.ok)
+                if (!res.ok) {
                     return { error: flowErrorMessage(res.code, res.detail), code: res.code };
+                }
                 const { name, ...rest } = res.value;
                 return { flowName: name, ...rest };
             });
@@ -366,10 +318,7 @@ export const FLOW_TOOLS = [
             'to the connected app. Returns { deleted: true } or a structured { error, code } (code not_found ' +
             'when no such flow — deleting an absent flow is an error, not a silent no-op).',
         inputSchema: {
-            flow: z
-                .string()
-                .optional()
-                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            flow: FLOW_NAME_ALIAS,
             flowName: z
                 .string()
                 .describe('Flow file name (without .json extension) from reticle_flow{action:"list"}.'),
@@ -384,12 +333,13 @@ export const FLOW_TOOLS = [
             code: z.string().optional(),
         },
         handler: (deps, args) => {
-            const projectId = sessionProjectId(deps, asString(args['sessionId']));
-            return deps.flows
+            const { flows, projectId } = flowsForSessionId(deps, asString(args['sessionId']));
+            return flows
                 .remove(asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '', projectId)
                 .then((res) => {
-                if (!res.ok)
+                if (!res.ok) {
                     return { error: flowErrorMessage(res.code, res.detail), code: res.code };
+                }
                 return { deleted: true };
             });
         },
@@ -405,15 +355,14 @@ export const FLOW_TOOLS = [
             'document) — neither pass nor fail, treat as UNKNOWN. ' +
             'An ok replay of a flow asserting no consequence also carries unverifiable:{reason} — do not ' +
             'treat as proof. ' +
-            'Early halt carries halted:{atStep, notAttempted}: `steps` is shorter because replay stopped.',
+            'Early halt carries halted:{atStep, notAttempted}: `steps` is shorter because replay stopped. ' +
+            'A start page that kept loading past the step budget carries startPageWait:{waitedMs, budgetMs, stillLoading}.',
         inputSchema: {
-            flow: z
-                .string()
-                .optional()
-                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            flow: FLOW_NAME_ALIAS,
             flowName: z
                 .string()
-                .describe('Flow file name (without .json extension) from reticle_flow{action:"list"}.'),
+                .optional()
+                .describe('Flow file name (without .json extension) from reticle_flow{action:"list"}. Required, here or as `flow`.'),
             [CALL_SECRETS_ARG]: callSecretsArg,
             confirmDangerous: confirmDangerousArg('this replay'),
             from: z
@@ -469,6 +418,11 @@ export const FLOW_TOOLS = [
                 .object({ atStep: z.number(), notAttempted: z.number() })
                 .optional()
                 .describe('Set when the replay STOPPED at a failing step: `steps` is shorter than the flow, and this says where it stopped and how many steps were never attempted. Absent means every step ran.'),
+            // Declared for the same reason as `halted`: an undeclared field is stripped.
+            startPageWait: z
+                .object({ waitedMs: z.number(), budgetMs: z.number(), stillLoading: z.boolean() })
+                .optional()
+                .describe('Set when replay waited past the step budget because the start page was still loading. stillLoading is what the tab said the last time replay asked. Absent means the wait stayed inside the budget.'),
             // Declared here or a validating profile strips it -- the same way `name` was stripped once.
             // A field the handler sets and the schema omits arrives as nothing, silently.
             /*
@@ -510,7 +464,7 @@ export const FLOW_TOOLS = [
         },
         // The decision envelope is attached by replayNamedFlow only on drift/fail (clean pass stays
         // token-flat). Single-flow replay and whole-suite verify share that one implementation.
-        handler: (deps, args) => replayOneFlow(deps, args, leasableAppUrl(deps, asString(args['sessionId']))),
+        handler: (deps, args) => replayOneFlow(deps, aliasParam(args, 'flowName', ['flow']), leasableAppUrl(deps, asString(args['sessionId']))),
     },
     {
         name: ReticleTool.FLOW_VERIFY,
@@ -533,6 +487,7 @@ export const FLOW_TOOLS = [
                 .optional()
                 .describe('Run this many flows at once, each in its own isolated leased browser context (needs the browser pool). Clamped to the pool capacity and the flow count. Omit for the sequential single-tab run.'),
             confirmDangerous: confirmDangerousArg('this run of the suite'),
+            skipWrites: SKIP_WRITES_ARG,
             sessionId: z
                 .string()
                 .optional()
@@ -583,6 +538,8 @@ export const FLOW_TOOLS = [
                 .array(z.unknown())
                 .optional()
                 .describe('Flows whose prerequisite is not in this run — filtered out by a label, quarantined, or never saved. They did NOT run, because failing them would report the wrong thing.'),
+            replayability: REPLAYABILITY_OUTPUT,
+            skippedWrites: z.array(z.string()).optional().describe('Flows held back by skipWrites.'),
             // Session-EXEMPT, so it does not inherit `sessionEnvelopeShape` — declare the one-shot human
             // feedback ask here or a validating profile strips it off the suite verdict.
             feedback_prompt: z.unknown().optional(),
@@ -602,12 +559,14 @@ export const FLOW_TOOLS = [
                 ...(0 === selected.unmatched.length ? {} : { unmatched: selected.unmatched }),
                 ...(selected.cycles === undefined ? {} : { cycles: selected.cycles }),
                 ...(selected.unsatisfied === undefined ? {} : { unsatisfied: selected.unsatisfied }),
+                ...(selected.writing === undefined ? {} : { skippedWrites: selected.writing }),
             };
             // verify:server — hand the whole suite to the hosted runner; it records the verification itself.
             const cloud = await resolveProjectCloud(deps.fs, rootForTarget(deps, target), homedir(), process.env);
             const server = await runServerVerify(deps, cloud, sessionId, requested);
-            if (server !== null)
+            if (server !== null) {
                 return server;
+            }
             // PARALLEL: flows race the DOM only when they share ONE tab. Given the lease pool, each
             // flow gets its own isolated context, so a large suite finishes in interactive time. Opt-in via
             // `parallel`; a missing prerequisite (no pool, unknown app URL) falls back to the sequential path
@@ -688,12 +647,7 @@ export const FLOW_TOOLS = [
             const timed = [];
             // Sequential default: every flow replays against the same live session, so they must not overlap.
             //
-            // They also START wherever the previous flow left the app, which makes a verdict depend on RUN
-            // ORDER — measured, and the cause of a contradiction that moved between flows run by run. A
-            // reset between flows was BUILT AND REVERTED: see the ledger's 9.2. Playwright's
-            // `storageState` carries cookies and localStorage and NOT sessionStorage, so a forced reload
-            // restores part of an app's auth and drops the rest, and the suite went from noisy to FAILING
-            // (1 of 2 flows). Restoring two thirds of a session is worse than restoring none.
+            // Each starts where the last left the app; a reset was built and reverted (see the ledger's 9.2).
             for (const flowName of requested) {
                 const start = deps.now();
                 const replay = await replayAndLearn(deps, { flowName, sessionId, ...confirmed });
@@ -737,10 +691,7 @@ export const FLOW_TOOLS = [
             'recorded name. Returns { name, stepCount, degraded, empty } or { error, code } (code ' +
             'flow_no_recorded when no recording is present).',
         inputSchema: {
-            flow: z
-                .string()
-                .optional()
-                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            flow: FLOW_NAME_ALIAS,
             flowName: z
                 .string()
                 .optional()
@@ -786,15 +737,17 @@ export const FLOW_TOOLS = [
             // The store stamps the project into the file AND routes it to the per-project subdir (a shared
             // daemon serves many apps), so location and content agree from one source of truth.
             const emptyRecorded = emptyFlowRefusal(flow.steps.length, flow.name);
-            if (emptyRecorded !== undefined)
+            if (emptyRecorded !== undefined) {
                 return emptyRecorded;
+            }
             // Resolved like every other path now. This save used to go to the daemon's root while the
             // recorded-flow save resolved per session, so where a flow landed depended on which tool wrote
             // it — and the pair that disagreed were the two ways to save the same thing.
             const target = { projectId: session.projectId, origin: originOf(session.url) };
             const res = await flowsForSession(deps, target).flows.saveFlow(flow, session.projectId);
-            if (!res.ok)
+            if (!res.ok) {
                 return { error: flowErrorMessage(res.code, res.detail), code: res.code };
+            }
             // If logged in to Reticle, mirror the saved flow to the team's regression suite. Best-effort
             // and non-blocking: the flow is already on disk, so a sync failure never fails the save.
             void syncSavedFlowToCloud(deps, flow, target);
@@ -815,12 +768,9 @@ export const FLOW_TOOLS = [
             'untouched). Returns { name, status: healed|drift|unhealable|consequence_broken|' +
             'nothing_to_heal|error, applied, proposals[], changed[], message }.',
         inputSchema: {
-            flow: z
-                .string()
-                .optional()
-                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            flow: FLOW_NAME_ALIAS,
             flowName: z.string().describe('Flow file name to heal (from reticle_flow{action:"list"}).'),
-            apply: z.boolean().optional(),
+            apply: z.boolean().optional().describe('Write the rebind. Omit to see the proposal only.'),
             confirmDangerous: confirmDangerousArg('this heal replay'),
             sessionId: z
                 .string()
@@ -828,10 +778,7 @@ export const FLOW_TOOLS = [
                 .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
         },
         outputSchema: {
-            flow: z
-                .string()
-                .optional()
-                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            flow: FLOW_NAME_ALIAS,
             flowName: z.string(),
             status: z.string(),
             applied: z.boolean(),
@@ -859,16 +806,19 @@ async function loadInvoked(flows, flow, projectId) {
     const seen = new Set([flow.name]);
     while (queue.length > 0) {
         const current = queue.shift();
-        if (current === undefined)
+        if (current === undefined) {
             continue;
+        }
         for (const step of flattenSteps(current.steps)) {
             const name = step.invoke;
-            if (name === undefined || seen.has(name))
+            if (name === undefined || seen.has(name)) {
                 continue;
+            }
             seen.add(name);
             const sub = await flows.load(name, projectId);
-            if (!sub.ok || sub.value === undefined)
+            if (!sub.ok || sub.value === undefined) {
                 continue;
+            }
             out.set(name, sub.value);
             queue.push(sub.value);
         }

package/dist/language/flows/flows.d.ts

@@ -4,7 +4,8 @@ import { type FlowResult } from './flow-result.js';
 export type { FlowResult } from './flow-result.js';
 import type { FlowAnchor, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
 import type { CompiledProgram, RecordedStep } from './recording/tape/recordings.js';
-import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import { type FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import { type Replayability } from './flow-replayable.js';
 import type { Clock } from '../../machine/clock.js';
 /** Pick the on-disk anchor for a normalized step: testid > component(auto) > degraded role. */
 export declare function anchorForStep(args: Record<string, unknown>): {
@@ -49,6 +50,8 @@ interface SaveSummary {
      * and absent the moment the flow carries prose or an `intentId`. See `flowIntentGap`.
      */
     intentGap?: InstrumentationGap;
+    /** Absent when the flow replays as it is; else whether it can, and why not, by step. */
+    replayability?: Replayability;
 }
 /**
  * The structured annotations folded onto a flow at save time: per-step
@@ -66,11 +69,6 @@ export interface FlowAnnotations {
 /** Persists anchored flows to .reticle/flows/<name>.json. Filesystem + clock are injected. */
 export declare class FlowStore {
     #private;
-    /**
-     * `onWrote` is told after a save lands, so cloud sync cycles on a new flow the way it does on a
-     * new run (`RunStore` takes the same callback). Without it a flow saved with no run behind it
-     * waited for the timer, and a daemon that exited first never sent it.
-     */
     constructor(fs: FileSystemPort, root: string, clock: Clock, opts?: {
         onWrote?: () => void;
     });