@reticlehq/server 2.11.0 → 2.13.0

package/dist/tools/lease-tools.js

@@ -1,17 +1,20 @@
 /**
  * Lease tools — the agent-facing surface of the BrowserPool.
  *
- * `reticle_lease_acquire` opens a fresh isolated headless context navigated to the app URL and returns
- * the sessionId the app's SDK will register (stamped via __reticle_session so the lease and the session
- * correlate 1:1). This is the "one of 10 flows" entry point: 10 agents acquire 10 leases, the pool
- * keeps them in ONE browser, capped and queued. `reticle_lease_release` frees the slot.
+ * `reticle_lease_acquire` opens an isolated headless context navigated to the app URL and returns
+ * the sessionId the app's SDK will register. A second acquire on the same origin reuses the live
+ * lease rather than minting another tab — that second tab used to poison default session resolution
+ * for the rest of the run. The parallel suite still mints via `acquireLeasedSession`, because ten
+ * flows on one origin need isolation on purpose.
  *
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
 import { z } from 'zod';
 import { leaseNotConnectedHint } from './lease-hint.js';
+import { probeSdkMarker } from './sdk-marker-probe.js';
 import { readProjectFramework, readProjectId } from '../cli/cli-port.js';
 import { hasConnectedBefore } from '../session/connection-memory.js';
+import { AGENT_DRIVING_ELSEWHERE, AGENT_DRIVING_HERE_AGAIN, watchersToNotify, } from '../session/lease-visibility.js';
 import { reticleStateHome } from '../daemon/daemon.js';
 import { RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
@@ -24,19 +27,42 @@ import { chromiumHint } from '../cli/chromium-hint.js';
  * printed a static differential over the top of it — telling one agent in `reticle_sessions` that
  * the wiring was proven correct and telling it seconds later that the port was probably wrong.
  */
-function leaseEvidence(deps, port) {
+/**
+ * Async only for the marker probe, which is the piece that decides whether this app ships an SDK at
+ * all — the difference between the diagnosis a new user needs and four causes that all assume the
+ * install already happened. It is one localhost GET on a path that has already failed and is about
+ * to print a paragraph, and it can only ever add a sentence: the probe returns `undefined` on any
+ * doubt and the hint then says nothing about markers.
+ */
+async function leaseEvidence(deps, port, url) {
     const cwd = process.cwd();
     const projectId = readProjectId(cwd);
     const refusal = deps.sessions.lastClosure()?.reason;
     const framework = readProjectFramework(cwd);
+    const sdkMarker = await probeSdkMarker(url);
     return {
         ...(refusal === undefined ? {} : { refusal }),
         ...(framework === undefined ? {} : { framework }),
+        ...(sdkMarker === undefined ? {} : { sdkMarker }),
         previouslyConnected: hasConnectedBefore(reticleStateHome(), port, projectId),
         initialized: projectId !== undefined,
     };
 }
 const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
+/** The origin of a URL, or undefined when it does not parse. */
+export function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+const ALREADY_HELD_LEASE = 'you already hold a lease on this origin';
+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. Release first if you want a fresh one.');
+}
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
@@ -105,6 +131,39 @@ export function resolveLeasedSessionId(sessions, leaseId) {
         return leaseId;
     return sessions.all().find((s) => sessionParamOf(s.url) === leaseId)?.id;
 }
