@reticlehq/server 3.6.0 → 3.7.0

package/dist/features/harness/script/script-run.js

@@ -8,15 +8,108 @@
  * Barriers cannot deadlock: a journey only waits on one in an EARLIER lane (`checkScript`), lanes
  * are started in order, so whatever is waited on has already started.
  */
-import { PredicateKind, ReplayStatus, ReticleTool, ScriptStatus, Verified, asRecord, } from '@reticlehq/core';
-import { ScriptStepKind, barriersOf, stepLabel, } from '@reticlehq/core/artifacts';
-import { checkTally } from '../drive-report.js';
-import { goalsIn } from '../goals.js';
+import { PredicateKind, ReplayStatus, ReticleTool, ScriptStatus, Verified, asRecord, asString, } from '@reticlehq/core';
+import { JourneyBy, JourneyOutcome, ScriptStepKind, barriersOf, stepLabel, } from '@reticlehq/core/artifacts';
+import { ReplayOutcome, checkTally, replayedFlows } from '../drive-report.js';
+import { endOf, lookFor } from '../goals.js';
 import { DEFAULT_MAX_STEPS, StopReason, } from '../harness.js';
 /** Why a journey failed when its goal, not a check, is what was missing. */
 const GOAL_NOT_REACHED = 'the goal was not reached, though its checks may have held';
 /** A planned open journey gets the same budget a named persona drive gets. */
 const OPEN_GOAL_STEPS = DEFAULT_MAX_STEPS;
