@reticlehq/server 3.8.0 → 3.8.2

package/dist/portal/pool/pool-lease.js

@@ -0,0 +1,49 @@
+/**
+ * The pool's lease handle and lease record, its options, and its limits: the types and constants
+ * `BrowserPool` is built from.
+ */
+/** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
+export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
+/**
+ * How long a lease outlives the MCP connection that took it. Long enough for an agent whose
+ * connection only blipped to touch it again; short enough that a gone agent's window closes soon.
+ */
+export const ORPHANED_LEASE_GRACE_MS = 30_000;
+/** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
+export const DEFAULT_NAV_TIMEOUT_MS = 30_000;
+/**
+ * How many reaped lease ids to remember. Only the most recent departure is ever asked about, so
+ * this is slack for a burst sweep, not a history.
+ */
+export const MAX_REMEMBERED_REAPED_LEASES = 64;
+/** What a headed lease is refused with where no window can be opened. */
+export const NO_HEADED_BROWSER = 'no headed browser can be opened here';
+/**
+ * An acquire that asked to be refused rather than queued found every slot taken (#1535). Queued,
+ * it waited behind the cap with no deadline and no status, and `reticle drive` reported the 60 s
+ * timeout as a daemon shutting down. The message names the cap and the one override for it.
+ */
+export class PoolAtCapacityError extends Error {
+    max;
+    constructor(max) {
+        super(`all ${String(max)} lease slots are in use. Release one (reticle_lease{action:"release"}, or ` +
+            'stop a `reticle drive`), or raise RETICLE_MAX_CONTEXTS.');
+        this.max = max;
+        this.name = 'PoolAtCapacityError';
+    }
+}
+/**
+ * What an acquire that asked for an init script is refused with when the page cannot run one.
+ *
+ * A refusal rather than a lease: the caller asked for a stub of the bindings a desktop shell
+ * injects, and a tab opened without it would throw in the app's view and read as a broken app.
+ */
+export const INIT_SCRIPT_UNSUPPORTED = 'Init script failed: this page does not support init scripts, so the requested stub would not be there';
+/** Whether the page's document has not finished loading. A page that cannot be asked counts as loaded. */
+export async function pageLoading(page) {
+    if (page.evaluate === undefined) {
+        return false;
+    }
+    const state = await page.evaluate('document.readyState');
+    return 'string' === typeof state && state !== 'complete';
+}

package/dist/portal/production/production-activation.d.ts

