@reticlehq/server 3.8.1 → 3.9.0

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

@@ -12,7 +12,7 @@
 import * as production from '../../portal/production/production-activation.js';
 import { z } from 'zod';
 import { leaseNotConnectedHint, leaseReaderFailedHint, leaseStillLoadingHint, } from './lease-hint.js';
-import { connectOrInject, moveReusedLease, notReadyReason, probeLeaseAlive, } from './lease-readiness.js';
+import { LEASE_READY_TIMEOUT_MS, awaitLeaseAnswering, connectOrInject, connectWaitUntil, moveReusedLease, notReadyReason, probeLeaseAlive, } from './lease-readiness.js';
 import { probeSdkMarker } from './gaps/sdk-marker-probe.js';
 import { observeWebDocument } from '../../portal/session/dev-server/served-document.js';
 import { diagnoseObservedWebCsp } from '@reticlehq/init';
@@ -25,7 +25,8 @@ import { LeaseNotReadyReason, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, SeedStora
 import { HudVisibility, ReticleTool, SESSION_HEALTH } from '@reticlehq/core';
 import { HOST_STUB_NOTE } from './tool-kit.js';
 import { PoolAtCapacityError } from '../../portal/pool/browser-pool.js';
-import { asString } from '@reticlehq/core';
+import { asNumber, asString } from '@reticlehq/core';
+import { timeoutMsSchema } from './args/numeric-bounds.js';
 import { chromiumPreflightRefusal } from '../../command/cli/doctor/browser/chromium-hint.js';
 import { LEASE_PERMISSIONS_ARG, hintOf, notificationReadBack, parseLeasePermissions, permissionRefusal, refuseRegrant, } from './lease-permissions.js';
 import { LEASE_EMULATE_ARG, leaseEmulationOf } from '../../portal/input/viewport-tools.js';
@@ -90,7 +91,7 @@ function alreadyHeldHint(sessionId, origin) {
     return (`${ALREADY_HELD_LEASE} (${origin}): ${sessionId} — reused it rather than opening a second ` +
         'tab, which would make every later call require sessionId. It is still signed in as whoever ' +
         'used it last (cookies and storage come with it): release it first for a fresh context or ' +
-        'another identity.');
+        'another identity, or pass fresh: true to open a separate tab and keep this one.');
 }
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
@@ -259,6 +260,10 @@ export const LEASE_ACQUIRE_TOOL = {
             .optional()
             .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
         seedStorage: SeedStorageSchema.optional().describe('Initial storage state (local, session and cookies) to seed before the first navigation (e.g. `seedStorage: { local: { token: "..." } }` to start already authenticated).'),
+        fresh: z
+            .boolean()
+            .optional()
+            .describe('Open a separate tab even when this connection already holds a lease on the origin, and keep that one. For parallel work that shares one MCP connection (sub-agents). Pass the returned sessionId to every later call.'),
         initScript: z
             .string()
             .optional()
@@ -278,6 +283,9 @@ export const LEASE_ACQUIRE_TOOL = {
         permissions: LEASE_PERMISSIONS_ARG,
         emulate: LEASE_EMULATE_ARG,
         production: production.PRODUCTION_LEASE_ARG,
+        timeout_ms: timeoutMsSchema
+            .optional()
+            .describe(`How long to wait for the leased tab to connect and answer before answering ready:false with notReadyReason. Default ${String(LEASE_READY_TIMEOUT_MS)}. 0 looks once without waiting.`),
         root: z
             .string()
             .optional()
@@ -288,7 +296,7 @@ export const LEASE_ACQUIRE_TOOL = {
         url: z.string(),
         ready: z
             .boolean()
-            .describe('Whether the leased tab is connected AND answering. It is NOT a claim that the app has hydrated, so an act can miss: make the first act reticle_act_and_wait with an `until`, or reticle_assert { action: "wait" }. Empty reads may mean not hydrated. False ⇒ read notReadyReason.'),
+            .describe('Whether the leased tab is connected AND answered a probe under sessionId, so the next call finds it. acquire waits for this, up to timeout_ms. It is NOT a claim that the app has hydrated, so an act can miss: make the first act reticle_act_and_wait with an `until`, or reticle_assert { action: "wait" }. Empty reads may mean not hydrated. False ⇒ read notReadyReason.'),
         zeroInstall: z
             .boolean()
             .optional()
@@ -297,6 +305,10 @@ export const LEASE_ACQUIRE_TOOL = {
             .string()
             .optional()
             .describe('Present when this leased tab runs an init script stubbing the bindings a desktop shell injects. Verdicts on this lease are about the app with that stub, not about the real shell.'),
+        cspWidenedFor: z
+            .string()
+            .optional()
+            .describe("Present when the lease added this origin (the daemon's WebSocket) to the page CSP connect-src, so the zero-install reader can connect. The rest of the page CSP applies as the server sent it."),
         notReadyReason: z
             .enum([
             LeaseNotReadyReason.SDK_NEVER_DIALLED,
@@ -408,14 +420,17 @@ export const LEASE_ACQUIRE_TOOL = {
             // an init script has to exist before the page's own scripts run, which a loaded page cannot
             // do, and the resolve below then finds nothing and mints a fresh context with the stub. A
             // lease of the other kind is left alone, exactly as it is when a window was asked for.
-            const heldForStub = origin === undefined ? undefined : pool.leaseIdOnOrigin(origin, deps.attachId);
+            // `fresh` asks for a separate tab: the held one is neither reused nor released (#1932).
+            const fresh = true === args['fresh'];
+            const heldOn = (o) => fresh || o === undefined ? undefined : pool.leaseIdOnOrigin(o, deps.attachId);
+            const heldForStub = heldOn(origin);
             if (initScript !== undefined &&
                 heldForStub !== undefined &&
                 pool.isHeaded(heldForStub) === headed &&
                 pool.hostStubScript?.(heldForStub) !== initScript) {
                 await pool.release(heldForStub);
             }
-            const held = origin === undefined ? undefined : pool.leaseIdOnOrigin(origin, deps.attachId);
+            const held = heldOn(origin);
             const existing = held !== undefined && pool.isHeaded(held) === headed ? held : undefined;
             // A context's certificate setting is fixed when it is made, so an explicit request for the
             // other one cannot be answered by the held lease: handing it back would keep checks off after
@@ -475,6 +490,7 @@ export const LEASE_ACQUIRE_TOOL = {
                         // Asked of the pool, not remembered here: the stub was installed when THIS lease was
                         // minted, and the caller reusing it now may be seeing it for the first time.
                         ...(true === pool.stubInstalled?.(existing) ? { hostStub: HOST_STUB_NOTE } : {}),
+                        ...cspWidenedOf(pool, existing),
                         ...(alreadyOpen === undefined
                             ? {}
                             : { preferExisting: { sessionId: alreadyOpen, note: PREFER_EXISTING_NOTE } }),
@@ -526,12 +542,18 @@ export const LEASE_ACQUIRE_TOOL = {
             // Resolved rather than assumed: an app that names its own session registers under that name,
             // and the id we hand back has to be the one the agent can actually drive.
             let registeredId;
-            const waitStartedAt = Date.now();
-            const waited = await production.guardedForProduction(pool, lease, activated);
-            const { ready, zeroInstall, stillLoading, readerFailure } = await connectOrInject(waited, () => {
+            const isRegistered = () => {
                 registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
                 return registeredId !== undefined;
-            });
+            };
+            const waitStartedAt = deps.now();
+            const deadline = waitStartedAt + (asNumber(args['timeout_ms']) ?? LEASE_READY_TIMEOUT_MS);
+            const waited = await production.guardedForProduction(pool, lease, activated);
+            const { ready: connected, zeroInstall, stillLoading, readerFailure, } = await connectOrInject(waited, isRegistered, connectWaitUntil(deadline, deps.now));
+            // Connected is a row in the sessions map. Ready is a reply from it, so the next call works.
+            const answerReason = connected
+                ? await awaitLeaseAnswering(() => (isRegistered() ? deps.sessions.get(registeredId ?? lease.sessionId) : undefined), deadline, deps.now)
+                : undefined;
             // Tell the pool the other name this lease answers to. Every later touch and release arrives
             // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
             // without this the touches miss, the lease ages out despite continuous activity, and the
@@ -541,6 +563,7 @@ export const LEASE_ACQUIRE_TOOL = {
             }
             const effectiveSessionId = registeredId ?? lease.sessionId;
             const session = deps.sessions.get(effectiveSessionId);
+            const ready = connected && answerReason === undefined;
             if (validatedSeed !== undefined && session !== undefined) {
                 const failureReason = evaluateSeedPrecondition(url, session.url, validatedSeed, lease.navStatus);
                 if (failureReason !== undefined) {
@@ -552,18 +575,17 @@ export const LEASE_ACQUIRE_TOOL = {
             if (readerFailure === undefined) {
                 tellWatchers(deps, projectId, AGENT_DRIVING_ELSEWHERE);
             }
-            // ready means the SDK dialled in — not that contracts match. Carry the skew warning on acquire
+            // ready means the SDK answers — not that contracts match. Carry the skew warning on acquire
             // so the agent does not learn it only after a CDP tool invents a closed page (#688).
-            const mintReason = readerFailure?.reason ??
-                notReadyReason(ready, session, LeaseNotReadyReason.SDK_NEVER_DIALLED);
+            const mintReason = readerFailure?.reason ?? (connected ? answerReason : LeaseNotReadyReason.SDK_NEVER_DIALLED);
             const versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
             let notReadyHint;
-            if (!ready) {
+            if (!connected) {
                 if (readerFailure !== undefined) {
                     notReadyHint = leaseReaderFailedHint(url, readerFailure);
                 }
                 else if (true === stillLoading) {
-                    notReadyHint = leaseStillLoadingHint(url, Date.now() - waitStartedAt);
+                    notReadyHint = leaseStillLoadingHint(url, deps.now() - waitStartedAt);
                 }
                 else if (activated !== undefined) {
                     notReadyHint = production.notActivatedHint(url);
@@ -596,6 +618,7 @@ export const LEASE_ACQUIRE_TOOL = {
                 ...(versionSkew === undefined ? {} : { versionSkew }),
                 ...production.summary(activated),
                 ...(initScript === undefined ? {} : { hostStub: HOST_STUB_NOTE }),
+                ...cspWidenedOf(pool, lease.sessionId),
                 ...hintOf(notReadyHint, ready ? await notificationReadBack(pool, lease.sessionId, permissions) : undefined),
             };
         }
@@ -607,6 +630,11 @@ export const LEASE_ACQUIRE_TOOL = {
         }
     },
 };
+/** `cspWidenedFor` when the lease changed its page CSP: a change to the page is declared (#2016). */
+function cspWidenedOf(pool, leaseId) {
+    const origin = pool.cspWidenedFor?.(leaseId);
+    return origin === undefined ? {} : { cspWidenedFor: origin };
+}
 /** The whole not-connected diagnosis, gathered and worded. Split out so the acquire path stays flat. */
 async function notConnectedHint(deps, url, dialledUrl) {
     const bridgePort = deps.bridgePort ?? RETICLE_DEFAULT_PORT;

package/dist/surface/tools/real-input-attempt.js

@@ -19,7 +19,7 @@
  * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
  * frame.
  */
-import { ActionType, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { ActionType, clickInputProblem, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { boxCenter, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act/act-danger.js';
 import { assertNativeAllowed } from '../../portal/production/production-drive.js';
@@ -101,10 +101,12 @@ const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3
  * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
  */
 function expandUserPath(rawPath, home) {
-    if ('~' === rawPath)
+    if ('~' === rawPath) {
         return home;
-    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))
+    }
+    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\')) {
         return join(home, rawPath.slice(2));
+    }
     return rawPath;
 }
 /** True when `real` is inside `root` after both have been realpath'd / resolved. */
@@ -132,15 +134,18 @@ async function readUploadRoots(projectRoot, fs, home) {
     catch {
         return [];
     }
-    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed)) {
         return [];
+    }
     const listed = parsed['uploadRoots'];
-    if (!Array.isArray(listed))
+    if (!Array.isArray(listed)) {
         return [];
+    }
     const roots = [];
     for (const entry of listed) {
-        if ('string' !== typeof entry || 0 === entry.trim().length)
+        if ('string' !== typeof entry || 0 === entry.trim().length) {
             continue;
+        }
         roots.push(resolve(expandUserPath(entry.trim(), home)));
     }
     return roots;
@@ -191,11 +196,13 @@ async function resolveUploadPath(rawPath, projectRoot, fs, uploadRoots, home) {
 export async function rewriteUploadArgs(deps, action, innerArgs, 
 /** Injected for tests; production uses the process home directory. */
 home = homedir()) {
-    if (action !== ActionType.UPLOAD)
+    if (action !== ActionType.UPLOAD) {
         return innerArgs;
+    }
     const rawPath = asString(innerArgs['path']);
-    if (rawPath === undefined)
-        return innerArgs; // no path → browser handles as inline upload
+    if (rawPath === undefined) {
+        return innerArgs;
+    } // no path → browser handles as inline upload
     // Project root is one level above .reticle/
     const projectRoot = resolve(join(deps.reticleRoot, '..'));
     const uploadRoots = await readUploadRoots(projectRoot, deps.fs, home);
@@ -236,14 +243,17 @@ function synthetic(reason) {
 function performArgsOf(inner) {
     const performArgs = {};
     const value = asString(inner['value']);
-    if (value !== undefined)
+    if (value !== undefined) {
         performArgs.value = value;
+    }
     const text = asString(inner['text']);
-    if (text !== undefined)
+    if (text !== undefined) {
         performArgs.text = text;
+    }
     const key = asString(inner['key']);
-    if (key !== undefined)
+    if (key !== undefined) {
         performArgs.key = key;
+    }
     const modifiers = inner['modifiers'];
     if (Array.isArray(modifiers)) {
         performArgs.modifiers = modifiers.filter((m) => 'string' === typeof m);
@@ -251,9 +261,14 @@ function performArgsOf(inner) {
     // A held key is the whole point of a hold-to-confirm control, and the synthetic path has honoured
     // `holdMs` all along. Not forwarding it made the real keyboard the WEAKER of the two paths: it
     // drove the key instantly and reported a hold that never held.
+    const button = asString(inner['button']);
+    if (button !== undefined) {
+        performArgs.button = button;
+    }
     const holdMs = asNumber(inner['holdMs']);
-    if (holdMs !== undefined)
+    if (holdMs !== undefined) {
         performArgs.holdMs = holdMs;
+    }
     // `keys` and `code` are read but not forwarded: both are routed away by the caller — a multi-key
     // sequence and an explicit physical code have no driver spelling — so carrying them into the
     // provider would only invite it to guess at a gesture the caller did not ask for.
@@ -285,11 +300,13 @@ const ANCHOR_FIELDS = [
  */
 async function pressOnLease(deps, session, ref, inner) {
     const pool = deps.pool;
-    if (pool === undefined || !pool.hasKeyboard(session.id))
+    if (pool === undefined || !pool.hasKeyboard(session.id)) {
         return undefined;
+    }
     const unspellable = unspellablePressReason('', inner);
-    if (unspellable !== undefined)
+    if (unspellable !== undefined) {
         return synthetic(unspellable);
+    }
     // What the focused element is called, from the focus act's own report, so the saved step can
     // find it again: the real keyboard reports no element of its own.
     let anchor = {};
@@ -307,8 +324,9 @@ async function pressOnLease(deps, session, ref, inner) {
         }
     }
     const performed = await pool.pressLease(session.id, performArgsOf(inner));
-    if (performed?.performed !== true)
+    if (performed?.performed !== true) {
         return undefined;
+    }
     return {
         result: {
             ...anchor,
@@ -382,15 +400,17 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     if (box === undefined) {
         throw new Error(HOVER_NEEDS_POINTER_MSG);
     }
-    if (!inView)
+    if (!inView) {
         throw new Error(HOVER_OFF_VIEWPORT_MSG);
+    }
     if (providerReady && provider !== undefined) {
         try {
             const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
             // Hover always has a resolved box, so there is always a center to report: the provider's own
             // reading, or the box's if it reported none. Both are the same point, not a fabricated one.
-            if (performed.performed)
+            if (performed.performed) {
                 return hoverSucceeded(performed.center ?? boxCenter(box), scrolled);
+            }
         }
         catch {
             // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
@@ -428,8 +448,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if (provider === undefined) {
         if (action === ActionType.PRESS) {
             const leased = await pressOnLease(deps, session, ref, inner);
-            if (leased !== undefined)
+            if (leased !== undefined) {
                 return leased;
+            }
         }
         // Silent by default: with no provider EVERY action is synthetic, and a reason on all of them is
         // noise on the most-used tool in the product. But an agent that passed native:true asked a
@@ -441,11 +462,13 @@ export async function tryRealInput(deps, session, ref, action, args) {
     // one was asked for, instead of a different gesture being sent. See `unspellablePressReason`.
     if (action === ActionType.PRESS) {
         const unspellable = unspellablePressReason(ref, inner);
-        if (unspellable !== undefined)
+        if (unspellable !== undefined) {
             return synthetic(unspellable);
+        }
     }
-    if (!isRealInputAction(action))
-        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
+    if (!isRealInputAction(action)) {
+        return synthetic(InputModeReason.NOT_POINTER);
+    } // fill/type stay synthetic
     // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
     // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
     // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
@@ -453,6 +476,13 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && !askedForNative) {
         return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
     }
+    // The page refuses the same arguments on the synthetic path. A native click must not drop one.
+    if (action === ActionType.CLICK || action === ActionType.DBLCLICK) {
+        const problem = clickInputProblem(action, inner);
+        if (problem !== undefined) {
+            throw new Error(`cannot ${action}: ${problem}`);
+        }
+    }
     // Under version skew CDP is unusable while DOM tools still work (#688). Surface the skew sentence
     // rather than "page not correlated" / a silent provider-error fallback — those send the agent
     // hunting a dead context that is not dead.
@@ -466,15 +496,17 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if (action !== ActionType.PRESS && session.versionSkew !== undefined) {
         throw new Error(session.versionSkew);
     }
-    if (!(await provider.isAvailableFor(session.url)))
+    if (!(await provider.isAvailableFor(session.url))) {
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    }
     const performArgs = performArgsOf(inner);
     // A document key has no element of its own: skip INSPECT and the box entirely.
     if (action === ActionType.PRESS) {
         try {
             const performed = await provider.perform(session.url, action, PRESS_HAS_NO_BOX, performArgs);
-            if (!performed.performed)
+            if (!performed.performed) {
                 return synthetic(InputModeReason.PROVIDER_DECLINED);
+            }
             // No `center`: a key addresses focus, not a point. The placeholder's zero happened nowhere.
             //
             // `heldMs` IS forwarded, and it is the whole reason this object is not just the three fields
@@ -521,13 +553,15 @@ export async function tryRealInput(deps, session, ref, action, args) {
     let box = asBox(inspected);
     // A box outside the viewport after the reveal is a gesture that would land on nothing. The
     // synthetic path scrolls and hit-tests on its own, so it is the honest answer.
-    if (box === undefined || !source.inView)
+    if (box === undefined || !source.inView) {
         return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
+    }
     let toBox;
     if (action === ActionType.DRAG) {
         const toRef = asString(inner['toRef']);
-        if (toRef === undefined)
+        if (toRef === undefined) {
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+        }
         const target = await inspectRevealed(deps, session, toRef);
         const targetInspected = target.inspected;
         // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
@@ -549,12 +583,14 @@ export async function tryRealInput(deps, session, ref, action, args) {
             }
         }
     }
-    if (toBox !== undefined)
+    if (toBox !== undefined) {
         performArgs.toBox = toBox;
+    }
     try {
         const performed = await provider.perform(session.url, action, box, performArgs);
-        if (!performed.performed)
+        if (!performed.performed) {
             return synthetic(InputModeReason.PROVIDER_DECLINED);
+        }
         return {
             result: {
                 performed: true,
@@ -566,8 +602,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
         };
     }
     catch {
-        if (session.versionSkew !== undefined)
+        if (session.versionSkew !== undefined) {
             throw new Error(session.versionSkew);
+        }
         return {
             result: undefined,
             settled: false,
@@ -585,8 +622,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
  * A Proxy, not a copy: the session keeps private state its own methods read.
  */
 export function withLeaseKeyboard(deps, session) {
-    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true)
+    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true) {
         return session;
+    }
     const command = async (name, args = {}, timeoutMs) => {
         if (ReticleCommand.ACT === name && ActionType.PRESS === args['action']) {
             const ref = asString(args['ref']) ?? '';
@@ -600,8 +638,9 @@ export function withLeaseKeyboard(deps, session) {
     };
     return new Proxy(session, {
         get(target, key) {
-            if ('command' === key)
+            if ('command' === key) {
                 return command;
+            }
             const value = Reflect.get(target, key, target);
             return 'function' === typeof value
                 ? value.bind(target)

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 };
+}