@reticlehq/server 3.6.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
@@ -55,13 +118,30 @@ function parse(body) {
         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 } }
+                ? {
+                    credits: {
+                        used,
+                        limit,
+                        ...(kind === undefined ? {} : { kind }),
+                        ...(endsAt === undefined ? {} : { endsAt }),
+                    },
+                }
                 : {}),
         };
     }
@@ -83,6 +163,7 @@ 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();
@@ -91,7 +172,11 @@ export async function fetchPlatformConfig(env, doFetch = (url, init) => fetch(ur
         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)

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/script-run.d.ts

@@ -9,7 +9,7 @@
  * are started in order, so whatever is waited on has already started.
  */
 import { type PlanView } from '@reticlehq/core';
-import { type DriveScript } from '@reticlehq/core/artifacts';
+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. */
@@ -25,6 +25,33 @@ export interface ScriptPorts {
     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;
@@ -35,6 +62,8 @@ export interface ScriptRun {
     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. */