@reticlehq/server 3.1.0 → 3.3.0

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;