@reticlehq/server 3.8.2 → 3.10.0

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

@@ -1,10 +1,10 @@
-import { carryReticleIdentity } from './lease-tools.js';
+import { carryReticleIdentity, LEASE_ACQUIRE_TOOL } from './lease-tools.js';
 import { z } from 'zod';
 import { navigateResult } from './act/navigation/navigate-result.js';
 import { absoluteTarget, awaitArrival, idsOpenAtDispatch, ARRIVAL_TIMEOUT_MS, } from './act/navigation/navigate-arrival.js';
-import { reloadResult } from './act/navigation/reload-result.js';
+import { HardReload, hardReloadOf, reloadResult } from './act/navigation/reload-result.js';
 import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS, } from '../../portal/session/session-reconnect.js';
-import { ReticleCommand } from '@reticlehq/core';
+import { NO_SESSION_CONNECTED_ERROR, ReticleCommand, SESSION_STARTED_NOTE, SessionStartedVia, relativeUrlNoSession, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { sessionIdShape, commandOrThrow } from './tool-kit.js';
@@ -17,8 +17,9 @@ const MSG_LEASE_WITHOUT_SDK = 'This page has no Reticle SDK, so only browser-lev
 async function navigateLease(deps, sessionId, url, args) {
     const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
     const went = (await deps.pool?.gotoLease(sessionId, url, timeoutMs)) ?? false;
-    if (!went)
+    if (!went) {
         return { ok: false, url, reason: 'the leased page did not navigate' };
+    }
     const back = await waitForSession(deps, sessionId, timeoutMs);
     return back
         ? { ok: true, url, confirmed: true, sessionId }
@@ -28,19 +29,74 @@ async function navigateLease(deps, sessionId, url, args) {
 async function waitForSession(deps, sessionId, timeoutMs) {
     const start = deps.now();
     for (;;) {
-        if (deps.sessions.get(sessionId) !== undefined)
+        if (deps.sessions.get(sessionId) !== undefined) {
             return true;
-        if (deps.now() - start >= timeoutMs)
+        }
+        if (deps.now() - start >= timeoutMs) {
             return false;
+        }
         await new Promise((resolve) => setTimeout(resolve, LEASE_POLL_MS));
     }
 }
 const LEASE_POLL_MS = 100;
+/** `sessionStarted` on the result. See `SessionStarted` in core. */
+const SessionStartedSchema = z.object({
+    sessionId: z.string(),
+    via: z.nativeEnum(SessionStartedVia),
+    zeroInstall: z.boolean().optional(),
+});
+/** The origin a relative-URL refusal names when the project app cannot be found. */
+const EXAMPLE_ORIGIN = 'http://localhost:3000';
+function isHttpUrl(url) {
+    try {
+        const { protocol } = new URL(url);
+        return 'http:' === protocol || 'https:' === protocol;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * No session, and an absolute URL: open a lease on it through the lease tool itself, so the same
+ * owner, browser preflight and production rules apply as on an explicit `reticle_lease` acquire.
+ */
+async function startSessionOn(deps, url) {
+    const leased = (await LEASE_ACQUIRE_TOOL.handler(deps, { url }));
+    const sessionStarted = {
+        sessionId: leased.sessionId,
+        via: SessionStartedVia.LEASE,
+        ...(true === leased.zeroInstall ? { zeroInstall: true } : {}),
+    };
+    const note = leased.hint === undefined ? SESSION_STARTED_NOTE : `${SESSION_STARTED_NOTE} ${leased.hint}`;
+    return {
+        ok: true,
+        url,
+        confirmed: leased.ready,
+        sessionId: leased.sessionId,
+        sessionStarted,
+        note,
+    };
+}
+/**
+ * No session, and a relative URL: nothing names the app. Keep the no-session refusal (and its
+ * diagnosis), and add the absolute form of the same path.
+ */
+async function refuseRelativeWithoutSession(deps, path) {
+    let message = NO_SESSION_CONNECTED_ERROR;
+    try {
+        deps.sessions.resolve();
+    }
+    catch (err) {
+        message = err instanceof Error ? err.message : String(err);
+    }
+    const origin = (await deps.projectAppUrl?.().catch(() => undefined)) ?? EXAMPLE_ORIGIN;
+    throw new Error(`${message}${relativeUrlNoSession(path, origin)}`);
+}
 export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
         example: { url: '/settings' },
-        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the old page cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect. `confirmed:true` with a `sessionId` means the requested page arrived and you can act immediately. `confirmed:false` with `landedOn` means the navigation arrived but the app landed at another URL, such as an authentication or route-guard redirect; use `landedOn` to understand where the browser actually ended up. `confirmed:false` without `landedOn` means the target was not observed within the wait window; a slow app may still be on its way, so increase `timeout_ms` when appropriate.',
+        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the old page cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect. `confirmed:true` with a `sessionId` means the requested page arrived and you can act immediately. `confirmed:false` with `landedOn` means the navigation arrived but the app landed at another URL, such as an authentication or route-guard redirect; use `landedOn` to understand where the browser actually ended up. `confirmed:false` without `landedOn` means the target was not observed within the wait window; a slow app may still be on its way, so increase `timeout_ms` when appropriate. With no session connected, an absolute URL opens a leased tab on it and the result carries `sessionStarted`.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
@@ -50,7 +106,7 @@ export const BROWSER_TOOLS = [
             hard: z
                 .boolean()
                 .optional()
-                .describe('With reload:true, bypass the browser cache (Cmd+Shift+R). Default: false.'),
+                .describe('With reload:true, bypass the browser cache (Cmd+Shift+R) on a leased tab. On a tab Reticle does not drive, only the document is fetched again; scripts and modules can still come from the cache. Default: false.'),
             timeout_ms: timeoutMsSchema
                 .optional()
                 .describe('How long to wait for the page to come back (the SDK reconnecting at the new URL, or under the same id on a reload) before answering confirmed:false. Default 5000. 0 looks once without waiting. An SPA reattaching under HMR has been measured at 30-60s — say so here instead of polling reticle_sessions.'),
@@ -74,7 +130,11 @@ export const BROWSER_TOOLS = [
              * of "Reticle stopped waiting" and "the page never came back" you are looking at.
              */
             waitedMs: z.number().optional(),
+            /** Present only when no session was connected and this call opened one on the URL. */
+            sessionStarted: SessionStartedSchema.optional(),
             note: z.string().optional(),
+            /** On a `hard` reload: whether the browser ignored its cache, or only the document was fetched again. */
+            hardReload: z.nativeEnum(HardReload).optional(),
         },
         handler: async (deps, args) => {
             // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
@@ -90,9 +150,13 @@ export const BROWSER_TOOLS = [
                 // coming back `contradicted` by hundreds of 500s against resources that were already gone.
                 before.lastAct.markNavigated(before.elapsed());
                 deps.recordings.markNavigated();
-                await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
-                    hard: true === args['hard'],
-                });
+                const hard = true === args['hard'];
+                // A leased tab reloads through the browser with the cache ignored. The page itself can only
+                // re-fetch its document: scripts and modules still come from the cache (#1785).
+                const throughBrowser = hard && true === (await deps.pool?.hardReloadLease(before.id));
+                if (!throughBrowser) {
+                    await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, { hard });
+                }
                 // WAIT for the page to come back, rather than telling the agent to. The id survives the
                 // reload, but the seconds between dispatch and the new HELLO are seconds in which every call
                 // lands in the old, disconnected session — measured as reticle_run failing 5 of 5 on a page
@@ -107,11 +171,12 @@ export const BROWSER_TOOLS = [
                 // Not a bare `{ ok: true }`. The URL branch below already discloses that `ok` means
                 // DISPATCHED — the reload branch had identical semantics and said nothing, on the path most
                 // likely to need it. See reload-result.
-                return reloadResult(back, timeoutMs);
+                return reloadResult(back, timeoutMs, hardReloadOf(hard, throughBrowser));
             }
             const requested = asString(args['url']);
-            if (requested === undefined || 0 === requested.length)
+            if (requested === undefined || 0 === requested.length) {
                 return { ok: false, reason: 'url required' };
+            }
             assertNotPaymentNavigation(requested);
             const named = asString(args['sessionId']);
             // A lease whose page has no SDK right now (it was navigated to an image, a PDF, another site):
@@ -123,6 +188,15 @@ export const BROWSER_TOOLS = [
                     return navigateLease(deps, named, carryReticleIdentity(leaseUrl, requested), args);
                 }
             }
+            // Nothing is connected at all, and the call named no tab. An absolute URL names the app, so
+            // open a lease on it instead of refusing. Several sessions, or one in another project, keep
+            // the refusal that resolve gives below: a lease there would guess.
+            if (named === undefined && 0 === deps.sessions.count()) {
+                if (isHttpUrl(requested)) {
+                    return startSessionOn(deps, requested);
+                }
+                return refuseRelativeWithoutSession(deps, requested);
+            }
             // Record navigate as an action. Its window is usually empty (the page unloads and the SDK
             // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
             const session = deps.sessions.resolve(asString(args['sessionId']));

package/dist/surface/tools/compare-tools.d.ts

@@ -0,0 +1,11 @@
+import { type CompareCommandOptions } from '../../command/cli/two-builds/compare-command.js';
+import type { ToolDef } from './tool-kit.js';
+type RunCompare = (options: CompareCommandOptions) => Promise<{
+    code: number;
+    lines: string[];
+}>;
+type Sleep = (ms: number) => Promise<void>;
+/** The compare tool. `run` and `sleep` are injected so a test needs no daemon. */
+export declare function compareTool(run?: RunCompare, sleep?: Sleep): ToolDef;
+export declare const COMPARE_TOOLS: ToolDef[];
+export {};

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

@@ -0,0 +1,94 @@
+/**
+ * `reticle_verify { action: "compare" }`: `reticle compare` for an agent whose tools are loaded.
+ *
+ * It runs the CLI's own compare (`runCompareCommand`) against this daemon, over the same loopback
+ * transport the CLI uses, so the answer is the `--json` object of `reticle compare` and nothing
+ * else. The leased tabs resolve their own project from the page, as every lease does. A compare takes minutes, longer than one tool call may wait, so within `wait` seconds it
+ * answers the result, or `{ status: "running", runId }` to poll with `runId`, as `explore` does.
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { RETICLE_DEFAULT_PORT, ReticleTool } from '@reticlehq/core';
+import { pairingToken, runCompareCommand, } from '../../command/cli/two-builds/compare-command.js';
+const RUN_PREFIX = 'compare-';
+const COMPARE_ACTION = 'compare';
+const RUNNING = 'running';
+/** Seconds one call waits for the result before it answers with a run id. */
+const DEFAULT_WAIT_S = 50;
+const MAX_WAIT_S = 240;
+const MS_PER_S = 1000;
+/** The most finished runs kept for polling. A run is read back once or twice, not for ever. */
+const KEPT_RUNS = 8;
+const MSG_NEEDS_URLS = 'compare needs `reference` and `candidate`, the urls of two running builds';
+const MSG_UNKNOWN_RUN = 'no compare run has the id';
+const asText = (value) => 'string' === typeof value && value.length > 0 ? value : undefined;
+/** The JSON object the CLI printed, or the line itself when it is not one. */
+function parsed(lines) {
+    const line = lines[0] ?? '';
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return { error: line };
+    }
+}
+/** The compare tool. `run` and `sleep` are injected so a test needs no daemon. */
+export function compareTool(run = runCompareCommand, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+    const runs = new Map();
+    const answer = async (runId, result, waitS) => {
+        const timedOut = Symbol(RUNNING);
+        const first = await Promise.race([result, sleep(waitS * MS_PER_S).then(() => timedOut)]);
+        if (first !== timedOut) {
+            return first;
+        }
+        return { status: RUNNING, runId, next: { action: COMPARE_ACTION, runId } };
+    };
+    return {
+        name: ReticleTool.VERIFY_COMPARE,
+        description: 'Drive two running builds of one app the same way (for example main and a pull request preview) and list each difference in what users see and in the requests and console errors the app made. Nothing is installed in the app. One opinionated recipe: plan every action on the reference, drive it on the reference two times and the candidate one time, and ignore what changes between the two reference runs. With `base`, each difference is tagged regression, target-missed or changed, with a score. Answers the JSON of `reticle compare --json`: `verified` yes (same), no (different) or unknown (the run proves nothing). Within `wait` seconds the result, or { status: "running", runId } to poll with `runId`. DESTRUCTIVE: it presses every button it finds.',
+        inputSchema: {
+            reference: z.string().optional().describe('URL of the build that is right, e.g. main.'),
+            candidate: z.string().optional().describe('URL of the build to check.'),
+            base: z.string().optional().describe('URL of the build before the change.'),
+            runId: z
+                .string()
+                .optional()
+                .describe('The run id a compare call answered with; pass it to poll that run.'),
+            wait: z.number().min(0).max(MAX_WAIT_S).optional().describe('Seconds; default 50.'),
+        },
+        handler: async (deps, args) => {
+            const waitS = 'number' === typeof args['wait'] ? args['wait'] : DEFAULT_WAIT_S;
+            const polled = asText(args['runId']);
+            if (polled !== undefined) {
+                const result = runs.get(polled);
+                if (result === undefined) {
+                    return { error: `${MSG_UNKNOWN_RUN} ${polled}` };
+                }
+                return answer(polled, result, waitS);
+            }
+            const reference = asText(args['reference']);
+            const candidate = asText(args['candidate']);
+            if (reference === undefined || candidate === undefined) {
+                return { error: MSG_NEEDS_URLS };
+            }
+            const base = asText(args['base']);
+            const token = pairingToken();
+            const runId = `${RUN_PREFIX}${randomUUID()}`;
+            const result = run({
+                reference,
+                candidate,
+                ...(base === undefined ? {} : { base }),
+                json: true,
+                port: deps.bridgePort ?? RETICLE_DEFAULT_PORT,
+                ...(token === undefined ? {} : { token }),
+            }).then((out) => parsed(out.lines));
+            runs.set(runId, result);
+            // ponytail: the oldest runs are dropped by count. Drop by age if a session polls very late.
+            for (const old of [...runs.keys()].slice(0, Math.max(0, runs.size - KEPT_RUNS))) {
+                runs.delete(old);
+            }
+            return answer(runId, result, waitS);
+        },
+    };
+}
+export const COMPARE_TOOLS = [compareTool()];

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

@@ -63,7 +63,7 @@ export function buildCoverageTools() {
                 app: z
                     .boolean()
                     .optional()
-                    .describe('Also fold into the app-wide ledger; returns `app.levels`.'),
+                    .describe('Also fold into the app-wide ledger; returns `app.levels`, `app.holes` and `app.findings`.'),
                 ...sessionIdShape,
             },
             outputSchema: {

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { runTool } from './invoke-tool.js';
 import { buildErrorPayload, codedRefusalOf } from './error-recovery.js';
+import { withRepeatHint } from './repeat-hint.js';
 import { mergedNameRedirect, mergedNameMessage, retiredToolNames } from './merged-name-redirect.js';
 import { CATALOGUE_SUMMARY_LENGTH, firstSentence } from './first-sentence.js';
 import { takeVersionSkewOnto } from '../../command/version/version-nudge.js';
@@ -309,10 +310,17 @@ callable) {
                     hint: `pass them inside args: reticle_run { tool, args: { ${strayTop.join(', ')}: … } } if the target tool declares them`,
                 };
             }
-            const name = 'string' === typeof args['tool'] ? args['tool'] : '';
-            const given = 'object' === typeof args['args'] && args['args'] !== null
+            const asked = 'string' === typeof args['tool'] ? args['tool'] : '';
+            const passed = 'object' === typeof args['args'] && args['args'] !== null
                 ? args['args']
                 : {};
+            // A merged name is CALLED, as the MCP layer does (mcp.ts). Explaining it here left
+            // `reticle verify --expect` unable to wait, so it could never give a verdict. The old name is
+            // the action, so it wins over an `action` in the arguments.
+            const moved = byName.has(asked) ? undefined : mergedNameRedirect(asked);
+            const routed = moved?.action !== undefined && byName.has(moved.tool);
+            const name = routed ? moved.tool : asked;
+            const given = routed ? { ...passed, action: moved.action } : passed;
             const aimed = args['sessionId'];
             const target = byName.get(name);
             if (target === undefined) {
@@ -381,7 +389,7 @@ callable) {
                 // is reached through here: a stale ref, a paused session, a missing pairing token all came
                 // back as the agent's arguments being wrong, which is advice that spends the retry.
                 const message = error instanceof Error ? error.message : String(error);
-                const payload = buildErrorPayload(message, codedRefusalOf(error));
+                const payload = withRepeatHint(buildErrorPayload(message, codedRefusalOf(error)), error);
                 return { ...takeVersionSkewOnto(payload, deps.peerSkew), tool: name };
             }
         },

package/dist/surface/tools/empty-session-list.d.ts

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { wiringConsent } from '../../portal/session/no-session-next-action.js';
 export { wiringConsent };
 import type { ToolDeps } from './tool-kit.js';
+/** The field that carries the next step for an unwired project. */
+export declare const NEXT_STEP_FIELD = "next_step";
 /** The fields only an empty list carries, declared so a schema-aware client does not strip them. */
 export declare const EMPTY_SESSION_LIST_OUTPUT: {
     why: z.ZodOptional<z.ZodString>;

package/dist/surface/tools/empty-session-list.js

@@ -32,6 +32,8 @@ const LEASABLE_ACTIONS = new Set([
     NoSessionAction.OPEN_APP,
 ]);
 const LOCALHOST = 'http://localhost';
+/** The field that carries the next step for an unwired project. */
+export const NEXT_STEP_FIELD = 'next_step';
 /** The fields only an empty list carries, declared so a schema-aware client does not strip them. */
 export const EMPTY_SESSION_LIST_OUTPUT = {
     why: z
@@ -51,7 +53,7 @@ export const EMPTY_SESSION_LIST_OUTPUT = {
         .string()
         .optional()
         .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
-    next_step: z
+    [NEXT_STEP_FIELD]: z
         .object({
         offered: z.nativeEnum(NextStepOffered),
         lease: z.string().optional(),
@@ -141,7 +143,7 @@ export function emptySessionList(deps, sessions) {
         sessions,
         ...(why === undefined ? {} : { why }),
         ...(next === undefined ? {} : { next_action: next }),
-        ...(nextStep === undefined ? {} : { next_step: nextStep }),
+        ...(nextStep === undefined ? {} : { [NEXT_STEP_FIELD]: nextStep }),
         ...(undefined === lastKnown ? {} : { lastKnown }),
         // Setup that never connects is where most people give up; it is the talk worth having.
         talk_to_us: DiscoveryInvite.AGENT,

package/dist/surface/tools/error-recovery.d.ts

@@ -8,7 +8,7 @@
  * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
  * baseline stores). No clock, no IO — unit-testable in isolation.
  */
-import { RefusalReason, type CodedRefusal } from '@reticlehq/core';
+import { RefusalDetail, RefusalReason, type CodedRefusal } from '@reticlehq/core';
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
 export declare const RECOVERY: {
     readonly NO_SESSION: string;
@@ -97,6 +97,11 @@ export declare const RECOVERY: {
  * saying a server is running and the recovery saying to go start one.
  */
 export declare function recoveryFor(message: string): string | undefined;
+/** A refusal's bucket, and the cause inside it when the recovery table can tell. */
+export interface RefusalClass {
+    readonly reason: RefusalReason;
+    readonly detail?: RefusalDetail;
+}
 /**
  * WHY a tool refused, as one of the six buckets in core's `RefusalReason`.
  *
@@ -106,6 +111,12 @@ export declare function recoveryFor(message: string): string | undefined;
  * this table rather than about anybody's app.
  */
 export declare function refusalReasonFor(rawMessage: string, coded?: CodedRefusal): RefusalReason;
+/**
+ * The bucket and, when the recovery table names one, the cause inside it. The cause comes from the
+ * same rule that chose the agent's advice, so the two cannot disagree. No detail means no rule
+ * matched, or the message diagnosed itself (`noSessionReason` carries that cause).
+ */
+export declare function classifyRefusal(rawMessage: string, coded?: CodedRefusal): RefusalClass;
 /**
  * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
  * where Reticle failed in a way nobody anticipated — the single highest-value moment to hear from the