+/** Fewer model turns left than this and a continuation could not take the step it is sent for. */
+const MIN_CONTINUE_STEPS = 3;
+/** Why a journey whose replays decided nothing was handed to the model. */
+const FELL_BACK = 'its replays decided nothing, so the model drove its goal';
+/** A replay that neither held nor failed: drifted, unverifiable, or a flow not on this computer. */
+const UNDECIDED_REPLAY = new Set([
+    ReplayOutcome.DRIFT,
+    ReplayOutcome.MISSING,
+    ReplayStatus.UNVERIFIABLE,
+    undefined,
+]);
+/**
+ * The journey's replays decided nothing about the app: one could not anchor or run, and none failed.
+ * A held sign-in beside a drifted mid-session flow is not a failure of the app, and read "Failed".
+ */
+function replaysDecidedNothing(calls) {
+    const replays = replayedFlows(calls);
+    return (replays.some((r) => UNDECIDED_REPLAY.has(r.status)) &&
+        !replays.some((r) => ReplayOutcome.ERROR === r.status));
+}
+/** Why a journey whose replay could not anchor or run is undecided, not failed. */
+const msgReplayUndecided = (flow) => `the recording ${flow} could not anchor or run on this app, which decides nothing about the app`;
+/** The flows a journey replayed or saved, each once, in the order it touched them. */
+function flowsOf(calls) {
+    const names = calls.flatMap((call) => {
+        if (ReticleTool.FLOW_REPLAY === call.name)
+            return [asString(asRecord(call.args)['flowName'])];
+        if (ReticleTool.FLOW_SAVE !== call.name || call.isError)
+            return [];
+        const args = asRecord(call.args);
+        return [
+            asString(asRecord(call.result)['name']) ??
+                asString(args['saveAs']) ??
+                asString(args['flowName']),
+        ];
+    });
+    return [...new Set(names.filter((n) => n !== undefined))];
+}
+/** What a journey's own model drives cost, and what it touched. */
+function journeyRun(id, calls, own) {
+    const credits = own.flatMap((d) => (d.creditsSpent === undefined ? [] : [d.creditsSpent]));
+    // Replayed only when it replayed: a model goal the end-already-shown guard stopped spent no
+    // tokens and was called "replayed, no model tokens" on a journey that had no replay at all.
+    const by = 0 < own.length
+        ? JourneyBy.MODEL
+        : 0 < replayedFlows(calls).length
+            ? JourneyBy.REPLAY
+            : undefined;
+    return {
+        id,
+        ...(by === undefined ? {} : { by }),
+        tokens: own.reduce((n, d) => n + d.usage.input + d.usage.output + d.usage.cacheRead + d.usage.cacheWrite, 0),
+        ...(0 === credits.length ? {} : { credits: credits.reduce((a, b) => a + b, 0) }),
+        flows: flowsOf([...calls, ...own.flatMap((d) => d.toolCalls)]),
+    };
+}
+/** Two lanes' runs of one journey, as one: the model's cost added, every flow kept. */
+function mergeRuns(a, b) {
+    const credits = a.credits === undefined && b.credits === undefined
+        ? undefined
+        : (a.credits ?? 0) + (b.credits ?? 0);
+    const by = [JourneyBy.MODEL, JourneyBy.REPLAY].find((k) => k === a.by || k === b.by);
+    return {
+        id: a.id,
+        ...(by === undefined ? {} : { by }),
+        tokens: a.tokens + b.tokens,
+        ...(credits === undefined ? {} : { credits }),
+        flows: [...new Set([...a.flows, ...b.flows])],
+    };
+}
+/** How a journey was answered, as its line says it: only what was measured. */
+function byText(run) {
+    if (run?.by === undefined)
+        return '';
+    return JourneyBy.REPLAY === run.by
+        ? ' · replayed, no model tokens'
+        : ` · driven by the model, ${String(run.tokens)} tokens`;
+}
+/** Why a journey whose end the page showed before it acted is not credited with it. */
+const msgEndAlreadyShown = (end) => `"${end}" was already on the page before this journey acted, so reaching it proves nothing`;
+/**
+ * Whether a journey picks up where the one before it in its lane left off: it builds on one there
+ * (`dependsOn`), or it looks at how one failed. Every other journey starts from the lane's start.
+ */
+function continuesLane(journey, before) {
+    return (journey.dependsOn.some((id) => before.has(id)) ||
+        (journey.when !== undefined &&
+            JourneyOutcome.FAILED === journey.when.is &&
+            before.has(journey.when.journey)));
+}
+/** What a drive that stopped short of its end state is sent back with. */
+const continueGoal = (goal, end) => `${goal}\n\nContinue from the page you are on: it does not show "${end}" yet. ` +
+    'Take the next step this journey names; do not start over.';
 export async function runScript(script, ports, onChange = () => undefined) {
     const view = planView(script, Math.min(ports.parallel, script.maxParallel ?? ports.parallel));
     const toolCalls = [];
@@ -30,7 +123,8 @@ export async function runScript(script, ports, onChange = () => undefined) {
             /* the picture of a drive is never a reason to stop it */
         }
     };
