@reticlehq/server 3.8.2 → 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/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/tool-kit.d.ts

@@ -96,6 +96,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 +308,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.

package/dist/surface/tools/tools.js

@@ -1,7 +1,7 @@
 import { TESTID_FOUND_UNDER_SCHEMA } from './query-hint-schema.js';
 import { z } from 'zod';
-import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, nextStepBesideLiveSessions, } from './empty-session-list.js';
-import { AttrNamesSchema, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, NEXT_STEP_FIELD, nextStepBesideLiveSessions, } from './empty-session-list.js';
+import { AttrNamesSchema, NearestTargetSchema, QueryBy, ReticleCommand, SnapshotMode, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { withSizeCost } from '../../portal/session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './read/snapshot-delta.js';
@@ -145,11 +145,12 @@ export const RAW_TOOLS = withCompactEnvelope([
             })));
             const sessions = await list();
             // An empty list is a dead end on its own; see empty-session-list.ts for what it carries.
-            if (0 === sessions.length)
+            if (0 === sessions.length) {
                 return emptySessionList(deps, sessions);
+            }
             // Another project's tab is up. This caller's project may still never have been wired.
             const nextStep = nextStepBesideLiveSessions(deps, sessions);
-            return nextStep === undefined ? { sessions } : { sessions, next_step: nextStep };
+            return nextStep === undefined ? { sessions } : { sessions, [NEXT_STEP_FIELD]: nextStep };
         },
     },
     {
@@ -284,7 +285,7 @@ export const RAW_TOOLS = withCompactEnvelope([
             name: z
                 .string()
                 .optional()
-                .describe('Accessible name filter — narrows results when `by` is role and the page has many elements of that role.'),
+                .describe('Exact accessible-name filter - narrows results when `by` is role and the page has many elements of that role. Matches the whole name; use `text` for a partial match.'),
             scope: z
                 .string()
                 .optional()
@@ -398,6 +399,10 @@ export const RAW_TOOLS = withCompactEnvelope([
                     .optional()
                     .describe('Present when a ROLE+NAME search missed and that role DOES carry a nearly-matching name — role+name is exact, so "Mesh" does not find "2 Mesh". Retry with one of these spellings; no snapshot needed.'),
                 testidFoundUnder: TESTID_FOUND_UNDER_SCHEMA,
+                nearest: z
+                    .array(NearestTargetSchema)
+                    .optional()
+                    .describe('Present when a search missed and the page has visible targets like the one asked for: up to 3, the asked role first, then by name similarity. Each has a ref to retry with. nameTruncated is true when the name was cut. Advice only, never a match.'),
             })
                 .optional()
                 .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
@@ -422,8 +427,9 @@ export const RAW_TOOLS = withCompactEnvelope([
             // Accept the predicate's named-field spelling too — see query-shape.ts.
             const args = normalizeQueryArgs(rawArgs);
             const empty = emptyQueryRefusal(args);
-            if (empty !== undefined)
+            if (empty !== undefined) {
                 return Promise.reject(empty);
+            }
             const session = deps.sessions.resolve(asString(args['sessionId']));
             return commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.QUERY, {
                 by: args['by'],
@@ -603,14 +609,17 @@ export const RETIRED_FROM_SURFACE = [
  * The browser counts what leanness passed over, so the tool can say which of the two it is.
  */
 function noteEmptyLeanTree(result, mode) {
-    if (SnapshotMode.INTERACTIVE !== mode)
+    if (SnapshotMode.INTERACTIVE !== mode) {
         return result;
+    }
     const row = asRecord(result);
-    if (0 !== asNumber(row['nodes']))
+    if (0 !== asNumber(row['nodes'])) {
         return result;
+    }
     const skipped = asNumber(row['leanSkipped']) ?? 0;
-    if (0 === skipped)
+    if (0 === skipped) {
         return result;
+    }
     return {
         ...row,
         note: `no element on this page carries an interactive ARIA role, so this mode found nothing — ` +
@@ -635,18 +644,22 @@ function noteEmptyLeanTree(result, mode) {
  * empty tree it replaces.
  */
 function noteHiddenPage(result, mode) {
-    if (SnapshotMode.STATUS === mode)
+    if (SnapshotMode.STATUS === mode) {
         return result;
+    }
     const row = asRecord(result);
-    if (0 !== asNumber(row['nodes']))
+    if (0 !== asNumber(row['nodes'])) {
         return result;
+    }
     // A note already there is the more specific one (leanness), and two explanations for one empty
     // tree is worse than the better of them alone.
-    if (row['note'] !== undefined)
+    if (row['note'] !== undefined) {
         return result;
+    }
     const skipped = asNumber(row['hiddenSkipped']) ?? 0;
-    if (0 === skipped)
+    if (0 === skipped) {
         return result;
+    }
     return {
         ...row,
         note: `this is NOT an empty page: ${String(skipped)} subtree(s) were skipped because their root ` +