+/**
+ * Carry a claimed identity across a navigation.
+ *
+ * A LEASED tab is addressed by `__reticle_session` in its URL: that param is how the pool finds the
+ * context it opened, and — since succession was tightened — it is also the ONLY thing that lets the
+ * reconnecting document inherit the lease. `reticle_navigate` sent the caller's raw URL, so the very
+ * first navigation stripped the marker, the tab re-announced as an ordinary anonymous session, and
+ * the lease was orphaned: "no sessions are connected at all", with a browser window still open on
+ * screen. A leased browser that cannot survive being navigated is not a usable one.
+ *
+ * A tab that claims nothing is left exactly as it was — this must never bolt Reticle's params onto
+ * a human's own URL.
+ */
+export function carryReticleIdentity(fromUrl, toUrl) {
+    const session = sessionParamOf(fromUrl);
+    if (session === undefined)
+        return toUrl;
+    // Already addressed (a caller passing the stamped URL back) — appending would be a no-op at best.
+    if (sessionParamOf(toUrl) !== undefined)
+        return toUrl;
+    const projectId = projectParamOf(fromUrl);
+    return appendReticleParams(toUrl, session, projectId);
+}
+function projectParamOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).searchParams.get(RETICLE_URL_PARAM.PROJECT) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function sessionParamOf(url) {
     if (url === undefined)
         return undefined;
@@ -163,7 +222,7 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
  */
 export const LEASE_ACQUIRE_TOOL = {
     name: ReticleTool.LEASE_ACQUIRE,
-    description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done.',
+    description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). If this origin is already leased and still connected, this returns THAT session rather than minting a second tab — a second acquire on the same origin poisons default session resolution. Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done. PREFER AN ALREADY-OPEN TAB: if reticle_sessions lists a non-leased session for this app, drive THAT instead — a lease is invisible to the person watching the app, whose HUD lives in their own tab, and a tab flagged hidden/throttled is often still driveable. Lease for isolation you actually need (a second identity, a clean context, parallel flows) or when driving the open tab has failed — this call answers with `preferExisting` when a live tab was available.',
     inputSchema: {
         url: z
             .string()
@@ -184,7 +243,21 @@ export const LEASE_ACQUIRE_TOOL = {
             .describe('Milliseconds until this lease expires if untouched. Each tool call that targets this session resets the clock. Plan your work to finish or re-acquire before this runs out.'),
         leased: z.number().describe('How many contexts are currently leased from the pool.'),
         queued: z.number().describe('How many acquires are waiting for a free slot.'),
+        preferExisting: z
+            .object({ sessionId: z.string(), note: z.string() })
+            .optional()
+            .describe('Present when a live NON-leased tab for this app was already connected. That tab is the one a human can see; this lease is not. Release this lease and drive that sessionId unless you specifically need an isolated context.'),
+        reused: z
+            .boolean()
+            .optional()
+            .describe('True when this acquire returned an existing live lease on the same origin rather than minting a second context.'),
         hint: z.string().optional(),
+        versionSkew: z
+            .string()
+            .optional()
+            .describe("Present when the leased tab's SDK disagrees with this daemon. ready is still true — the " +
+            'page dialled in — but CDP-backed tools (screenshot, viewport, real input, network_mock) ' +
+            'will fail until the versions match. Same sentence as reticle_sessions.versionSkew.'),
     },
     handler: async (deps, args) => {
         const pool = deps.pool;
@@ -205,6 +278,33 @@ export const LEASE_ACQUIRE_TOOL = {
             }
         }
         const projectId = asString(args['projectId']);
+        // Sampled BEFORE acquiring: afterwards this lease is itself a session, and the point is to name
+        // a tab that already existed. A human's open tab is the one they can watch, so if one is here
+        // the agent should be told at the moment it is choosing — not after it has gone dark on them.
+        const alreadyOpen = liveTabFor(deps, projectId);
+        const origin = originOf(url);
+        const existing = origin === undefined ? undefined : pool.leaseIdOnOrigin?.(origin);
+        if (existing !== undefined && origin !== undefined) {
+            if (deps.sessions.get(existing) !== undefined) {
+                pool.touch(existing);
+                return {
+                    sessionId: existing,
+                    url,
+                    ready: true,
+                    reused: true,
+                    expiresInMs: pool.leaseTtlMs(),
+                    leased: pool.activeCount(),
+                    queued: pool.queuedCount(),
+                    hint: alreadyHeldHint(existing, origin),
+                    ...(alreadyOpen === undefined
+                        ? {}
+                        : { preferExisting: { sessionId: alreadyOpen, note: PREFER_EXISTING_NOTE } }),
+                };
+            }
+            // The lease is still held but the tab has gone — a reload dropped the session. Free the
+            // slot and mint, rather than handing back a dead id or leaving both contexts occupied.
+            await pool.release(existing);
+        }
         const sessionId = newLeaseId();
         const navUrl = appendReticleParams(url, sessionId, projectId);
         let lease;
@@ -230,6 +330,11 @@ export const LEASE_ACQUIRE_TOOL = {
         // reaper closes the context mid-flow. See BrowserPool.alias and #157.
         if (registeredId !== undefined)
             pool.alias(registeredId, lease.sessionId);
+        // The lease now exists, so any HUD a human is watching has just gone dark. Say so.
+        tellWatchers(deps, projectId, AGENT_DRIVING_ELSEWHERE);
+        // ready means the SDK dialled in — 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 versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
         return {
             sessionId: registeredId ?? lease.sessionId,
             url,
@@ -237,18 +342,31 @@ export const LEASE_ACQUIRE_TOOL = {
             expiresInMs: pool.leaseTtlMs(),
             leased: pool.activeCount(),
             queued: pool.queuedCount(),
+            ...(alreadyOpen === undefined
+                ? {}
+                : {
+                    preferExisting: {
+                        sessionId: alreadyOpen,
+                        note: PREFER_EXISTING_NOTE,
+                    },
+                }),
+            ...(versionSkew === undefined ? {} : { versionSkew }),
             ...(ready
                 ? {}
-                : (() => {
-                    const bridgePort = deps.bridgePort ?? RETICLE_DEFAULT_PORT;
-                    return {
-                        hint: leaseNotConnectedHint(url, bridgePort, leaseEvidence(deps, bridgePort)),
-                    };
-                })()),
+                : { hint: await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId)) }),
         };
     },
 };
