@reticlehq/server 3.4.0 → 3.6.0

package/dist/features/harness/drivers.js

@@ -1,19 +1,15 @@
 /**
- * The names of the drivers the harness can be asked for.
+ * The Harness's driver names.
  *
- * A leaf module on purpose. These used to be re-exported from `harness-explore.ts`, which sits in
- * the tool surface and is reached, through the toolset and the tool table, from the very tool that
- * needs to declare them as an enum — a cycle that left the list `[undefined, undefined]` at the
- * moment zod read it, and failed inside a JSON-schema parser rather than anywhere near the cause.
- * Nothing here imports anything, so nothing can be half-initialised when it is read.
+ * A leaf module on purpose: the tool table reads these while the tool surface is still loading, and
+ * a module that imports nothing cannot be read half-initialised.
+ *
+ * There is one driver. Every Harness decision, its models and its planning run on the Reticle
+ * platform, on the workspace's monthly Harness credits; this machine executes what it is told.
  */
-/** Generates its tool calls as text, and names the journeys it records. The default. */
-export const ANTHROPIC_DRIVER_NAME = 'anthropic';
-/** Answers typed questions; picks from the elements on the page and cannot invent one. */
-export const JEV_DRIVER_NAME = 'jev';
-/** Generates its tool calls, over Chat Completions. Here so an A/B has a third arm. */
-export const OPENAI_DRIVER_NAME = 'openai';
-/** What a caller may name. Order is the order a reader sees them in the tool description. */
-export const DRIVER_NAMES = [ANTHROPIC_DRIVER_NAME, JEV_DRIVER_NAME, OPENAI_DRIVER_NAME];
+/** The platform's Harness: it decides on its side, this machine executes. See server-driver.ts. */
+export const SERVER_DRIVER = 'server';
 /** An injected driver: not selectable, because only a caller in-process can supply one. */
 export const CUSTOM_DRIVER_NAME = 'custom';
+/** What a drive needs, said once for every place that tells somebody. */
+export const EXPLORE_NEEDS = 'Runs on the Reticle platform: needs a linked project (`reticle connect`); Free has credits.';

package/dist/features/harness/fill-values.d.ts

@@ -1,73 +1,7 @@
 /**
- * What to type into a field, and the one place in a drive worth paying a generating model for.
+ * What to type into a text field, from its label alone.
  *
- * A System One model answers typed questions against a state; it cannot write a string. That is not
- * a shortcoming to route around everywhere — it is why the drive is two orders of magnitude cheaper,
- * and every decision it makes (which tool, which element, what should follow) is a decision, not a
- * composition. But a text field is a composition. "A card number", "a search term that returns
- * results", "a description a human would write" cannot be enumerated from the page, and a label-keyed
- * table of guesses is what stands in for them today.
- *
- * ## Why this is escalation rather than partnership
- *
- * Put a generating model in the per-turn loop and you pay its per-turn tax on every step, which is
- * the cost the cheap driver exists to avoid. Typing is a small minority of what a drive does —
- * clicks and navigations are the overwhelming majority — so the model is called for the few steps
- * that compose text, never for the many that select, and a drive with no text fields never calls it
- * at all.
- *
- * ## Why it is cached, and cached where it is
- *
- * A generated value is paid for ONCE and then belongs to the project: the same field on the same
- * app wants the same value tomorrow, and a replay must send exactly what the recording sent or it
- * is not a replay. Writing them to `.reticle` makes the second drive free, makes the values
- * reviewable by a human who can correct a bad one by hand, and keeps them out of the model's way
- * entirely. It is the same economics as the flows themselves: pay once, replay forever.
- *
- * ## What it must never do
- *
- * Fill a slot, never propose a call. The driver decides what to click and what to claim; this
- * answers one question — "what text goes in this box" — and a wrong answer costs one act, not a
- * wrong verdict. Nothing here touches what is judged.
- */
-import { type HarnessDriverOptions } from './driver.js';
-/** What the caller must be able to do for values to survive past this drive. */
-export interface FillCache {
-    get(label: string): string | undefined;
-    set(label: string, value: string): void;
-}
-/**
- * The fallback, and still the answer for most fields.
- *
- * An exploration drive needs PLAUSIBLE input, not creative input: the engine is judging what the app
- * did with the value, not the value. A field that rejects everything here is itself worth finding,
- * and shows up as an act that did not settle.
+ * Used by the crawl, which fills a field to see what the app does with it and never needs the value
+ * to be clever. The Harness fills fields on the platform, where its engine decides them.
  */
 export declare function heuristicFillValue(label: string): string;
