@reticlehq/server 2.4.0 → 2.5.0

package/dist/tools/read-tools.js

@@ -2,18 +2,43 @@
  * Read / record / replay tools — baselines + diff, recordings + replay, narrate, clock, state,
  * explore. Split out of tools.ts; assembled back via...READ_TOOLS.
  */
+import { resolveAnnotateTarget } from '../flows/annotate-target.js';
 import { z } from 'zod';
 import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { proposeConsequences } from '../oracles/propose-consequences.js';
 import { replayProgram } from '../flows/replay.js';
 import { diffLines } from '../project/baselines.js';
-import { selectPath, capDepth } from '../session/state-select.js';
+import { selectPath, capDepth, projectComponentState } from '../session/state-select.js';
 import { costHint } from '../session/output-budget.js';
 import { buildReactionReport } from '../events/reaction.js';
 import { asString, asNumber, parseInteractive } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../session/session-health.js';
+/**
+ * What record-stop says about a step that compiled to no anchor at all.
+ *
+ * `stable: false` does not mean "brittle". It means the compiler found no testid, no accessible
+ * role+name and no component/source, so the step is bound to a live `ref` — a handle that dies with
+ * the session. The replayer already states this outcome in full (see DEGRADED_STEP_REASON): the step
+ * can never resolve on replay.
+ *
+ * The old wording here — "replay may be brittle (in-session only)" — described a fatal condition as
+ * a quality note, so the agent saved the flow and learned the truth several calls later, as an
+ * unhealable `anchor_degraded` drift at flow_verify, by which point nothing on screen points back
+ * to the element that needed the attribute. Capture time is the only moment the fix is cheap: the
+ * element is still on the page and the human is still in the loop.
+ */
+function unanchoredWarning(count) {
+    return (`${String(count)} step(s) not bound to a testid, an accessible role+name, or a component — ` +
+        'they are pinned to a live ref, so they will replay in THIS session and can never resolve in ' +
+        'another one. Add a data-testid to those elements and record the flow again, or accept that ' +
+        'this recording is single-session only.');
+}
+/** Severities the presenter HUD can render. */
+const HUD_LEVELS = ['info', 'warn', 'error'];
+const HUD_LEVEL_LIST = HUD_LEVELS.join(' | ');
+const hudLevelEnum = z.enum(HUD_LEVELS);
 export const READ_TOOLS = [
     {
         name: ReticleTool.BASELINE_SAVE,
@@ -64,7 +89,11 @@ export const READ_TOOLS = [
             buffer: z.unknown().optional(),
         },
         handler: async (deps, args) => {
-            const name = asString(args['baseline']) ?? 'default';
+            // `name` too: the merged reticle_baseline family made this required field optional, and the
+            // SIBLING that creates a baseline calls it `name` — its description even says to reuse it
+            // here. So `{ action:"diff", name:"x" }` is a valid call that used to look up 'default' and
+            // report "no baseline named 'default'", naming something the caller never mentioned.
+            const name = asString(args['baseline']) ?? asString(args['name']) ?? 'default';
             const base = deps.baselines.get(name);
             if (base === undefined)
                 throw new Error(`no baseline named '${name}'`);
@@ -127,10 +156,17 @@ export const READ_TOOLS = [
         },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const name = asString(args['recordingName']) ?? 'default';
+            // The recording actually RUNNING when there is exactly one, not the literal name `default` —
+            // the same defaulting that made `annotate` report "no steps" against a recording full of them.
+            // With several running, `default` stays the documented answer rather than a guess.
+            const name = resolveAnnotateTarget(asString(args['recordingName']), deps.recordings.active());
             const rec = deps.recordings.stop(name);
-            if (rec === undefined)
-                throw new Error(`no active recording named '${name}'`);
+            if (rec === undefined) {
+                const active = deps.recordings.active();
+                throw new Error(0 === active.length
+                    ? `no active recording named '${name}' — none is in progress`
+                    : `no active recording named '${name}'; in progress: ${active.map((r) => `'${r}'`).join(', ')}`);
+            }
             const events = session.eventsSince(rec.cursor);
             const program = {
                 name,
@@ -147,7 +183,7 @@ export const READ_TOOLS = [
                 program,
                 ...(unstable > 0
                     ? {
-                        warning: `${String(unstable)} step(s) not bound to a testid; replay may be brittle (in-session only)`,
+                        warning: unanchoredWarning(unstable),
                     }
                     : {}),
                 ...(proposedConsequences.length > 0 ? { proposedConsequences } : {}),
@@ -186,7 +222,7 @@ export const READ_TOOLS = [
                 throw new Error(`no compiled recording named '${name}'`);
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const since = session.elapsed();
-            const steps = await replayProgram(session, program, args['confirmDangerous'] === true);
+            const steps = await replayProgram(session, program, true === args['confirmDangerous']);
             return { recordingName: name, since, steps, ok: steps.every((s) => s.ok) };
         },
     },
@@ -197,10 +233,11 @@ export const READ_TOOLS = [
             text: z
                 .string()
                 .describe('Short sentence describing your next action, shown on the presenter HUD for the developer watching.'),
-            level: z
-                .string()
+            // Derived, like every other advertised vocabulary here: a free string let a typo through to
+            // a HUD that then rendered an unknown severity.
+            level: hudLevelEnum
                 .optional()
-                .describe('Display severity: info | warn | error. Default: info.'),
+                .describe(`Display severity: ${HUD_LEVEL_LIST}. Default: info.`),
             ...sessionIdShape,
         },
         outputSchema: { ok: z.boolean() },
@@ -227,9 +264,11 @@ export const READ_TOOLS = [
             reset: z.boolean().optional().describe('Restore the real clock.'),
             ...sessionIdShape,
         },
+        // The command returns `{ frozen }`. It used to declare `{ ok, elapsed }` — neither of which any
+        // clock code path produces — and MCP strips undeclared fields from structuredContent, so a
+        // successful freeze and a failed one both validated to `{}` and became indistinguishable.
         outputSchema: {
-            ok: z.boolean().optional(),
-            elapsed: z.number().optional(),
+            frozen: z.boolean().optional(),
         },
         handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CLOCK, {
             freeze: args['freeze'],
@@ -275,7 +314,21 @@ export const READ_TOOLS = [
             // concludes the key it wants is absent when it is merely past the cap.
             totalKeys: z.number().optional(),
             component: z
-                .object({ ok: z.boolean(), reason: z.string().optional(), state: z.unknown().optional() })
+                .object({
+                ok: z.boolean(),
+                reason: z.string().optional(),
+                state: z.unknown().optional(),
+                // The component name and the projected hook VALUES — declared so a schema-strict client
+                // keeps them (they were the point of passing `ref` at all).
+                component: z.string().optional(),
+                hooks: z.array(z.unknown()).optional(),
+                // Present only when effect hooks were projected out. Declared for the same reason as the
+                // store truncation report below: a shortened list with no marker reads as a complete one.
+                truncation: z
+                    .object({ droppedItems: z.number(), note: z.string() })
+                    .optional()
+                    .describe('Present only when effect hooks were dropped — `hooks` is a projection.'),
+            })
                 .optional(),
             // Truncation report — present ONLY when a transport cap trimmed the value. Declared so a
             // schema-strict client on the `full` profile KEEPS it: this is a false-green GUARD, and dropping
@@ -298,23 +351,31 @@ export const READ_TOOLS = [
             // Forward path/depth so a CURRENT browser SDK scopes the read IN-PAGE, before the transport —
             // the value never gets size-truncated in transit. (An older SDK ignores them and returns the
             // whole store; we then scope server-side below as a back-compat fallback.)
-            const result = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.STATE_READ, {
+            const raw = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.STATE_READ, {
                 ref: args['ref'],
                 store,
                 path,
                 depth,
             });
+            // Project the component hook read BEFORE anything else touches it: React hands back the raw
+            // fiber hook list, whose effect entries are chained null-filled internals an agent cannot act
+            // on (measured: 2632 -> 1459 bytes on a five-state/three-effect component). Done here rather
+            // than in the SDK so an older browser build gets the same projection. The drop is disclosed
+            // on `component.truncation`.
+            const result = 'object' === typeof raw && null !== raw && 'component' in raw
+                ? { ...raw, component: projectComponentState(raw.component) }
+                : raw;
             // Normalize storeNames to a string[] regardless of how the wire delivered it — the
             // outputSchema requires an array, and a non-array here makes MCP reject the whole result
             // (so the agent gets nothing instead of the state). Defensive: a string becomes a 1-element array.
             const root = result;
             const names = Array.isArray(root.storeNames)
-                ? root.storeNames.filter((n) => typeof n === 'string')
-                : typeof root.storeNames === 'string' && root.storeNames.length > 0
+                ? root.storeNames.filter((n) => 'string' === typeof n)
+                : 'string' === typeof root.storeNames && root.storeNames.length > 0
                     ? [root.storeNames]
                     : [];
             // The browser already scoped it in-page (the `found` shape) — pass through, just safe storeNames.
-            if (typeof root.found === 'boolean') {
+            if ('boolean' === typeof root.found) {
                 return { ...root, storeNames: names };
             }
             if (path === undefined && depth === undefined) {
@@ -372,7 +433,7 @@ export const READ_TOOLS = [
                 // The walk stops at its node cap and returns a document-order prefix, so an inventory taken
                 // from a big page is a floor, not a census — and this is the tool crawl's description points
                 // agents at first for "a non-destructive list of what is here".
-                ...(snap.truncated === true ? { truncated: true } : {}),
+                ...(true === snap.truncated ? { truncated: true } : {}),
                 consoleErrors,
                 hint: 'act on each ref, observe the reaction, and report failed requests / console errors / dead controls',
                 // Buffer-honesty: the console-error count spans the whole buffer, which evicts — signal it.
@@ -412,13 +473,13 @@ export const READ_TOOLS = [
             const area = asString(args['area']);
             const key = asString(args['key']);
             const result = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.STORAGE_READ, area !== undefined ? { area } : {});
-            const data = (typeof result === 'object' && result !== null ? result : {});
+            const data = ('object' === typeof result && result !== null ? result : {});
             if (key === undefined)
                 return data;
             // Look up the key in the scoped area, or across all three areas when none was named.
             const areas = area !== undefined ? [data] : [data['local'], data['session'], data['cookies']];
             for (const a of areas) {
-                if (typeof a === 'object' && a !== null && key in a) {
+                if ('object' === typeof a && a !== null && key in a) {
                     return { area, key, value: String(a[key]), found: true };
                 }
             }

package/dist/tools/real-input-attempt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The native-input attempt — everything that decides whether a pointer action is driven through a
+ * real input provider or falls back to the occlusion-honest synthetic path, and WHY.
+ *
+ * Split out of act-tools.ts along its natural seam: the act tools care only about the outcome
+ * (`result` defined = it went native), never about provider availability, box resolution,
+ * drag-target inspection or the reason taxonomy.
+ */
+import { ActionType, InputModeReason } from '@reticlehq/core';
+import type { Session } from '../session/session.js';
+import { type ToolDeps } from './tool-kit.js';
+interface RealActResult {
+    /** Defined only on a successful native action; `undefined` means the synthetic path runs. */
+    result: unknown;
+    settled: boolean;
+    /** Set when a provider was available but threw — surfaces the fallback to the agent. */
+    fellBack?: boolean;
+    /** Why we went synthetic despite a configured provider (field bug #2: never a silent fallback). */
+    reason?: InputModeReason;
+}
+/**
+ * Attempt to drive a pointer action via native input. Returns a synthetic outcome (with a
+ * `reason` when a provider is configured) whenever the synthetic path should run — no matching
+ * page, unresolvable box, declined, etc. A throw inside the provider becomes a synthetic fallback
+ * flagged with `fellBack`. `result` is defined only on a real success.
+ */
+export declare function tryRealInput(deps: ToolDeps, session: Session, ref: string, action: ActionType, args: Record<string, unknown>): Promise<RealActResult>;
+export {};

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

@@ -0,0 +1,88 @@
+/**
+ * The native-input attempt — everything that decides whether a pointer action is driven through a
+ * real input provider or falls back to the occlusion-honest synthetic path, and WHY.
+ *
+ * Split out of act-tools.ts along its natural seam: the act tools care only about the outcome
+ * (`result` defined = it went native), never about provider availability, box resolution,
+ * drag-target inspection or the reason taxonomy.
+ */
+import { ActionType, InputModeReason, ReticleCommand } from '@reticlehq/core';
+import { isPointerAction } from '../input/real-input.js';
+import { assertDragNotDestructive, assertNotDestructive } from './act-danger.js';
+import { NATIVE_INPUT_ARG } from '@reticlehq/core';
+import { asString, asRecord } from './tools-helpers.js';
+import { commandOrThrow } from './tool-kit.js';
+import { asBox } from './act-helpers.js';
+/** Synthetic outcome with a diagnostic reason (provider configured but native input skipped). */
+function synthetic(reason) {
+    return reason === undefined
+        ? { result: undefined, settled: false }
+        : { result: undefined, settled: false, reason };
+}
+/**
+ * Attempt to drive a pointer action via native input. Returns a synthetic outcome (with a
+ * `reason` when a provider is configured) whenever the synthetic path should run — no matching
+ * page, unresolvable box, declined, etc. A throw inside the provider becomes a synthetic fallback
+ * flagged with `fellBack`. `result` is defined only on a real success.
+ */
+export async function tryRealInput(deps, session, ref, action, args) {
+    const provider = deps.realInput;
+    if (provider === undefined)
+        return synthetic(); // real input not configured — no diagnostic
+    if (!isPointerAction(action))
+        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
+    const inner = asRecord(args['args']);
+    // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
+    // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
+    // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
+    // isTrusted-gated handlers). hover/drag genuinely need native pointer state, so they stay real.
+    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) &&
+        inner[NATIVE_INPUT_ARG] !== true) {
+        return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
+    }
+    if (!(await provider.isAvailableFor(session.url)))
+        return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
+    assertNotDestructive(action, inner, inspected);
+    const box = asBox(inspected);
+    if (box === undefined)
+        return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
+    let toBox;
+    if (action === ActionType.DRAG) {
+        const toRef = asString(inner['toRef']);
+        if (toRef === undefined)
+            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+        const targetInspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, {
+            ref: toRef,
+        });
+        // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
+        // thing being dragged looks.
+        assertDragNotDestructive(inner, inspected, targetInspected);
+        toBox = asBox(targetInspected);
+        if (toBox === undefined)
+            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+    }
+    const performArgs = {};
+    const value = asString(inner['value']);
+    if (value !== undefined)
+        performArgs.value = value;
+    const text = asString(inner['text']);
+    if (text !== undefined)
+        performArgs.text = text;
+    if (toBox !== undefined)
+        performArgs.toBox = toBox;
+    try {
+        const performed = await provider.perform(session.url, action, box, performArgs);
+        if (!performed.performed)
+            return synthetic(InputModeReason.PROVIDER_DECLINED);
+        return { result: { performed: true, center: performed.center, action }, settled: true };
+    }
+    catch {
+        return {
+            result: undefined,
+            settled: false,
+            fellBack: true,
+            reason: InputModeReason.PROVIDER_ERROR,
+        };
+    }
+}

package/dist/tools/reconcile-tools.js

@@ -28,17 +28,17 @@ async function capturedBodies(session, since, urlContains) {
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
-        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
         if (urlContains !== undefined && !url.includes(urlContains))
             continue;
         total += 1;
         const raw = event.data['responseBody'];
-        if (typeof raw !== 'string' || raw.length === 0)
+        if (typeof raw !== 'string' || 0 === raw.length)
             continue;
         // A capped body is not an absent one. Recover the records that closed before the cut rather than
         // reporting nothing about the page with the most data on it.
         const salvaged = salvageJson(raw);
-        if (salvaged.values.length === 0)
+        if (0 === salvaged.values.length)
             continue;
         bodies.push(...salvaged.values);
         withBody += 1;
@@ -79,11 +79,11 @@ export const RECONCILE_TOOLS = [
             const { bodies, withBody, total, truncated } = await capturedBodies(session, since, asString(args['urlContains']));
             // An empty result over data that was never read is the exact false green this tool exists to
             // prevent, so the two cases are reported differently and neither is silent.
-            if (bodies.length === 0) {
+            if (0 === bodies.length) {
                 return withControl(session, {
                     mismatches: [],
                     compared: 0,
-                    note: total === 0
+                    note: 0 === total
                         ? 'no responses in this window matched — nothing was compared'
                         : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. Enable it where your app calls connect(): \`reticle.connect({ captureNetworkBodies: true })\`, then re-run`,
                 });
@@ -92,7 +92,7 @@ export const RECONCILE_TOOLS = [
                 mode: SnapshotMode.FULL,
             });
             const tree = snapshot.tree;
-            const mismatches = reconcile(bodies, typeof tree === 'string' ? tree : '');
+            const mismatches = reconcile(bodies, 'string' === typeof tree ? tree : '');
             // A truncated body is declared whether or not anything was found in it: "no mismatches" over a
             // partially-read payload is a weaker statement than over a whole one, and the difference is
             // exactly the kind of omission this layer exists to refuse.
@@ -100,7 +100,7 @@ export const RECONCILE_TOOLS = [
                 ? {
                     note: `${String(truncated)} of ${String(withBody)} response(s) exceeded the body cap and were read only up to the cut — records after it were not compared`,
                 }
-                : mismatches.length === 0
+                : 0 === mismatches.length
                     ? {
                         note: `compared ${String(withBody)} response(s); nothing on screen contradicts them`,
                     }

package/dist/tools/reload-result.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What `navigate { reload: true }` reports.
+ *
+ * It answered a bare `{ ok: true }`, while the URL branch of the same tool returns `confirmed: false`
+ * plus a note — because `ok` means the browser accepted the instruction, not that the page arrived.
+ * Identical semantics, one branch disclosing them and one not, and the silent one is the path most
+ * likely to need the caveat: a reload tears the SDK down, and a caller that acts on `ok: true` hits
+ * the window before it comes back.
+ *
+ * The permanent session loss reported alongside this is fixed separately — session-continuity.ts
+ * remembers the id in sessionStorage so a reload rejoins the SAME session instead of appearing as a
+ * new one. This is the remaining half: saying that the page is not back yet.
+ */
+export declare function reloadResult(reconnected?: boolean): Record<string, unknown>;

package/dist/tools/reload-result.js

@@ -0,0 +1,29 @@
+/**
+ * What `navigate { reload: true }` reports.
+ *
+ * It answered a bare `{ ok: true }`, while the URL branch of the same tool returns `confirmed: false`
+ * plus a note — because `ok` means the browser accepted the instruction, not that the page arrived.
+ * Identical semantics, one branch disclosing them and one not, and the silent one is the path most
+ * likely to need the caveat: a reload tears the SDK down, and a caller that acts on `ok: true` hits
+ * the window before it comes back.
+ *
+ * The permanent session loss reported alongside this is fixed separately — session-continuity.ts
+ * remembers the id in sessionStorage so a reload rejoins the SAME session instead of appearing as a
+ * new one. This is the remaining half: saying that the page is not back yet.
+ */
+/** The reload's own disclosure — the same shape and the same advice the URL branch gives. */
+const RELOAD_NOTE = 'ok means the reload was DISPATCHED, not that the page came back — the SDK is torn down by the ' +
+    'reload itself, so nothing here can see the new document yet. Call reticle_sessions to confirm ' +
+    'the session reconnected before acting; the session id is preserved across a reload, so it will ' +
+    'be the same one.';
+/**
+ * What a CONFIRMED reload says. The page re-announced itself under the same id before this returned,
+ * so the next call is safe — which is the whole reason the tool now waits instead of advising.
+ */
+const RELOAD_RECONNECTED_NOTE = 'the page came back and re-announced itself under the same session id, so this session is live ' +
+    'again — no re-selection needed. Anything captured before the reload is gone with the old document.';
+export function reloadResult(reconnected = false) {
+    return reconnected
+        ? { ok: true, confirmed: true, note: RELOAD_RECONNECTED_NOTE }
+        : { ok: true, confirmed: false, note: RELOAD_NOTE };
+}

package/dist/tools/snapshot-delta.d.ts

@@ -18,13 +18,13 @@ export declare const SnapshotDeltaMode: {
     readonly UNCHANGED: "unchanged";
 };
 export type SnapshotDeltaMode = (typeof SnapshotDeltaMode)[keyof typeof SnapshotDeltaMode];
-export interface SnapshotDelta {
+interface SnapshotDelta {
     added: string[];
     removed: string[];
     addedCount: number;
     removedCount: number;
 }
-export type DeltaDecision = {
+type DeltaDecision = {
     mode: typeof SnapshotDeltaMode.FULL;
 } | {
     mode: typeof SnapshotDeltaMode.UNCHANGED;
@@ -43,9 +43,7 @@ export declare class SnapshotCache {
     remember(key: string, route: string, tree: string): void;
 }
 export declare function snapshotCacheKey(sessionId: string, scope: string, mode: string): string;
-/** Said out loud when a diff was computed over a capped tree, so "unchanged" cannot mean "nothing happened". */
-export declare const CAPPED_DIFF_NOTE = "this diff covers only the first N nodes of the page (the snapshot hit its cap), so \"unchanged\" means \"unchanged in the part that was captured\" \u2014 narrow with `scope` to see the rest";
-export interface SnapshotDeltaOpts {
+interface SnapshotDeltaOpts {
     sessionId: string;
     scope: string;
     mode: string;
@@ -58,3 +56,4 @@ export interface SnapshotDeltaOpts {
  * the pure `snapshotDelta`.
  */
 export declare function applySnapshotDelta(raw: unknown, opts: SnapshotDeltaOpts, cache: SnapshotCache): unknown;
+export {};

package/dist/tools/tool-kit.d.ts

@@ -35,6 +35,14 @@ export interface ToolDeps {
     reticleRoot: string;
     /** injected clock for the contract's generatedAt stamp. */
     now: () => number;
+    /**
+     * The port this daemon's bridge listens on.
+     *
+     * Needed wherever a message has to name the OTHER half of a port mismatch — the commonest reason
+     * a leased tab loads the app and never dials in. Optional so every existing test construction of
+     * ToolDeps keeps working; absent falls back to the default port.
+     */
+    bridgePort?: number;
 }
 export interface ToolDef {
     name: string;

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

@@ -0,0 +1,83 @@
+import type { ToolDef } from './tools.js';
+/**
+ * There is ONE tool surface. This is not a menu.
+ *
+ * The advertised tool DEFINITIONS are re-sent to the model on every turn, so the surface is a
+ * per-turn cost that compounds across a loop, and fewer tools also makes the model wander less.
+ * What ships is the verify loop (navigate→look→act→observe→assert, with direct network + console +
+ * state) advertised directly, plus two meta-tools — `reticle_tools` to discover and `reticle_run` to
+ * invoke — that keep every other tool exactly one call away. Nothing is unreachable; the cold tail
+ * just is not re-sent every turn.
+ *
+ * Five profiles were tried. Four are gone, each for a measured reason rather than a taste:
+ *
+ * `core` was BYTE-IDENTICAL to the default — 16 tools, 18,183 bytes, the same list. One behaviour
+ * behind two names is how "I set it and nothing changed" becomes a support question with no answer.
+ *
+ * `standard` advertised 17 more tools directly for ~3,500 extra tokens EVERY TURN, buying only the
+ * removal of an occasional `reticle_run` hop. Nothing about that was characterisable as a use case.
+ *
+ * `dynamic` advertised the 2 meta-tools and nothing else. Not one harness, app or bench ever
+ * selected it, and this repo's own measurement (bench/agent-loop-and-replay.md) says a pure
+ * on-demand surface does NOT hold accuracy with a generic model: "it needs the hot-set schemas.
+ * On-demand is for the cold tail, not the hot path." An option that is unused and measured-worse is
+ * a trap, not a choice — it looks like a 4,000-token saving and costs correctness.
+ *
+ * ALL is what remains, and it is deliberately NOT a profile: it is a verification switch. It is the
+ * only mode that advertises `outputSchema`, which is what makes the MCP layer validate tool OUTPUT —
+ * the check that caught `reticle_verify_change` returning a payload its own schema rejected. It
+ * cannot be folded into the default: measured, carrying output schemas on the 16-tool surface costs
+ * 18,183 -> 41,117 bytes, 2.26x, +5,733 tokens per turn. And it cannot simply be deleted without
+ * losing that defect class. So it stays, named for what it is, and no user is asked to pick it.
+ *
+ * Sizes are NOT restated here — not as a current figure, not as a historical one. Four generations
+ * of this comment got them wrong. They live in surface-sizes.test.ts, which reads them off the real
+ * surface. (The numbers above are the two measurements that JUSTIFY a decision, which is a different
+ * job from documenting the current size; both were taken with a fresh daemon per reading.)
+ */
+export declare const TOOL_SURFACE: {
+    /** What every user gets: the verify loop, plus the 2 meta-tools that reach everything else. */
+    readonly DEFAULT: "default";
+    /** Every tool advertised directly, WITH output schemas. A verification switch — see above. */
+    readonly ALL: "all";
+};
+export type ToolSurface = (typeof TOOL_SURFACE)[keyof typeof TOOL_SURFACE];
+/**
+ * The switch that turns on the full, output-schema-carrying surface. A boolean, not a menu.
+ *
+ * Named for what it does rather than which "profile" it selects, because the previous name invited
+ * users to shop among alternatives that did not meaningfully differ.
+ */
+export declare const ADVERTISE_ALL_ENV = "RETICLE_ADVERTISE_ALL_TOOLS";
+/**
+ * The retired setting, still read so nobody's shell profile breaks.
+ *
+ * Every value it ever accepted resolves to something sensible: `full` to the ALL surface, everything
+ * else to the default. Silently honouring them would repeat the original sin, so `describeToolSurface`
+ * says the setting retired and what was used instead.
+ */
+export declare const TOOL_PROFILE_ENV = "RETICLE_TOOL_PROFILE";
+export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Which surface is live.
+ *
+ * `explicit` is the programmatic override (tests, `advertisedTools` callers). Otherwise the ALL
+ * switch decides, and the retired setting is honoured last so an old shell profile still works.
+ */
+export declare function resolveToolSurface(explicit?: string): ToolSurface;
+/** The live surface plus what chose it — see describeToolSurface. */
+export interface ToolSurfaceOrigin {
+    active: ToolSurface;
+    source: string;
+}
+/**
+ * Which surface is live, and what chose it.
+ *
+ * These settings are read by the DAEMON at startup, never by the client, so exporting one in an
+ * agent's environment while a daemon is already running changes nothing at all — which is exactly
+ * the observation that produced a "standard and full advertise the same tools" report. Documenting
+ * that was not enough; the setting failing to take has to be VISIBLE, so this rides along in the
+ * reticle_tools catalog.
+ */
+export declare function describeToolSurface(active: ToolSurface, requested?: string): ToolSurfaceOrigin;
+export declare function filterTools(tools: ToolDef[], surface: ToolSurface): ToolDef[];