@reticlehq/server 2.14.0 → 3.2.0

package/dist/features/harness/drive-report.js

@@ -0,0 +1,196 @@
+/**
+ * What a drive did, written from the evidence rather than narrated by the model that drove.
+ *
+ * `HarnessResult.summary` is the driver's own account, and it has always carried a warning that
+ * nothing downstream grades it. That was a caveat when the driver was a language model. It became a
+ * hole the moment a System One model could drive: Jev answers typed questions and cannot produce a
+ * sentence, so `summary` came back EMPTY, and an agent calling `explore` got a result with no
+ * account of what had happened in it at all.
+ *
+ * Restoring prose would have been the obvious fix and the wrong one. The drive already records
+ * every call it made, with the arguments it used and the verdict the engine returned — so the
+ * account can be DERIVED. That is strictly better than a narration: a model summarising its own
+ * drive is the one witness with a reason to round "unknown" up to "worked", and this cannot, because
+ * it is not writing about the drive, it is reading it.
+ *
+ * Written for the agent on the other end of the MCP call. It leads with what was proved, because
+ * that is what a coding agent has to gate on, and it says "not proved" in those words rather than
+ * leaving a verdict of `unknown` to be read as a pass.
+ */
+import { asRecord, asString, ReticleTool, Verified } from '@reticlehq/core';
+/** How many steps are listed before the account starts counting instead of naming. */
+const MAX_LISTED = 12;
+/** Actions that change the app. Reads are not part of the story of what was driven. */
+const DRIVING_TOOLS = new Set([
+    ReticleTool.ACT,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.NAVIGATE,
+]);
+/**
+ * The human-readable name of what was acted on.
+ *
+ * The ref (`e42`) is meaningless to the agent reading this — it is a handle that expired when the
+ * page changed. A description that says `button "Create"` survives being read tomorrow, so the ref
+ * is only the fallback.
+ */
+function targetOf(args, result) {
+    const described = asString(result['element']) ?? asString(result['name']);
+    if (described !== undefined && 0 < described.length)
+        return described;
+    const target = asRecord(args['target']);
+    for (const key of ['testid', 'text', 'label', 'name']) {
+        const value = asString(target[key]);
+        if (value !== undefined && 0 < value.length)
+            return `${key}=${value}`;
+    }
+    const url = asString(args['url']);
+    if (url !== undefined && 0 < url.length)
+        return url;
+    return asString(args['ref']) ?? 'the page';
+}
+/**
+ * Replays this drive ran, and what each came back with.
+ *
+ * The verdict is `status`, not `passed`. Reading the wrong key reported ten replays as "undecided"
+ * on a run where every one of them had answered — which is the same false-nothing this report was
+ * written to stop, made by the report itself.
+ *
+ * Three outcomes, kept apart because they mean different things to whoever reads this. `ok` is the
+ * journey still holding. `error` is it failing. `drift` is the flow's own anchors no longer
+ * resolving — the app moved under a recording, which is a finding about the RECORDING rather than
+ * proof the feature broke, and collapsing it into "failed" would send somebody to fix working code.
+ */
+export const ReplayOutcome = { OK: 'ok', DRIFT: 'drift', ERROR: 'error' };
+export function replayedFlows(toolCalls) {
+    const out = [];
+    for (const call of toolCalls) {
+        if (ReticleTool.FLOW_REPLAY !== call.name)
+            continue;
+        const name = asString(asRecord(call.args)['flowName']) ?? 'a flow';
+        out.push({
+            name,
+            status: call.isError ? ReplayOutcome.ERROR : asString(asRecord(call.result)['status']),
+        });
+    }
+    return out;
+}
+/**
+ * The declared consequence, as a short phrase rather than a JSON dump.
+ *
+ * One line per kind, because a reader triaging a red needs "it claimed a POST" and not the
+ * predicate's wire shape. Unknown kinds fall back to the kind name, which is still more than the
+ * nothing this used to say.
+ */
+function describeClaim(until) {
+    const p = asRecord(until);
+    const kind = asString(p['kind']);
+    if (kind === undefined)
+        return undefined;
+    if ('signal' === kind) {
+        const name = asString(p['name']);
+        return name === undefined ? 'a signal' : `signal ${name}`;
+    }
+    if ('net' === kind) {
+        const method = asString(p['method']);
+        const url = asString(p['urlContains']);
+        return `a ${method ?? ''} request${url === undefined ? '' : ` to ${url}`}`.replace('  ', ' ');
+    }
+    if ('route' === kind)
+        return `a route containing ${asString(p['contains']) ?? '?'}`;
+    if ('not' === kind) {
+        const inner = describeClaim(p['predicate']);
+        return inner === undefined ? 'not something' : `to leave ${inner}`;
+    }
+    if ('anyOf' === kind)
+        return 'a request or a signal';
+    return kind;
+}
+/** Reduce the raw call log to the actions that actually drove the app. */
+export function drivenSteps(toolCalls) {
+    const steps = [];
+    for (const call of toolCalls) {
+        if (!DRIVING_TOOLS.has(call.name))
+            continue;
+        const args = asRecord(call.args);
+        const result = asRecord(call.result);
+        const action = ReticleTool.NAVIGATE === call.name ? 'navigate' : (asString(args['action']) ?? 'act');
+        steps.push({
+            action,
+            target: targetOf(args, result),
+            verified: call.isError ? 'error' : asString(result['verified']),
+            because: call.isError ? asString(result['error']) : asString(result['because']),
+            claimed: describeClaim(args['until']),
+        });
+    }
+    return steps;
+}
+/**
+ * The account, as lines.
+ *
+ * Proved and not-proved are counted separately and both are stated, because the failure mode this
+ * whole product exists to prevent is a reader taking "we did twelve things" for "twelve things
+ * work". `unknown` is deliberately grouped under NOT proved and labelled as undecided evidence
+ * rather than as a failure — it calls for a better check, not a code change, and collapsing the two
+ * would send an agent to rewrite working code.
+ */
+export function describeDrive(toolCalls, savedFlows) {
+    const steps = drivenSteps(toolCalls);
+    const replays = replayedFlows(toolCalls);
+    /*
+     * A run that only REPLAYED is not a run that did nothing.
+     *
+     * "Nothing was driven" was true of the actions and wrong about the run: sixteen recorded journeys
+     * replayed deterministically, for zero model tokens, and the report called it empty. That is the
+     * cheap half of the plan working exactly as intended, and it has to read as a result.
+     */
+    const replayLine = 0 === replays.length
+        ? undefined
+        : (() => {
+            const held = replays.filter((r) => ReplayOutcome.OK === r.status);
+            const failed = replays.filter((r) => ReplayOutcome.ERROR === r.status);
+            const drifted = replays.filter((r) => ReplayOutcome.DRIFT === r.status);
+            const lines = [
+                `Replayed ${String(replays.length)} recorded journey(s) with NO model in the loop: ` +
+                    `${String(held.length)} still hold, ${String(failed.length)} failed, ${String(drifted.length)} drifted.`,
+            ];
+            if (0 < failed.length)
+                lines.push(`  FAILED: ${failed.map((r) => r.name).join(', ')} — regressions in journeys that used to pass.`);
+            if (0 < drifted.length)
+                lines.push(`  DRIFTED: ${drifted.map((r) => r.name).join(', ')} — the app moved under these recordings; the flow needs re-anchoring, not the app fixing.`);
+            return lines.join('\n');
+        })();
+    if (0 === steps.length)
+        return (replayLine ??
+            'Nothing was driven and nothing was replayed: the run made no action against the app.');
+    const proved = steps.filter((step) => Verified.YES === step.verified);
+    const failed = steps.filter((step) => Verified.NO === step.verified);
+    const undecided = steps.filter((step) => Verified.YES !== step.verified && Verified.NO !== step.verified);
+    const lines = [
+        ...(replayLine === undefined ? [] : [replayLine]),
+        `Drove ${String(steps.length)} action(s): ${String(proved.length)} proved, ` +
+            `${String(failed.length)} failed, ${String(undecided.length)} not decided.`,
+    ];
+    for (const step of steps.slice(0, MAX_LISTED)) {
+        const verdict = step.verified ?? 'nothing declared';
+        const because = step.because === undefined ? '' : ` — ${step.because}`;
+        // The claim, on failures only: it is what separates "the app is broken" from "the drive guessed
+        // wrong", and those two readings need opposite responses from whoever reads this.
+        // Shown on anything that did not pass, not just on a red. `no-fault` means "the consequence was
+        // already true, so this proved nothing" -- which is unreadable without knowing WHAT was claimed,
+        // and is the line that exposed a GET offer being satisfied by a dashboard's own polling.
+        const claimed = Verified.YES !== step.verified && step.claimed !== undefined
+            ? ` (claimed ${step.claimed})`
+            : '';
+        lines.push(`  ${step.action} ${step.target}: ${verdict}${claimed}${because}`);
+    }
+    if (MAX_LISTED < steps.length)
+        lines.push(`  … and ${String(steps.length - MAX_LISTED)} more.`);
+    if (0 < failed.length)
+        lines.push(`${String(failed.length)} action(s) FAILED — the app did not do what the drive declared it would. These are findings.`);
+    if (0 < undecided.length)
+        lines.push(`${String(undecided.length)} action(s) were NOT PROVED. That is undecided evidence, not a failure: it calls for a better check, not a code change.`);
+    if (0 < savedFlows.length)
+        lines.push(`Replay any of this without a model: reticle_verify { action: "flows" } — saved ${savedFlows.join(', ')}.`);
+    return lines.join('\n');
+}

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

