@reticlehq/server 3.4.0 → 3.6.0

package/dist/features/harness/platform/server-driver.js

@@ -0,0 +1,179 @@
+/**
+ * The platform's Harness, seen from the daemon: the platform decides, this machine executes.
+ *
+ * Every turn is one HTTPS request this daemon makes: it posts what the last calls did, and the
+ * platform answers with the next calls, chosen by its own model, persona and verification mode. The
+ * loop around it (`runHarness`) is unchanged: it executes the calls through Reticle's own tools and
+ * hands the outcomes back here. Nothing is held open between turns, a lost response is retried with
+ * the same turn number, and the platform answers that from its record without a second model call.
+ *
+ * This is the only Harness driver: every decision is the platform's, for a workspace with a plan or
+ * trial. A secret field travels by name only, and its value is filled in here before the call runs.
+ */
+import { ReticleEnv, cloudUrlFrom } from '@reticlehq/core';
+import { DriveStoppedError, } from '../harness.js';
+export const SERVER_DRIVER_NAME = 'server';
+const RUNS_PATH = '/v1/harness/runs';
+const TURN_TIMEOUT_MS = 110_000;
+const RETRIES = 1;
+/** The platform's code for a run whose project had autonomous driving switched off. */
+const HARNESS_OFF = 'harness_off';
+const FINISH = 'finish';
+/** The platform's url and this project's key, when the machine is linked. */
+export function serverOptionsFromEnv(env) {
+    const url = cloudUrlFrom(env);
+    const apiKey = env[ReticleEnv.API_KEY];
+    return url === undefined || apiKey === undefined || 0 === apiKey.length
+        ? undefined
+        : { url: url.replace(/\/+$/, ''), apiKey };
+}
+export class ServerHarnessError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export function serverDriver(options) {
+    const doFetch = options.fetch ?? ((url, init) => fetch(url, init));
+    let runId;
+    let turn = 0;
+    let seen = 0;
+    const call = async (path, body) => {
+        let last;
+        for (let attempt = 0; attempt <= RETRIES; attempt += 1) {
+            try {
+                const res = await doFetch(`${options.url}${path}`, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${options.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(TURN_TIMEOUT_MS),
+                });
+                const text = await res.text();
+                if (!res.ok) {
+                    const message = errorMessage(text) ?? `the platform answered ${String(res.status)}`;
+                    // A person turned it off: the drive ends, and the result says that rather than "broken".
+                    if (HARNESS_OFF === errorCode(text))
+                        throw new DriveStoppedError(message);
+                    // A refusal is an answer; only a network failure is worth asking again.
+                    throw new ServerHarnessError(message, res.status);
+                }
+                return JSON.parse(text);
+            }
+            catch (error) {
+                if (error instanceof ServerHarnessError || error instanceof DriveStoppedError)
+                    throw error;
+                last = error;
+            }
+        }
+        throw last instanceof Error ? last : new Error(String(last));
+    };
+    return {
+        async turn(input) {
+            if (runId === undefined) {
+                const started = (await call(RUNS_PATH, {
+                    ...(options.persona === undefined ? {} : { persona: options.persona }),
+                    ...(options.journey === undefined ? {} : { journey: options.journey }),
+                    ...(options.mode === undefined ? {} : { mode: options.mode }),
+                    ...(options.plan === undefined ? {} : { plan: options.plan }),
+                    ...(options.maxSteps === undefined ? {} : { maxSteps: options.maxSteps }),
+                    ...(options.planSteps === undefined ? {} : { planSteps: options.planSteps }),
+                    ...(options.vocabulary === undefined ? {} : { vocabulary: options.vocabulary }),
+                    secrets: secretNames(options.env ?? process.env),
+                    tools: input.tools.filter((t) => FINISH !== t.name).map(toolSpec),
+                }));
+                if ('string' !== typeof started.runId)
+                    throw new ServerHarnessError('the platform started no run', 502);
+                runId = started.runId;
+            }
+            // Only what happened since the last turn: the platform holds everything before it.
+            const fresh = input.history.slice(seen);
+            seen = input.history.length;
+            const outcomes = fresh.flatMap((entry) => 'tool' === entry.role ? entry.outcomes.map(outcomeOf) : []);
+            const reply = (await call(`${RUNS_PATH}/${encodeURIComponent(runId)}/turn`, {
+                turn,
+                outcomes,
+            }));
+            turn = reply.turn + 1;
+            // The platform's spend, reported so the drive's cost is visible here as it is for a local one.
+            const usage = reply.usage === undefined ? {} : { usage: reply.usage };
+            if (reply.done) {
+                // The platform has finished: `finish` ends the local loop the same way a local model would.
+                return {
+                    text: reply.text,
+                    ...usage,
+                    calls: [
+                        {
+                            id: `server-finish-${String(reply.turn)}`,
+                            name: FINISH,
+                            args: {
+                                summary: reply.summary ?? reply.text,
+                                ...('boolean' === typeof reply.goalMet ? { goalMet: reply.goalMet } : {}),
+                            },
+                        },
+                    ],
+                };
+            }
+            // A field the platform knows only by name is filled here, from this machine, and never sent.
+            const env = options.env ?? process.env;
+            return {
+                text: reply.text,
+                calls: reply.calls.map((c) => ({ ...c, args: withSecrets(c.args, env) })),
+                ...usage,
+            };
+        },
+    };
+}
+function toolSpec(tool) {
+    return { name: tool.name, description: tool.description, inputSchema: tool.inputSchema };
+}
+function outcomeOf(o) {
+    return { id: o.id, name: o.name, result: o.result, isError: o.isError };
+}
+function errorCode(text) {
+    try {
+        const body = JSON.parse(text);
+        return 'string' === typeof body.error?.code ? body.error.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function errorMessage(text) {
+    try {
+        const body = JSON.parse(text);
+        return 'string' === typeof body.error?.message ? body.error.message : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The prefix of a variable holding one secret field: `RETICLE_SECRET_AUTH_PASSWORD`. */
+const SECRET_ENV_PREFIX = 'RETICLE_SECRET_';
+/** What the platform types into a field whose secret this machine holds. */
+const SECRET_PLACEHOLDER = 'reticle-secret:';
+/** The secret fields this machine can fill, by name only. */
+export function secretNames(env) {
+    return Object.keys(env)
+        .filter((key) => key.startsWith(SECRET_ENV_PREFIX) && 0 < (env[key] ?? '').length)
+        .map((key) => key.slice(SECRET_ENV_PREFIX.length));
+}
+/** The call's arguments with every secret placeholder replaced by its value from this machine. */
+export function withSecrets(args, env) {
+    const swap = (value) => {
+        if ('string' === typeof value && value.startsWith(SECRET_PLACEHOLDER)) {
+            const field = value.slice(SECRET_PLACEHOLDER.length);
+            const name = field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase();
+            return env[`${SECRET_ENV_PREFIX}${name}`] ?? value;
+        }
+        if (Array.isArray(value))
+            return value.map(swap);
+        if ('object' === typeof value && null !== value)
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, swap(v)]));
+        return value;
+    };
+    return swap(args);
+}

package/dist/features/harness/platform-config.d.ts

@@ -40,6 +40,13 @@ export interface PlatformModelConfig {
      * not have its silence treated as a refusal.
      */
     providerReady: boolean;
+    /** Harness credits used and held this 30 days. Absent when the plan is unbounded or the API is older. */
+    credits?: {
+        used: number;
+        limit: number;
+    };
+    /** The platform that answered, no trailing slash: where the HUD's settings and plan links go. */
+    platformUrl?: string;
 }
 /** A GET, narrowed to what this file uses, so a test can answer it without a network. */
 export type ConfigFetch = (url: string, init: {

package/dist/features/harness/platform-config.js

@@ -48,11 +48,21 @@ function parse(body) {
         const ready = 'object' === typeof available && null !== available
             ? available[provider]
             : undefined;
+        const credits = record['credits'];
+        const used = 'object' === typeof credits && null !== credits
+            ? credits['used']
+            : undefined;
+        const limit = 'object' === typeof credits && null !== credits
+            ? credits['limit']
+            : undefined;
         return {
             provider,
             harnessEnabled: 'boolean' === typeof enabled ? enabled : true,
             harnessEntitled: 'boolean' === typeof entitled ? entitled : true,
             providerReady: 'boolean' === typeof ready ? ready : true,
+            ...('number' === typeof used && 'number' === typeof limit
+                ? { credits: { used, limit } }
+                : {}),
         };
     }
     catch {
@@ -78,14 +88,16 @@ export async function fetchPlatformConfig(env, doFetch = (url, init) => fetch(ur
         controller.abort();
     }, timeoutMs);
     try {
-        const res = await doFetch(`${host.replace(/\/+$/, '')}${CONFIG_PATH}`, {
+        const base = host.replace(/\/+$/, '');
+        const res = await doFetch(`${base}${CONFIG_PATH}`, {
             method: 'GET',
             headers: { authorization: `Bearer ${key}` },
             signal: controller.signal,
         });
         if (!res.ok)
             return undefined;
-        return parse(await res.text());
+        const config = parse(await res.text());
+        return config === undefined ? undefined : { ...config, platformUrl: base };
     }
     catch {
         return undefined;

package/dist/features/harness/script/app-controls.d.ts

@@ -0,0 +1,5 @@
+import type { ToolOutcome } from '../harness.js';
+/** Every named control a drive saw, by page, then what the crawl clicked. */
+export declare function appControlsOf(calls: readonly ToolOutcome[], crawled: ToolOutcome | undefined): {
+    appControls?: string[];
+};

package/dist/features/harness/script/app-controls.js

@@ -0,0 +1,40 @@
+/**
+ * The app map a drive leaves for the next plan: the controls on every page the drive looked at.
+ *
+ * The planner reads the start page live. The crawl's clicks alone spent their budget on a
+ * dashboard's navigation and never listed the Refund button on its Transactions page, so no journey
+ * went near the app's costliest defects. Every lane snapshots the pages it reaches, and those
+ * snapshots already hold the controls a plan needs.
+ */
+import { ReticleTool, asRecord, parseInteractive } from '@reticlehq/core';
+/** The most controls kept: a dashboard's navigation and its pages' main buttons, not its rows. */
+const MAX_APP_CONTROLS = 120;
+/** A snapshot line as a page's control: `button "Refund"`, with no ref, value or state. */
+const NAMED_CONTROL = /^-?\s*([a-z]+) "([^"]+)"/;
+/** The page part of an address: its path and hash, without the session query a lease adds. */
+function pageOf(route) {
+    return route.replace(/\?[^#]*/, '') || '/';
+}
+/** Every named control a drive saw, by page, then what the crawl clicked. */
+export function appControlsOf(calls, crawled) {
+    const seen = [];
+    for (const call of calls) {
+        if (ReticleTool.SNAPSHOT !== call.name || call.isError)
+            continue;
+        const result = asRecord(call.result);
+        const tree = result['tree'];
+        const route = asRecord(result['status'])['route'];
+        if ('string' !== typeof tree || 'string' !== typeof route)
+            continue;
+        for (const item of parseInteractive(tree)) {
+            const named = NAMED_CONTROL.exec(item.desc.trim());
+            if (named !== null)
+                seen.push(`${pageOf(route)}: ${String(named[1])} "${String(named[2])}"`);
+        }
+    }
+    const visited = asRecord(crawled?.result)['visited'];
+    if (Array.isArray(visited))
+        seen.push(...visited.filter((v) => 'string' === typeof v));
+    const names = [...new Set(seen)];
+    return 0 === names.length ? {} : { appControls: names.slice(0, MAX_APP_CONTROLS) };
+}

package/dist/features/harness/script/lane-ids.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The Harness id each lane of one drive runs under.
+ *
+ * Lanes in leased contexts used to share the drive's one id, so each lane's session, ending, synced
+ * a run under the same `harness-<id>` and the last lane to finish overwrote the others. A lane on
+ * its own session gets its own id; a drive that never leased keeps the one id it always had.
+ */
+export interface LaneIds {
+    /** The id for the lane on `sessionId`, minted once and reused. */
+    idFor(sessionId: string | undefined): string;
+    /** Every id this drive ran under, in the order the lanes started. */
+    all(): string[];
+}
+export declare function laneIds(harness: string, leasing: boolean): LaneIds;

package/dist/features/harness/script/lane-ids.js

@@ -0,0 +1,16 @@
+export function laneIds(harness, leasing) {
+    const bySession = new Map();
+    return {
+        idFor(sessionId) {
+            if (!leasing || sessionId === undefined)
+                return harness;
+            const known = bySession.get(sessionId);
+            if (known !== undefined)
+                return known;
+            const id = `${harness}-L${String(bySession.size + 1)}`;
+            bySession.set(sessionId, id);
+            return id;
+        },
+        all: () => (0 < bySession.size ? [...bySession.values()] : [harness]),
+    };
+}

package/dist/features/harness/script/script-run.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Run a drive script: lanes side by side, journeys in order, every step through Reticle's own tools.
+ *
+ * Replays, exact acts and asserts need no model and are judged by the tool's own verdict. Only an
+ * open goal reaches the model. The browser, the model and the clock of concurrency all arrive as
+ * ports, so the scheduling below is tested without either.
+ *
+ * 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 { type PlanView } from '@reticlehq/core';
+import { type DriveScript } from '@reticlehq/core/artifacts';
+import { type HarnessResult, type HarnessToolset, type ToolOutcome } from '../harness.js';
+export interface ScriptPorts {
+    /** A browser context for one lane. Without a pool this is the user's own tab, every time. */
+    lease(laneId: string): Promise<{
+        sessionId?: string;
+        release(): Promise<void>;
+    }>;
+    /** Reticle's tools on a lane's tab, as the journey's persona when it has one. */
+    toolset(sessionId: string | undefined, persona: string | undefined): HarnessToolset;
+    /** Hand an open goal to the model, on that toolset. */
+    drive(toolset: HarnessToolset, goal: string, maxSteps: number): Promise<HarnessResult>;
+    /** Lanes at once. 1 when there is no pool, so lanes take turns on the one tab. */
+    parallel: number;
+    /** A person switched autonomous driving off. */
+    stopped(): boolean;
+}
+export interface ScriptRun {
+    view: PlanView;
+    /** Every tool call the run made, in the order each lane made them. */
+    toolCalls: ToolOutcome[];
+    /** The model drives the open goals took. */
+    drives: HarnessResult[];
+    stopped: boolean;
+    /** One line per journey, for the drive's report. */
+    lines: string[];
+}
+export declare function runScript(script: DriveScript, ports: ScriptPorts, onChange?: (view: PlanView) => void): Promise<ScriptRun>;
+/** The HUD's picture of a script before anything ran. */
+export declare function planView(script: DriveScript, parallel: number): PlanView;

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

@@ -0,0 +1,299 @@
+/**
+ * Run a drive script: lanes side by side, journeys in order, every step through Reticle's own tools.
+ *
+ * Replays, exact acts and asserts need no model and are judged by the tool's own verdict. Only an
+ * open goal reaches the model. The browser, the model and the clock of concurrency all arrive as
+ * ports, so the scheduling below is tested without either.
+ *
+ * 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 { 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;
+export async function runScript(script, ports, onChange = () => undefined) {
+    const view = planView(script, Math.min(ports.parallel, script.maxParallel ?? ports.parallel));
+    const toolCalls = [];
+    const drives = [];
+    let stopped = false;
+    const tell = () => {
+        try {
+            onChange(structuredClone(view));
+        }
+        catch {
+            /* 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.
+    const outcome = new Map();
+    const firstLane = new Map();
+    for (const lane of script.lanes) {
+        for (const id of lane.journeys) {
+            if (firstLane.has(id))
+                continue;
+            firstLane.set(id, lane.id);
+            let settle = () => undefined;
+            const promise = new Promise((resolve) => (settle = resolve));
+            outcome.set(id, { promise, settle });
+        }
+    }
+    const journeyById = new Map(script.journeys.map((j) => [j.id, j]));
+    /** Journeys whose checks may have held but whose goal the drive did not reach. */
+    const goalMissed = new Set();
+    const broken = new Map();
+    tell();
+    const runLane = async (lane, laneIndex) => {
+        const cards = view.lanes[laneIndex]?.journeys ?? [];
+        const settleOwned = (id, ok) => {
+            if (firstLane.get(id) === lane.id)
+                outcome.get(id)?.settle(ok);
+        };
+        let lease;
+        let blocked = false;
+        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;
+                    card.status = ScriptStatus.BLOCKED;
+                    settleOwned(id, false);
+                    tell();
+                    continue;
+                }
+                lease ??= await ports.lease(lane.id);
+                const tools = recording(ports.toolset(lease.sessionId, journey.persona), toolCalls);
+                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, () => {
+                    stopped = true;
+                });
+                card.status = ok ? ScriptStatus.PASSED : ScriptStatus.FAILED;
+                drives.push(...own);
+                if (!ok && own.some((d) => false === d.goalMet))
+                    goalMissed.add(card);
+                blocked = !ok;
+                settleOwned(id, ok);
+                tell();
+            }
+        }
+        catch (error) {
+            // The lease or a tool broke the lane: everything it had not finished is blocked, and says why.
+            const message = error instanceof Error ? error.message : String(error);
+            broken.set(lane.id, message.split('\n')[0] ?? message);
+            for (const card of cards) {
+                if (ScriptStatus.PENDING === card.status || ScriptStatus.RUNNING === card.status) {
+                    card.status = ScriptStatus.BLOCKED;
+                }
+            }
+            for (const id of lane.journeys)
+                settleOwned(id, false);
+            tell();
+        }
+        finally {
+            await lease?.release().catch(() => undefined);
+        }
+    };
+    // Lanes start in order, `parallel` at a time: whatever a barrier waits on has already started.
+    let next = 0;
+    const worker = async () => {
+        for (let index = next++; index < script.lanes.length; index = next++) {
+            const lane = script.lanes[index];
+            if (lane !== undefined)
+                await runLane(lane, index);
+        }
+    };
+    await Promise.all(Array.from({ length: view.parallel }, worker));
+    const lines = view.lanes.flatMap((lane) => lane.journeys.map((card) => {
+        const why = ScriptStatus.BLOCKED === card.status
+            ? 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)})`}`;
+    }));
+    return { view, toolCalls, drives, stopped: stopped || ports.stopped(), lines };
+}
+async function runJourney(journey, cards, tools, ports, drives, tell, stop) {
+    const checkpoints = new Map();
+    for (const [index, step] of journey.steps.entries()) {
+        const card = cards[index];
+        if (card === undefined)
+            continue;
+        if (ports.stopped()) {
+            card.status = ScriptStatus.BLOCKED;
+            tell();
+            return 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);
+        }
+        else {
+            ok = await runLeaf(step, tools, ports, drives, stop);
+        }
+        card.status = ok ? ScriptStatus.PASSED : ScriptStatus.FAILED;
+        tell();
+        if (!ok) {
+            for (const rest of cards.slice(index + 1))
+                rest.status = ScriptStatus.BLOCKED;
+            tell();
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 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.
+ */
+async function runBranch(step, reenter, tools, ports, drives, stop) {
+    let all = true;
+    for (const [index, branchCase] of step.cases.entries()) {
+        if (ports.stopped())
+            return false;
+        if (0 < index) {
+            if (reenter === undefined)
+                return false;
+            const back = await replay(tools, { flowName: reenter.flow, to: reenter.to });
+            if (!back)
+                return false;
+        }
+        if (branchCase.when !== undefined && !(await holds(tools, branchCase.when)))
+            continue;
+        for (const leaf of branchCase.steps) {
+            if (!(await runLeaf(leaf, tools, ports, drives, stop))) {
+                all = false;
+                break;
+            }
+        }
+    }
+    return all;
+}
+async function runLeaf(step, tools, ports, drives, stop) {
+    switch (step.kind) {
+        case ScriptStepKind.REPLAY:
+            return replay(tools, {
+                flowName: step.flow,
+                ...(step.at === undefined ? {} : { at: step.at }),
+                ...(step.to === undefined ? {} : { to: step.to }),
+            });
+        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);
+                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;
+            }
+            const result = await call(tools, ReticleTool.ACT_AND_WAIT, {
+                ...(step.target === undefined ? {} : { target: step.target }),
+                action: step.action,
+                ...(step.args === undefined ? {} : { args: step.args }),
+                ...(step.until === undefined ? {} : { until: step.until }),
+            });
+            return Verified.YES === asRecord(result)['verified'];
+        }
+    }
+}
+async function replay(tools, args) {
+    return ReplayStatus.OK === asRecord(await call(tools, ReticleTool.FLOW_REPLAY, args))['status'];
+}
+async function holds(tools, predicate) {
+    return true === asRecord(await call(tools, ReticleTool.ASSERT, { predicate }))['pass'];
+}
+/** A tool that throws is a failed step, not a crashed run. */
+async function call(tools, name, args) {
+    try {
+        return await tools.invoke(name, args);
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** The toolset, with every call kept, so the run's report reads them like a model drive's. */
+function recording(tools, into) {
+    return {
+        tools: tools.tools,
+        async invoke(name, args) {
+            const id = `script-${String(into.length + 1)}`;
+            try {
+                const result = await tools.invoke(name, args);
+                into.push({ id, name, args, result, isError: false });
+                return result;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                into.push({ id, name, args, result: { error: message }, isError: true });
+                throw error;
+            }
+        },
+    };
+}
+/** The HUD's picture of a script before anything ran. */
+export function planView(script, parallel) {
+    const byId = new Map(script.journeys.map((j) => [j.id, j]));
+    return {
+        parallel: Math.max(1, Math.min(parallel, script.lanes.length)),
+        lanes: script.lanes.map((lane) => ({
+            id: lane.id,
+            journeys: lane.journeys.flatMap((id) => {
+                const journey = byId.get(id);
+                if (journey === undefined)
+                    return [];
+                return [
+                    {
+                        id,
+                        title: journey.title,
+                        ...(journey.persona === undefined ? {} : { persona: journey.persona }),
+                        waitsOn: barriersOf(script, lane.id, id),
+                        status: ScriptStatus.PENDING,
+                        steps: journey.steps.map((step) => ({
+                            label: stepLabel(step),
+                            status: ScriptStatus.PENDING,
+                        })),
+                    },
+                ];
+            }),
+        })),
+    };
+}
+function mark(status) {
+    if (ScriptStatus.PASSED === status)
+        return '✓';
+    if (ScriptStatus.FAILED === status)
+        return '✗';
+    return '○';
+}

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

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