@@ -19,20 +19,12 @@ export declare const PRODUCTION_MODE_NOT_LINKED = "production mode needs a linke
 /** The `production` argument of `reticle_lease { action: "acquire" }`. */
 export declare const ProductionLeaseArgSchema: z.ZodObject<{
     workspaceId: z.ZodString;
-    scope: z.ZodNativeEnum<{
+    scope: z.ZodEnum<{
         readonly OBSERVE: "observe";
         readonly ACT: "act";
     }>;
     intent: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    workspaceId: string;
-    scope: "observe" | "act";
-    intent?: string | undefined;
-}, {
-    workspaceId: string;
-    scope: "observe" | "act";
-    intent?: string | undefined;
-}>;
+}, z.core.$strip>;
 export type TicketFetch = (url: string, init: {
     method: string;
     headers: Record<string, string>;
@@ -86,31 +78,17 @@ export declare function leaseWithoutInjection<L extends {
 /** `reticle_lease`'s `production` argument, described for the agent. */
 export declare const PRODUCTION_LEASE_ARG: z.ZodOptional<z.ZodObject<{
     workspaceId: z.ZodString;
-    scope: z.ZodNativeEnum<{
+    scope: z.ZodEnum<{
         readonly OBSERVE: "observe";
         readonly ACT: "act";
     }>;
     intent: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    workspaceId: string;
-    scope: "observe" | "act";
-    intent?: string | undefined;
-}, {
-    workspaceId: string;
-    scope: "observe" | "act";
-    intent?: string | undefined;
-}>>;
+}, z.core.$strip>>;
 /** What a production lease reports back. */
 export declare const PRODUCTION_LEASE_OUTPUT: z.ZodOptional<z.ZodObject<{
     scope: z.ZodString;
     expiresAt: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    scope: string;
-    expiresAt: number;
-}, {
-    scope: string;
-    expiresAt: number;
-}>>;
+}, z.core.$strip>>;
 /** The lease's ports activation reads. */
 interface ActivationPorts {
     nonces?: NonceMinter | undefined;

package/dist/portal/session/control-envelope.d.ts

@@ -30,7 +30,7 @@ interface PausedResult {
  * human's message entirely (not merely hides it). Declared here beside PausedResult so the schema and
  * the runtime shape are the same source; spread into each act tool's outputSchema.
  */
-export declare const pausedOutputShape: z.ZodRawShape;
+export declare const pausedOutputShape: Record<string, z.ZodType>;
 /** The optional `control` key `withControl` may add — keeps callers' return types honest. */
 type ControlSpread = {
     control?: ControlEnvelope;

package/dist/portal/session/zero-install-first-call.d.ts

@@ -18,6 +18,8 @@ export interface FirstCallOpened {
 }
 /** Compared both as written and with links resolved: either spelling may be the one lsof used. */
 export declare function within(child: string | undefined, parent: string): boolean;
+/** The caller's running app, for a lease that names no url. */
+export declare function projectAppUrlFinder(io: Pick<FirstCallIo, 'project' | 'serving' | 'servingDirectory'>): () => Promise<string | undefined>;
 /** One lease per project for the daemon's life: a failure is reported once, never retried. */
 export declare function firstCallOpener(io: FirstCallIo): () => Promise<FirstCallOpened | undefined>;
 /**
@@ -30,4 +32,5 @@ export declare function agentWiring(sessions: {
 }, lease: (url: string) => Promise<unknown>): {
     firstRun: FirstRunWiring;
     openUnwiredApp: () => Promise<FirstCallOpened | undefined>;
+    projectAppUrl: () => Promise<string | undefined>;
 };

package/dist/portal/session/zero-install-first-call.js

@@ -47,6 +47,28 @@ function openedNotice(url, init) {
         `file:line). To wire it for good: ${wiringConsent(init)} Then restart the dev server and ` +
         'reload the page.');
 }
+/**
+ * The one dev server that runs in this project's folder, or undefined when there is none or more
+ * than one. Two servers in one project is a choice the caller makes, not one Reticle guesses.
+ */
+async function projectAppUrlIn(io, dir) {
+    const pinned = detectDevCommandInProject(dir)?.port;
+    const candidates = new Set(DEV_SERVER_PORTS);
+    if (pinned !== undefined) {
+        candidates.add(pinned);
+    }
+    const own = (await io.serving([...candidates]))
+        .map((port) => `${LOCALHOST}:${String(port)}`)
+        .filter((url) => within(io.servingDirectory(url), dir));
+    return 1 === own.length ? own[0] : undefined;
+}
+/** The caller's running app, for a lease that names no url. */
+export function projectAppUrlFinder(io) {
+    return async () => {
+        const dir = io.project();
+        return dir === undefined ? undefined : projectAppUrlIn(io, dir);
+    };
+}
 /** One lease per project for the daemon's life: a failure is reported once, never retried. */
 export function firstCallOpener(io) {
     const tried = new Set();
@@ -54,16 +76,9 @@ export function firstCallOpener(io) {
         const dir = io.project();
         if (dir === undefined || tried.has(dir))
             return undefined;
-        const pinned = detectDevCommandInProject(dir)?.port;
-        const candidates = new Set(DEV_SERVER_PORTS);
-        if (pinned !== undefined)
-            candidates.add(pinned);
-        const own = (await io.serving([...candidates]))
-            .map((port) => `${LOCALHOST}:${String(port)}`)
-            .filter((url) => within(io.servingDirectory(url), dir));
-        const [url] = own;
+        const url = await projectAppUrlIn(io, dir);
         // ponytail: nothing serving yet is not an attempt, so a later call looks again.
-        if (url === undefined || 1 !== own.length)
+        if (url === undefined)
             return undefined;
         tried.add(dir);
         await io.lease(url).catch(() => undefined);
@@ -79,12 +94,18 @@ export function firstCallOpener(io) {
  */
 export function agentWiring(sessions, lease) {
     const firstRun = firstRunWiring();
-    const openUnwiredApp = firstCallOpener({
+    const io = {
         project: () => firstRun.projectDirectory(callingClientDirectory() ?? process.cwd()),
         serving: async (ports) => (await probeDevServerStates(ports)).serving,
         servingDirectory: (url) => servingDirectoryOf(url),
         lease,
         connected: () => 0 < sessions.list().length,
-    });
-    return { firstRun, openUnwiredApp };
+    };
+    // Wired or not: a lease that names no url wants the app this caller works in either way.
+    const callerFolder = () => callingClientDirectory() ?? process.cwd();
+    return {
+        firstRun,
+        openUnwiredApp: firstCallOpener(io),
+        projectAppUrl: projectAppUrlFinder({ ...io, project: callerFolder }),
+    };
 }

package/dist/surface/mcp/mcp.d.ts

@@ -18,7 +18,7 @@ export declare const CALL_TOOL_METHOD = "tools/call";
  * tool with a strict schema (`reticle_context`) failed the whole call on a validating client the
  * first time one of them rode on it.
  */
-export declare function withSessionEnvelope(_name: string, outputSchema: z.ZodRawShape | undefined): z.ZodRawShape | undefined;
+export declare function withSessionEnvelope(_name: string, outputSchema: Record<string, z.ZodType> | undefined): Record<string, z.ZodType> | undefined;
 /**
  * Abbreviations whose internal period is NOT a sentence end.
  *
@@ -93,8 +93,8 @@ tools?: readonly ToolDef[]): ToolDef[];
  */
 export declare function advertisedConfig(tool: ToolDef, advertised: readonly ToolDef[], profile: ToolSurface): {
     description: string;
-    inputSchema: z.ZodRawShape;
-    outputSchema?: z.ZodRawShape;
+    inputSchema: Record<string, z.ZodType>;
+    outputSchema?: Record<string, z.ZodType>;
     annotations: ToolAnnotations;
 };
 export declare function installFriendlyArgErrors(server: McpServer, examples: Map<string, string>, allowedKeys?: Map<string, ReadonlySet<string>>): void;

package/dist/surface/mcp/mcp.js

@@ -8,7 +8,7 @@ import { tableForSurface } from '../tools/tools.js';
 import { filterTools, describeToolSurface, TOOL_SURFACE, toolAnnotations, } from '../tools/tool-surface.js';
 import { ReticleTool } from '@reticlehq/core';
 import { sharedParamShort } from './shared-params.js';
-import { buildDynamicTools } from '../tools/dynamic-tools.js';
+import { buildDynamicTools, descriptionOf } from '../tools/dynamic-tools.js';
 import { runTool } from '../tools/invoke-tool.js';
 import { sessionEnvelopeShape, newSnapshotCache } from '../tools/tool-kit.js';
 import { buildErrorPayload, codedRefusalOf } from '../tools/error-recovery.js';
@@ -150,11 +150,9 @@ function leanZodShape(shape, advertised, predicateAnchor) {
     for (const [key, schema] of Object.entries(shape)) {
         if (isPredicateParam(schema)) {
             // Every tool keeps the kinds; only the navigation hint is anchored.
-            const compact = z
-                .record(z.unknown())
-                .describe(hintSpent ? PREDICATE_KINDS : COMPACT_PREDICATE_DESCRIPTION);
+            const compact = z.record(z.string(), z.unknown());
+            out[key] = (schema.isOptional() ? compact.optional() : compact).describe(hintSpent ? PREDICATE_KINDS : COMPACT_PREDICATE_DESCRIPTION);
             hintSpent = true;
-            out[key] = schema.isOptional() ? compact.optional() : compact;
             continue;
         }
         // Shared boilerplate is documented once in the initialize instructions instead of on every
@@ -169,7 +167,7 @@ function leanZodShape(shape, advertised, predicateAnchor) {
         }
         // Through the same rewrite as tool descriptions: a parameter that says "a ref from
         // reticle_snapshot" names a tool this surface does not have.
-        const desc = schema.description;
+        const desc = descriptionOf(schema);
         out[key] =
             'string' === typeof desc
                 ? schema.describe(liveCallText(firstSentence(desc), advertised))

package/dist/surface/tools/act/act-danger.js

@@ -1,4 +1,4 @@
-import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, OutwardAction, isDangerousActionText, isDangerousNavigation, isInertHref, isPaymentProviderUrl, outwardActionOf, outwardRefusal, } from '@reticlehq/core';
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, OutwardAction, isDangerousActionText, isDangerousNavigation, isInertHref, isPaymentProviderUrl, outwardActionOf, outwardRefusal, withoutFilenameTokens, } from '@reticlehq/core';
 import { currentDrivenBy, harnessOutwardAllowed } from '../../../hooks/driven-by.js';
 import { asRecord, asString } from '@reticlehq/core';
 /**
@@ -14,10 +14,12 @@ import { asRecord, asString } from '@reticlehq/core';
  */
 function descriptorText(value) {
     const descriptor = asRecord(value);
+    // Filename tokens are stripped from the name, the text and the value only: an href or a
+    // formAction is a target, not words on the control, and its destination must be read whole.
     return [
-        asString(descriptor['name']) ?? '',
-        asString(descriptor['text']) ?? '',
-        asString(descriptor['value']) ?? '',
+        withoutFilenameTokens(asString(descriptor['name']) ?? ''),
+        withoutFilenameTokens(asString(descriptor['text']) ?? ''),
+        withoutFilenameTokens(asString(descriptor['value']) ?? ''),
         asString(descriptor['href']) ?? '',
         asString(descriptor['formAction']) ?? '',
         asString(descriptor['formText']) ?? '',
@@ -30,37 +32,45 @@ function descriptorRole(value) {
 function isDestructiveDescriptor(value) {
     // A real link is a navigation, judged by where it goes: the same rule as the SDK path.
     const href = asString(asRecord(value)['href']);
-    if (href !== undefined && !isInertHref(href))
+    if (href !== undefined && !isInertHref(href)) {
         return isDangerousNavigation(href);
+    }
     return isDangerousActionText(descriptorText(value), descriptorRole(value));
 }
 /** A Harness call presses an outward control only when its journey asked (`harnessOutwardAllowed`). */
 function assertOutwardAllowed(...descriptors) {
     const allowed = harnessOutwardAllowed();
-    if (allowed === undefined)
+    if (allowed === undefined) {
         return;
+    }
     for (const descriptor of descriptors) {
         const kind = outwardActionOf(descriptorText(descriptor), descriptorRole(descriptor));
-        if (kind !== undefined && !allowed.includes(kind))
+        if (kind !== undefined && !allowed.includes(kind)) {
             throw new Error(outwardRefusal(kind));
+        }
     }
 }
 /** A Harness call goes to a payment provider's origin only when its journey asked to pay. */
 export function assertNotPaymentNavigation(url) {
     const allowed = harnessOutwardAllowed();
-    if (allowed === undefined || allowed.includes(OutwardAction.PAY))
+    if (allowed === undefined || allowed.includes(OutwardAction.PAY)) {
         return;
-    if (isPaymentProviderUrl(url))
+    }
+    if (isPaymentProviderUrl(url)) {
         throw new Error(outwardRefusal(OutwardAction.PAY));
+    }
 }
 export function assertNotDestructive(action, innerArgs, inspected) {
-    if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
+    if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK) {
         return;
+    }
     assertOutwardAllowed(inspected);
-    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG]) {
         return;
-    if (!isDestructiveDescriptor(inspected))
+    }
+    if (!isDestructiveDescriptor(inspected)) {
         return;
+    }
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }
 /**
@@ -70,10 +80,12 @@ export function assertNotDestructive(action, innerArgs, inspected) {
  */
 export function assertDragNotDestructive(innerArgs, from, to) {
     assertOutwardAllowed(from, to);
-    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG]) {
         return;
-    if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to))
+    }
+    if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to)) {
         return;
+    }
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }
 /**
@@ -90,8 +102,9 @@ export const NATIVE_INPUT_UNSUPPORTED = `reticle_act_and_wait cannot drive nativ
     'consequence with reticle_assert / reticle_observe using the `since` cursor it returns.';
 /** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
 export function assertNativeInputSupported(innerArgs) {
-    if (true === innerArgs[NATIVE_INPUT_ARG])
+    if (true === innerArgs[NATIVE_INPUT_ARG]) {
         throw new Error(NATIVE_INPUT_UNSUPPORTED);
+    }
 }
 /**
  * The agent's own declaration counts as the confirmation, for that one control.
@@ -104,10 +117,12 @@ export function assertNativeInputSupported(innerArgs) {
  * guard decides alone.
  */
 export function confirmedByDeclaration(innerArgs, target, declared) {
-    if (!declared || true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+    if (!declared || true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG]) {
         return innerArgs;
-    if (currentDrivenBy() !== undefined)
+    }
+    if (currentDrivenBy() !== undefined) {
         return innerArgs;
+    }
     const named = asRecord(target);
     // The words must themselves be the dangerous ones: naming "Continue" on a button whose form posts
     // to /delete-account consents to nothing, and the guard still reads the whole control.

package/dist/surface/tools/act/durable.js

@@ -20,7 +20,7 @@ export const durableArg = z
     .describe('After a yes, reload and require the element/text/state part of `until` to hold again.');
 // Loose and undescribed on purpose: the output surface is re-sent every turn. `because` carries
 // the answer; this is the detail — { held?, observed?, skipped? }.
-export const durableOutput = z.record(z.unknown()).optional();
+export const durableOutput = z.record(z.string(), z.unknown()).optional();
 const RE_READABLE = new Set([
     PredicateKind.ELEMENT,
     PredicateKind.TEXT,

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

@@ -122,7 +122,7 @@ export const ACT_SEQUENCE_TOOL = {
     description: "Drive a WHOLE journey in ONE round-trip, with NO snapshot first. Name each step's element by {testid} | {label} | {role,name} | {text} in `target` and Reticle resolves it AT THE MOMENT THAT STEP RUNS — so a control that does not exist yet (a modal an earlier step opens, a row it creates) is still addressable, and waits up to timeout_ms to appear. This is the fast path: snapshot -> act -> snapshot -> act costs a model turn per step and is the slowest thing an agent can do. Give each step an `expect` and the sequence stops at the first one that does not hold, returning the un-run `tail` verbatim so you re-plan only the failure. Returns per-step effects[] (see reticle_act).",
     inputSchema: {
         steps: z
-            .array(z.record(z.unknown()))
+            .array(z.record(z.string(), z.unknown()))
             .describe('Ordered list of { ref | target, action, args?, expect? } objects. Each step is equivalent to one reticle_act call, and takes its arguments either way: `{ ref, action: "fill", value: "…" }` flat, as reticle_act does, or nested as `args: { value }`. Give `ref` from a snapshot/query, or `target` ({ testid } | { label } | { role, name } | { text }) to resolve in this call. Put confirmDangerous:true in a destructive step args object. `expect` is the same predicate shape as reticle_act_and_wait `until`, and it is what makes a step PROVE something: a step without one is driven, not verified, and the result says so. Naming the consequence is also FASTER — a named consequence is detected the instant it fires, where waiting for the page to settle can only conclude by waiting for silence.'),
         // A plain number, not boolean|number: a zod union serialises to a JSON-Schema `anyOf` that
         // cost 174 B on a surface re-sent every turn, against 81 B of headroom. One spelling is also
@@ -163,14 +163,14 @@ export const ACT_SEQUENCE_TOOL = {
         /** How many steps declared a consequence, of how many were driven. Never averaged away. */
         coverage: z.object({ declared: z.number(), total: z.number() }).optional(),
         /** Steps never run, verbatim, so a caller re-plans the failure rather than the whole journey. */
-        tail: z.array(z.record(z.unknown())).optional(),
+        tail: z.array(z.record(z.string(), z.unknown())).optional(),
         /**
          * Each step carries the same effect record a REPLAYED step carries: `window` (the
          * `reticle_observe { since, until }` drill address), `digest` (what the app did, as counts) and
          * `contradictions` (channels that disagree, present even when the step passed). Declared here
          * because an undeclared field is stripped from structuredContent and would be silently lost.
          */
-        steps: z.array(z.record(z.unknown())).optional(),
+        steps: z.array(z.record(z.string(), z.unknown())).optional(),
         result: z.unknown().optional(),
         session: z
             .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })

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

@@ -116,14 +116,14 @@ export const ACT_TOOLS = [
                 .optional()
                 .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`. A press of Escape, Tab, or a modifier shortcut (Cmd+K) is a document key and needs neither.`),
             target: z
-                .record(z.unknown())
+                .record(z.string(), z.unknown())
                 .optional()
                 .describe('Find the element and act on it in ONE call, instead of a reticle_query round trip first: { testid } | { text } | { role, name } | { label }. Refuses if it matches more than one, rather than guessing.'),
             action: actionTypeEnum.describe('Action to perform.'),
             args: z
-                .record(z.unknown())
+                .record(z.string(), z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer or the key DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
+                .describe('Action-specific arguments: { value } for fill/select (select also drives an ARIA combobox: it opens it and clicks the option by its label), { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K) or a click/dblclick (Shift+click range select), { button: "right" | "middle" } for a click (right sends contextmenu), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer or the key DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -264,14 +264,14 @@ export const ACT_TOOLS = [
                 .optional()
                 .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`. A press of Escape, Tab, or a modifier shortcut (Cmd+K) is a document key and needs neither.`),
             target: z
-                .record(z.unknown())
+                .record(z.string(), z.unknown())
                 .optional()
                 .describe('Find the element and act on it in ONE call, instead of a reticle_query round trip first: { testid } | { text } | { role, name } | { label }. Refuses if it matches more than one, rather than guessing.'),
             action: actionTypeEnum.describe('Action to perform.'),
             args: z
-                .record(z.unknown())
+                .record(z.string(), z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
+                .describe('Action-specific arguments: { value } for fill/select (select also drives an ARIA combobox: it opens it and clicks the option by its label), { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut or a click (Meta/Control/Shift/Alt), { button: "right" | "middle" } for a click, { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
             predicate: PredicateSchema.optional().describe('Alias for `until`.'),
             until: PredicateSchema.optional().describe('Predicate to wait for after the action completes (same shape as reticle_assert). OMIT to wait for the page to SETTLE — network + DOM idle — the deterministic default instead of a sleep. To assert a consequence AND settle, allOf them: { kind: "allOf", predicates: [<your predicate>, { kind: "settled" }] }.'),
             timeout_ms: timeoutMsSchema
@@ -289,6 +289,7 @@ export const ACT_TOOLS = [
             durable: durableOutput,
             effect: z
                 .unknown()
+                .optional()
                 .describe('The reticle_act result (dispatched, settled, inputMode, etc.).'),
             verdict: z.object({
                 pass: z.boolean(),
@@ -316,9 +317,11 @@ export const ACT_TOOLS = [
             }),
             trace: z
                 .unknown()
+                .optional()
                 .describe('Reaction digest: { window_ms, summary } of what the app did (DOM/network/route/console/signal counts). The full per-event timeline is one reticle_observe { since } away.'),
             summary: z
                 .unknown()
+                .optional()
                 .describe('Bounded causal summary: net {total,errors,headline}, consoleErrors, statePathsChanged, storageKeysChanged, stateDiffs [{path,from,to}], storageDiffs [{key,from,to}], route, signals, layoutShift, longTasks — real before→after diffs (capped), not just readings. THIS IS THE ANSWER TO "what did that click do": console, network, storage and state for this action are all here, so do NOT follow an act with reticle_console + reticle_network + reticle_state to find out — call them only to go deeper into something this block already pointed at. Every list is length-capped so the verdict can never be the field a client truncates; `elided` says which lists lost entries and how many. `stateUnwatched: true` means NO subscribable store is registered, so an empty stateDiffs means unwatched, NOT unchanged — no state conclusion is available until one is registered.'),
             // Promoted out of `effect` on RED only — the file:line the failure came from, the first thing a
             // repair wants. Undeclared, it was stripped on the validating profile exactly like the structured
@@ -354,6 +357,7 @@ export const ACT_TOOLS = [
             engineBlindSpots: engineBlindSpotsOutput,
             honesty: z
                 .unknown()
+                .optional()
                 .describe('The verdict trust block { grade, attribution, coverage, integrity, envelope? } — a green never looks stronger than this. Gate on grade ≥ net AND integrity.clean. Fields that were not measured are OMITTED rather than reported as zero, so treat an absent `envelope` as "not sampled", never as a failure.'),
             since: z
                 .number()
@@ -505,17 +509,12 @@ export const ACT_TOOLS = [
                     ? undefined
                     : buildDivergenceCapsule(links, windowEvents, bufferLost);
                 /*
-                 * The blast radius travels on a GREEN too, which is the only verdict where it is news.
-                 *
-                 * On a red the capsule already carries it and the fault is the headline. On a green nothing
-                 * carried it at all — and "the consequence I declared held, AND this action also posted
-                 * somewhere I never mentioned" is exactly the finding a passing verdict buries. A click that
-                 * works and also fires a DELETE is a green that did extra damage.
+                 * The blast radius goes on a GREEN too. On a red the capsule carries it. On a green, a click
+                 * that works and also sends a DELETE did extra damage, and no other field shows that.
+                 * It is attached only when it is not empty, because its presence is the signal. The full
+                 * capsule stays red-only: its divergence walk and causal summary answer a red's question.
                  *
-                 * One pass over a window already in hand, and only attached when it is non-empty: a field
-                 * that is always present teaches a reader to skim it, and the whole value here is that its
-                 * presence is the signal. The full capsule stays red-only — the divergence walk and the
-                 * causal summary are the expensive halves and answer a question a green does not have.
+                 * One pass over a window that is already in hand.
                  */
                 const greenRadius = verdict.pass ? blastRadius(links, windowEvents) : [];
                 // Grade from what the verdict PROVED, not what it declared. A green anyOf holds on one branch, so

package/dist/surface/tools/agent/compact-envelope.d.ts

@@ -75,6 +75,6 @@ export declare function shapeForAgent(tool: string, args: Record<string, unknown
  */
 export declare function withCompactEnvelope<T extends {
     name: string;
-    inputSchema: z.ZodRawShape;
-    outputSchema?: z.ZodRawShape;
+    inputSchema: Record<string, z.ZodType>;
+    outputSchema?: Record<string, z.ZodType>;
 }>(tools: T[]): T[];

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

@@ -69,7 +69,7 @@ export function buildCoverageTools() {
             outputSchema: {
                 // The app-wide ledger — see features/exhaust/ledger.ts. Loose: run-only, and the levels
                 // carry their own shape.
-                app: z.record(z.unknown()).optional(),
+                app: z.record(z.string(), z.unknown()).optional(),
                 total: z.number(),
                 exercised: z.number(),
                 untouched: z.array(z.object({ ref: z.string(), label: z.string() })),

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

@@ -1,5 +1,13 @@
+import { z } from 'zod';
 import type { ToolDef } from './tool-kit.js';
 import { type ToolSurfaceOrigin } from './tool-surface.js';
+/**
+ * A parameter's description, wherever in its wrappers it was written.
+ *
+ * zod 4 keeps a description on the schema `.describe()` was called on. `z.string().describe(d)
+ * .optional()` has none on the outside, although the JSON Schema an agent reads still carries `d`.
+ */
+export declare function descriptionOf(schema: z.ZodTypeAny): string | undefined;
 /**
  * Build the two dynamic meta-tools over the full tool table. `reticle_run` dispatches through the same
  * `runTool` chokepoint as a direct call, so session-health splicing and every other invariant hold.

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

@@ -8,25 +8,43 @@ import { ReticleTool } from '@reticlehq/core';
 import { ADVERTISE_ALL_ENV } from './tool-surface.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { isPredicateParam, predicateGrammar, } from '@reticlehq/engine/question/predicate/predicate-eval.js';
+/** One wrapper that does not change the value a schema accepts, peeled off; undefined at the core. */
+function unwrapOnce(schema) {
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+        return schema.unwrap();
+    }
+    if (schema instanceof z.ZodDefault) {
+        return schema.removeDefault();
+    }
+    if (schema instanceof z.ZodPipe) {
+        // A transform pipes the schema into the transform; a preprocess pipes the other way round.
+        return (schema.in instanceof z.ZodTransform ? schema.out : schema.in);
+    }
+    return undefined;
+}
 /** The schema without the wrappers that do not change the value it accepts. */
 function unwrappedOf(schema) {
     let inner = schema;
-    for (;;) {
-        if (inner instanceof z.ZodOptional || inner instanceof z.ZodNullable) {
-            inner = inner.unwrap();
-        }
-        else if (inner instanceof z.ZodDefault) {
-            inner = inner.removeDefault();
-        }
-        else if (inner instanceof z.ZodEffects) {
-            inner = inner.innerType();
-        }
-        else {
-            break;
-        }
+    for (let next = unwrapOnce(inner); next !== undefined; next = unwrapOnce(inner)) {
+        inner = next;
     }
     return inner;
 }
+/**
+ * A parameter's description, wherever in its wrappers it was written.
+ *
+ * zod 4 keeps a description on the schema `.describe()` was called on. `z.string().describe(d)
+ * .optional()` has none on the outside, although the JSON Schema an agent reads still carries `d`.
+ */
+export function descriptionOf(schema) {
+    for (let current = schema; current !== undefined;) {
+        if (current.description !== undefined) {
+            return current.description;
+        }
+        current = unwrapOnce(current);
+    }
+    return undefined;
+}
 /**
  * A numeric parameter's enforced bounds, read off the schema that enforces them (#1537).
  *
@@ -39,7 +57,9 @@ function boundsOf(schema) {
     if (!(inner instanceof z.ZodNumber)) {
         return {};
     }
-    const { minValue: min, maxValue: max } = inner;
+    // `.int()` reports the safe-integer range as its bounds. That range bounds nothing an agent sends.
+    const min = Number.MIN_SAFE_INTEGER < (inner.minValue ?? Number.MIN_SAFE_INTEGER) ? inner.minValue : null;
+    const max = Number.MAX_SAFE_INTEGER > (inner.maxValue ?? Number.MAX_SAFE_INTEGER) ? inner.maxValue : null;
     return { ...(null === min ? {} : { min }), ...(null === max ? {} : { max }) };
 }
 /**
@@ -68,7 +88,7 @@ function paramInfo(shape) {
         return {
             name,
             required: !schema.isOptional(),
-            description: schema.description ?? '',
+            description: descriptionOf(schema) ?? '',
             ...(values === undefined ? {} : { values }),
             ...boundsOf(schema),
         };
@@ -260,7 +280,7 @@ callable) {
     };
     const runShape = {
         tool: z.string().describe('Tool name to invoke, e.g. reticle_clock.'),
-        args: z.record(z.unknown()).optional().describe('Arguments object for that tool.'),
+        args: z.record(z.string(), z.unknown()).optional().describe('Arguments object for that tool.'),
         // Accepted AND FORWARDED, not merely tolerated. reticle_run is the only way to reach an
         // unadvertised tool, so on a machine running several projects it has to be aimable — and
         // `sessionId` is the shape an agent already uses on every other tool. Reported from the field