@@ -0,0 +1,50 @@
+/**
+ * The model binding: the one file in the harness that knows there is a network.
+ *
+ * Everything about the loop lives in harness.ts against the `ModelDriver` interface, so this file is
+ * a translation layer and nothing else. That split is not tidiness — it is what lets the loop be
+ * tested against a scripted model with no API key, on every run of the unit gate.
+ *
+ * It speaks the Messages API over `fetch` rather than through a vendor SDK. The loop is ours (the
+ * harness owns the step budget and has to record every call even when a run is cut short), so an SDK
+ * would contribute one HTTP POST and a dependency — and this package's dependency list is short on
+ * purpose.
+ */
+import type { ModelDriver } from './harness.js';
+/**
+ * The default driver model.
+ *
+ * Deliberately not the largest model available. The harness is not reasoning about business logic; it
+ * is exploring an interface and stating consequences, and the verdict is produced by the engine
+ * reading what it drove. If finding defects required a frontier model HERE, the engine would not be
+ * doing its job — so the model tier is also a standing test of the design.
+ */
+export declare const DEFAULT_HARNESS_MODEL = "claude-sonnet-5";
+export declare const DEFAULT_HARNESS_BASE_URL = "https://api.anthropic.com";
+/** The one call this file makes. Injected so a test can drive the translation with no network. */
+export type HarnessFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+export interface HarnessDriverOptions {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    /** Injected for tests. Defaults to the platform `fetch`. */
+    fetch?: HarnessFetch;
+}
+/**
+ * Read the harness's configuration out of the environment.
+ *
+ * Returns `undefined` when there is no key, which is the ONLY thing that decides whether the harness
+ * is available. Stated as a read rather than a throw because "you have not configured this" is a
+ * routine answer a caller offers a way out of, not a failure.
+ */
+export declare function harnessOptionsFromEnv(env: Record<string, string | undefined>): HarnessDriverOptions | undefined;
+/** Build a driver backed by the Messages API. */
+export declare function harnessDriver(options: HarnessDriverOptions): ModelDriver;