-export const LEASE_RELEASE_TOOL = {
+/** 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;
+    const evidence = await leaseEvidence(deps, bridgePort, url);
+    return leaseNotConnectedHint(url, bridgePort, {
+        ...evidence,
+        ...(dialledUrl === undefined ? {} : { dialledUrl }),
+    });
+}
+const LEASE_RELEASE_TOOL = {
     name: ReticleTool.LEASE_RELEASE,
     description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
     inputSchema: {
@@ -268,8 +386,68 @@ export const LEASE_RELEASE_TOOL = {
         if (sessionId === undefined || 0 === sessionId.length) {
             throw new Error('reticle_lease{action:"release"} requires a sessionId');
         }
+        // Read the project BEFORE releasing: afterwards the session is gone and there is nothing to
+        // ask which project it belonged to.
+        const projectId = deps.sessions.get(sessionId)?.projectId;
         await pool.release(sessionId);
+        // Only once the LAST lease is gone. Announcing "live again" while another lease still drives
+        // would be a lie, and a HUD that says the wrong thing is worse than one that says nothing.
+        if (0 === pool.activeCount())
+            tellWatchers(deps, projectId, AGENT_DRIVING_HERE_AGAIN);
         return { released: true, leased: pool.activeCount() };
     },
 };
+/**
+ * What to say when a lease was taken while a real tab was already open.
+ *
+ * Not a refusal. Leases are the highest-value path for autonomous work and an agent that genuinely
+ * needs isolation must still get one — but a human watching their own tab cannot see a lease, so
+ * when both exist the visible one is the better default and the agent should hear that here, where
+ * it is choosing, rather than discover it when somebody asks why nothing is happening.
+ */
+export const PREFER_EXISTING_NOTE = 'a non-leased tab for this app was already connected — that is the one a human can see, and this lease is not. Unless you need an isolated context (a second identity, a clean profile, parallel flows), release this lease and drive that sessionId instead.';
+/**
+ * The first live non-leased session for this project, if any.
+ *
+ * Reuses the watcher selector rather than re-deriving "which sessions belong to a human": one rule
+ * for one question, so the tab we announce to and the tab we recommend can never disagree.
+ */
+function liveTabFor(deps, projectId) {
+    const pool = deps.pool;
+    if (pool === undefined)
+        return undefined;
+    try {
+        const candidates = deps.sessions
+            .all()
+            .map((session) => ({ id: session.id, projectId: session.projectId }));
+        return watchersToNotify(candidates, pool.leasedSessionIds(), projectId)[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Tell the tabs a human is watching that the agent has gone somewhere they cannot see.
+ *
+ * Fire-and-forget, and deliberately never able to fail the tool: this is a courtesy to a person, and
+ * a lease that succeeded must not be reported as failed because a narration could not be posted to
+ * some unrelated tab. `pushNarration` is already fire-and-forget; the try/catch covers a session
+ * that disconnects between listing it and posting to it.
+ */
+function tellWatchers(deps, projectId, text) {
+    const pool = deps.pool;
+    if (pool === undefined)
+        return;
+    try {
+        const candidates = deps.sessions
+            .all()
+            .map((session) => ({ id: session.id, projectId: session.projectId }));
+        for (const id of watchersToNotify(candidates, pool.leasedSessionIds(), projectId)) {
+            deps.sessions.get(id)?.pushNarration(text);
+        }
+    }
+    catch {
+        // A HUD that missed one line is a smaller problem than a lease reported as broken.
+    }
+}
 export const LEASE_TOOLS = [LEASE_ACQUIRE_TOOL, LEASE_RELEASE_TOOL];

package/dist/tools/merged-name-redirect.d.ts

@@ -8,6 +8,19 @@ interface MergedNameRedirect {
 }
 /** Where `name` went, or undefined when it is a live tool or not ours. */
 export declare function mergedNameRedirect(name: string): MergedNameRedirect | undefined;
+/**
+ * Every retired name against the call that replaces it — the tombstones, as one block.
+ *
+ * The redirect above answers an agent that already guessed the old name. This answers the one that
+ * is reading the surface to find out what exists, and is the case a redirect cannot reach: nothing
+ * in the catalogue says `reticle_crawl` became `reticle_verify { action: "crawl" }`, so instructions
+ * written against an earlier release lead either to an error string or to nothing at all.
+ *
+ * Derived from the same two declarations as `BY_OLD_NAME`, for the same reason: a hand-written
+ * migration list is one merge away from being wrong, and wrong is worse than absent here — the agent
+ * retries into it.
+ */
+export declare function retiredToolNames(): Readonly<Record<string, string>>;
 /** The sentence handed to an agent that called `name`. */
 export declare function mergedNameMessage(name: string, redirect: MergedNameRedirect): string;
 export {};

package/dist/tools/merged-name-redirect.js

@@ -46,6 +46,28 @@ const BY_OLD_NAME = (() => {
 export function mergedNameRedirect(name) {
     return BY_OLD_NAME.get(name);
 }
+/**
+ * Every retired name against the call that replaces it — the tombstones, as one block.
+ *
+ * The redirect above answers an agent that already guessed the old name. This answers the one that
+ * is reading the surface to find out what exists, and is the case a redirect cannot reach: nothing
+ * in the catalogue says `reticle_crawl` became `reticle_verify { action: "crawl" }`, so instructions
+ * written against an earlier release lead either to an error string or to nothing at all.
+ *
+ * Derived from the same two declarations as `BY_OLD_NAME`, for the same reason: a hand-written
+ * migration list is one merge away from being wrong, and wrong is worse than absent here — the agent
+ * retries into it.
+ */
+export function retiredToolNames() {
+    const tombstones = {};
+    for (const [old, redirect] of BY_OLD_NAME) {
+        tombstones[old] =
+            redirect.action === undefined
+                ? `retired; ${redirect.note ?? `use ${redirect.tool}`}`
+                : `retired; use ${redirect.tool} { action: "${redirect.action}" }`;
+    }
+    return tombstones;
+}
 /** The sentence handed to an agent that called `name`. */
 export function mergedNameMessage(name, redirect) {
     return redirect.action === undefined

package/dist/tools/navigate-arrival.d.ts

@@ -13,8 +13,6 @@
  */
 import type { SessionManager } from '../session/session-manager.js';
 import type { NavigateArrival } from './navigate-result.js';
-/** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
-export declare const ARRIVAL_TIMEOUT_MS = 5000;
 export interface ArrivalClock {
     now: () => number;
     sleep: (ms: number) => Promise<void>;

package/dist/tools/navigate-arrival.js

@@ -12,7 +12,7 @@
  * the sleep are injected so this is testable without waiting on a real one.
  */
 /** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
-export const ARRIVAL_TIMEOUT_MS = 5_000;
+const ARRIVAL_TIMEOUT_MS = 5_000;
 const POLL_MS = 100;
 /**
  * Compare only origin + pathname.

package/dist/tools/numeric-bounds.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared bounds for numeric TOOL INPUTS.
+ *
+ * An unknown parameter is refused with "They were NOT applied — a result computed without them
+ * would look like an answer." A known parameter carrying a value the code cannot honour is the
+ * same failure: `reticle_state { depth: -5 }` used to return the full unscoped store, because
+ * `capDepth` treats a negative budget as "no cap". The agent cannot tell a bound it asked for
+ * from a bound that was dropped.
+ *
+ * A single rule for every number would be wrong (`since: 0` is a real cursor; `timeout_ms: 0`
+ * on assert means evaluate now; `threshold` is a 0–1 ratio). Each helper below is one policy,
+ * with the sentence for why that bound and not another.
+ */
+import { z } from 'zod';
+/**
+ * Hard cap on "return the first N". The ring buffer holds this many events; asking for a billion
+ * cannot be honoured from memory we do not keep, and would look like a complete listing.
+ */
+export declare const MAX_RESULT_COUNT: 2000;
+/**
+ * Hard cap on a numeric millisecond argument that does NOT block the caller's request.
+ * `timeout_ms: 0` stays legal — it means evaluate once, do not wait.
+ */
+export declare const MAX_TIMEOUT_MS = 120000;
+export declare const MAX_BLOCKING_WAIT_MS: number;
+/**
+ * `capDepth` at this many levels is already past any store an agent can read.
+ *
+ * Not lower: `numeric-args-are-bounded.test.ts` pins depth 50 as legal, because a large depth is a
+ * SCOPE choice and not an error. A ceiling that refuses it would turn a working call into a refusal
+ * in the name of bounding one that never worked.
+ */
+export declare const MAX_STATE_DEPTH = 256;
+/** A crawl that clicks forever is not a bound. */
+export declare const MAX_CRAWL_STEPS = 500;
+/** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
+export declare const MAX_SCROLLS = 200;
+/** Fake-clock jump. One day of timers is a test; a billion ms is not. */
+export declare const MAX_ADVANCE_MS = 86400000;
+/** Presenter idle window. One hour is a slow app; larger values never fire. */
+export declare const MAX_IDLE_MS = 3600000;
+/** Viewport CSS px — matches the clamp the handler already applied, now as a refusal. */
+export declare const MIN_VIEWPORT_PX = 64;
+export declare const MAX_VIEWPORT_PX = 10000;
+/**
+ * A page cursor. 0 is the start of the buffer, so `.positive()` would refuse a legitimate first
+ * page. Negative is not a cursor.
+ */
+export declare const cursorSchema: z.ZodNumber;
+/**
+ * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
+ */
+export declare const timeoutMsSchema: z.ZodNumber;
+/**
+ * A count / cap. 0 means "return none", which is a real request. Negative is not.
+ * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.
+ */
+export declare const countSchema: z.ZodNumber;
+/**
+ * Store projection depth. Negative used to mean "no cap" inside `capDepth`, which is how
+ * `depth: -5` silently returned the full store — that is the defect this bound closes.
+ *
+ * 0 stays REFUSED, which is the policy already on the surface (a zero-level read is not a read).
+ * `capDepth(v, 0)` does return a size marker, so accepting it would be defensible — but that is a
+ * change to what the tool answers, not a bound on what it cannot honour, and it belongs in its own
+ * change with its own reason.
+ */
+export declare const depthSchema: z.ZodNumber;
+/**
+ * Pixel-diff ratios (`threshold`, `maxRatio`). pixelmatch's threshold and our pass ratio are both
+ * 0..1; `.int()` would refuse 0.01.
+ */
+export declare const ratioSchema: z.ZodNumber;
+/** HTTP status on a mock or a filter. */
+export declare const httpStatusSchema: z.ZodNumber;
+/** Viewport CSS px. `.int()` alone still accepted 5 and 999999, then the handler silently clamped. */
+export declare const viewportPxSchema: z.ZodNumber;
+/** Crawl / scroll step budgets. 0 is a documented no-op on crawl ("raise it to crawl at all"). */
+export declare const stepCountSchema: z.ZodNumber;
+export declare const scrollCountSchema: z.ZodNumber;
+export declare const advanceMsSchema: z.ZodNumber;
+export declare const idleMsSchema: z.ZodNumber;
+/** Delay before a mocked response. 0 is immediate. */
+export declare const delayMsSchema: z.ZodNumber;
+/**
+ * Observe lookback. Must be > 0 — a non-positive window used to mint a FUTURE cursor, so the
+ * tool returned zero events and looked like a quiet page. Capped so `window_ms: 1e12` cannot hang.
+ */
+export declare const windowMsSchema: z.ZodNumber;
+/**
+ * Parallelism for suite replay. 0 (and omit) means sequential. Capped at the session/pool ceiling;
+ * asking for a thousand workers cannot be honoured.
+ */
+export declare const workerCountSchema: z.ZodNumber;
+/**
+ * A row index / list length in a virtualized table. Those lists are large on purpose; the ring
+ * buffer's 2000 is the wrong ceiling. A billion-row claim is not a list, it is a hang.
+ */
+export declare const MAX_LIST_INDEX = 1000000;
+export declare const listIndexSchema: z.ZodNumber;

package/dist/tools/numeric-bounds.js

@@ -0,0 +1,125 @@
+/**
+ * Shared bounds for numeric TOOL INPUTS.
+ *
+ * An unknown parameter is refused with "They were NOT applied — a result computed without them
+ * would look like an answer." A known parameter carrying a value the code cannot honour is the
+ * same failure: `reticle_state { depth: -5 }` used to return the full unscoped store, because
+ * `capDepth` treats a negative budget as "no cap". The agent cannot tell a bound it asked for
+ * from a bound that was dropped.
+ *
+ * A single rule for every number would be wrong (`since: 0` is a real cursor; `timeout_ms: 0`
+ * on assert means evaluate now; `threshold` is a 0–1 ratio). Each helper below is one policy,
+ * with the sentence for why that bound and not another.
+ */
+import { z } from 'zod';
+import { RING_BUFFER_DEFAULTS, TRANSPORT_LIMITS } from '@reticlehq/core';
+/**
+ * Hard cap on "return the first N". The ring buffer holds this many events; asking for a billion
+ * cannot be honoured from memory we do not keep, and would look like a complete listing.
+ */
+export const MAX_RESULT_COUNT = RING_BUFFER_DEFAULTS.MAX_EVENTS;
+/**
+ * Hard cap on a numeric millisecond argument that does NOT block the caller's request.
+ * `timeout_ms: 0` stays legal — it means evaluate once, do not wait.
+ */
+export const MAX_TIMEOUT_MS = 120_000;
+/**
+ * Hard cap on a wait the CALLER BLOCKS ON, which is a different ceiling from the one above.
+ *
+ * A blocking wait is bounded by the client's patience, not by ours. The MCP SDK's default request
+ * timeout is 60s and clients configure it lower; we advertised 120s. A caller who believed the
+ * advertised bound and asked for 90s got a TRANSPORT error at 60s — not a Reticle verdict, not a
+ * near-miss diagnosis, nothing to act on. The wait was honoured right up to the point where the
+ * only thing that could report it had gone.
+ *
+ * So the ceiling is set below the SDK default rather than at it: the margin is what lets Reticle's
+ * own "timed out, here is the near miss" answer beat the client's abort. A refused argument is a
+ * bad ceiling costing one round trip; an accepted one that cannot be delivered costs the drive.
+ *
+ * This does not make long waits possible, and is not meant to — it makes the ADVERTISED bound one
+ * that can actually be honoured. A caller that genuinely needs to outlast this polls: several short
+ * waits, each of which returns a verdict. See #601 for the bounded-wait cursor that would let one
+ * call do it properly.
+ */
+const MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+export const MAX_BLOCKING_WAIT_MS = MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS - 5_000;
+/**
+ * `capDepth` at this many levels is already past any store an agent can read.
+ *
+ * Not lower: `numeric-args-are-bounded.test.ts` pins depth 50 as legal, because a large depth is a
+ * SCOPE choice and not an error. A ceiling that refuses it would turn a working call into a refusal
+ * in the name of bounding one that never worked.
+ */
+export const MAX_STATE_DEPTH = 256;
+/** A crawl that clicks forever is not a bound. */
+export const MAX_CRAWL_STEPS = 500;
+/** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
+export const MAX_SCROLLS = 200;
+/** Fake-clock jump. One day of timers is a test; a billion ms is not. */
+export const MAX_ADVANCE_MS = 86_400_000;
+/** Presenter idle window. One hour is a slow app; larger values never fire. */
+export const MAX_IDLE_MS = 3_600_000;
+/** Viewport CSS px — matches the clamp the handler already applied, now as a refusal. */
+export const MIN_VIEWPORT_PX = 64;
+export const MAX_VIEWPORT_PX = 10_000;
+/**
+ * A page cursor. 0 is the start of the buffer, so `.positive()` would refuse a legitimate first
+ * page. Negative is not a cursor.
+ */
+export const cursorSchema = z.number().finite().int().nonnegative();
+/**
+ * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
+ */
+export const timeoutMsSchema = z.number().finite().int().nonnegative().max(MAX_BLOCKING_WAIT_MS);
+/**
+ * A count / cap. 0 means "return none", which is a real request. Negative is not.
+ * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.
+ */
+export const countSchema = z.number().finite().int().nonnegative().max(MAX_RESULT_COUNT);
+/**
+ * Store projection depth. Negative used to mean "no cap" inside `capDepth`, which is how
+ * `depth: -5` silently returned the full store — that is the defect this bound closes.
+ *
+ * 0 stays REFUSED, which is the policy already on the surface (a zero-level read is not a read).
+ * `capDepth(v, 0)` does return a size marker, so accepting it would be defensible — but that is a
+ * change to what the tool answers, not a bound on what it cannot honour, and it belongs in its own
+ * change with its own reason.
+ */
+export const depthSchema = z.number().finite().int().positive().max(MAX_STATE_DEPTH);
+/**
+ * Pixel-diff ratios (`threshold`, `maxRatio`). pixelmatch's threshold and our pass ratio are both
+ * 0..1; `.int()` would refuse 0.01.
+ */
+export const ratioSchema = z.number().finite().min(0).max(1);
+/** HTTP status on a mock or a filter. */
+export const httpStatusSchema = z.number().finite().int().min(100).max(599);
+/** Viewport CSS px. `.int()` alone still accepted 5 and 999999, then the handler silently clamped. */
+export const viewportPxSchema = z.number().finite().int().min(MIN_VIEWPORT_PX).max(MAX_VIEWPORT_PX);
+/** Crawl / scroll step budgets. 0 is a documented no-op on crawl ("raise it to crawl at all"). */
+export const stepCountSchema = z.number().finite().int().nonnegative().max(MAX_CRAWL_STEPS);
+export const scrollCountSchema = z.number().finite().int().nonnegative().max(MAX_SCROLLS);
+export const advanceMsSchema = z.number().finite().int().nonnegative().max(MAX_ADVANCE_MS);
+export const idleMsSchema = z.number().finite().int().nonnegative().max(MAX_IDLE_MS);
+/** Delay before a mocked response. 0 is immediate. */
+export const delayMsSchema = z.number().finite().int().nonnegative().max(MAX_TIMEOUT_MS);
+/**
+ * Observe lookback. Must be > 0 — a non-positive window used to mint a FUTURE cursor, so the
+ * tool returned zero events and looked like a quiet page. Capped so `window_ms: 1e12` cannot hang.
+ */
+export const windowMsSchema = z.number().finite().int().positive().max(MAX_TIMEOUT_MS);
+/**
+ * Parallelism for suite replay. 0 (and omit) means sequential. Capped at the session/pool ceiling;
+ * asking for a thousand workers cannot be honoured.
+ */
+export const workerCountSchema = z
+    .number()
+    .finite()
+    .int()
+    .nonnegative()
+    .max(TRANSPORT_LIMITS.MAX_SESSIONS);
+/**
+ * A row index / list length in a virtualized table. Those lists are large on purpose; the ring
+ * buffer's 2000 is the wrong ceiling. A billion-row claim is not a list, it is a hang.
+ */
+export const MAX_LIST_INDEX = 1_000_000;
+export const listIndexSchema = z.number().finite().int().nonnegative().max(MAX_LIST_INDEX);