-/**
- * Whether a label is worth spending a model call on.
- *
- * The heuristic is RIGHT about an email box and an amount box, and a generated "john@example.com"
- * is not an improvement on `harness@reticle.dev`. What it cannot do is a field whose label it does
- * not recognise at all, where it falls back to typing the words "reticle harness" into whatever the
- * app asked for. That fallback is the whole of what generation is for.
- */
-export declare function needsGeneration(label: string): boolean;
-/**
- * The seam the driver calls: a label in, a value out, always.
- *
- * Three layers, cheapest first, and the expensive one is skipped entirely unless the two above it
- * have nothing better than "type the words reticle harness into this box".
- */
-export declare function fillValues(deps: {
-    cache?: FillCache;
-    generator?: HarnessDriverOptions;
-    /** One line about where the drive is, so a value suits the page it is typed on. */
-    context?: () => string;
-    /**
-     * A value the user SUPPLIED for this field — the same `RETICLE_SECRET_<FIELD>` replay reads for
-     * a redacted one. Checked first so a drive gets past a login, and never cached: the cache is a
-     * file on disk.
-     */
-    secret?: (label: string) => string | undefined;
-}): (label: string) => Promise<string>;

package/dist/features/harness/fill-values.js

@@ -1,54 +1,8 @@
 /**
- * What to type into a field, and the one place in a drive worth paying a generating model for.
+ * What to type into a text field, from its label alone.
  *
- * A System One model answers typed questions against a state; it cannot write a string. That is not
- * a shortcoming to route around everywhere — it is why the drive is two orders of magnitude cheaper,
- * and every decision it makes (which tool, which element, what should follow) is a decision, not a
- * composition. But a text field is a composition. "A card number", "a search term that returns
- * results", "a description a human would write" cannot be enumerated from the page, and a label-keyed
- * table of guesses is what stands in for them today.
- *
- * ## Why this is escalation rather than partnership
- *
- * Put a generating model in the per-turn loop and you pay its per-turn tax on every step, which is
- * the cost the cheap driver exists to avoid. Typing is a small minority of what a drive does —
- * clicks and navigations are the overwhelming majority — so the model is called for the few steps
- * that compose text, never for the many that select, and a drive with no text fields never calls it
- * at all.
- *
- * ## Why it is cached, and cached where it is
- *
- * A generated value is paid for ONCE and then belongs to the project: the same field on the same
- * app wants the same value tomorrow, and a replay must send exactly what the recording sent or it
- * is not a replay. Writing them to `.reticle` makes the second drive free, makes the values
- * reviewable by a human who can correct a bad one by hand, and keeps them out of the model's way
- * entirely. It is the same economics as the flows themselves: pay once, replay forever.
- *
- * ## What it must never do
- *
- * Fill a slot, never propose a call. The driver decides what to click and what to claim; this
- * answers one question — "what text goes in this box" — and a wrong answer costs one act, not a
- * wrong verdict. Nothing here touches what is judged.
- */
-import { DEFAULT_HARNESS_BASE_URL, } from './driver.js';
-/** Deliberately small. A field value is a phrase; anything longer is the model misunderstanding. */
-const MAX_TOKENS = 64;
-const ANTHROPIC_VERSION = '2023-06-01';
-const MESSAGES_PATH = '/v1/messages';
-/**
- * How many values one drive will generate.
- *
- * The cache makes the steady state nearly free, but the FIRST drive on a form-heavy app is the one
- * that pays, and an uncapped loop on a page with forty inputs is a bill nobody agreed to. Past the
- * cap the heuristic answers, which is what every drive used before this existed.
- */
-const MAX_PER_DRIVE = 12;
-/**
- * The fallback, and still the answer for most fields.
- *
- * An exploration drive needs PLAUSIBLE input, not creative input: the engine is judging what the app
- * did with the value, not the value. A field that rejects everything here is itself worth finding,
- * and shows up as an act that did not settle.
+ * Used by the crawl, which fills a field to see what the app does with it and never needs the value
+ * to be clever. The Harness fills fields on the platform, where its engine decides them.
  */
 export function heuristicFillValue(label) {
     const l = label.toLowerCase();
@@ -70,87 +24,3 @@ export function heuristicFillValue(label) {
         return '42';
     return 'reticle harness';
 }
-/**
- * Whether a label is worth spending a model call on.
- *
- * The heuristic is RIGHT about an email box and an amount box, and a generated "john@example.com"
- * is not an improvement on `harness@reticle.dev`. What it cannot do is a field whose label it does
- * not recognise at all, where it falls back to typing the words "reticle harness" into whatever the
- * app asked for. That fallback is the whole of what generation is for.
- */
-export function needsGeneration(label) {
-    return heuristicFillValue(label) === heuristicFillValue('');
-}
-const PROMPT = (label, context) => `A test harness is filling in a form field on a web application so it can check what the app does with the input.\n\n` +
-    `The field is labelled: "${label}"\n` +
-    `${context}\n\n` +
-    `Reply with ONLY the value to type. No quotes, no explanation, no markdown. It must be something a ` +
-    `real user would plausibly enter, and short. If the field wants an identifier or a code, invent a ` +
-    `well-formed one.`;
-/** One string from a generating model, or nothing. Never throws: a drive must not fail over a field. */
-async function generateOne(options, label, context) {
-    const call = options.fetch ?? ((url, init) => fetch(url, init));
-    const baseUrl = options.baseUrl ?? DEFAULT_HARNESS_BASE_URL;
-    try {
-        const res = await call(`${baseUrl}${MESSAGES_PATH}`, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                'x-api-key': options.apiKey,
-                'anthropic-version': ANTHROPIC_VERSION,
-            },
-            body: JSON.stringify({
-                model: options.model ?? 'claude-sonnet-5',
-                max_tokens: MAX_TOKENS,
-                messages: [{ role: 'user', content: PROMPT(label, context) }],
-            }),
-        });
-        if (!res.ok)
-            return undefined;
-        const parsed = JSON.parse(await res.text());
-        const content = parsed.content ?? [];
-        const text = content
-            .filter((block) => 'text' === block.type)
-            .map((block) => block.text ?? '')
-            .join('')
-            .trim()
-            .split('\n')[0];
-        if (text === undefined || 0 === text.length)
-            return undefined;
-        // A model asked for one value occasionally answers with a sentence about the value. Anything
-        // long enough to be prose is not a field value, and typing prose proves nothing about the app.
-        return 80 < text.length ? undefined : text.replace(/^["']|["']$/g, '');
-    }
-    catch {
-        // Offline, refused, rate-limited, malformed. All the same answer: use the heuristic.
-        return undefined;
-    }
-}
-/**
- * The seam the driver calls: a label in, a value out, always.
- *
- * Three layers, cheapest first, and the expensive one is skipped entirely unless the two above it
- * have nothing better than "type the words reticle harness into this box".
- */
-export function fillValues(deps) {
-    let spent = 0;
-    return async (label) => {
-        const supplied = deps.secret?.(label);
-        if (supplied !== undefined && supplied.length > 0)
-            return supplied;
-        const cached = deps.cache?.get(label);
-        if (cached !== undefined)
-            return cached;
-        const fallback = heuristicFillValue(label);
-        if (deps.generator === undefined || !needsGeneration(label) || MAX_PER_DRIVE <= spent)
-            return fallback;
-        spent += 1;
-        const generated = await generateOne(deps.generator, label, deps.context?.() ?? '');
-        if (generated === undefined)
-            return fallback;
-        // Cached under the LABEL, not the ref: refs expire with the page, labels are what the next drive
-        // and every replay will meet again.
-        deps.cache?.set(label, generated);
-        return generated;
-    };
-}

package/dist/features/harness/goals.d.ts

@@ -0,0 +1,21 @@
+export interface GoalCheck {
+    /** The text that had to be on the page. */
+    text: string;
+    /** The engine's verdict on it: only `yes` is proved. */
+    verified: string;
+}
+/** The observable goals in a persona: whatever it quoted. */
+export declare function goalsIn(persona: string | undefined): string[];
+/**
+ * Check each goal on the page the drive ended on, recording ONE assert for the drive.
+ *
+ * Each quote used to be its own assert, and every assert is a check in the drive's run, so a goal
+ * that quotes where it starts ("from "Count is 0" to "Count is 1"") recorded a "no" for the start
+ * text a working app had rightly replaced, and the run synced as a failing flow. The page is read
+ * once to answer each quote; the one recorded assert covers the quotes shown, or all of them when
+ * none is, so a goal the page never reached still leaves a failed check behind. A check that cannot
+ * run is `unknown`, never skipped.
+ */
+export declare function checkGoals(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>, goals: readonly string[]): Promise<GoalCheck[]>;
+/** One line naming the goals the drive did not prove, or undefined when it proved them all. */
+export declare function unprovedGoals(checks: readonly GoalCheck[]): string | undefined;

package/dist/features/harness/goals.js

@@ -0,0 +1,77 @@
+/**
+ * The goals a drive was asked to prove, and whether it did.
+ *
+ * A drive asked to "check that "Ada Lovelace" and "Grace Hopper" are listed" replayed old journeys,
+ * dismissed a reminder and reported `finished` without looking for either name (#1316). The driver's
+ * word for it is not evidence, so after every drive the harness checks each goal itself, with the
+ * same assert any agent would make, and reports one verdict per goal.
+ */
+import { PredicateKind, ReticleTool, Verified, asRecord } from '@reticlehq/core';
+/** More than this and the persona is a document, not a set of goals. */
+const MAX_GOALS = 10;
+const MAX_GOAL_LENGTH = 200;
+/** A string the persona quoted: "straight" or “curly”. Single quotes are apostrophes too often. */
+const QUOTED = /"([^"\n]{1,200})"|“([^”\n]{1,200})”/g;
+/** The observable goals in a persona: whatever it quoted. */
+export function goalsIn(persona) {
+    if (persona === undefined)
+        return [];
+    const found = [...persona.matchAll(QUOTED)].map((m) => (m[1] ?? m[2] ?? '').trim());
+    return [...new Set(found.filter((g) => 0 < g.length))].slice(0, MAX_GOALS);
+}
+/**
+ * Check each goal on the page the drive ended on, recording ONE assert for the drive.
+ *
+ * Each quote used to be its own assert, and every assert is a check in the drive's run, so a goal
+ * that quotes where it starts ("from "Count is 0" to "Count is 1"") recorded a "no" for the start
+ * text a working app had rightly replaced, and the run synced as a failing flow. The page is read
+ * once to answer each quote; the one recorded assert covers the quotes shown, or all of them when
+ * none is, so a goal the page never reached still leaves a failed check behind. A check that cannot
+ * run is `unknown`, never skipped.
+ */
+export async function checkGoals(invoke, goals) {
+    const texts = [
+        ...new Set(goals.slice(0, MAX_GOALS).map((g) => g.trim().slice(0, MAX_GOAL_LENGTH))),
+    ].filter((t) => 0 < t.length);
+    if (0 === texts.length)
+        return [];
+    let page;
+    try {
+        const tree = asRecord(await invoke(ReticleTool.SNAPSHOT, { mode: SNAPSHOT_FULL }))['tree'];
+        if ('string' === typeof tree)
+            page = tree;
+    }
+    catch {
+        /* unread: every quote rests on the assert below */
+    }
+    const shown = texts.filter((t) => true === page?.includes(t));
+    const recorded = 0 < shown.length ? shown : texts;
+    let verified = Verified.UNKNOWN;
+    try {
+        const result = asRecord(await invoke(ReticleTool.ASSERT, { predicate: allOf(recorded) }));
+        if ('string' === typeof result['verified'])
+            verified = result['verified'];
+    }
+    catch {
+        /* stays unknown: the goal was not proved */
+    }
+    // A quote the page read did not show is a "no" only beside one it did: with none shown, every
+    // quote rests on the recorded assert.
+    return texts.map((text) => ({
+        text,
+        verified: 0 === shown.length || shown.includes(text) ? verified : Verified.NO,
+    }));
+}
+const SNAPSHOT_FULL = 'full';
+function allOf(texts) {
+    const each = texts.map((contains) => ({ kind: PredicateKind.TEXT, contains }));
+    return 1 === each.length ? (each[0] ?? {}) : { kind: PredicateKind.ALL_OF, predicates: each };
+}
+/** One line naming the goals the drive did not prove, or undefined when it proved them all. */
+export function unprovedGoals(checks) {
+    const missed = checks.filter((c) => Verified.YES !== c.verified);
+    if (0 === missed.length)
+        return undefined;
+    return (`Not proved: ${missed.map((c) => `"${c.text}" (${c.verified})`).join(', ')}. ` +
+        'The drive did not finish the job it was given, whatever its own account says.');
+}

