@reticlehq/server 3.8.2 → 3.10.0

package/dist/surface/tools/repeat-hint.d.ts

@@ -0,0 +1,40 @@
+/** The call in a streak that gets the hint. Two calls can be a deliberate retry; three is a loop. */
+export declare const REPEAT_HINT_AT = 3;
+export declare const RepeatHint: {
+    readonly NO_MATCH: string;
+    /** A no_match whose refusal listed the nearest targets: the retry is one of those refs. */
+    readonly noMatchNearest: (ref: string) => string;
+    readonly LOOK_SAME: string;
+    readonly RECOVERY: string;
+    readonly SAME: `You made this call ${string} times in a row with the same result.`;
+    /** A verdict repeated: name its own reason, the only thing the result says about why. */
+    readonly verdict: (verified: string, because: string | undefined) => string;
+};
+/** What a call came back with, as far as a repeat is concerned: an identity and the line to say. */
+export interface RepeatOutcome {
+    readonly id: string;
+    readonly hint: string;
+}
+/** The outcome of a call that threw: its refusal reason. */
+export declare function outcomeOfError(error: unknown): RepeatOutcome;
+/** The outcome of a call that answered: its refusal reason, its verdict, or its whole answer. */
+export declare function outcomeOfResult(tool: string, result: unknown): RepeatOutcome;
+/** Tests only. */
+export declare function resetRepeatHints(): void;
+/**
+ * Note one call of one connection, and answer the hint when this call is the third in a streak.
+ * `owner` is the agent connection; undefined (the Harness, the HUD, an embedding) is never counted.
+ */
+export declare function noteRepeat(owner: string | undefined, tool: string, args: Record<string, unknown>, outcome: RepeatOutcome): string | undefined;
+/**
+ * Run one call of one connection inside its repeat streak. Answers the result and, on the third
+ * identical call, the hint. A call that throws keeps its hint beside the error (`withRepeatHint`).
+ */
+export declare function inRepeatStreak(owner: string | undefined, tool: string, args: Record<string, unknown>, run: () => Promise<unknown>): Promise<{
+    raw: unknown;
+    hint: string | undefined;
+}>;
+/** The answer with the hint beside it. Extra text only: the verdict and every field stay as they are. */
+export declare function withHintOn(answer: unknown, hint: string | undefined): unknown;
+/** The error payload with the hint its call earned, if any. */
+export declare function withRepeatHint<T extends object>(payload: T, error: unknown): T;

package/dist/surface/tools/repeat-hint.js

