@reticlehq/server 3.2.0 → 3.4.0

package/dist/features/exhaust/session-port.js

@@ -0,0 +1,102 @@
+/**
+ * A live session, as the explorer's port.
+ *
+ * The one hard part is that a full page load REPLACES the session: the SDK reconnects under the
+ * same id (sessionStorage keeps it) but as a new object, and a command in flight on the old one is
+ * rejected. So every call reads the CURRENT session, and anything that may have navigated waits for
+ * the successor before it answers — the same wait `navigate { reload }` does.
+ */
+import { ActionType, ReticleCommand, ReticleTool, SnapshotMode, asRecord, asString, } from '@reticlehq/core';
+import { RELOAD_RECONNECT_TIMEOUT_MS, waitForReconnect, } from '../../portal/session/session-reconnect.js';
+import { isSessionReplacedError } from '../../portal/session/facts/session-replaced.js';
+export function sessionPort(input) {
+    let current = input.start;
+    /** Wait for the document that replaced `before`. False when none arrived in time. */
+    const successor = async (before) => {
+        const back = await waitForReconnect({
+            current: () => input.sessions.get(before.id),
+            previous: before,
+            timeoutMs: RELOAD_RECONNECT_TIMEOUT_MS,
+            now: input.now,
+            sleep: input.sleep,
+        });
+        const next = input.sessions.get(before.id);
+        if (!back || next === undefined)
+            return false;
+        current = next;
+        return true;
+    };
+    const look = async () => {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                const res = await current.command(ReticleCommand.SNAPSHOT, {
+                    mode: SnapshotMode.INTERACTIVE,
+                });
+                const body = asRecord(res.result);
+                const route = asString(asRecord(body['status'])['route']);
+                return { tree: asString(body['tree']) ?? '', ...(route === undefined ? {} : { route }) };
+            }
+            catch (error) {
+                // A click that followed a real link leaves the next read on a dead document.
+                if (!isSessionReplacedError(error) || !(await successor(current)))
+                    break;
+            }
+        }
+        return { tree: '' };
+    };
+    return {
+        current: () => current,
+        look,
+        async reset() {
+            const before = current;
+            try {
+                const res = await before.command(ReticleCommand.NAVIGATE, { url: input.startUrl });
+                if (!res.ok)
+                    return false;
+            }
+            catch (error) {
+                if (!isSessionReplacedError(error))
+                    return false;
+            }
+            if (!(await successor(before)))
+                return false;
+            await input.sleep(input.settleMs);
+            return true;
+        },
+        async act(ref, action, value) {
+            const session = current;
+            const since = session.elapsed();
+            session.beginAction?.(ReticleTool.CRAWL, { ref, action });
+            let ok = false;
+            let replaced = false;
+            try {
+                const res = await session.command(ReticleCommand.ACT, {
+                    ref,
+                    action: 'fill' === action ? ActionType.FILL : ActionType.CLICK,
+                    args: value === undefined ? {} : { value },
+                });
+                ok = res.ok && false !== asRecord(res.result)['dispatched'];
+            }
+            catch (error) {
+                // Following a real link replaces the document mid-command: the click WORKED.
+                if (!isSessionReplacedError(error))
+                    throw error;
+                replaced = true;
+                ok = true;
+            }
+            finally {
+                session.finishAction?.();
+            }
+            await input.sleep(input.settleMs);
+            const events = session.eventsSince(since);
+            if (replaced && (await successor(session)))
+                return { ok, events: [...events, ...current.eventsSince(0)] };
+            return { ok, events };
+        },
+        ...(input.setMocks === undefined
+            ? {}
+            : {
+                mock: (rules) => input.setMocks?.(current.url, rules) ?? Promise.resolve(false),
+            }),
+    };
+}

package/dist/features/harness/drive-report.d.ts

@@ -61,13 +61,4 @@ export declare function replayedFlows(toolCalls: readonly ToolOutcome[]): {
 }[];
 /** Reduce the raw call log to the actions that actually drove the app. */
 export declare function drivenSteps(toolCalls: readonly ToolOutcome[]): DrivenStep[];
-/**
- * The account, as lines.
- *
- * Proved and not-proved are counted separately and both are stated, because the failure mode this
- * whole product exists to prevent is a reader taking "we did twelve things" for "twelve things
- * work". `unknown` is deliberately grouped under NOT proved and labelled as undecided evidence
- * rather than as a failure — it calls for a better check, not a code change, and collapsing the two
- * would send an agent to rewrite working code.
- */
 export declare function describeDrive(toolCalls: readonly ToolOutcome[], savedFlows: readonly string[]): string;