package/dist/features/harness/harness.d.ts

@@ -107,7 +107,12 @@ export declare const StopReason: {
     readonly STALLED: "stalled";
     /** The toolset or the model itself failed in a way the loop cannot continue through. */
     readonly BROKEN: "broken";
+    /** A person switched autonomous driving off while it was driving. Not a failure. */
+    readonly STOPPED: "stopped";
 };
+/** Thrown by a driver when a person, not a fault, ended the drive. */
+export declare class DriveStoppedError extends Error {
+}
 export type StopReason = (typeof StopReason)[keyof typeof StopReason];
 export interface HarnessResult {
     stopReason: StopReason;
@@ -118,7 +123,23 @@ export interface HarnessResult {
     usage: TokenUsage;
     /** Set when `stopReason` is BROKEN. */
     error?: string;
+    /**
+     * Whether the drive ran at least one check: an `act_and_wait` with an `until`, or an `assert`,
+     * that did not error. A drive without one clicked things and proved nothing.
+     */
+    proved: boolean;
+    /**
+     * Whether the drive reached its whole goal, as the platform judged when it finished. Checks that
+     * held are not the goal reached: "open each section" passed on two presses of Sign in.
+     */
+    goalMet?: boolean;
 }
+/**
+ * The answer to a `finish` that came before anything was proved. Sent once per drive: a real drive
+ * asked to "click twice and check it reads 2" clicked once, finished, and saved a flow whose replay
+ * verifies nothing, which is the paid feature producing an empty pass.
+ */
+export declare const MSG_FINISH_UNPROVED: string;
 /**
  * The one tool the harness adds to Reticle's surface.
  *

package/dist/features/harness/harness.js

@@ -17,6 +17,7 @@
  * 3. **Everything is injected** — the model, the tools, the clock. The loop below has no network in
  *    it, which is what lets the whole thing be tested against a scripted model with no API key.
  */
+import { ReticleTool, asRecord } from '@reticlehq/core';
 import { withTimeout } from './with-timeout.js';
 /** Why a run stopped. Every one of these is a real outcome; none of them is an error. */
 export const StopReason = {
@@ -28,7 +29,33 @@ export const StopReason = {
     STALLED: 'stalled',
     /** The toolset or the model itself failed in a way the loop cannot continue through. */
     BROKEN: 'broken',
+    /** A person switched autonomous driving off while it was driving. Not a failure. */
+    STOPPED: 'stopped',
 };
+/** Thrown by a driver when a person, not a fault, ended the drive. */
+export class DriveStoppedError extends Error {
+}
+/** The finish's judgement of the goal, when it carried one. */
+function goalMetOf(args) {
+    const met = args['goalMet'];
+    return 'boolean' === typeof met ? { goalMet: met } : {};
+}
+/**
+ * The answer to a `finish` that came before anything was proved. Sent once per drive: a real drive
+ * asked to "click twice and check it reads 2" clicked once, finished, and saved a flow whose replay
+ * verifies nothing, which is the paid feature producing an empty pass.
+ */
+export const MSG_FINISH_UNPROVED = `Not finished: nothing has been proved yet. Before finishing, end the journey with ` +
+    `${ReticleTool.ACT_AND_WAIT} and an \`until\` naming the end state it must reach, or ` +
+    `${ReticleTool.ASSERT} on it. A drive that proves nothing replays as "verified nothing".`;
+/** A check that ran: the only thing that turns a drive into evidence. */
+function isProof(outcome) {
+    if (outcome.isError)
+        return false;
+    if (ReticleTool.ASSERT === outcome.name)
+        return true;
+    return ReticleTool.ACT_AND_WAIT === outcome.name && asRecord(outcome.args)['until'] !== undefined;
+}
 /**
  * The one tool the harness adds to Reticle's surface.
  *
@@ -126,6 +153,8 @@ export async function runHarness(driver, toolset, options = {}) {
     const history = [{ role: 'user', text: OPENING }];
     const toolCalls = [];
     const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    const proved = () => toolCalls.some(isProof);
+    let askedToProve = false;
     for (let step = 0; step < maxSteps; step += 1) {
         let turn;
         try {
@@ -133,11 +162,12 @@ export async function runHarness(driver, toolset, options = {}) {
         }
         catch (error) {
             return {
-                stopReason: StopReason.BROKEN,
+                stopReason: error instanceof DriveStoppedError ? StopReason.STOPPED : StopReason.BROKEN,
                 summary: '',
                 steps: step,
                 toolCalls,
                 usage,
+                proved: proved(),
                 error: error instanceof Error ? error.message : String(error),
             };
         }
@@ -156,10 +186,38 @@ export async function runHarness(driver, toolset, options = {}) {
                 steps: step + 1,
                 toolCalls,
                 usage,
+                proved: proved(),
             };
         }
         history.push({ role: 'assistant', text: turn.text, calls: turn.calls });
         const finish = turn.calls.find((call) => FINISH_TOOL.name === call.name);
+        if (finish !== undefined && !proved() && !askedToProve) {
+            // Whatever else the turn asked for runs first: a check sent alongside `finish` is proof.
+            const others = await Promise.all(turn.calls.filter((c) => c !== finish).map((c) => invokeOne(toolset, c)));
+            toolCalls.push(...others);
+            if (proved()) {
+                const summary = finish.args['summary'];
+                return {
+                    stopReason: StopReason.FINISHED,
+                    summary: 'string' === typeof summary ? summary : turn.text,
+                    steps: step + 1,
+                    toolCalls,
+                    usage,
+                    proved: true,
+                    ...goalMetOf(finish.args),
+                };
+            }
+            askedToProve = true;
+            const refused = {
+                id: finish.id,
+                name: finish.name,
+                args: finish.args,
+                result: { error: MSG_FINISH_UNPROVED },
+                isError: true,
+            };
+            history.push({ role: 'tool', outcomes: [...others, refused] });
+            continue;
+        }
         if (finish !== undefined) {
             const summary = finish.args['summary'];
             return {
@@ -168,6 +226,8 @@ export async function runHarness(driver, toolset, options = {}) {
                 steps: step + 1,
                 toolCalls,
                 usage,
+                proved: proved(),
+                ...goalMetOf(finish.args),
             };
         }
         // Every call the model asked for is answered, including ones that fail. A dropped result leaves
@@ -177,7 +237,14 @@ export async function runHarness(driver, toolset, options = {}) {
         toolCalls.push(...outcomes);
         history.push({ role: 'tool', outcomes });
     }
-    return { stopReason: StopReason.BUDGET, summary: '', steps: maxSteps, toolCalls, usage };
+    return {
+        stopReason: StopReason.BUDGET,
+        summary: '',
+        steps: maxSteps,
+        toolCalls,
+        usage,
+        proved: proved(),
+    };
 }
 /**
  * One tool call, with its failure captured rather than thrown.

package/dist/features/harness/platform/drive-target.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Make ready the tab a platform drive runs in, as its spec asks, and say what was and was not done.
+ *
+ * The person's own tab, or one opened for the drive: headless, or in a window they can watch. Then
+ * the HUD as asked. Every step that cannot be done is reported, never thrown: a drive asked for a
+ * window on a machine with no display still runs headless if that is all there is, and says so.
+ */
+import { HudVisibility, type DriveApplied, type DriveSpec, type SpecIgnored } from '@reticlehq/core';
+/** How many times the HUD is asked for before giving up: a page's HUD mounts after it connects. */
+export declare const HUD_ATTEMPTS = 4;
+export declare const HUD_RETRY_MS = 500;
+/** What a refused drive is told when no address was given to open. */
+export declare const NO_ADDRESS_TO_OPEN = "Nothing says where this app runs, so no browser could be opened for it. Open the app once with Reticle running, or give the drive an address.";
+export interface DriveTargetPorts {
+    /** The person's own tab for the drive, as the chat already picks it. Null: none may be driven. */
+    pickTab: () => Promise<string | null | undefined>;
+    /** Open `url` in a browser of the daemon's own; answers the tab's session id. Throws why not. */
+    open: (url: string, headed: boolean, hud: HudVisibility | undefined) => Promise<string>;
+    /** Ask the page for this HUD; throws when the page did not take it (no HUD yet, an older SDK). */
+    tuneHud: (sessionId: string, hud: HudVisibility) => Promise<void>;
+    sleep: (ms: number) => Promise<void>;
+}
+export interface PreparedDrive {
+    sessionId: string | null | undefined;
+    applied: DriveApplied;
+    ignored: SpecIgnored[];
+    /** Why the drive cannot run, in a person's words, when it cannot. */
+    refusal?: string;
+}
+export declare function prepareDrive(spec: DriveSpec, fallbackUrl: string | undefined, ports: DriveTargetPorts): Promise<PreparedDrive>;

package/dist/features/harness/platform/drive-target.js

@@ -0,0 +1,81 @@
+/**
+ * Make ready the tab a platform drive runs in, as its spec asks, and say what was and was not done.
+ *
+ * The person's own tab, or one opened for the drive: headless, or in a window they can watch. Then
+ * the HUD as asked. Every step that cannot be done is reported, never thrown: a drive asked for a
+ * window on a machine with no display still runs headless if that is all there is, and says so.
+ */
+import { DriveMode, DriveTarget, HudVisibility, SpecIgnoredReason, } from '@reticlehq/core';
+/** How many times the HUD is asked for before giving up: a page's HUD mounts after it connects. */
+export const HUD_ATTEMPTS = 4;
+export const HUD_RETRY_MS = 500;
+/** What a refused drive is told when no address was given to open. */
+export const NO_ADDRESS_TO_OPEN = 'Nothing says where this app runs, so no browser could be opened for it. Open the app once with Reticle running, or give the drive an address.';
+export async function prepareDrive(spec, fallbackUrl, ports) {
+    const mode = spec.mode ?? DriveMode.LOCAL;
+    const ignored = [];
+    let target = spec.target ?? DriveTarget.TAB;
+    let sessionId;
+    let url;
+    if (DriveTarget.TAB !== target) {
+        url = spec.url ?? fallbackUrl;
+        if (url === undefined)
+            return {
+                sessionId: null,
+                applied: { target, mode },
+                ignored,
+                refusal: NO_ADDRESS_TO_OPEN,
+            };
+        try {
+            sessionId = await ports.open(url, DriveTarget.HEADED === target, spec.hud);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            // A window that cannot open falls back to a browser with none: the drive still runs.
+            if (DriveTarget.HEADED !== target)
+                return { sessionId: null, applied: { target, mode, url }, ignored, refusal: detail };
+            ignored.push({ field: 'target', reason: SpecIgnoredReason.UNAVAILABLE, detail });
+            target = DriveTarget.HEADLESS;
+            try {
+                sessionId = await ports.open(url, false, spec.hud);
+            }
+            catch (again) {
+                const why = again instanceof Error ? again.message : String(again);
+                return { sessionId: null, applied: { target, mode, url }, ignored, refusal: why };
+            }
+        }
+    }
+    else {
+        sessionId = await ports.pickTab();
+    }
+    const applied = {
+        target,
+        mode,
+        ...(url === undefined ? {} : { url }),
+        ...('string' === typeof sessionId ? { sessionId } : {}),
+    };
+    if (spec.hud !== undefined && 'string' === typeof sessionId) {
+        const taken = await tune(ports, sessionId, spec.hud);
+        if (taken === undefined)
+            applied.hud = spec.hud;
+        else
+            ignored.push({ field: 'hud', reason: SpecIgnoredReason.UNAVAILABLE, detail: taken });
+    }
+    return { sessionId, applied, ignored };
+}
+/** Ask for the HUD until the page takes it; answers why not when it never does. */
+async function tune(ports, sessionId, hud) {
+    let why = 'the page did not take it';
+    for (let attempt = 1; attempt <= HUD_ATTEMPTS; attempt += 1) {
+        try {
+            await ports.tuneHud(sessionId, hud);
+            return undefined;
+        }
+        catch (error) {
+            why = error instanceof Error ? error.message : String(error);
+            if (attempt < HUD_ATTEMPTS)
+                await ports.sleep(HUD_RETRY_MS);
+        }
+    }
+    return why;
+}