@reticlehq/server 3.5.0 → 3.7.0

package/dist/features/harness/explore/site-map.js

@@ -0,0 +1,150 @@
+/**
+ * Map first: before the Harness pursues a goal, it surveys the app, cheaply and with no model.
+ *
+ * Persona drives missed goals that sat one page away: the drive committed to a route, a prediction
+ * missed, and it graded where it stood. A person new to an app looks around first. The survey reads
+ * the start page, presses each nav link and each toggle once (never a field, never a name on the
+ * never-pressed list), reads where that leads, and goes back. The map is kept per app and refreshed
+ * by every drive's own reads, so the survey runs again only when the map is old.
+ */
+import { PredicateKind, ReticleTool, SnapshotMode, asRecord } from '@reticlehq/core';
+import { HarnessMapLimit, HarnessMapSchema, } from '@reticlehq/core/artifacts';
+import { navLinks, overlayOpen, parseTree, readPage, routeOf, textsOf, toggles, } from './page-tree.js';
+/** Presses the survey may spend: a dashboard's navigation and its toggles, not its rows. */
+export const SURVEY_PRESSES = 12;
+/** A map older than this is surveyed again; a younger one is reused and refreshed from drives. */
+export const MAP_FRESH_MS = 24 * 60 * 60 * 1000;
+/** How long a page gets to settle after a press before it is read. */
+const SETTLE_MS = 3000;
+/**
+ * Whether the app was surveyed for the run that started at `since` (or there is no map at all): a
+ * run that reused a fresh map does not sweep the whole app again.
+ */
+export function surveyedSince(map, since) {
+    return map === undefined || since <= map.surveyedAt;
+}
+/** One page read, as the map keeps it. */
+export function pageFrom(read, at, reachedBy) {
+    const lines = parseTree(read.tree);
+    const heading = lines.find((l) => 'heading' === l.role && 0 < l.name.length)?.name;
+    const clip = (t) => t.slice(0, HarnessMapLimit.TEXT);
+    return {
+        route: clip(read.route),
+        ...(heading === undefined ? {} : { heading: clip(heading) }),
+        texts: textsOf(lines, HarnessMapLimit.TEXTS).map(clip),
+        controls: lines
+            .filter((l) => l.ref !== undefined && 0 < l.name.length)
+            .slice(0, HarnessMapLimit.CONTROLS)
+            .map((l) => clip(`${l.role} "${l.name}"`)),
+        ...(reachedBy === undefined ? {} : { reachedBy: clip(reachedBy) }),
+        at,
+    };
+}
+/** Pages merged by route, the newest read winning, newest first, within the map's bound. */
+export function mergePages(map, pages, surveyedAt = map.surveyedAt) {
+    const byRoute = new Map(map.pages.map((p) => [p.route, p]));
+    for (const page of pages) {
+        const was = byRoute.get(page.route);
+        if (was === undefined || was.at <= page.at) {
+            const reachedBy = page.reachedBy ?? was?.reachedBy;
+            byRoute.set(page.route, { ...page, ...(reachedBy === undefined ? {} : { reachedBy }) });
+        }
+    }
+    const pagesOut = [...byRoute.values()]
+        .sort((a, b) => b.at - a.at)
+        .slice(0, HarnessMapLimit.PAGES);
+    return { surveyedAt, pages: pagesOut };
+}
+/** The pages a drive read in full, for refreshing the map from what it saw. */
+export function pagesReadIn(calls, at) {
+    return calls.flatMap((call) => {
+        // Only a full read of an unobstructed page: a quick read has no text, and a page behind an open
+        // menu reads as the menu. Either one once replaced the survey's page and emptied the map.
+        if (ReticleTool.SNAPSHOT !== call.name || call.isError)
+            return [];
+        if (SnapshotMode.FULL !== asRecord(call.args)['mode'])
+            return [];
+        const result = asRecord(call.result);
+        const tree = result['tree'];
+        const route = asRecord(result['status'])['route'];
+        if ('string' !== typeof tree || 'string' !== typeof route)
+            return [];
+        if (overlayOpen(parseTree(tree)))
+            return [];
+        return [pageFrom({ tree, route: routeOf(route) }, at)];
+    });
+}
+const label = (line) => `${line.role} "${line.name}"`;
+async function settle(invoke) {
+    try {
+        await invoke(ReticleTool.WAIT_FOR, {
+            predicate: { kind: PredicateKind.SETTLED },
+            timeout_ms: SETTLE_MS,
+        });
+    }
+    catch {
+        /* a page that never settles is read as it stands */
+    }
+}
+/**
+ * Survey the app from where the tab stands, and leave the tab where it started. Every press is
+ * found again by its name on a fresh read of the start page, since a ref does not survive a reload.
+ */
+export async function surveyApp(invoke, now, presses = SURVEY_PRESSES) {
+    let start = await readPage(invoke);
+    if (start === undefined)
+        return undefined;
+    // A menu left open hides the page behind it: reload it once before reading what it offers.
+    if (overlayOpen(parseTree(start.tree))) {
+        await invoke(ReticleTool.NAVIGATE, { url: start.route }).catch(() => undefined);
+        start = (await readPage(invoke)) ?? start;
+    }
+    const pages = [pageFrom(start, now())];
+    const startLines = parseTree(start.tree);
+    const targets = [...navLinks(startLines), ...toggles(startLines)]
+        .map(label)
+        .filter((name, i, all) => all.indexOf(name) === i)
+        .slice(0, presses);
+    for (const target of targets) {
+        try {
+            const here = await readPage(invoke);
+            const line = parseTree(here?.tree ?? '').find((l) => l.ref !== undefined && label(l) === target);
+            if (line?.ref === undefined)
+                continue;
+            await invoke(ReticleTool.ACT, { ref: line.ref, action: 'click' });
+            await settle(invoke);
+            const read = await readPage(invoke);
+            if (read !== undefined)
+                pages.push(pageFrom(read, now(), target));
+            if (read !== undefined && read.route !== start.route)
+                await invoke(ReticleTool.NAVIGATE, { url: start.route });
+        }
+        catch {
+            /* a press that fails is a page the map does not have */
+        }
+    }
+    return mergePages({ surveyedAt: now(), pages: [] }, pages, now());
+}
+/** The map from its file's text, or undefined when there is none or it does not parse. */
+export function parseMap(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const parsed = HarnessMapSchema.safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The map as the platform takes it: pages only, the fields its engine reads. */
+export function mapForPlatform(map) {
+    return {
+        pages: map.pages.map((p) => ({
+            route: p.route,
+            ...(p.heading === undefined ? {} : { heading: p.heading }),
+            texts: p.texts,
+            controls: p.controls,
+        })),
+    };
+}

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

@@ -1,77 +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';
-import { type OpenAiDriverOptions } from './openai-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;
-    /** GPT, the generator a Jev drive pairs with. Asked ahead of `generator` when both are set. */
-    openai?: OpenAiDriverOptions;
-    /** Anthropic, for a machine that holds only that key. */
-    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,55 +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';
-import { DEFAULT_OPENAI_MODEL, OPENAI_REASONING_EFFORT, openAiCompletionsUrl, } from './openai-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();
@@ -71,122 +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.`;
-/**
- * A model's one-line answer as a field value, or nothing. 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.
- */
-function asValue(raw) {
-    const text = raw?.trim().split('\n')[0];
-    if (text === undefined || 0 === text.length)
-        return undefined;
-    return 80 < text.length ? undefined : text.replace(/^["']|["']$/g, '');
-}
-/** One string from GPT over Chat Completions — directly, or through the platform with its key. */
-async function generateWithOpenAi(options, label, context) {
-    const call = options.fetch ?? ((url, init) => fetch(url, init));
-    try {
-        const res = await call(openAiCompletionsUrl(options), {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', authorization: `Bearer ${options.apiKey}` },
-            body: JSON.stringify({
-                model: options.model ?? DEFAULT_OPENAI_MODEL,
-                max_completion_tokens: MAX_TOKENS,
-                reasoning_effort: OPENAI_REASONING_EFFORT,
-                messages: [{ role: 'user', content: PROMPT(label, context) }],
-            }),
-        });
-        if (!res.ok)
-            return undefined;
-        const parsed = JSON.parse(await res.text());
-        return asValue(parsed.choices?.[0]?.message?.content ?? undefined);
-    }
-    catch {
-        return undefined;
-    }
-}
-/** 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 ?? [];
-        return asValue(content
-            .filter((block) => 'text' === block.type)
-            .map((block) => block.text ?? '')
-            .join(''));
-    }
-    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);
-        const { openai, generator } = deps;
-        if ((openai === undefined && generator === undefined) ||
-            !needsGeneration(label) ||
-            MAX_PER_DRIVE <= spent)
-            return fallback;
-        spent += 1;
-        const context = deps.context?.() ?? '';
-        const generated = openai !== undefined
-            ? await generateWithOpenAi(openai, label, context)
-            : generator !== undefined
-                ? await generateOne(generator, label, context)
-                : undefined;
-        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,82 @@
+/** One goal: text the page must show, or — when the persona negated it — must not. */
+export interface Goal {
+    text: string;
+    /** The persona said the page must NOT show it: an absence goal, graded by asserting it is not there. */
+    absent?: true;
+}
+export interface GoalCheck {
+    /** The text that had to be on the page (or, for an absence goal, not on it). */
+    text: string;
+    /** Set for an absence goal. */
+    absent?: true;
+    /** The engine's verdict on it: only `yes` is proved. */
+    verified: string;
+    /** Why it was not checked, when it was not. */
+    reason?: string;
+}
+/**
+ * Whether `shown` — one element's text, maybe cut short with "…" — is text the Harness wrote itself
+ * rather than the app: one of `own` (its journey, the names of the plan and the flows it saved), in
+ * full or cut short, holding `goal`. A Harness asked to rename a plan stopped on the /plans list and
+ * was graded PROVED on every quote: the plan it had just saved was named after the journey, and the
+ * journey quoted them all. An element showing exactly the goal is the app's, whoever else wrote it.
+ */
+export declare function writtenByHarness(shown: string, goal: string, own: readonly string[]): boolean;
+/** The end state a goal quotes: its last quoted text that it does not negate. */
+export declare function endOf(goal: string): string | undefined;
+/** The observable goals in a persona: whatever it quoted, each marked absent when it was negated. */
+export declare function parseGoals(persona: string | undefined): Goal[];
+/** The texts a persona says must be on the page: the quoted goals it did not negate. */
+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 let
+ * settle, read once, and each goal is scrolled to by its text — one below the fold read `unknown`
+ * on a drive that never scrolled. The one recorded assert covers the goals found. A goal not found
+ * is undecided, not failed: nothing here knows the drive reached the page that would show it. 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 | Goal)[], 
+/** The page as it read before the drive: a goal it already showed proves nothing at the end. */
+opening?: string, 
+/** Text the Harness wrote itself (its journey, its plan's and flows' names): never evidence. */
+own?: readonly string[]): Promise<GoalCheck[]>;
+/**
+ * Whether the page shows `text` once it has settled, scrolled to if need be — how a person looks
+ * for something before saying it is not there. Records no check.
+ */
+export declare function lookFor(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>, text: string, 
+/** Text the Harness wrote itself: a match inside it is not the page showing the goal. */
+own?: readonly string[]): Promise<boolean>;
+/** The page as it reads now, or undefined when it cannot be read. Taken before a drive starts. */
+export declare function readOpening(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>): Promise<string | undefined>;
+/**
+ * The end state the caller declared, checked like any assert.
+ *
+ * Quoted text only proves some words are on the last page, which is how a drive that never used the
+ * app could pass: from the field, "it only checks that I have certain titles on my page". An `expect`
+ * names an OUTCOME — a route reached, a request made, state changed — in the same predicate grammar
+ * as reticle_assert, and is graded the same way. A check that cannot run is `unknown`.
+ */
+export declare function checkExpect(invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>, predicate: Record<string, unknown>): Promise<GoalCheck>;
+/** Whether the drive met the goals it was given: undefined when it was given none. */
+export declare function goalsMet(checks: readonly GoalCheck[]): boolean | undefined;
+/**
+ * Whether the drive met its goal, as the answer and the run report it. The driver's own `goalMet`
+ * is its word, never evidence: a run answered `goalMet: true` after zero actions on a tab that
+ * already showed the end state, and another with both its goals `unknown`. With goals, met exactly
+ * when every one was proved; with none, the driver's word stands, and only after an action ran.
+ * Undefined when nothing judged it.
+ */
+export declare function goalOfDrive(claimed: boolean | undefined, checks: readonly GoalCheck[], acted: boolean): boolean | undefined;
+/** 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;
+/**
+ * The goals a drive is graded on: every quote, less a value the drive typed — an input, never
+ * evidence — except the journey's end (its last text to show), which stays even when typed: saving
+ * "Order 7" and then seeing it listed is the journey. Absence goals always stay.
+ */
+export declare function endGoalsOf(goals: readonly Goal[], typed: readonly string[]): Goal[];