package/dist/features/harness/drive-report.js

@@ -134,6 +134,18 @@ export function drivenSteps(toolCalls) {
  * rather than as a failure — it calls for a better check, not a code change, and collapsing the two
  * would send an agent to rewrite working code.
  */
+/** The pages the drive's own snapshots reported, in order, each distinct page once. */
+function pagesReached(toolCalls) {
+    const pages = [];
+    for (const call of toolCalls) {
+        if (ReticleTool.SNAPSHOT !== call.name || call.isError)
+            continue;
+        const route = asString(asRecord(asRecord(call.result)['status'])['route']);
+        if (route !== undefined && !pages.includes(route))
+            pages.push(route);
+    }
+    return pages;
+}
 export function describeDrive(toolCalls, savedFlows) {
     const steps = drivenSteps(toolCalls);
     const replays = replayedFlows(toolCalls);
@@ -166,10 +178,16 @@ export function describeDrive(toolCalls, savedFlows) {
     const proved = steps.filter((step) => Verified.YES === step.verified);
     const failed = steps.filter((step) => Verified.NO === step.verified);
     const undecided = steps.filter((step) => Verified.YES !== step.verified && Verified.NO !== step.verified);
+    const pages = pagesReached(toolCalls);
     const lines = [
         ...(replayLine === undefined ? [] : [replayLine]),
         `Drove ${String(steps.length)} action(s): ${String(proved.length)} proved, ` +
             `${String(failed.length)} failed, ${String(undecided.length)} not decided.`,
+        // How DEEP it got. An action count reads the same for a checkout walked to its receipt and for
+        // eleven clicks on the home page; the pages reached are what tell them apart.
+        ...(0 === pages.length
+            ? []
+            : [`Reached ${String(pages.length)} page(s): ${pages.join(' → ')}.`]),
     ];
     for (const step of steps.slice(0, MAX_LISTED)) {
         const verdict = step.verified ?? 'nothing declared';

package/dist/features/harness/driver.js

@@ -11,7 +11,7 @@
  * purpose.
  */
 import { z } from 'zod';
-import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+import { ReticleEnv, platformCredentialFrom } from '@reticlehq/core';
 /**
  * The default driver model.
  *
@@ -91,13 +91,10 @@ export function harnessOptionsFromEnv(env) {
      *
      * An explicit `ANTHROPIC_API_KEY` still wins: someone who exported one meant it.
      */
-    const cloudKey = apiKeyFrom(env);
-    const cloudUrl = env[ReticleEnv.CLOUD_URL];
-    if (cloudKey === undefined || 0 === cloudKey.length)
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
-    if (cloudUrl === undefined || 0 === cloudUrl.length)
-        return undefined;
-    return withOptions(cloudKey, cloudUrl);
+    return withOptions(cloud.apiKey, cloud.url);
 }
 /** Build a driver backed by the Messages API. */
 export function harnessDriver(options) {

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

@@ -64,4 +64,10 @@ export declare function fillValues(deps: {
     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

@@ -135,6 +135,9 @@ async function generateOne(options, label, context) {
 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;

package/dist/features/harness/jev-driver.js

@@ -21,7 +21,7 @@
  * 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 { RETICLE_URL_PARAM, ReticleEnv, ReticleTool, apiKeyFrom, asRecord, parseInteractive, } from '@reticlehq/core';
+import { RETICLE_URL_PARAM, ReticleEnv, ReticleTool, platformCredentialFrom, asRecord, parseInteractive, } from '@reticlehq/core';
 import { FINISH_TOOL } from './harness.js';
 import { heuristicFillValue } from './fill-values.js';
 export const DEFAULT_JEV_MODEL = 'jev-latest';
@@ -55,12 +55,15 @@ const Tool = {
     RECORD: ReticleTool.RECORD,
     FLOW_SAVE: ReticleTool.FLOW_SAVE,
     FLOW_REPLAY: ReticleTool.FLOW_REPLAY,
+    NAVIGATE: ReticleTool.NAVIGATE,
     FINISH: FINISH_TOOL.name,
 };
 /** The synthetic option meaning "stop driving". Not a tool arg — a key in the choice set. */
 const FINISH_OPTION = 'finish';
 /** The synthetic option meaning "I cannot tell from this page; look again". */
 const RELOOK_OPTION = 'look_again';
+/** Back to the page before this one — a dead end used to end the whole drive where it stood. */
+const BACK_OPTION = 'go_back';
 /**
  * Tools the model may route to, beyond acting on a control.
  *
@@ -244,14 +247,11 @@ export function jevOptionsFromEnv(env) {
         };
     }
     // The ordinary path: the key the user minted on the platform, against the platform's own proxy.
-    // Reticle never ships a Jev key, so without a base URL to send it to this is not a usable driver.
-    const cloudKey = apiKeyFrom(env);
-    const cloudUrl = env[ReticleEnv.CLOUD_URL];
-    if (cloudKey === undefined || 0 === cloudKey.length)
+    // Reticle never ships a Jev key; the URL is the configured platform, else the hosted service.
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
-    if (cloudUrl === undefined || 0 === cloudUrl.length)
-        return undefined;
-    return { apiKey: cloudKey, baseUrl: cloudUrl };
+    return { apiKey: cloud.apiKey, baseUrl: cloud.url };
 }
 /** Strip the snapshot's list marker, so a description reads as a phrase rather than a bullet. */
 function cleanDesc(desc) {
@@ -287,6 +287,8 @@ function readState(history) {
         saved: [],
         tree: undefined,
         route: undefined,
+        pages: [],
+        proved: [],
         replayed: [],
         acted: [],
         blocked: [],
@@ -333,13 +335,22 @@ function readState(history) {
                 if ('string' === typeof tree)
                     state.tree = tree;
                 const route = asRecord(result['status'])['route'];
-                if ('string' === typeof route)
+                if ('string' === typeof route) {
                     state.route = appRoute(route);
+                    if (state.pages.at(-1) !== route)
+                        state.pages.push(route);
+                }
             }
+            if (Tool.NAVIGATE === outcome.name)
+                state.tree = undefined;
             if (Tool.ACT_AND_WAIT === outcome.name) {
                 const ref = asRecord(outcome.args)['ref'];
                 const failure = asRecord(outcome.result)['error'];
                 const refused = outcome.isError && 'string' === typeof failure && failure.includes(DANGEROUS_ARG);
+                const until = asRecord(asRecord(outcome.args)['until']);
+                const signal = until['name'];
+                if ('yes' === asRecord(outcome.result)['verified'] && 'string' === typeof signal)
+                    state.proved.push(signal);
                 if ('string' === typeof ref) {
                     // A refused act never happened, so it is not something this drive has driven. Recording
                     // it as driven would retire the control after an attempt that never reached the app.
@@ -496,12 +507,10 @@ export function jevDriver(options) {
             const unsaved = drive.unsaved[0];
             if (unsaved !== undefined)
                 return only(
-                // `intent` is not decoration. A flow saved without one still replays, but when it goes
-                // red the report can only name the step that broke, not the thing that stopped being true.
-                request(Tool.FLOW_SAVE, {
-                    flowName: unsaved,
-                    intent: `Autonomous coverage drive of ${slugAfter(unsaved)}: ${String(drive.acted.length)} actions.`,
-                }), `save ${unsaved}`);
+                // No intent. A drive has no business rule of its own to state, and what it used to send
+                // ("Autonomous coverage drive: N actions") was a count of what it did, filed in the ledger
+                // as a rule and re-amended every time the count changed.
+                request(Tool.FLOW_SAVE, { flowName: unsaved }), `save ${unsaved}`);
             /*
              * THE PLAN'S CHEAP HALF, and it runs before the model is asked anything.
              *
@@ -552,7 +561,7 @@ export function jevDriver(options) {
             // ── the one real decision ────────────────────────────────────────────────────────────────
             // What the drive is currently for: the first plan step that is not a replay. Replays are all
             // done by the time we reach here, so whatever is left is the intent nobody has proved.
-            const objective = plan.find((step) => PLAN_REPLAY !== step.kind);
+            const objective = plan.find((step) => PLAN_REPLAY !== step.kind && !drive.proved.includes(step.target));
             const candidates = candidatesFrom(drive.tree);
             /**
              * A page with nothing to act on ends the DRIVE, not just the journey.
@@ -569,11 +578,15 @@ export function jevDriver(options) {
                 return only(request(Tool.RECORD, { action: 'stop', recordingName: drive.open.name }), 'nothing interactive on this page; wind up');
             }
             const criteria = {
-                [FINISH_OPTION]: 'Stop driving: the app has been covered, or nothing here leads anywhere new.',
+                [FINISH_OPTION]: 'Stop driving: every journey started here reached its end state, or nothing leads anywhere new.',
                 [RELOOK_OPTION]: 'Look at the page again without acting, because this reading looks incomplete.',
                 [OBSERVE_OPTION]: 'Read what the application DID since the last action — the requests it made and what it logged. Choose this when something was driven and it is not yet clear whether it worked.',
                 [STATE_OPTION]: "Read the application's own state, which is the strongest evidence there is and the one thing a screen cannot fake.",
             };
+            const previous = drive.pages.at(-2);
+            if (previous !== undefined)
+                criteria[BACK_OPTION] =
+                    `Go back to ${previous}: this page is a dead end, or a journey started there is not finished.`;
             for (const candidate of candidates) {
                 const verb = actionFor(candidate.role);
                 const already = drive.acted.includes(candidate.ref) ? ' (already driven once)' : '';
@@ -582,12 +595,12 @@ export function jevDriver(options) {
             const response = await callJev({ apiKey: options.apiKey, model, baseUrl, path, doFetch }, buildState(input.system, input.history, drive, objective), {
                 next_action: {
                     type: 'choice',
-                    instructions: 'Which single action best advances coverage of this application right now? Prefer a control that completes a real user journey, and prefer something not already driven.',
+                    instructions: 'Which single action carries the current user journey forward toward its END state — a submitted form, a saved record, a confirmation? Finish the journey this page started before opening a new one; prefer something not already driven only once it is finished.',
                     criteria,
                 },
                 journey_complete: {
                     type: 'noul',
-                    instructions: 'The application has been meaningfully covered by the actions driven so far, and further clicking would add nothing.',
+                    instructions: 'Every journey started so far has been carried to its end state and checked there, and further driving would add nothing.',
                 },
             });
             const usage = {
@@ -604,6 +617,8 @@ export function jevDriver(options) {
             }
             if (RELOOK_OPTION === chosen)
                 return only(request(Tool.SNAPSHOT, { mode: 'interactive' }), 'look again', usage);
+            if (BACK_OPTION === chosen && previous !== undefined)
+                return only(request(Tool.NAVIGATE, { url: previous }), `back to ${previous}`, usage);
             // Routing to a READ rather than an action. Neither changes the app, so neither is recorded as
             // something driven — they are how the drive finds out whether what it drove worked.
             if (OBSERVE_OPTION === chosen)
@@ -640,9 +655,8 @@ export function jevDriver(options) {
                 ref: picked.ref,
                 action,
                 ...(wasRefused ? { args: { [DANGEROUS_ARG]: true } } : {}),
-                // The element's own description, so the drive reads back as a journey rather than as refs.
-                // A ref is a handle that expired when the page changed; this survives being read tomorrow.
-                intent: `${action} ${picked.desc}`,
+                // No `intent`: "click button \"Save\"" describes a step, not a rule, and the ledger refuses it.
+                // The recorded step keeps the element's role and name, which is what reads back as a journey.
                 ...(consequence === undefined ? {} : { until: consequence.predicate }),
             };
             if ('fill' === action) {

package/dist/features/harness/openai-driver.js

@@ -17,7 +17,7 @@
  * it is reported below so the number is visible rather than assumed.
  */
 import { z } from 'zod';
-import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+import { ReticleEnv, platformCredentialFrom } from '@reticlehq/core';
 /**
  * The default model.
  *
@@ -71,13 +71,10 @@ export function openAiOptionsFromEnv(env) {
     const direct = env[ReticleEnv.HARNESS_OPENAI_KEY];
     if (direct !== undefined && 0 < direct.length)
         return withModel({ apiKey: direct });
-    const cloudKey = apiKeyFrom(env);
-    const cloudUrl = env[ReticleEnv.CLOUD_URL];
-    if (cloudKey === undefined || 0 === cloudKey.length)
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
-    if (cloudUrl === undefined || 0 === cloudUrl.length)
-        return undefined;
-    return withModel({ apiKey: cloudKey, baseUrl: cloudUrl });
+    return withModel({ apiKey: cloud.apiKey, baseUrl: cloud.url });
 }
 function toWireTool(tool) {
     return {

package/dist/features/harness/platform-config.d.ts

@@ -30,6 +30,16 @@ export interface PlatformModelConfig {
      * report "you turned this off" to somebody whose free months quietly ran out.
      */
     harnessEntitled: boolean;
+    /**
+     * Whether the platform actually holds a key for the provider this project is pointed at.
+     *
+     * Entitlement and readiness are different facts and the HUD needs both. A workspace can be fully
+     * entitled -- claimed period, `harnessEnabled` on -- against a deployment that has no provider key
+     * configured, and every signal then reads healthy while a drive cannot run. Absent reads as READY,
+     * on the same rule as the two booleans above: an older API that does not report availability must
+     * not have its silence treated as a refusal.
+     */
+    providerReady: boolean;
 }
 /** A GET, narrowed to what this file uses, so a test can answer it without a network. */
 export type ConfigFetch = (url: string, init: {

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

@@ -16,7 +16,7 @@
  *   - 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 { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+import { platformCredentialFrom } from '@reticlehq/core';
 const CONFIG_PATH = '/v1/model/config';
 /**
  * How long the daemon will wait for a preference before driving without it.
@@ -41,10 +41,18 @@ function parse(body) {
         // Same rule for both, for the same reason: an older API that reports neither must not have its
         // silence read as a refusal.
         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
+        // about whether THIS one can drive.
+        const available = record['available'];
+        const ready = 'object' === typeof available && null !== available
+            ? available[provider]
+            : undefined;
         return {
             provider,
             harnessEnabled: 'boolean' === typeof enabled ? enabled : true,
             harnessEntitled: 'boolean' === typeof entitled ? entitled : true,
+            providerReady: 'boolean' === typeof ready ? ready : true,
         };
     }
     catch {
@@ -60,12 +68,11 @@ function parse(body) {
  * warning printed on a path that then works correctly is how people learn to ignore stderr.
  */
 export async function fetchPlatformConfig(env, doFetch = (url, init) => fetch(url, init), timeoutMs = TIMEOUT_MS) {
-    const key = apiKeyFrom(env);
-    const host = env[ReticleEnv.CLOUD_URL];
-    if (key === undefined || 0 === key.length)
-        return undefined;
-    if (host === undefined || 0 === host.length)
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
+    const key = cloud.apiKey;
+    const host = cloud.url;
     const controller = new AbortController();
     const timer = setTimeout(() => {
         controller.abort();

package/dist/index.d.ts

@@ -15,13 +15,22 @@ export type { ToolDeps, ToolDef } from './surface/tools/tools.js';
 export { createToolInvoker, UNKNOWN_TOOL_ERROR } from './surface/tools/tool-invoker.js';
 export { runTool, SESSION_BOUND_TOOLS, SESSION_EXEMPT_TOOLS } from './surface/tools/invoke-tool.js';
 export type { ToolInvoker } from './surface/tools/tool-invoker.js';
+/**
+ * The port-presence check the CLI commands (`drive`, `verify`, `status`, `doctor`, `kill`) all share,
+ * re-exported so a consumer embedding `start()` in its own process can refuse a taken port the same
+ * honest way instead of letting a raw `EADDRINUSE` stack out — the gap `@reticlehq/test`'s
+ * `bootSession()` had (reticlehq/reticle#1141): it called `start()` directly with no pre-flight probe.
+ */
+export { probePresence, describePresence, PortPresence, } from './command/daemon/binding/port-presence.js';
+export { probeDaemon } from './surface/mcp/proxy/proxy-daemon-probe.js';
+export { fetchStatus } from './command/daemon/binding/daemon-status-probe.js';
 export { BaselineStore, normalizeLines, diffLines } from './memory/project/baselines.js';
 export { RecordingStore } from './language/flows/recording/tape/recordings.js';
 export type { RecordedStep, CompiledProgram } from './language/flows/recording/tape/recordings.js';
 export { FlowStore, recordedStepToFlowStep } from './language/flows/flows.js';
 export type { FlowResult } from './language/flows/flows.js';
 export type { Clock } from './machine/clock.js';
-export { assertSuccess, successToPredicate, dynamicTestids, successLabel, } from './language/flows/flow-success.js';
+export { assertSuccess, dynamicTestids, successLabel, successToPredicate, } from './language/flows/flow-success.js';
 export { classifyFlowAssertions, FlowAssertionGrade } from './language/flows/flow-classify.js';
 export type { FlowAssertionClassification } from './language/flows/flow-classify.js';
 export { buildDomainModel } from './judgement/domain/domain-model.js';