-    // A journey that sits in several lanes is answered by the FIRST lane holding it; barriers wait on that.
+    // A journey that sits in several lanes is answered by the FIRST lane holding it; barriers wait on
+    // that. It is answered with how it ended, because a condition can be waiting for a failure.
     const outcome = new Map();
     const firstLane = new Map();
     for (const lane of script.lanes) {
@@ -47,45 +141,134 @@ export async function runScript(script, ports, onChange = () => undefined) {
     /** Journeys whose checks may have held but whose goal the drive did not reach. */
     const goalMissed = new Set();
     const broken = new Map();
+    /** Per card, for its line; per id, for the platform. */
+    const runOf = new Map();
+    const runs = new Map();
     tell();
     const runLane = async (lane, laneIndex) => {
         const cards = view.lanes[laneIndex]?.journeys ?? [];
-        const settleOwned = (id, ok) => {
+        const settleOwned = (id, status) => {
             if (firstLane.get(id) === lane.id)
-                outcome.get(id)?.settle(ok);
+                outcome.get(id)?.settle(status);
         };
         let lease;
         let blocked = false;
+        /** Where the lane's first journey started, and the journeys the lane has driven since. */
+        let start;
+        const driven = new Set();
         try {
             for (const [position, id] of lane.journeys.entries()) {
                 const card = cards[position];
                 const journey = journeyById.get(id);
                 if (card === undefined || journey === undefined)
                     continue;
-                const waits = await Promise.all(barriersOf(script, lane.id, id).map((dep) => outcome.get(dep)?.promise ?? Promise.resolve(false)));
-                if (blocked || stopped || ports.stopped() || waits.includes(false)) {
-                    blocked = true;
+                const ended = (dep) => outcome.get(dep)?.promise ?? Promise.resolve(ScriptStatus.BLOCKED);
+                const waits = await Promise.all(barriersOf(script, lane.id, id).map(ended));
+                // A conditional journey is decided by how the journey it names ended, not by the lane: a
+                // failure earlier in the lane is often exactly what it is there to look at.
+                const when = journey.when;
+                const lanePast = when === undefined && blocked;
+                if (lanePast ||
+                    stopped ||
+                    ports.stopped() ||
+                    waits.some((s) => ScriptStatus.PASSED !== s)) {
+                    if (when === undefined)
+                        blocked = true;
                     card.status = ScriptStatus.BLOCKED;
-                    settleOwned(id, false);
+                    settleOwned(id, ScriptStatus.BLOCKED);
+                    tell();
+                    continue;
+                }
+                if (when !== undefined && (await ended(when.journey)) !== when.is) {
+                    card.status = ScriptStatus.NOT_TAKEN;
+                    settleOwned(id, ScriptStatus.NOT_TAKEN);
                     tell();
                     continue;
                 }
                 lease ??= await ports.lease(lane.id);
-                const tools = recording(ports.toolset(lease.sessionId, journey.persona), toolCalls);
+                const raw = ports.toolset(lease.sessionId, journey.persona);
+                // Unrecorded: where the journey starts is set-up, not something it drove or checked.
+                // Kept for a journey with a fallback too: its goal starts where the journey began, not
+                // on the page its own replays left (where the end may already show).
+                if (0 === driven.size && (1 < lane.journeys.length || journey.fallback !== undefined))
+                    start = asString(asRecord(asRecord(await call(raw, ReticleTool.SNAPSHOT, {}))['status'])['route']);
+                else if (start !== undefined && !continuesLane(journey, driven))
+                    await call(raw, ReticleTool.NAVIGATE, { url: start });
+                driven.add(id);
+                // This journey's calls alone too: lanes share `toolCalls`, and its replays decide its fallback.
+                const mine = [];
+                const tools = recording(recording(raw, toolCalls), mine);
                 card.status = ScriptStatus.RUNNING;
                 tell();
                 // This journey's own drives: lanes run side by side, so a slice of the shared list after the
                 // await could hold another lane's missed goal and blame it on this journey.
                 const own = [];
-                const ok = await runJourney(journey, card.steps, tools, ports, own, tell, () => {
+                const stop = () => {
                     stopped = true;
-                });
-                card.status = ok ? ScriptStatus.PASSED : ScriptStatus.FAILED;
+                };
+                // The end the fallback goal names, and whether the page showed it before anything ran: a
+                // replay can only be credited with an end it put there.
+                const end = journey.fallback === undefined ? undefined : endOf(journey.fallback.goal);
+                const endBefore = end !== undefined && (await lookFor(raw.invoke.bind(raw), end, ports.own));
+                let ran = await runJourney(journey, card.steps, tools, ports, own, tell, stop);
+                // Replay first: replays that decided nothing hand the journey's goal to the model. One that
+                // failed is a regression, and a regression is reported, never re-driven into a pass.
+                let refused;
+                if (!ran.ok &&
+                    ran.notTaken === undefined &&
+                    journey.fallback !== undefined &&
+                    !ports.stopped() &&
+                    replaysDecidedNothing(mine)) {
+                    // Replays that decided nothing can still have driven the journey to its end. Driven
+                    // over MCP: the replay pressed Generate and the page showed the goal's end text; the
+                    // Harness threw that away, re-drove from a start that signed the app out, and failed a
+                    // working app. The end is judged where the replay left it, by an assert kept as the
+                    // run's check — and never when the page showed it before the journey ran.
+                    const replayReachedEnd = end !== undefined &&
+                        !endBefore &&
+                        (await lookFor(raw.invoke.bind(raw), end, ports.own)) &&
+                        (await holds(tools, { kind: PredicateKind.TEXT, contains: end }));
+                    if (replayReachedEnd)
+                        ran = { ok: true };
+                    else
+                        refused = await ports.fallbackRefused?.();
+                    if (!replayReachedEnd && refused === undefined) {
+                        if (start !== undefined)
+                            await call(raw, ReticleTool.NAVIGATE, { url: start });
+                        ran = await runFallback(journey.fallback.goal, tools, ports, own, stop);
+                    }
+                }
+                const ok = ran.ok;
+                // A drive the platform cut off (credits gone, a refusal, a 5xx) judged nothing: blocked, and
+                // its reason said, never "failed" over an app nobody finished driving.
+                const cutDrive = own.find((d) => StopReason.BROKEN === d.stopReason);
+                const cut = refused === undefined ? cutDrive : { error: refused, stopReason: StopReason.BROKEN };
+                if (cut !== undefined)
+                    broken.set(lane.id, cut.error ?? StopReason.BROKEN);
+                card.status = ok
+                    ? ScriptStatus.PASSED
+                    : cut !== undefined
+                        ? ScriptStatus.BLOCKED
+                        : ran.notTaken !== undefined
+                            ? ScriptStatus.NOT_TAKEN
+                            : true === ran.undecided
+                                ? ScriptStatus.UNDECIDED
+                                : ScriptStatus.FAILED;
+                if (ran.notTaken !== undefined)
+                    card.why = ran.notTaken;
+                if (ran.why !== undefined)
+                    card.why = ran.why;
                 drives.push(...own);
+                const thisRun = journeyRun(id, mine, own);
+                runOf.set(card, thisRun);
+                const before = runs.get(id);
+                runs.set(id, before === undefined ? thisRun : mergeRuns(before, thisRun));
                 if (!ok && own.some((d) => false === d.goalMet))
                     goalMissed.add(card);
-                blocked = !ok;
-                settleOwned(id, ok);
+                // A conditional journey that failed leaves the lane as it found it: it was a side road.
+                if (when === undefined)
+                    blocked = !ok;
+                settleOwned(id, card.status);
                 tell();
             }
         }
@@ -99,7 +282,7 @@ export async function runScript(script, ports, onChange = () => undefined) {
                 }
             }
             for (const id of lane.journeys)
-                settleOwned(id, false);
+                settleOwned(id, ScriptStatus.BLOCKED);
             tell();
         }
         finally {
@@ -121,13 +304,22 @@ export async function runScript(script, ports, onChange = () => undefined) {
             ? broken.get(lane.id)
             : goalMissed.has(card)
                 ? GOAL_NOT_REACHED
-                : undefined;
-        return `${mark(card.status)} ${lane.id} · ${card.title} — ${card.status}${why === undefined ? '' : ` (${why.slice(0, 160)})`}`;
+                : card.why;
+        return `${mark(card.status)} ${lane.id} · ${card.title} — ${card.status}${why === undefined ? '' : ` (${why.slice(0, 160)})`}${byText(runOf.get(card))}`;
     }));
-    return { view, toolCalls, drives, stopped: stopped || ports.stopped(), lines };
+    return {
+        view,
+        toolCalls,
+        drives,
+        stopped: stopped || ports.stopped(),
+        lines,
+        journeys: [...runs.values()],
+    };
 }
 async function runJourney(journey, cards, tools, ports, drives, tell, stop) {
     const checkpoints = new Map();
+    // One journey is one chain: a replay after the first continues the page the one before it left.
+    let replayed = false;
     for (const [index, step] of journey.steps.entries()) {
         const card = cards[index];
         if (card === undefined)
@@ -135,32 +327,87 @@ async function runJourney(journey, cards, tools, ports, drives, tell, stop) {
         if (ports.stopped()) {
             card.status = ScriptStatus.BLOCKED;
             tell();
-            return false;
+            return { ok: false };
         }
         card.status = ScriptStatus.RUNNING;
         tell();
         let ok;
-        if (ScriptStepKind.CHECKPOINT === step.kind) {
-            checkpoints.set(step.id, step.reenter);
-            ok = true;
-        }
-        else if (ScriptStepKind.BRANCH === step.kind) {
-            ok = await runBranch(step, checkpoints.get(step.at), tools, ports, drives, stop);
+        let notTaken;
+        let why;
+        let undecided = false;
+        try {
+            if (ScriptStepKind.CHECKPOINT === step.kind) {
+                checkpoints.set(step.id, step.reenter);
+                ok = true;
+            }
+            else if (ScriptStepKind.BRANCH === step.kind) {
+                ok = await runBranch(step, checkpoints.get(step.at), tools, ports, drives, stop);
+            }
+            else {
+                ok = await runLeaf(step, tools, ports, drives, stop, replayed);
+                if (ScriptStepKind.REPLAY === step.kind)
+                    replayed = true;
+            }
         }
-        else {
-            ok = await runLeaf(step, tools, ports, drives, stop);
+        catch (error) {
+            if (error instanceof Undecided) {
+                why = error.message;
+                undecided = true;
+            }
+            else if (error instanceof StepNotTaken)
+                notTaken = error.message;
+            else
+                throw error;
+            ok = false;
         }
-        card.status = ok ? ScriptStatus.PASSED : ScriptStatus.FAILED;
+        card.status = ok
+            ? ScriptStatus.PASSED
+            : notTaken !== undefined
+                ? ScriptStatus.NOT_TAKEN
+                : undecided
+                    ? ScriptStatus.UNDECIDED
+                    : ScriptStatus.FAILED;
         tell();
         if (!ok) {
             for (const rest of cards.slice(index + 1))
                 rest.status = ScriptStatus.BLOCKED;
             tell();
-            return false;
+            return {
+                ok: false,
+                ...(notTaken === undefined ? {} : { notTaken }),
+                ...(why === undefined ? {} : { why }),
+                ...(undecided ? { undecided: true } : {}),
+            };
         }
     }
-    return true;
+    return { ok: true };
+}
+/** The journey's goal, driven by the model in place of replays that decided nothing. */
+async function runFallback(goal, tools, ports, drives, stop) {
+    try {
+        const ok = await runLeaf({ kind: ScriptStepKind.ACT, goal }, tools, ports, drives, stop);
+        return ok ? { ok } : { ok, why: FELL_BACK };
+    }
+    catch (error) {
+        if (error instanceof Undecided)
+            return { ok: false, why: error.message, undecided: true };
+        throw error;
+    }
 }
+/** The guard stopped a destructive step nobody acknowledged: the step was not taken, not failed. */
+class StepNotTaken extends Error {
+}
+/** The journey ran and decided nothing: neither proved nor a failure of the app. */
+class Undecided extends Error {
+}
+/** The journey's end was on the page before it acted: undecided, never credited, no model spent. */
+class EndAlreadyShown extends Undecided {
+}
+/** Why a journey that reached its goal with no check that could go red proves nothing. */
+const MSG_GOAL_WITHOUT_CHECK = 'it reached its goal, and no check could have gone red there';
+/** What the guard's refusal names, as `drive-report.ts` reads it too. */
+const DESTRUCTIVE_REFUSAL = 'confirmDangerous';
+const MSG_NOT_TAKEN = 'not taken: a step the flow marks destructive needs a person to acknowledge it (Run plan, Re-verify)';
 /**
  * Every case drives from the checkpoint. The first starts where the journey already is; each later
  * one re-enters it first, so no case inherits the page the previous case left behind.
@@ -188,35 +435,73 @@ async function runBranch(step, reenter, tools, ports, drives, stop) {
     }
     return all;
 }
-async function runLeaf(step, tools, ports, drives, stop) {
+async function runLeaf(step, tools, ports, drives, stop, 
+/** A replay ran before this one in the journey: continue its page, never reload it. */
+chained = false) {
     switch (step.kind) {
         case ScriptStepKind.REPLAY:
             return replay(tools, {
                 flowName: step.flow,
-                ...(step.at === undefined ? {} : { at: step.at }),
+                ...(step.at === undefined ? (chained ? { at: 0 } : {}) : { at: step.at }),
                 ...(step.to === undefined ? {} : { to: step.to }),
+                // The flow's own steps, acknowledged by the person who started the run.
+                ...(true === ports.confirmDangerous ? { [DESTRUCTIVE_REFUSAL]: true } : {}),
             });
         case ScriptStepKind.ASSERT:
             return holds(tools, step.predicate);
         case ScriptStepKind.ACT: {
             if (step.goal !== undefined) {
-                const drive = await ports.drive(tools, step.goal, step.maxSteps ?? OPEN_GOAL_STEPS);
+                const budget = step.maxSteps ?? OPEN_GOAL_STEPS;
+                // Parsed before the drive: an end the page already shows is already true, never proved.
+                const ending = endOf(step.goal);
+                if (ending !== undefined && (await lookFor(tools.invoke.bind(tools), ending, ports.own)))
+                    throw new EndAlreadyShown(msgEndAlreadyShown(ending));
+                let drive = await ports.drive(tools, step.goal, budget);
                 drives.push(drive);
                 if (StopReason.STOPPED === drive.stopReason)
                     stop();
-                // Passed means its checks held, not that it ran one: a refund journey whose two checks both
-                // failed was marked passed because a check had run.
-                const tally = checkTally(drive.toolCalls);
-                if (0 < tally.failed || false === drive.goalMet)
-                    return false;
                 // A goal that quotes where it ends is judged there, by an assert kept as the run's check:
                 // the model clicked a counter with no `until` and the journey failed on a counter that worked.
-                // ponytail: the LAST quote is the end state ("from "count: 0" to "count: 1""); a goal that
-                // quotes its end first needs the planner to say which quote is the end.
-                const end = goalsIn(step.goal).at(-1);
-                if (end !== undefined)
-                    return holds(tools, { kind: PredicateKind.TEXT, contains: end });
-                return 0 < tally.held;
+                // ponytail: the LAST quote the goal does not negate is the end state ("from "count: 0" to
+                // "count: 1""); a goal that quotes its end first needs the planner to say which is the end.
+                const end = ending;
+                if (end === undefined) {
+                    // Passed means its checks held, not that it ran one: a refund journey whose two checks
+                    // both failed was marked passed because a check had run.
+                    if (0 < checkTally(drive.toolCalls).failed)
+                        return false;
+                    if (0 < checkTally(drive.toolCalls).held)
+                        return false !== drive.goalMet;
+                    // Reached, by its own word, with nothing checked: not proved, and not a failure either.
+                    if (true === drive.goalMet)
+                        throw new Undecided(MSG_GOAL_WITHOUT_CHECK);
+                    return false;
+                }
+                // The drive's failures are judged after its end is: the model's own early look at the end
+                // ("Generated script for", asserted before the request that writes it had answered) is
+                // superseded when the end then holds, by the same rule as the run's verdict.
+                const failedBeside = (calls, endHeld) => 0 < checkTally(endHeld ? [...calls, endHeldCall(end)] : calls).failed;
+                let shown = await lookFor(tools.invoke.bind(tools), end, ports.own);
+                // A drive that finished with turns to spare, short of the end its own plan names (joined,
+                // opened Runs, never clicked Team), is sent on once from where it stands, not graded there.
+                const left = budget - drive.steps;
+                if (!shown && StopReason.FINISHED === drive.stopReason && MIN_CONTINUE_STEPS <= left) {
+                    if (failedBeside(drive.toolCalls, false))
+                        return false;
+                    drive = await ports.drive(tools, continueGoal(step.goal, end), left);
+                    drives.push(drive);
+                    if (StopReason.STOPPED === drive.stopReason)
+                        stop();
+                    shown = await lookFor(tools.invoke.bind(tools), end, ports.own);
+                }
+                // Never reached is the journey's miss, not a failed check on the app: no assert is kept. The
+                // page decides it, not the driver's word: an end the page shows was reached, whatever the
+                // driver said (a drive started on a dead link reached it and was failed on its own "no").
+                if (!shown)
+                    return false;
+                const endHeld = await holds(tools, { kind: PredicateKind.TEXT, contains: end });
+                // Passed means its checks held, not that it ran one.
+                return endHeld && !failedBeside(drive.toolCalls, true);
             }
             const result = await call(tools, ReticleTool.ACT_AND_WAIT, {
                 ...(step.target === undefined ? {} : { target: step.target }),
@@ -229,11 +514,33 @@ async function runLeaf(step, tools, ports, drives, stop) {
     }
 }
 async function replay(tools, args) {
-    return ReplayStatus.OK === asRecord(await call(tools, ReticleTool.FLOW_REPLAY, args))['status'];
+    const result = asRecord(await call(tools, ReticleTool.FLOW_REPLAY, args));
+    if (ReplayStatus.OK === result['status'])
+        return true;
+    const error = result['error'];
+    const message = asString(error) ?? asString(asRecord(error)['message']) ?? '';
+    if (message.includes(DESTRUCTIVE_REFUSAL))
+        throw new StepNotTaken(MSG_NOT_TAKEN);
+    const [outcome] = replayedFlows([
+        { id: 'replay', name: ReticleTool.FLOW_REPLAY, args, result, isError: false },
+    ]);
+    if (UNDECIDED_REPLAY.has(outcome?.status))
+        throw new Undecided(msgReplayUndecided(String(args['flowName'])));
+    return false;
 }
 async function holds(tools, predicate) {
     return true === asRecord(await call(tools, ReticleTool.ASSERT, { predicate }))['pass'];
 }
+/** The end check `holds` keeps, as a call the drive's tally can read beside the model's own. */
+function endHeldCall(end) {
+    return {
+        id: 'end',
+        name: ReticleTool.ASSERT,
+        args: { predicate: { kind: PredicateKind.TEXT, contains: end } },
+        result: { verified: Verified.YES },
+        isError: false,
+    };
+}
 /** A tool that throws is a failed step, not a crashed run. */
 async function call(tools, name, args) {
     try {

package/dist/features/license/license.d.ts

@@ -39,14 +39,14 @@ declare const LicensePayloadSchema: z.ZodObject<{
     exp: z.ZodNumber;
     features: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
-    org: string;
     plan: string;
+    org: string;
     lid: string;
     exp: number;
     features?: string[] | undefined;
 }, {
-    org: string;
     plan: string;
+    org: string;
     lid: string;
     exp: number;
     features?: string[] | undefined;

package/dist/features/visual/step-shots.d.ts

@@ -0,0 +1,31 @@
+import { ScreenshotSource, type FlowStepResult } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+export interface ShotOptions {
+    step?: string;
+    verdict?: boolean;
+}
+/** What a tool result carries: where the picture is and how it was taken, or why there is none. */
+export type ScreenshotField = {
+    path: string;
+    source: ScreenshotSource;
+} | {
+    error: string;
+};
+/**
+ * Width and height from a JPEG's frame header, or undefined when the bytes are not a JPEG.
+ * Read rather than trusted: the run record and the upload both state the size.
+ */
+export declare function jpegSize(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * Photograph the tab a step just ran on. Returns the result field; never throws, because a
+ * screenshot is evidence about a step and must never be the reason the step's answer is lost.
+ *
+ * `step` names the flow step a replay was on, as `<flow>#<index>`, so the run can pin the picture
+ * to it; `verdict` says the call produced a verdict, so the run can pair the picture with its check.
+ */
+export declare function takeStepShot(deps: ToolDeps, sessionId: string, tool: string, opts?: ShotOptions): Promise<ScreenshotField>;
+/** The replay hook that gives every reported flow step its screenshot, filed as `<flow>#<step>`. */
+export declare function replayStepShooter(deps: ToolDeps, sessionId: string): (result: FlowStepResult, flow: string) => Promise<void>;