@@ -0,0 +1,171 @@
+/**
+ * One hint when an agent makes the same call, with the same result, for the third time in a row.
+ *
+ * Agents in the field made the same call five times or more in a row. Each answer was the same, and
+ * nothing in it said so. This module remembers the LAST call of each agent connection and gives one
+ * line, on the third identical call, that says what to try instead.
+ *
+ * Advice only: it reads a result that is already decided and never changes or blocks it. A hint says
+ * only what the result supports. When there is nothing specific to say, it says that the call was
+ * repeated with the same result.
+ */
+import { createHash } from 'node:crypto';
+import { RefusalReason, ReticleTool, isPlainRecord } from '@reticlehq/core';
+import { resultIsError } from '../mcp/faults/mcp-is-error.js';
+import { buildErrorPayload, codedRefusalOf, refusalReasonFor } from './error-recovery.js';
+import { EnvelopeKey } from './tool-kit.js';
+import { NEAREST_TARGETS_LEAD } from './act/resolve-target.js';
+/** The call in a streak that gets the hint. Two calls can be a deliberate retry; three is a loop. */
+export const REPEAT_HINT_AT = 3;
+const COUNT = String(REPEAT_HINT_AT);
+export const RepeatHint = {
+    NO_MATCH: `You made this call ${COUNT} times and each time no element matched. Do not send it again. ` +
+        'Take one reticle_look { action: "find" } and use a ref from its answer.',
+    /** A no_match whose refusal listed the nearest targets: the retry is one of those refs. */
+    noMatchNearest: (ref) => `You made this call ${COUNT} times and each time no element matched. Do not send it again. ` +
+        `The refusal lists the nearest targets. Pass one of their refs as \`ref\`, for example "${ref}".`,
+    LOOK_SAME: `You made this look ${COUNT} times and each answer was the same, so the page did not change. ` +
+        'Act on the page, or wait for a change with reticle_assert { action: "wait" }.',
+    RECOVERY: `You made this call ${COUNT} times and it was refused for the same reason each time. ` +
+        'Do the step in `recovery` before you send it again.',
+    SAME: `You made this call ${COUNT} times in a row with the same result.`,
+    /** A verdict repeated: name its own reason, the only thing the result says about why. */
+    verdict: (verified, because) => `You made this call ${COUNT} times and each verdict was "${verified}".` +
+        (because === undefined ? '' : ` Its reason: "${because}".`) +
+        ' The same call gives the same verdict. Change the target, the action or the `until`.',
+};
+/**
+ * Result keys that change from call to call when nothing else did: the dispatcher's own advisories,
+ * the screenshot path, and the clock. A key that is missed here only means no hint fires.
+ */
+const VOLATILE_KEYS = new Set([
+    ...Object.values(EnvelopeKey),
+    'cursor',
+    'since',
+    'at',
+    'ms',
+    'elapsedMs',
+    'durationMs',
+]);
+/** The same JSON for the same value, whatever the key order. */
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableJson).join(',')}]`;
+    }
+    if (isPlainRecord(value)) {
+        const keys = Object.keys(value)
+            .filter((key) => value[key] !== undefined)
+            .sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'undefined';
+}
+/** A short digest, so a connection keeps a few bytes and not a whole page tree. */
+function digest(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/** The first ref in a no_match refusal's nearest-target list, or undefined when it has no list. */
+function firstNearestRef(message) {
+    const at = message.indexOf(NEAREST_TARGETS_LEAD);
+    if (-1 === at) {
+        return undefined;
+    }
+    return /^(\S+) \(/.exec(message.slice(at + NEAREST_TARGETS_LEAD.length))?.[1];
+}
+function refusal(reason, recovery, message) {
+    const id = `refused:${reason}`;
+    if (RefusalReason.NO_MATCH === reason) {
+        const ref = firstNearestRef(message);
+        return { id, hint: ref === undefined ? RepeatHint.NO_MATCH : RepeatHint.noMatchNearest(ref) };
+    }
+    return { id, hint: 'string' === typeof recovery ? RepeatHint.RECOVERY : RepeatHint.SAME };
+}
+/** The outcome of a call that threw: its refusal reason. */
+export function outcomeOfError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const coded = codedRefusalOf(error);
+    return refusal(refusalReasonFor(message, coded), buildErrorPayload(message, coded).recovery, message);
+}
+/** The outcome of a call that answered: its refusal reason, its verdict, or its whole answer. */
+export function outcomeOfResult(tool, result) {
+    if (!isPlainRecord(result)) {
+        return { id: `value:${digest(stableJson(result))}`, hint: RepeatHint.SAME };
+    }
+    if (resultIsError(result)) {
+        const message = String(result['error']);
+        return refusal(refusalReasonFor(message), result['recovery'], message);
+    }
+    if ('verified' in result) {
+        const verified = String(result['verified']);
+        const because = 'string' === typeof result['because'] ? result['because'] : undefined;
+        return {
+            id: `verdict:${verified}:${because ?? ''}`,
+            hint: RepeatHint.verdict(verified, because),
+        };
+    }
+    const kept = Object.fromEntries(Object.entries(result).filter(([key]) => !VOLATILE_KEYS.has(key)));
+    return {
+        id: `answer:${digest(stableJson(kept))}`,
+        hint: ReticleTool.LOOK === tool ? RepeatHint.LOOK_SAME : RepeatHint.SAME,
+    };
+}
+/** Bound on remembered connections: a daemon outlives them. Each keeps only its last call. */
+const MAX_CONNECTIONS = 500;
+const lastByConnection = new Map();
+/** Tests only. */
+export function resetRepeatHints() {
+    lastByConnection.clear();
+}
+/**
+ * Note one call of one connection, and answer the hint when this call is the third in a streak.
+ * `owner` is the agent connection; undefined (the Harness, the HUD, an embedding) is never counted.
+ */
+export function noteRepeat(owner, tool, args, outcome) {
+    if (owner === undefined) {
+        return undefined;
+    }
+    const call = digest(`${tool}:${stableJson(args)}`);
+    const last = lastByConnection.get(owner);
+    const count = last?.call === call && last.outcome === outcome.id ? last.count + 1 : 1;
+    // Delete first, so the map order is last use and the oldest connection is the one that goes.
+    lastByConnection.delete(owner);
+    if (lastByConnection.size >= MAX_CONNECTIONS) {
+        const oldest = lastByConnection.keys().next().value;
+        if (oldest !== undefined) {
+            lastByConnection.delete(oldest);
+        }
+    }
+    lastByConnection.set(owner, { call, outcome: outcome.id, count });
+    return REPEAT_HINT_AT === count ? outcome.hint : undefined;
+}
+/** Hints for calls that threw, kept beside the error so the boundary that answers can read them. */
+const hintByError = new WeakMap();
+/**
+ * Run one call of one connection inside its repeat streak. Answers the result and, on the third
+ * identical call, the hint. A call that throws keeps its hint beside the error (`withRepeatHint`).
+ */
+export async function inRepeatStreak(owner, tool, args, run) {
+    let raw;
+    try {
+        raw = await run();
+    }
+    catch (error) {
+        const hint = noteRepeat(owner, tool, args, outcomeOfError(error));
+        if (hint !== undefined && 'object' === typeof error && null !== error) {
+            hintByError.set(error, hint);
+        }
+        throw error;
+    }
+    return { raw, hint: noteRepeat(owner, tool, args, outcomeOfResult(tool, raw)) };
+}
+/** The answer with the hint beside it. Extra text only: the verdict and every field stay as they are. */
+export function withHintOn(answer, hint) {
+    return hint !== undefined && isPlainRecord(answer)
+        ? { ...answer, [EnvelopeKey.REPEAT_HINT]: hint }
+        : answer;
+}
+/** The error payload with the hint its call earned, if any. */
+export function withRepeatHint(payload, error) {
+    const hint = 'object' === typeof error && null !== error ? hintByError.get(error) : undefined;
+    return hint === undefined ? payload : { ...payload, [EnvelopeKey.REPEAT_HINT]: hint };
+}

package/dist/surface/tools/run-report.d.ts

@@ -14,8 +14,8 @@ export declare function renderRunReport(report: RunReport): string;
 export declare function endsRun(tool: string, args: Record<string, unknown>): boolean;
 /** What an answer says the run saved or read. An answer that refused counts for nothing. */
 export declare function noteToolResult(ledger: RunLedger, tool: string, args: Record<string, unknown>, result: unknown): void;
-/** The report as an answer field, or no field when the ledger holds no run. Empties the ledger. */
-export declare function runReportField(ledger: RunLedger, root: string | undefined, env: Record<string, string | undefined>, now: number): Partial<Record<typeof RUN_REPORT_FIELD, {
+/** The owner's report as an answer field, or no field when the owner has no run. Ends that run. */
+export declare function runReportField(ledger: RunLedger, root: string | undefined, env: Record<string, string | undefined>, now: number, owner?: string): Partial<Record<typeof RUN_REPORT_FIELD, {
     report: RunReport;
     markdown: string;
     instruction: string;

package/dist/surface/tools/run-report.js

@@ -34,12 +34,15 @@ function headline(report) {
     const count = (v) => all.filter((each) => v === each).length;
     const total = all.length;
     const word = `${HEAD}${WORD[report.verified]}**${SEP}`;
-    if (0 === total)
+    if (0 === total) {
         return `${word}${Said.NOTHING_CHECKED}`;
-    if (Verified.NO === report.verified)
+    }
+    if (Verified.NO === report.verified) {
         return `${word}${String(count(Verified.NO))} of ${plural(total, 'check')} did not hold`;
-    if (Verified.YES === report.verified)
+    }
+    if (Verified.YES === report.verified) {
         return `${word}${String(total)} of ${plural(total, 'check')} held`;
+    }
     return `${word}${String(total - count(Verified.YES) - count(Verified.NO))} of ${plural(total, 'check')} undecided`;
 }
 /** The report as markdown: the verdict, each claim with its evidence, then what the run left. */
@@ -95,39 +98,48 @@ const INTENT_READS = new Set(['list', 'index', 'subject', 'get']);
 const isRecord = (value) => null !== value && 'object' === typeof value && !Array.isArray(value);
 /** What an answer says the run saved or read. An answer that refused counts for nothing. */
 export function noteToolResult(ledger, tool, args, result) {
-    if (!isRecord(result) || result['error'] !== undefined)
+    if (!isRecord(result) || result['error'] !== undefined) {
         return;
+    }
     if (ReticleTool.FLOW_SAVE === tool || ReticleTool.FLOW_SAVE_RECORDED === tool) {
         const name = result['name'];
-        if ('string' === typeof name)
+        if ('string' === typeof name) {
             ledger.flowSaved(name);
+        }
         return;
     }
     const action = asString(args['action']);
     if (ReticleTool.INTENT === tool) {
         // The intent ledger in `.reticle/intent/` is the memory an unlinked project has.
-        if (IntentWrite.RECORD === action)
+        if (IntentWrite.RECORD === action) {
             ledger.memoryWritten();
+        }
         const declared = args['intents'];
-        if (IntentWrite.DECLARE === action && Array.isArray(declared))
+        if (IntentWrite.DECLARE === action && Array.isArray(declared)) {
             ledger.memoryWritten(declared.length);
-        if (action !== undefined && INTENT_READS.has(action))
+        }
+        if (action !== undefined && INTENT_READS.has(action)) {
             ledger.memoryRead([JSON.stringify(result)]);
+        }
         return;
     }
-    if (ReticleTool.MEMORY !== tool)
+    if (ReticleTool.MEMORY !== tool) {
         return;
-    if ('add' === action && result['added'] !== undefined)
+    }
+    if ('add' === action && result['added'] !== undefined) {
         ledger.memoryWritten();
+    }
     const known = result['known'];
-    if (Array.isArray(known))
+    if (Array.isArray(known)) {
         ledger.memoryRead(known.map((entry) => JSON.stringify(entry)));
+    }
 }
-/** The report as an answer field, or no field when the ledger holds no run. Empties the ledger. */
-export function runReportField(ledger, root, env, now) {
-    if (ledger.isEmpty())
+/** The owner's report as an answer field, or no field when the owner has no run. Ends that run. */
+export function runReportField(ledger, root, env, now, owner) {
+    if (ledger.isEmpty(owner)) {
         return {};
-    const taken = ledger.take(now);
+    }
+    const taken = ledger.take(now, owner);
     const silenced = env[UPGRADE_HINT_SILENCE_ENV] !== undefined;
     const linked = root === undefined || linkedToPlatform(root, env);
     const report = silenced || linked ? taken : { ...taken, cloud: CLOUD_VALUE_LINE };

package/dist/surface/tools/session-ports.d.ts

@@ -55,3 +55,17 @@ export declare function suiteFixturePort(realInput: RealInputProvider | undefine
  * is the reach the boundary guard exists to ask about.
  */
 export declare function sessionMutationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<NetworkMutationPort | undefined>;
+/**
+ * The state a verify run started in, put back before each flow after the first.
+ *
+ * `reticle verify` replays every flow in ONE driven page. A flow that signs out (an auto-saved
+ * "log out" fragment, or a journey that ends on the logout link) left every later flow signed out,
+ * and each of them then failed for a reason none of them named. The leased suite path never had
+ * this: each flow boots its own context from one captured seed. This gives the single-page path
+ * the same start.
+ *
+ * Call it before each flow. It answers `undefined` to go on, or the reason the flow cannot start
+ * where the run started, which the caller reports as not proved. Nothing to capture (no driven
+ * page, no storage support) means the run goes on as before.
+ */
+export declare function flowStartState(provider: RealInputProvider | undefined, currentUrl: () => string | undefined): () => Promise<string | undefined>;

package/dist/surface/tools/session-ports.js

@@ -100,3 +100,56 @@ export async function sessionMutationPort(realInput, appUrl) {
         return undefined;
     }
 }
+/**
+ * The state a verify run started in, put back before each flow after the first.
+ *
+ * `reticle verify` replays every flow in ONE driven page. A flow that signs out (an auto-saved
+ * "log out" fragment, or a journey that ends on the logout link) left every later flow signed out,
+ * and each of them then failed for a reason none of them named. The leased suite path never had
+ * this: each flow boots its own context from one captured seed. This gives the single-page path
+ * the same start.
+ *
+ * Call it before each flow. It answers `undefined` to go on, or the reason the flow cannot start
+ * where the run started, which the caller reports as not proved. Nothing to capture (no driven
+ * page, no storage support) means the run goes on as before.
+ */
+export function flowStartState(provider, currentUrl) {
+    let first = true;
+    let saved;
+    return async () => {
+        const url = currentUrl();
+        if (first) {
+            first = false;
+            if (provider === undefined || url === undefined) {
+                return undefined;
+            }
+            try {
+                const port = await fixturePortFor(provider, url);
+                saved = port === undefined ? undefined : { state: await port.capture(), url };
+            }
+            catch {
+                saved = undefined;
+            }
+            return undefined;
+        }
+        if (saved === undefined || provider === undefined) {
+            return undefined;
+        }
+        try {
+            // Straight to the provider, not through `fixturePortFor`: its address check compares the
+            // session's recorded address with the page's, and a flow that reloaded or signed out leaves
+            // the two different while the page is the same. The provider still refuses a page it does
+            // not drive (it answers false), so nothing is restored into a stranger's page.
+            // Tabs first: a tab the previous flow opened is a second connected session otherwise.
+            await provider.closeOtherPages?.();
+            const restored = await provider.applyStorageState?.(url ?? saved.url, saved.state);
+            return true === restored
+                ? undefined
+                : 'could not put the page back in the state the run started with: no driven page matched';
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return `could not put the page back in the state the run started with: ${message}`;
+        }
+    };
+}

package/dist/surface/tools/tool-kit.d.ts

@@ -31,6 +31,12 @@ export interface ToolDeps<Ext = unknown> {
      * the fake-pool lease tests are deliberately runnable without a real Chromium.
      */
     browserProbe?: () => Promise<ChromiumProbe>;
+    /**
+     * Whether something on this loopback port accepted a connection. Asked only after a lease
+     * navigation timed out, to tell a dev server compiling its first route from no server (#2005).
+     * Optional: absent ⇒ the timeout keeps its generic advice.
+     */
+    portAccepts?: (port: number) => Promise<boolean>;
     baselines: BaselineStore;
     recordings: RecordingStore;
     /** on-disk anchored-flow store (.reticle/flows/). */
@@ -96,6 +102,11 @@ export interface ToolDeps<Ext = unknown> {
     } | undefined>;
     /** The one dev server running in the caller's project folder, for a lease that names no url. */
     projectAppUrl?: () => Promise<string | undefined>;
+    /**
+     * The first-session offer for this attach id's first call, when no app is attached and the
+     * project is not wired (see zero-install-first-call.ts). Absent: no offer.
+     */
+    firstSessionOffer?: (attachId: string) => string | undefined;
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */
@@ -303,10 +314,17 @@ export declare const EnvelopeKey: {
      * what it cannot see, and the command that wires the app for good. See zero-install-first-call.ts.
      */
     readonly ZERO_INSTALL: "zero_install";
+    /**
+     * Once per agent connection, on its first call: this unwired web app can be checked now with the
+     * lease, and `init` needs the user's consent. See zero-install-first-call.ts.
+     */
+    readonly FIRST_SESSION_OFFER: "first_session_offer";
     /** Once-per-session advisory lines an agent's own call carries. See agent/notices.ts. */
     readonly NOTICES: "notices";
     /** The end-of-run report, on the call that ends an agent's run. See run-report.ts. */
     readonly RUN_REPORT: "runReport";
+    /** On the third identical call with the same result: what to try instead. See repeat-hint.ts. */
+    readonly REPEAT_HINT: "repeatHint";
 };
 export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
 /**

package/dist/surface/tools/tool-kit.js

@@ -99,10 +99,17 @@ export const EnvelopeKey = {
      * what it cannot see, and the command that wires the app for good. See zero-install-first-call.ts.
      */
     ZERO_INSTALL: 'zero_install',
+    /**
+     * Once per agent connection, on its first call: this unwired web app can be checked now with the
+     * lease, and `init` needs the user's consent. See zero-install-first-call.ts.
+     */
+    FIRST_SESSION_OFFER: 'first_session_offer',
     /** Once-per-session advisory lines an agent's own call carries. See agent/notices.ts. */
     NOTICES: 'notices',
     /** The end-of-run report, on the call that ends an agent's run. See run-report.ts. */
     RUN_REPORT: RUN_REPORT_FIELD,
+    /** On the third identical call with the same result: what to try instead. See repeat-hint.ts. */
+    REPEAT_HINT: 'repeatHint',
 };
 /**
  * The sentence every session-bound result carries while its leased tab runs on a stubbed shell.
@@ -149,6 +156,8 @@ export const CDP_TOOLS = new Set([
     // Breaks a request through the same Playwright route `reticle_network_mock` uses, so it fails the
     // same way under version skew and must be refused with the same sentence.
     ReticleTool.FLOW_MUTATE,
+    // Reads JS coverage through the lease's Playwright page, the way `reticle_network_mock` reaches it.
+    ReticleTool.LEASE_COVERAGE,
 ]);
 /**
  * Tools whose result hands the agent refs. The tab they were minted in is remembered, so the call
@@ -164,7 +173,6 @@ export const REF_MINTING_TOOLS = new Set([
     // The same three merged, on the `merged` surface. Its `state` action mints nothing, and
     // over-inclusion is the safe direction here: the worst case is a refusal naming two tabs.
     ReticleTool.LOOK,
-    ReticleTool.EXPLORE,
     // `crawl` mints refs for the controls it drives and `coverage` for the ones it reports untouched.
     // Both are actions on the merged verify tool now.
     ReticleTool.VERIFY,
@@ -205,11 +213,9 @@ export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.ANIMATIONS,
     ReticleTool.BASELINE, // merged save/list/diff — save+diff are live reads
     ReticleTool.RECORD, // merged start/stop — both live
-    ReticleTool.REPLAY,
     ReticleTool.CLOCK,
     ReticleTool.STATE,
     ReticleTool.STORAGE,
-    ReticleTool.EXPLORE,
     ReticleTool.SCROLL_TO,
     ReticleTool.NAVIGATE,
 ]);

package/dist/surface/tools/tool-surface.js

@@ -473,7 +473,6 @@ const OPEN_WORLD = new Set([
     ReticleTool.NAVIGATE,
     ReticleTool.SESSION,
     ReticleTool.VERIFY,
-    ReticleTool.EXPLORE,
     ReticleTool.FEEDBACK,
     ReticleTool.RUN,
 ]);