package/dist/features/harness/driver.js

@@ -0,0 +1,239 @@
+/**
+ * The model binding: the one file in the harness that knows there is a network.
+ *
+ * Everything about the loop lives in harness.ts against the `ModelDriver` interface, so this file is
+ * a translation layer and nothing else. That split is not tidiness — it is what lets the loop be
+ * tested against a scripted model with no API key, on every run of the unit gate.
+ *
+ * It speaks the Messages API over `fetch` rather than through a vendor SDK. The loop is ours (the
+ * harness owns the step budget and has to record every call even when a run is cut short), so an SDK
+ * would contribute one HTTP POST and a dependency — and this package's dependency list is short on
+ * purpose.
+ */
+import { z } from 'zod';
+import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+/**
+ * The default driver model.
+ *
+ * Deliberately not the largest model available. The harness is not reasoning about business logic; it
+ * is exploring an interface and stating consequences, and the verdict is produced by the engine
+ * reading what it drove. If finding defects required a frontier model HERE, the engine would not be
+ * doing its job — so the model tier is also a standing test of the design.
+ */
+export const DEFAULT_HARNESS_MODEL = 'claude-sonnet-5';
+export const DEFAULT_HARNESS_BASE_URL = 'https://api.anthropic.com';
+/** Output cap per turn. A driving turn is a sentence and a tool call, never an essay. */
+const MAX_TOKENS = 4096;
+const ANTHROPIC_VERSION = '2023-06-01';
+const MESSAGES_PATH = '/v1/messages';
+/**
+ * How much of one tool result the model is allowed to see.
+ *
+ * A snapshot of a dense page or a network window on a busy app is far larger than anything the model
+ * needs to choose its next click, and a handful of them will fill a context window that then has to
+ * be paid for on every subsequent turn. Truncation is announced in the payload rather than silent,
+ * because a model that cannot tell it was given a partial reading will reason about it as a complete
+ * one — and the tools already have cheaper lenses (`count_only`, `interactive`, `diff`) for exactly
+ * this. The full result is in the journal either way; nothing is lost from the record.
+ */
+const MAX_RESULT_CHARS = 8000;
+/** The cache breakpoint marker. One object, because it is the same fact in three places. */
+const CACHE_BREAKPOINT = { type: 'ephemeral' };
+/** What one turn of the wire looks like, narrowed at the boundary rather than trusted. */
+const TextBlock = z.object({ type: z.literal('text'), text: z.string() });
+const ToolUseBlock = z.object({
+    type: z.literal('tool_use'),
+    id: z.string(),
+    name: z.string(),
+    input: z.unknown(),
+});
+const OtherBlock = z.object({ type: z.string() }).passthrough();
+const MessageResponse = z.object({
+    content: z.array(z.union([TextBlock, ToolUseBlock, OtherBlock])).default([]),
+    usage: z
+        .object({
+        input_tokens: z.number().default(0),
+        output_tokens: z.number().default(0),
+        cache_read_input_tokens: z.number().nullish(),
+        cache_creation_input_tokens: z.number().nullish(),
+    })
+        .default({ input_tokens: 0, output_tokens: 0 }),
+});
+/**
+ * Read the harness's configuration out of the environment.
+ *
+ * Returns `undefined` when there is no key, which is the ONLY thing that decides whether the harness
+ * is available. Stated as a read rather than a throw because "you have not configured this" is a
+ * routine answer a caller offers a way out of, not a failure.
+ */
+export function harnessOptionsFromEnv(env) {
+    const model = env[ReticleEnv.HARNESS_MODEL];
+    const baseUrl = env[ReticleEnv.HARNESS_BASE_URL];
+    const withOptions = (apiKey, fallbackUrl) => {
+        const url = baseUrl === undefined || 0 === baseUrl.length ? fallbackUrl : baseUrl;
+        return {
+            apiKey,
+            ...(model === undefined || 0 === model.length ? {} : { model }),
+            ...(url === undefined || 0 === url.length ? {} : { baseUrl: url }),
+        };
+    };
+    const apiKey = env[ReticleEnv.HARNESS_KEY];
+    if (apiKey !== undefined && 0 < apiKey.length)
+        return withOptions(apiKey);
+    /**
+     * The platform key, against the platform.
+     *
+     * Reticle's own service answers the Messages API at `/v1/messages` and forwards with ITS provider
+     * key, so a user who has run `reticle link` can drive with a frontier model having never held an
+     * Anthropic key at all. Without this they would be told to set `ANTHROPIC_API_KEY` to a value
+     * beginning `rk_live_` — which works, and reads like a mistake, and is the sort of instruction
+     * people correct on the way past and then cannot explain why nothing runs.
+     *
+     * An explicit `ANTHROPIC_API_KEY` still wins: someone who exported one meant it.
+     */
+    const cloudKey = apiKeyFrom(env);
+    const cloudUrl = env[ReticleEnv.CLOUD_URL];
+    if (cloudKey === undefined || 0 === cloudKey.length)
+        return undefined;
+    if (cloudUrl === undefined || 0 === cloudUrl.length)
+        return undefined;
+    return withOptions(cloudKey, cloudUrl);
+}
+/** Build a driver backed by the Messages API. */
+export function harnessDriver(options) {
+    const model = options.model ?? DEFAULT_HARNESS_MODEL;
+    const baseUrl = options.baseUrl ?? DEFAULT_HARNESS_BASE_URL;
+    const call = options.fetch ?? ((url, init) => fetch(url, init));
+    return {
+        async turn({ system, tools, history }) {
+            const response = 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,
+                    max_tokens: MAX_TOKENS,
+                    system: [
+                        {
+                            type: 'text',
+                            text: system,
+                            // The system prompt and the tool list are byte-identical on every turn of a drive, and
+                            // a drive is dozens of turns. Caching the prefix is most of the cost of driving an app.
+                            cache_control: CACHE_BREAKPOINT,
+                        },
+                    ],
+                    tools: tools.map(toWireTool),
+                    messages: withConversationCache(history.map(toWireMessage)),
+                }),
+            });
+            const body = await response.text();
+            if (!response.ok) {
+                // Thrown, not returned: the loop calls a model that will not answer a BROKEN drive, and a
+                // broken drive is never reported as clean. Swallowing this would be a verdict about an app
+                // nobody drove.
+                throw new Error(`the model refused the request (HTTP ${String(response.status)}): ${body}`);
+            }
+            const parsed = MessageResponse.parse(JSON.parse(body));
+            const text = parsed.content
+                .filter((block) => 'text' === block.type)
+                .map((block) => block.text)
+                .join('\n');
+            const calls = parsed.content
+                .filter((block) => 'tool_use' === block.type)
+                .map((block) => ({
+                id: block.id,
+                name: block.name,
+                args: isRecord(block.input) ? block.input : {},
+            }));
+            return {
+                text,
+                calls,
+                usage: {
+                    input: parsed.usage.input_tokens,
+                    output: parsed.usage.output_tokens,
+                    // Reported so a missed cache is VISIBLE. A breakpoint that silently stops matching costs
+                    // full price and looks exactly like one that is working from every other angle.
+                    cacheRead: parsed.usage.cache_read_input_tokens ?? 0,
+                    cacheWrite: parsed.usage.cache_creation_input_tokens ?? 0,
+                },
+            };
+        },
+    };
+}
+/**
+ * Cache the conversation so far, so the next turn does not pay to re-read it.
+ *
+ * The API is stateless: every turn re-sends the whole conversation, and a drive is dozens of turns.
+ * The system prompt and the tool list are already cached from the first turn — but those are the half
+ * that does not grow. The messages are the half that does, and without a breakpoint every byte of
+ * them is processed again at full price on every single turn.
+ *
+ * ONE breakpoint, on the last content block of the most-recently-appended turn. Next turn, this
+ * entire conversation is the request's prefix, so it is read at roughly a tenth of the input price
+ * rather than processed again. Earlier entries stay valid read points, so the saving accrues as the
+ * conversation grows — which is exactly the shape of the cost.
+ *
+ * Not several breakpoints: four is the hard limit per request and the system block already spends
+ * one. More here would buy nothing, because the lookup from a later breakpoint already finds the
+ * earlier turn's entry as its prefix.
+ *
+ * The one thing that would break it is a single turn adding more than twenty content blocks — the
+ * lookback window is twenty, and a breakpoint that cannot see the previous entry silently misses. A
+ * turn here is one text block, N tool_use blocks and N tool_result blocks, so it would take ten
+ * parallel calls in one turn to reach that. Worth knowing; not worth a second breakpoint until it
+ * happens, and the cache-read count in `usage` is where it would show up.
+ */
+function withConversationCache(messages) {
+    const last = messages[messages.length - 1];
+    if (last === undefined)
+        return [...messages];
+    const content = last.content.map((block, index) => index === last.content.length - 1 ? { ...block, cache_control: CACHE_BREAKPOINT } : block);
+    return [...messages.slice(0, -1), { ...last, content }];
+}
+function toWireTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.inputSchema,
+    };
+}
+function toWireMessage(entry) {
+    if ('user' === entry.role) {
+        // A text BLOCK rather than a bare string: only a block can carry a cache breakpoint, and the
+        // opening message is the one that would otherwise be a string. It changes the billing and
+        // nothing the model reads.
+        return { role: 'user', content: [{ type: 'text', text: entry.text }] };
+    }
+    if ('assistant' === entry.role) {
+        const blocks = [];
+        if (entry.text.length > 0)
+            blocks.push({ type: 'text', text: entry.text });
+        for (const call of entry.calls) {
+            blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.args });
+        }
+        return { role: 'assistant', content: blocks };
+    }
+    // Every outcome goes back in ONE user message. Splitting tool results across messages teaches the
+    // model to stop asking for calls in parallel, which is most of what makes a drive fast.
+    return {
+        role: 'user',
+        content: entry.outcomes.map((outcome) => ({
+            type: 'tool_result',
+            tool_use_id: outcome.id,
+            content: truncate(JSON.stringify(outcome.result ?? null)),
+            is_error: outcome.isError,
+        })),
+    };
+}
+function truncate(text) {
+    if (text.length <= MAX_RESULT_CHARS)
+        return text;
+    const dropped = String(text.length - MAX_RESULT_CHARS);
+    return `${text.slice(0, MAX_RESULT_CHARS)}\n…[truncated ${dropped} characters — ask for a narrower lens (count_only, interactive, diff, or a path) if you need the rest]`;
+}
+function isRecord(value) {
+    return 'object' === typeof value && null !== value && !Array.isArray(value);
+}

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

