@reticlehq/server 3.5.0 → 3.7.0

package/dist/features/harness/platform-config.js

@@ -16,8 +16,10 @@
  *   - it never overrides someone who was EXPLICIT. A driver named in the call, or set in the
  *     environment, wins over the stored preference. Precedence lives in the caller.
  */
-import { platformCredentialFrom } from '@reticlehq/core';
+import { CreditKind, ReticleEnv, platformCredentialFrom } from '@reticlehq/core';
 const CONFIG_PATH = '/v1/model/config';
+/** The header naming the free drive a call belongs to. See `ReticleEnv.DRIVE_ID`. */
+export const DRIVE_HEADER = 'x-reticle-drive';
 /**
  * How long the daemon will wait for a preference before driving without it.
  *
@@ -26,6 +28,67 @@ const CONFIG_PATH = '/v1/model/config';
  * everybody had before this endpoint existed.
  */
 const TIMEOUT_MS = 2_000;
+const count = (value) => 'number' === typeof value && Number.isInteger(value) && value >= 0 ? value : undefined;
+const field = (value, key) => 'object' === typeof value && null !== value ? value[key] : undefined;
+/** `plan`, `harnessRuns` and `memory` out of `/v1/model/config`; each absent when not sent. */
+function hudFieldsOf(record) {
+    const plan = record['plan'];
+    const kind = Object.values(CreditKind).find((k) => k === field(plan, 'kind'));
+    const daysLeft = count(field(plan, 'daysLeft'));
+    const seats = count(field(plan, 'seats'));
+    const runs = count(field(record['harnessRuns'], 'total'));
+    const memory = count(field(record['memory'], 'entries'));
+    return {
+        ...(kind === undefined
+            ? {}
+            : {
+                plan: {
+                    kind,
+                    ...(daysLeft === undefined ? {} : { daysLeft }),
+                    ...(seats === undefined ? {} : { seats }),
+                },
+            }),
+        ...(runs === undefined ? {} : { harnessRuns: runs }),
+        ...(memory === undefined ? {} : { memoryEntries: memory }),
+    };
+}
+/** `{ [key]: value }` when `value` is an http(s) address, else nothing: a link must open. */
+function webUrl(value, key) {
+    if ('string' !== typeof value)
+        return {};
+    try {
+        const url = new URL(value);
+        return 'http:' === url.protocol || 'https:' === url.protocol
+            ? { [key]: value }
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The gate out of `/v1/model/config`, or undefined from a platform that does not send one. */
+function gateOf(record) {
+    const unlocked = record['harnessUnlocked'];
+    if ('boolean' !== typeof unlocked)
+        return undefined;
+    const score = record['coverageScore'];
+    const lock = record['harnessLock'];
+    const lockRecord = 'object' === typeof lock && null !== lock ? lock : {};
+    const reason = lockRecord['reason'];
+    const prompt = lockRecord['prompt'];
+    return {
+        unlocked,
+        // Rounded down, as core's rule is: a locked app never shows 80%.
+        ...('number' === typeof score ? { percent: Math.floor(score * 100 + 1e-9) } : {}),
+        ...('string' === typeof reason ? { reason } : {}),
+        ...('string' === typeof prompt ? { prompt } : {}),
+    };
+}
+/** When the grant ends, epoch ms, from an ISO date or a number. Anything else: not said. */
+function endsAtOf(value) {
+    const at = 'number' === typeof value ? value : 'string' === typeof value ? Date.parse(value) : NaN;
+    return Number.isFinite(at) ? at : undefined;
+}
 function parse(body) {
     try {
         const parsed = JSON.parse(body);
@@ -35,11 +98,11 @@ function parse(body) {
         const provider = record['provider'];
         if ('string' !== typeof provider || 0 === provider.length)
             return undefined;
-        // Absent reads as enabled: the platform's own default is on, and a daemon that treated a
-        // missing field as "off" would silently disable the feature for anyone on an older API.
+        // Absent reads as OFF: the Harness is opt-in, a new project starts with it off, and only the
+        // platform saying it is on lets a drive spend credits.
         const enabled = record['harnessEnabled'];
-        // Same rule for both, for the same reason: an older API that reports neither must not have its
-        // silence read as a refusal.
+        // Entitlement keeps the old rule: an older API that does not report it must not have its silence
+        // read as a refusal. The switch above is what keeps an unasked drive from running.
         const entitled = record['harnessEntitled'];
         // `available` is keyed by provider and says which ones the platform holds a key for. Read only
         // the entry for the provider this project uses: another provider being configured says nothing
@@ -48,11 +111,38 @@ function parse(body) {
         const ready = 'object' === typeof available && null !== available
             ? available[provider]
             : undefined;
+        const credits = record['credits'];
+        const used = 'object' === typeof credits && null !== credits
+            ? credits['used']
+            : undefined;
+        const limit = 'object' === typeof credits && null !== credits
+            ? credits['limit']
+            : undefined;
+        const kind = 'object' === typeof credits && null !== credits
+            ? Object.values(CreditKind).find((k) => k === credits['kind'])
+            : undefined;
+        const gate = gateOf(record);
+        const endsAt = endsAtOf('object' === typeof credits && null !== credits
+            ? credits['endsAt']
+            : undefined);
         return {
             provider,
-            harnessEnabled: 'boolean' === typeof enabled ? enabled : true,
+            harnessEnabled: true === enabled,
             harnessEntitled: 'boolean' === typeof entitled ? entitled : true,
             providerReady: 'boolean' === typeof ready ? ready : true,
+            ...(gate === undefined ? {} : { gate }),
+            ...hudFieldsOf(record),
+            ...webUrl(record['planUrl'], 'planUrl'),
+            ...('number' === typeof used && 'number' === typeof limit
+                ? {
+                    credits: {
+                        used,
+                        limit,
+                        ...(kind === undefined ? {} : { kind }),
+                        ...(endsAt === undefined ? {} : { endsAt }),
+                    },
+                }
+                : {}),
         };
     }
     catch {
@@ -73,19 +163,26 @@ export async function fetchPlatformConfig(env, doFetch = (url, init) => fetch(ur
         return undefined;
     const key = cloud.apiKey;
     const host = cloud.url;
+    const drive = env[ReticleEnv.DRIVE_ID];
     const controller = new AbortController();
     const timer = setTimeout(() => {
         controller.abort();
     }, timeoutMs);
     try {
-        const res = await doFetch(`${host.replace(/\/+$/, '')}${CONFIG_PATH}`, {
+        const base = host.replace(/\/+$/, '');
+        const res = await doFetch(`${base}${CONFIG_PATH}`, {
             method: 'GET',
-            headers: { authorization: `Bearer ${key}` },
+            // The free drive too: a workspace with no card is entitled for that drive and no other.
+            headers: {
+                authorization: `Bearer ${key}`,
+                ...(drive === undefined || 0 === drive.length ? {} : { [DRIVE_HEADER]: drive }),
+            },
             signal: controller.signal,
         });
         if (!res.ok)
             return undefined;
-        return parse(await res.text());
+        const config = parse(await res.text());
+        return config === undefined ? undefined : { ...config, platformUrl: base };
     }
     catch {
         return undefined;

package/dist/features/harness/route-guess.d.ts

@@ -0,0 +1,13 @@
+/** Said of a route guess that missed, on the step. */
+export declare const MSG_ROUTE_GUESS_MISSED = "the drive guessed this would change the route and it did not go where it said: the driver's wrong guess, not an app defect";
+/** Said of a route claim whose click opened a menu or dialog instead: the route comes after it. */
+export declare const MSG_OPENED_MENU = "it opened a menu or dialog; the route it named comes after a choice in it \u2014 progress, not a check";
+/** Whether a declared predicate claims nothing but a route (or leaving one). */
+export declare function claimsOnlyRoute(predicate: unknown): boolean;
+/** The pages the map knows, as one line for the model. */
+export declare const knownPagesLine: (routes: readonly string[]) => string;
+/**
+ * What to do instead of guessing again, after a route guess missed: the known page it was after,
+ * by its route, or the pages the map knows. Undefined when the map knows none.
+ */
+export declare function routeHint(predicate: unknown, routes: readonly string[]): string | undefined;

package/dist/features/harness/route-guess.js

@@ -0,0 +1,49 @@
+/**
+ * A Harness check that only claimed where the page would go, and missed.
+ *
+ * The driver declares a consequence before each click. When all it declares is a route ("this will
+ * leave /overview") and the route does something else, that is the driver guessing wrong about an
+ * in-page control (a Mine/Team toggle, a project picker, a dialog, a tab), not the app failing:
+ * three runs whose every goal was met read NOT PROVED with "findings" that were the driver's own
+ * predictions. Such a check is undecided, never failed, and never a finding.
+ *
+ * ponytail: a route-only claim is always read as a guess. A link that should navigate and does not
+ * is still found, by the crawl and by the goals, which are what a run is judged on.
+ */
+import { PredicateKind, asRecord, asString } from '@reticlehq/core';
+/** Said of a route guess that missed, on the step. */
+export const MSG_ROUTE_GUESS_MISSED = "the drive guessed this would change the route and it did not go where it said: the driver's wrong guess, not an app defect";
+/** Said of a route claim whose click opened a menu or dialog instead: the route comes after it. */
+export const MSG_OPENED_MENU = 'it opened a menu or dialog; the route it named comes after a choice in it — progress, not a check';
+/** Whether a declared predicate claims nothing but a route (or leaving one). */
+export function claimsOnlyRoute(predicate) {
+    const p = asRecord(predicate);
+    const kind = asString(p['kind']);
+    if (PredicateKind.ROUTE === kind)
+        return true;
+    return (PredicateKind.NOT === kind && PredicateKind.ROUTE === asString(asRecord(p['predicate'])['kind']));
+}
+/** How many known pages a line names; a map of hundreds is a list nobody reads. */
+const MAX_ROUTES_NAMED = 20;
+/** The pages the map knows, as one line for the model. */
+export const knownPagesLine = (routes) => routes.slice(0, MAX_ROUTES_NAMED).join(', ');
+/** The route a claim names arriving at, when it names one (`not` a route names none). */
+function claimedRoute(predicate) {
+    const p = asRecord(predicate);
+    if (PredicateKind.ROUTE !== asString(p['kind']))
+        return undefined;
+    return asString(p['pathname']) ?? asString(p['contains']);
+}
+/**
+ * What to do instead of guessing again, after a route guess missed: the known page it was after,
+ * by its route, or the pages the map knows. Undefined when the map knows none.
+ */
+export function routeHint(predicate, routes) {
+    if (0 === routes.length)
+        return undefined;
+    const wanted = claimedRoute(predicate);
+    const known = wanted === undefined ? undefined : routes.find((r) => r.includes(wanted));
+    return known === undefined
+        ? `That control does not lead where you guessed. The pages this app has: ${knownPagesLine(routes)}. Go to one by its link or reticle_navigate, rather than guessing which control leads there.`
+        : `That control does not lead to ${known}. It is a page this app has: press its link, or reticle_navigate { url: "${known}" }, rather than guessing another control.`;
+}

package/dist/features/harness/script/app-controls.d.ts

@@ -0,0 +1,5 @@
+import type { ToolOutcome } from '../harness.js';
+/** Every named control a drive saw, by page, then what the crawl clicked. */
+export declare function appControlsOf(calls: readonly ToolOutcome[], crawled: ToolOutcome | undefined): {
+    appControls?: string[];
+};

package/dist/features/harness/script/app-controls.js

@@ -0,0 +1,40 @@
+/**
+ * The app map a drive leaves for the next plan: the controls on every page the drive looked at.
+ *
+ * The planner reads the start page live. The crawl's clicks alone spent their budget on a
+ * dashboard's navigation and never listed the Refund button on its Transactions page, so no journey
+ * went near the app's costliest defects. Every lane snapshots the pages it reaches, and those
+ * snapshots already hold the controls a plan needs.
+ */
+import { ReticleTool, asRecord, parseInteractive } from '@reticlehq/core';
+/** The most controls kept: a dashboard's navigation and its pages' main buttons, not its rows. */
+const MAX_APP_CONTROLS = 120;
+/** A snapshot line as a page's control: `button "Refund"`, with no ref, value or state. */
+const NAMED_CONTROL = /^-?\s*([a-z]+) "([^"]+)"/;
+/** The page part of an address: its path and hash, without the session query a lease adds. */
+function pageOf(route) {
+    return route.replace(/\?[^#]*/, '') || '/';
+}
+/** Every named control a drive saw, by page, then what the crawl clicked. */
+export function appControlsOf(calls, crawled) {
+    const seen = [];
+    for (const call of calls) {
+        if (ReticleTool.SNAPSHOT !== call.name || call.isError)
+            continue;
+        const result = asRecord(call.result);
+        const tree = result['tree'];
+        const route = asRecord(result['status'])['route'];
+        if ('string' !== typeof tree || 'string' !== typeof route)
+            continue;
+        for (const item of parseInteractive(tree)) {
+            const named = NAMED_CONTROL.exec(item.desc.trim());
+            if (named !== null)
+                seen.push(`${pageOf(route)}: ${String(named[1])} "${String(named[2])}"`);
+        }
+    }
+    const visited = asRecord(crawled?.result)['visited'];
+    if (Array.isArray(visited))
+        seen.push(...visited.filter((v) => 'string' === typeof v));
+    const names = [...new Set(seen)];
+    return 0 === names.length ? {} : { appControls: names.slice(0, MAX_APP_CONTROLS) };
+}

package/dist/features/harness/script/lane-ids.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The Harness id each lane of one drive runs under.
+ *
+ * Lanes in leased contexts used to share the drive's one id, so each lane's session, ending, synced
+ * a run under the same `harness-<id>` and the last lane to finish overwrote the others. A lane on
+ * its own session gets its own id; a drive that never leased keeps the one id it always had.
+ */
+export interface LaneIds {
+    /** The id for the lane on `sessionId`, minted once and reused. */
+    idFor(sessionId: string | undefined): string;
+    /** Every id this drive ran under, in the order the lanes started. */
+    all(): string[];
+}
+export declare function laneIds(harness: string, leasing: boolean): LaneIds;

package/dist/features/harness/script/lane-ids.js

@@ -0,0 +1,16 @@
+export function laneIds(harness, leasing) {
+    const bySession = new Map();
+    return {
+        idFor(sessionId) {
+            if (!leasing || sessionId === undefined)
+                return harness;
+            const known = bySession.get(sessionId);
+            if (known !== undefined)
+                return known;
+            const id = `${harness}-L${String(bySession.size + 1)}`;
+            bySession.set(sessionId, id);
+            return id;
+        },
+        all: () => (0 < bySession.size ? [...bySession.values()] : [harness]),
+    };
+}

package/dist/features/harness/script/script-run.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Run a drive script: lanes side by side, journeys in order, every step through Reticle's own tools.
+ *
+ * Replays, exact acts and asserts need no model and are judged by the tool's own verdict. Only an
+ * open goal reaches the model. The browser, the model and the clock of concurrency all arrive as
+ * ports, so the scheduling below is tested without either.
+ *
+ * Barriers cannot deadlock: a journey only waits on one in an EARLIER lane (`checkScript`), lanes
+ * are started in order, so whatever is waited on has already started.
+ */
+import { type PlanView } from '@reticlehq/core';
+import { JourneyBy, type DriveScript } from '@reticlehq/core/artifacts';
+import { type HarnessResult, type HarnessToolset, type ToolOutcome } from '../harness.js';
+export interface ScriptPorts {
+    /** A browser context for one lane. Without a pool this is the user's own tab, every time. */
+    lease(laneId: string): Promise<{
+        sessionId?: string;
+        release(): Promise<void>;
+    }>;
+    /** Reticle's tools on a lane's tab, as the journey's persona when it has one. */
+    toolset(sessionId: string | undefined, persona: string | undefined): HarnessToolset;
+    /** Hand an open goal to the model, on that toolset. */
+    drive(toolset: HarnessToolset, goal: string, maxSteps: number): Promise<HarnessResult>;
+    /** Lanes at once. 1 when there is no pool, so lanes take turns on the one tab. */
+    parallel: number;
+    /** A person switched autonomous driving off. */
+    stopped(): boolean;
+    /**
+     * A person started this run and acknowledged the saved flows' destructive steps: replays take
+     * them. Never applied to a step the model decides.
+     */
+    confirmDangerous?: boolean;
+    /**
+     * Text the Harness wrote itself (the journey asked for, the plan's titles and goals): a page
+     * showing it back, as the saved plan's name on /plans, is not a journey's end reached.
+     */
+    own?: readonly string[];
+    /**
+     * Why the model may not drive a journey's fallback now (credits gone, Harness off), or undefined
+     * when it may. Asked only when a fallback is about to run: a plan that only replays never pays.
+     */
+    fallbackRefused?(): Promise<string | undefined>;
+}
+/** How one journey was answered, as the platform is told it. */
+export interface JourneyRun {
+    id: string;
+    /** Absent when it neither replayed nor drove: a guard stopped it first. */
+    by?: JourneyBy;
+    /** Model tokens the journey spent, cache reads and writes included; 0 for a pure replay. */
+    tokens: number;
+    /** Credits its model drives spent, when the platform said. */
+    credits?: number;
+    /** The flows it replayed or recorded. */
+    flows: string[];
+}
+export interface ScriptRun {
+    view: PlanView;
+    /** Every tool call the run made, in the order each lane made them. */
+    toolCalls: ToolOutcome[];
+    /** The model drives the open goals took. */
+    drives: HarnessResult[];
+    stopped: boolean;
+    /** One line per journey, for the drive's report. */
+    lines: string[];
+    /** Each journey that ran, once, however many lanes held it. */
+    journeys: JourneyRun[];
+}
+export declare function runScript(script: DriveScript, ports: ScriptPorts, onChange?: (view: PlanView) => void): Promise<ScriptRun>;
+/** The HUD's picture of a script before anything ran. */
+export declare function planView(script: DriveScript, parallel: number): PlanView;