@reticlehq/server 3.1.0 → 3.2.0

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

@@ -0,0 +1,153 @@
+/**
+ * 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 { 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.
+ */
+export function heuristicFillValue(label) {
+    const l = label.toLowerCase();
+    if (l.includes('email'))
+        return 'harness@reticle.dev';
+    if (l.includes('password'))
+        return 'password';
+    if (l.includes('url') || l.includes('link'))
+        return 'https://example.com';
+    if (l.includes('phone') || l.includes('tel'))
+        return '5550100';
+    if (l.includes('date'))
+        return '2026-01-01';
+    if (l.includes('amount') || l.includes('price') || l.includes('qty') || l.includes('quantity'))
+        return '2';
+    if (l.includes('search') || l.includes('filter'))
+        return 'a';
+    if (l.includes('number') || l.includes('count'))
+        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 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/jev-driver.d.ts

@@ -0,0 +1,188 @@
+/**
+ * A harness driver with no text generator in it.
+ *
+ * `driver.ts` binds the harness to a frontier model, and the comment at the top of it has always
+ * claimed the tier is "a standing test of the design": the driver is not reasoning about business
+ * logic, it is choosing what to touch next and saying what it expects, and if that needed a large
+ * model then the engine would not be doing its job. Nothing tested the claim, because the only
+ * driver in the repo was a large model.
+ *
+ * This is the test. Jev is a System One model — it evaluates typed questions against a state and
+ * answers with probabilities, in one parallel pass, and it does not emit prose. It therefore cannot
+ * invent a tool call. So every call this driver makes is built HERE, deterministically, out of what
+ * the page actually offers, and the model's only contribution is picking one of them. That is a
+ * strictly smaller surface than a generating driver has, and it is the whole reason this is worth
+ * having: a driver that cannot name an element that is not on the page cannot hallucinate one.
+ *
+ * What did NOT move: the verdict. `decideVerified` still decides, on evidence, with no model in it.
+ * A System One model cannot hallucinate a type, but it still returns a PROBABILITY, and a
+ * probability is not proof. Anyone reading this file as an invitation to let Jev answer
+ * "did it work?" should read `engine/src/evidence/verified.ts` first — the seventeen clauses there
+ * exist because this product is the verdict, and a verdict sourced from a model's confidence is the
+ * thing Reticle sells the absence of.
+ */
+import type { ModelDriver } from './harness.js';
+import type { HarnessFetch } from './driver.js';
+export declare const DEFAULT_JEV_MODEL = "jev-latest";
+export declare const DEFAULT_JEV_BASE_URL = "https://api.typesafe.ai";
+/**
+ * The consequences the driver can declare, and the predicate each one becomes.
+ *
+ * Declaring one is not optional decoration — it is the difference between a drive and a click. The
+ * first version of this driver emitted `act_and_wait` with no `until` at all, and the engine said
+ * so in every single result: "the page settled and no channel reported a problem, but nothing was
+ * declared to prove — this is not verification". Six actions, zero proved. A flow recorded from that
+ * drive passes even when the feature is broken, which is the exact failure this product exists to
+ * catch, sitting inside the thing meant to catch it.
+ *
+ * Every predicate here is BARE — a kind with no specifics — because before acting the driver does
+ * not know which endpoint, signal or route to expect. Bare is still consequence-grade evidence: it
+ * asserts the app's own machinery moved, which a presence check on screen text does not.
+ *
+ * Only SIGNAL and NET can be declared bare, and that is a fact about the engine rather than a
+ * preference. `engine/src/evidence/already-true.ts` lists the kinds that read live state — element,
+ * text, route and state — and those are checked BEFORE the action as well as after, precisely so a
+ * condition that already held cannot be sold as something the action caused. A bare predicate of
+ * one of those kinds is unconditionally true: there is always a current route, and there is always
+ * some store. That file says so in as many words at its `ROUTE` case.
+ *
+ * This driver tried all four anyway and the engine refused all four, every time, with
+ * `already_true` — "the declared consequence was already true before this action, so it proves
+ * nothing about it". Signal and net are event-based and floored at the act's own cursor, so they
+ * cannot be answered by the past, which is exactly what makes them safe to declare with no
+ * specifics. Route and state come back the moment the driver can name a pathname or a store path
+ * instead of a bare kind, and they are the stronger evidence when it can.
+ *
+ * `anyOf` is not a loophole: it reports as live-reading if ANY branch does, so it holds only the
+ * two safe kinds for the same reason.
+ *
+ * ponytail: bare `net` can in principle be satisfied by unrelated traffic inside the action's
+ * window — a page polling every second would answer for a button that did nothing. The window is
+ * the action's own, not "ever", so the exposure is small but real. The upgrade is to learn the
+ * app's vocabulary first (one `reticle_observe` early in the drive gives the actual signal names
+ * and endpoint paths) and declare `urlContains`/`name` instead of a bare kind. Until then `state`
+ * and `signal` are the trustworthy ones and `net` is the one to distrust on a chatty app.
+ */
+export interface Consequence {
+    predicate: Record<string, unknown>;
+    describes: string;
+    /**
+     * Whether a SAVED FLOW can carry this claim, which is a different question from whether the drive
+     * can prove it.
+     *
+     * A recorded step keeps an expectation only in the forms a replay can re-check, and that filter
+     * refuses every unbound kind: `signal "export:generated"` survives, a bare "some signal fires"
+     * does not; `net { method: "POST" }` survives, a bare "some request happens" does not; `not` and
+     * `anyOf` have no representation at all.
+     *
+     * Measured on a real dashboard before this field existed: every one of the four consequences on
+     * offer was unbound, so 0 of 22 steps across 16 machine-driven flows recorded a single
+     * expectation, against 211 of 419 in the hand-authored flows beside them. The drive proved things
+     * and then saved flows that had forgotten all of it. Since a flow is meant to BE the regression
+     * suite, that is the product's own claim failing at its last step: those flows can only ever
+     * catch "the click stopped landing", never "the feature broke".
+     */
+    recordable: boolean;
+}
+/**
+ * The app's own route, with Reticle's fingerprints wiped off it.
+ *
+ * A pooled launcher appends `__reticle_opened=1` to the URL it opens, and that parameter ended up
+ * inside a declared consequence: "this click leaves a route containing /?__reticle_opened=1". On a
+ * hash-routed app that claim can never hold, because the query string never changes -- only the
+ * fragment does -- so every navigation link was a guaranteed red, and the red was about OUR query
+ * parameter rather than about the application. Found by making a failed action say what it claimed;
+ * before that it read as an ordinary "the declared consequence did not hold".
+ *
+ * The fragment is kept, and is the point: on a hash-routed app it is the only part that moves.
+ */
+export declare function appRoute(route: string): string;
+/**
+ * The consequences on offer, given where the app currently is and what it says it can do.
+ *
+ * Two things shape this list, and the second one was missing for a whole release.
+ *
+ * It is a function of the CURRENT ROUTE, because "this takes us off the page we are on" is only
+ * falsifiable against a route actually read.
+ *
+ * It is also a function of the app's OWN VOCABULARY, because an unbound claim cannot be saved. A
+ * drive that declares "some signal fires" proves something real at the time and writes a flow that
+ * asserts nothing, so every later replay passes as long as the clicks still land. Offering the
+ * declared signal NAMES turns the same choice into one a flow can keep, and costs nothing extra:
+ * the names are already read out of `.reticle` to build the plan.
+ */
+export declare function consequencesFor(route: string | undefined, vocabulary?: readonly string[]): Record<string, Consequence>;
+/**
+ * One step of the plan the caller built from `.reticle`.
+ *
+ * Structural rather than imported: this package is a SINK — it is handed a toolset and a driver and
+ * reaches into nothing — so the plan arrives as data with the shape it needs and no dependency on
+ * where it was built.
+ */
+export interface DrivePlanStep {
+    /** `replay` for a journey already recorded, `drive` for declared intent nobody has proved. */
+    kind: string;
+    /** The flow to replay, or the signal/control a drive step is aimed at. */
+    target: string;
+    /** Why this step is worth taking, in the project's own words. */
+    why: string;
+}
+export interface JevDriverOptions {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    /**
+     * The loop's step budget, so the driver can stop exploring in time to save what it drove.
+     *
+     * The loop does not tell a driver how much budget is left — it does not have to, because a
+     * generating model is expected to call `finish` when it is ready. This driver has a teardown it
+     * must reach, so it needs the number. Absent ⇒ no reserve, and a run that ends on BUDGET keeps
+     * nothing, which is why every caller inside the repo passes it.
+     */
+    maxSteps?: number;
+    /**
+     * What this drive is FOR, read from `.reticle` before it started.
+     *
+     * Replay steps run FIRST and deterministically, with no model call at all — a journey already on
+     * disk must never be re-driven, which is the whole reason the plan exists. Only once they are
+     * done is the model asked anything, and then it is asked against the intent these steps carry
+     * rather than against whatever happens to be on the page.
+     */
+    plan?: readonly DrivePlanStep[];
+    /**
+     * The signal names the app declares, untested ones first, read out of `.reticle` with the plan.
+     *
+     * Offered as consequences so a declaration can name something. Absent is not a failure: the
+     * method-bound network consequences are still recordable, and an app that declares no signals is
+     * simply an app with less to claim.
+     */
+    vocabulary?: readonly string[];
+    /**
+     * What to type into a text field, when the label alone is not enough to guess.
+     *
+     * The one place a drive is a COMPOSITION rather than a decision, and therefore the one place worth
+     * paying a generating model for. Absent ⇒ the label heuristic answers, which is what every drive
+     * did before this seam existed; a drive with no text fields never reaches it either way. See
+     * `fill-values.ts` for why it is escalation rather than a second model in the loop.
+     */
+    fillValue?: (label: string) => Promise<string>;
+    /** Injected for tests. Defaults to the platform `fetch`. */
+    fetch?: HarnessFetch;
+}
+/**
+ * Read this driver's configuration out of the environment.
+ *
+ * A direct Jev key wins over the platform key, so that someone debugging the upstream is never
+ * quietly talking to the proxy they were trying to bypass. Returns `undefined` when neither is set,
+ * which is a routine answer and not a failure — the caller falls back to the Anthropic driver.
+ */
+export declare function jevOptionsFromEnv(env: Record<string, string | undefined>): JevDriverOptions | undefined;
+/**
+ * Build a driver backed by a System One model.
+ *
+ * Every turn emits exactly ONE call. The loop dispatches a turn's calls with `Promise.all`, so an
+ * act and the snapshot that reads its result cannot be batched into one turn — they would race, and
+ * the snapshot would describe a page mid-flight. One call per turn costs a step and buys a reading
+ * that is actually of the page the action produced.
+ */
+export declare function jevDriver(options: JevDriverOptions): ModelDriver;