@@ -0,0 +1,19 @@
+/**
+ * The names of the drivers the harness can be asked for.
+ *
+ * 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.
+ */
+/** Generates its tool calls as text, and names the journeys it records. The default. */
+export declare const ANTHROPIC_DRIVER_NAME = "anthropic";
+/** Answers typed questions; picks from the elements on the page and cannot invent one. */
+export declare const JEV_DRIVER_NAME = "jev";
+/** Generates its tool calls, over Chat Completions. Here so an A/B has a third arm. */
+export declare const OPENAI_DRIVER_NAME = "openai";
+/** What a caller may name. Order is the order a reader sees them in the tool description. */
+export declare const DRIVER_NAMES: readonly ["anthropic", "jev", "openai"];
+/** An injected driver: not selectable, because only a caller in-process can supply one. */
+export declare const CUSTOM_DRIVER_NAME = "custom";

package/dist/features/harness/drivers.js

@@ -0,0 +1,19 @@
+/**
+ * The names of the drivers the harness can be asked for.
+ *
+ * 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.
+ */
+/** 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];
+/** An injected driver: not selectable, because only a caller in-process can supply one. */
+export const CUSTOM_DRIVER_NAME = 'custom';

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

@@ -0,0 +1,67 @@
+/**
+ * What to type into a field, and the one place in a drive worth paying a generating model for.
+ *
+ * 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.
+ */
+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;
+}): (label: string) => Promise<string>;