@reticlehq/server 2.4.0 → 2.5.0

package/dist/tools/tool-surface.js

@@ -0,0 +1,204 @@
+import { ReticleTool } from './tool-names.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 const TOOL_SURFACE = {
+    /** What every user gets: the verify loop, plus the 2 meta-tools that reach everything else. */
+    DEFAULT: 'default',
+    /** Every tool advertised directly, WITH output schemas. A verification switch — see above. */
+    ALL: 'all',
+};
+/**
+ * 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 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 const TOOL_PROFILE_ENV = 'RETICLE_TOOL_PROFILE';
+const RETIRED_PROFILE_VALUES = {
+    full: TOOL_SURFACE.ALL,
+    hybrid: TOOL_SURFACE.DEFAULT,
+    core: TOOL_SURFACE.DEFAULT,
+    standard: TOOL_SURFACE.DEFAULT,
+    dynamic: TOOL_SURFACE.DEFAULT,
+};
+// The set an agent needs to verify a change end-to-end. Tool DEFINITIONS are re-sent every turn, so
+// this set is a per-turn cost, and every name in it has to earn its place.
+//
+// MEASURED per-turn `tools/list` cost, off the real wire (spawn `mcp`, read tools/list, measure the
+// serialized result), with a FRESH DAEMON per reading — the setting is read by the daemon at startup,
+// so a loop that reuses one daemon measures the first surface every time and looks like proof that
+// the setting does nothing. That happened while taking this very reading.
+//
+//   default    18,183 B  ~4,546 tok/turn    16 tools
+//   all       127,903 B ~31,976 tok/turn    48 tools
+//
+// Treat these as the SHAPE of the gap and re-measure before quoting one; counts are asserted in
+// surface-sizes.test.ts, never from this comment.
+//
+// Where the cost sits on the default surface: inputSchema is 76% of the payload (parameter
+// descriptions are half of that), tool descriptions are 12%, outputSchema ~0 because it is dropped.
+// So the next real saving is in parameter prose, not in dropping more tools.
+//
+// There is a floor, though: an 8-tool cut (dropping act/navigate/wait_for/sessions) was MEASURED to
+// regress real-agent accuracy 5/5 -> 3/5, because the model loses scaffolding and wanders on harder
+// flows. Direct network/console stay (far more discoverable than observe-with-filters -> fewer turns,
+// better verdicts).
+//
+// Evidence status: the 5/5 figure came from a single gpt-4o run and is STALE as a justification.
+// Current-model evidence is indirect but real — the cost-delta run (bench/fix-loop/COST-DELTA.md)
+// drove this surface on a current model and fixed 4/4 cells with ~25% FEWER tool calls than the
+// baseline. A formal A/B against a leaner surface on a current model is still UNRUN.
+// See bench/agent-loop-and-replay.md.
+export const CORE_TOOL_NAMES = new Set([
+    ReticleTool.SESSIONS,
+    ReticleTool.NAVIGATE,
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.ACT,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.OBSERVE,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.WAIT_FOR,
+    ReticleTool.ASSERT,
+    ReticleTool.STATE,
+    // INSPECT is what turns a finding into an EDIT: it maps a DOM node to `src/App.tsx:104`. Finding a
+    // bug is half the job; knowing which file to open is the half that makes the agent useful, and it
+    // is the one capability here with no substitute in any other verification tool. It sat in
+    // `standard`, so under the default profile an agent had to already know it existed and reach it
+    // through reticle_run — which, observed over a drive of the whole surface, means it never gets called.
+    // The measured floor that justifies a lean core was about CUTTING to 8 (accuracy 5/5 → 3/5), not
+    // about holding at 12; one tool of schema tax to close the find→fix loop is the right trade.
+    ReticleTool.INSPECT,
+    // FEEDBACK is in every profile for the same reason INSPECT is: a tool an agent has to already know
+    // about, and reach through reticle_run, is a tool that never gets called. That is fatal here in a way
+    // it is not elsewhere — an unadvertised feedback channel collects nothing, which is indistinguishable
+    // from not having built one. It is also the cheapest tool on the surface to carry (three params) and
+    // the only one whose whole purpose is telling us which of the other fifteen are failing.
+    ReticleTool.FEEDBACK,
+    // SESSION is here because the product ORDERS the agent to call it. The session lease block is
+    // spliced onto the first result of every session ("call reticle_session {action:'yield'}"), and
+    // the pause hint is spliced onto every refusal while a human has the session paused, where
+    // {action:"resume"} is the only exit. Both were naming a tool the default surface did not
+    // advertise: an agent that obeyed got `unknown tool`, and an agent that did not left the panel
+    // reading "live" after it had stopped driving — which is the state the whole handback protocol
+    // exists to prevent.
+    //
+    // Measured cost: ~1.3 KB of prose (455 B description + ~780 B of parameter descriptions) on a
+    // surface whose prose is ~23.7 KB, so roughly +5%, a few hundred tokens a turn. The alternative —
+    // deleting the instruction from the lease and the pause hint — deletes the handback protocol,
+    // because there is nowhere else those two calls are ever named.
+    ReticleTool.SESSION,
+]);
+/** Is the truthy form of a boolean env var set? `1`, `true`, `yes` — anything else is off. */
+function envFlagOn(raw) {
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return '1' === value || 'true' === value || 'yes' === value || 'on' === value;
+}
+/**
+ * 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 function resolveToolSurface(explicit) {
+    if (explicit === TOOL_SURFACE.ALL)
+        return TOOL_SURFACE.ALL;
+    if (explicit === TOOL_SURFACE.DEFAULT)
+        return TOOL_SURFACE.DEFAULT;
+    const retiredExplicit = explicit === undefined ? undefined : RETIRED_PROFILE_VALUES[explicit];
+    if (retiredExplicit !== undefined)
+        return retiredExplicit;
+    if (envFlagOn(process.env[ADVERTISE_ALL_ENV]))
+        return TOOL_SURFACE.ALL;
+    const retiredEnv = RETIRED_PROFILE_VALUES[process.env[TOOL_PROFILE_ENV] ?? ''];
+    return retiredEnv ?? TOOL_SURFACE.DEFAULT;
+}
+/**
+ * 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 function describeToolSurface(active, requested) {
+    const retired = requested ?? process.env[TOOL_PROFILE_ENV];
+    if (retired !== undefined && retired in RETIRED_PROFILE_VALUES) {
+        return {
+            active,
+            source: `${TOOL_PROFILE_ENV}=${retired} is RETIRED — there is one tool surface now; using '${active}' (set ${ADVERTISE_ALL_ENV}=1 for the full, schema-carrying surface)`,
+        };
+    }
+    if (retired !== undefined && 0 < retired.length) {
+        return {
+            active,
+            source: `${TOOL_PROFILE_ENV} is RETIRED and '${retired}' was never one of its values; using '${active}'`,
+        };
+    }
+    const flag = process.env[ADVERTISE_ALL_ENV];
+    if (envFlagOn(flag)) {
+        return { active, source: `${ADVERTISE_ALL_ENV} set in the DAEMON's environment at startup` };
+    }
+    // "unset" and "set to 0" are different facts, and only one of them means "you did not ask for it".
+    // Reporting the second as the first is how somebody spends an afternoon on a switch that IS being
+    // read and is simply off.
+    return flag === undefined || 0 === flag.length
+        ? {
+            active,
+            source: `the one tool surface (${ADVERTISE_ALL_ENV} unset when the daemon started)`,
+        }
+        : { active, source: `the one tool surface (${ADVERTISE_ALL_ENV}='${flag}' is off)` };
+}
+export function filterTools(tools, surface) {
+    // CORE_TOOL_NAMES is what it always really was: the set advertised directly. It was never the
+    // interesting thing about the `core` PROFILE, whose only distinction was a second name for this.
+    if (surface === TOOL_SURFACE.DEFAULT)
+        return tools.filter((t) => CORE_TOOL_NAMES.has(t.name));
+    return tools;
+}

package/dist/tools/tools-helpers.js

@@ -11,13 +11,13 @@ export function parseInteractive(tree) {
     return items;
 }
 export function asString(value) {
-    return typeof value === 'string' ? value : undefined;
+    return 'string' === typeof value ? value : undefined;
 }
 export function asNumber(value) {
-    return typeof value === 'number' ? value : undefined;
+    return 'number' === typeof value ? value : undefined;
 }
 export function asRecord(value) {
-    return typeof value === 'object' && value !== null ? value : {};
+    return 'object' === typeof value && value !== null ? value : {};
 }
 /**
  * A `{ file, line }` source location off an untrusted result payload, or undefined.
@@ -27,15 +27,15 @@ export function asRecord(value) {
  * worse than no location at all — it looks like an answer.
  */
 export function sourceOf(value) {
-    if (value === null || typeof value !== 'object')
+    if (null === value || typeof value !== 'object')
         return undefined;
     const record = value;
     const file = record['file'];
     const line = record['line'];
-    if (typeof file !== 'string' || file.length === 0 || typeof line !== 'number')
+    if (typeof file !== 'string' || 0 === file.length || typeof line !== 'number')
         return undefined;
     const out = { file, line };
-    if (typeof record['column'] === 'number')
+    if ('number' === typeof record['column'])
         out.column = record['column'];
     return out;
 }

package/dist/tools/tools.d.ts

@@ -1,3 +1,18 @@
 import { type ToolDef } from './tool-kit.js';
+import { type MergePlan } from './merge-tools.js';
 export type { ToolDef, ToolDeps } from './tool-kit.js';
+/**
+ * surface consolidation. Tool defs are re-sent EVERY turn, so the advertised count is a per-turn
+ * tax multiplied by loop length. Sibling families collapse into one action-dispatched tool; the member
+ * handlers stay defined above and are simply no longer advertised separately.
+ *
+ * Guardrail (from the plan): the 12-tool core hot-set keeps its EXACT names and shapes and is never
+ * merged — sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state.
+ */
+export declare const MERGE_PLANS: MergePlan[];
+/**
+ * Retired from the MCP surface entirely (capability preserved elsewhere, per the plan):
+ * - run_record: auto-recording on flow_replay already persists run outcomes.
+ */
+export declare const RETIRED_FROM_SURFACE: string[];
 export declare const TOOLS: ToolDef[];

package/dist/tools/tools.js

@@ -1,10 +1,22 @@
 import { z } from 'zod';
-import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { withSizeCost } from '../session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './snapshot-delta.js';
 import { asString, asNumber } from './tools-helpers.js';
+import { normalizeQueryArgs } from './query-shape.js';
 import { paginateQueryResult } from './query-paginate.js';
+/**
+ * The query strategies, derived from the enum in core — never retyped.
+ *
+ * The description used to hand-list them and had already drifted: it named six and omitted
+ * `component`, which is real and works. Deriving both the schema and the prose from one source is
+ * the repo's own rule, and here it is also the difference between refusing `by:'css'` and silently
+ * answering "0 matches" to it.
+ */
+const QUERY_BY_VALUES = Object.values(QueryBy);
+const QUERY_BY_LIST = QUERY_BY_VALUES.join(' | ');
+const queryByEnum = z.enum(QUERY_BY_VALUES);
 import { CONTRACT_TOOLS } from './contract-tools.js';
 import { DOMAIN_TOOLS } from '../domain/domain-tools.js';
 import { BROWSER_TOOLS } from './browser-tools.js';
@@ -49,6 +61,10 @@ const RAW_TOOLS = [
                 title: z.string().optional(),
                 adapters: z.array(z.string()),
                 hasCapabilities: z.boolean(),
+                versionSkew: z
+                    .string()
+                    .optional()
+                    .describe("Present only when this page's SDK version differs from the daemon's. A skewed pair connects and then disagrees about tool behaviour — usually surfacing as a bare -32000. Fix it before trusting any verdict from this session."),
                 lastSeenMs: z.number(),
                 throttled: z.boolean(),
                 focused: z.boolean(),
@@ -151,19 +167,24 @@ const RAW_TOOLS = [
                 sessionId: resolved.id,
                 scope: asString(args['scope']) ?? '',
                 mode,
-                diff: args['diff'] === true,
+                diff: true === args['diff'],
             }, SNAPSHOT_CACHE)));
         },
     },
     {
         name: ReticleTool.QUERY,
         example: { by: 'testid', value: 'todo-list' },
-        description: 'Find elements by Testing-Library semantics, INCLUDING open shadow roots — `count_only:true` gives just the count (~30x smaller); `limit` caps descriptors. Pass `by` (role|text|label|placeholder|testid|alt) and `value` (the query string). Returns matching refs + descriptors + visibility. Pass `attrs:["href"]` to project attributes (link/image URLs) onto each match. Pass `limit` to cap descriptors (broad role queries can be large) or `count_only:true` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentRegions[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot.',
+        description: `Find elements by Testing-Library semantics, INCLUDING open shadow roots — \`count_only:true\` gives just the count (~30x smaller); \`limit\` caps descriptors. Pass \`by\` (${QUERY_BY_LIST}) and \`value\` (the query string). Returns matching refs + descriptors + visibility. Pass \`attrs:["href"]\` to project attributes (link/image URLs) onto each match. Pass \`limit\` to cap descriptors (broad role queries can be large) or \`count_only:true\` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentRegions[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot.`,
         inputSchema: {
-            by: z.string().describe('Query strategy: role | text | label | placeholder | testid | alt'),
+            // Constrained to the enum, NOT z.string(). A free string let `by:'css'` through to the
+            // browser's `default: return []`, so an unsupported strategy answered "0 matches" — which
+            // reads as "the element is not on the page". Measured on a live page: by:'css' value:'body'
+            // returned count 0. A false negative is the one answer this product must never invent.
+            by: queryByEnum.optional().describe(`Query strategy: ${QUERY_BY_LIST}`),
             value: z
                 .string()
-                .describe('Query value for the selected strategy (e.g. by=role value=button, or by=testid value=submit-btn).'),
+                .optional()
+                .describe('Query value for the selected strategy (e.g. by=role value=button, or by=testid value=submit-btn). Or use the predicate spelling directly: { testid: "submit" }, { text: "Deploy" }.'),
             name: z
                 .string()
                 .optional()
@@ -185,6 +206,14 @@ const RAW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Return just { count } (no element descriptors) — use when you only need "how many match?" and not their refs.'),
+            // The predicate's spelling, accepted as an alias for by/value so the shape an agent learns from
+            // act_and_wait/assert also works here. See query-shape.ts.
+            testid: z.string().optional().describe('Alias for by="testid" value=… (predicate spelling).'),
+            text: z.string().optional().describe('Alias for by="text" value=… (predicate spelling).'),
+            role: z.string().optional().describe('Alias for by="role" value=… (predicate spelling).'),
+            label: z.string().optional().describe('Alias for by="label" value=… (predicate spelling).'),
+            placeholder: z.string().optional().describe('Alias for by="placeholder" value=… .'),
+            alt: z.string().optional().describe('Alias for by="alt" value=… (predicate spelling).'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -257,16 +286,20 @@ const RAW_TOOLS = [
                 .optional()
                 .describe('True when a `scope` was given but resolved to nothing — zero matches then means the scope is gone, NOT that the element is absent. The search did not widen to the whole page. Re-check the scope before concluding anything.'),
         },
-        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.QUERY, {
-            by: args['by'],
-            value: args['value'],
-            name: args['name'],
-            scope: args['scope'],
-            // The handler forwards an explicit allowlist, so a new input is silently dropped unless it is
-            // added here — the browser saw no `attrs` and returned undefined while the unit tests, which
-            // call matchQuery directly, passed. Schema plus implementation is not the whole wire.
-            attrs: args['attrs'],
-        }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args['limit']), args['count_only'] === true))),
+        handler: (deps, rawArgs) => {
+            // Accept the predicate's named-field spelling too — see query-shape.ts.
+            const args = normalizeQueryArgs(rawArgs);
+            return commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.QUERY, {
+                by: args['by'],
+                value: args['value'],
+                name: args['name'],
+                scope: args['scope'],
+                // The handler forwards an explicit allowlist, so a new input is silently dropped unless it is
+                // added here — the browser saw no `attrs` and returned undefined while the unit tests, which
+                // call matchQuery directly, passed. Schema plus implementation is not the whole wire.
+                attrs: args['attrs'],
+            }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args['limit']), true === args['count_only'])));
+        },
     },
     {
         name: ReticleTool.INSPECT,
@@ -383,7 +416,7 @@ const RAW_TOOLS = [
  * Guardrail (from the plan): the 12-tool core hot-set keeps its EXACT names and shapes and is never
  * merged — sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state.
  */
-const MERGE_PLANS = [
+export const MERGE_PLANS = [
     {
         name: ReticleTool.BASELINE,
         description: 'Semantic-state baselines: { action: "save" } snapshots the current state under a name, "list" returns saved names, "diff" compares the live page against a saved baseline (REMOVED/ADDED elements + console-error count).',
@@ -419,6 +452,9 @@ const MERGE_PLANS = [
             review: ReticleTool.REVIEW,
             narrate: ReticleTool.NARRATE,
         },
+        // The handback the lease block orders on every session — the one call an agent MUST make, so it
+        // is the one that must not need a schema lookup first.
+        example: { action: 'yield', mode: 'waiting' },
     },
     {
         name: ReticleTool.LEASE,
@@ -430,7 +466,7 @@ const MERGE_PLANS = [
  * Retired from the MCP surface entirely (capability preserved elsewhere, per the plan):
  * - run_record: auto-recording on flow_replay already persists run outcomes.
  */
-const RETIRED_FROM_SURFACE = [
+export const RETIRED_FROM_SURFACE = [
     ReticleTool.RUN_RECORD, // auto-recording on flow_replay already persists run outcomes
     ReticleTool.REFRESH, // absorbed into reticle_navigate { reload: true }
     ReticleTool.WAIT_READY, // server-internal: the first live call already blocks for the session

package/dist/tools/unadvertised-help.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Guidance for `name`, or undefined when there is nothing useful to add — the tool IS advertised (so
+ * any error belongs to the call itself), or the name is not ours to explain.
+ */
+export declare function unadvertisedToolHelp(name: string, advertised: ReadonlySet<string>, known: ReadonlySet<string>): string | undefined;

package/dist/tools/unadvertised-help.js

@@ -0,0 +1,39 @@
+/**
+ * What to say when an agent calls a real Reticle tool that this profile does not advertise.
+ *
+ * The default profile advertises 16 of 46 tools. That is deliberate — every advertised tool's schema
+ * is re-sent on every turn, and the trim is most of why `hybrid` is cheap — and the other 30 stay
+ * fully callable through `reticle_run`, which `profile-reachability.test.ts` guards.
+ *
+ * The gap was in the ERROR. The MCP SDK answers `Tool <name> not found`, which is indistinguishable
+ * from "this tool does not exist", so an agent that trusts it stops trying. Reported from a real
+ * sweep of a Next app-router project: the first pass scored 25 failures that were nothing of the
+ * kind — every one of those tools worked through `reticle_run` seconds later.
+ *
+ * So: a name Reticle owns never comes back as "not found". It comes back with the call that works
+ * and the switch that makes it stop being necessary.
+ */
+import { ReticleTool } from './tool-names.js';
+import { TOOL_SURFACE, TOOL_PROFILE_ENV } from './tool-surface.js';
+import { mergedNameRedirect, mergedNameMessage } from './merged-name-redirect.js';
+/**
+ * Guidance for `name`, or undefined when there is nothing useful to add — the tool IS advertised (so
+ * any error belongs to the call itself), or the name is not ours to explain.
+ */
+export function unadvertisedToolHelp(name, advertised, known) {
+    if (advertised.has(name))
+        return undefined;
+    // A name that MOVED gets the move, not a profile lecture — it is not un-advertised, it is gone.
+    const moved = mergedNameRedirect(name);
+    if (moved !== undefined)
+        return mergedNameMessage(name, moved);
+    if (!known.has(name))
+        return undefined;
+    return (`${name} exists and works, but is not advertised under this tool profile — the schemas for all ` +
+        `tools are re-sent every turn, so the default advertises a subset and keeps the rest one call ` +
+        `away. It is NOT missing: invoke it with ` +
+        `${ReticleTool.RUN} { tool: "${name}", args: { ... } }. ` +
+        `Call ${ReticleTool.TOOLS} { names: ["${name}"] } for its parameters. ` +
+        `If you need it repeatedly, set ${TOOL_PROFILE_ENV}=${TOOL_SURFACE.ALL} to advertise ` +
+        `every tool directly.`);
+}

package/dist/trace.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Verbose internal flow tracing, for people working ON Reticle.
+ *
+ * The gap it fills: the journal records what the AGENT did to the app, and telemetry records
+ * aggregates. Neither says which of OUR code a tool call went through, in what order, or where the
+ * time went — so every "why is this flow slow" and "which path produced this verdict" was
+ * reconstructed by hand from reading source. One line per stage answers both.
+ *
+ * Design, in order of what it cost to get wrong elsewhere in this repo:
+ *
+ *  - OFF by default, and ~126ns per site when off (measured) — `span` calls the function and
+ *    returns. A trace on every tool call is a real cost on the hot path, and the hot path is a
+ *    verification loop of 50–200 calls.
+ *  - ONE line per stage, emitted when it ENDS, carrying its own duration. A start line as well
+ *    would double the volume to say something the end line already implies.
+ *  - Correlated by a call id and a depth, carried in AsyncLocalStorage rather than threaded through
+ *    every signature. Several agents are inside `runTool` at once — interleaving is the normal case
+ *    — so without an id the output is a pile of unrelated lines, and instrumenting anything would
+ *    mean changing its parameters, which is how instrumentation stops being added.
+ *  - Through the existing `log()`, so it lands in the same stderr stream the daemon already
+ *    redirects to `~/.reticle/daemon-<port>.log`. No new sink, no new file, nothing else to tail.
+ */
+/**
+ * Whether tracing is on.
+ *
+ * Read per call, not cached at import, and the reason is `loadDotEnv`: the CLI populates
+ * `process.env` from the project's .env AFTER every module has been imported, so a value captured at
+ * import time would miss a `RETICLE_TRACE` set there — silently, which is the worst way for a
+ * diagnostic switch to fail. (The reason originally given here — "so it can be turned on while the
+ * daemon runs" — was wrong: nothing outside a process can change its environment.)
+ *
+ * Measured cost of reading it per call: 126ns per traced site when tracing is OFF, against a ~9ns
+ * bare call. With a handful of spans per tool call that is under a microsecond on a call that takes
+ * milliseconds — cheap enough to be worth the correctness, and not the literal zero this comment
+ * used to imply.
+ */
+export declare function traceEnabled(): boolean;
+/**
+ * Bind a callback to the call that is running NOW, so it reports inside that call when it fires later.
+ *
+ * `waitForPredicate` re-checks its predicate from a WebSocket event listener and an interval. Neither
+ * is in the awaited chain, so AsyncLocalStorage does not reach them and every re-check used to open a
+ * brand new call at depth 0. Measured on one healthy run: 165 spans across 60 callIds, 25 of them a
+ * `browser.command` with no matching `tool.handler`.
+ *
+ * That is not cosmetic. The documented signature of a HUNG tool call is exactly "a browser.command
+ * with no tool.handler for that callId, ever" — the invariant that located a real hang. A clean run
+ * emitting 23 of them makes the invariant unusable and hides the next hang in its own noise.
+ *
+ * Returns `fn` unchanged when there is no call to bind to, so a caller outside a span is not given a
+ * fabricated parent.
+ */
+export declare function bindSpanContext<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void;
+/**
+ * Run `fn` as a named stage, recording how long it took and how it sat inside the call around it.
+ *
+ * Wrap a stage worth a line in a bottleneck hunt — a session resolve, a browser round-trip, a
+ * predicate evaluation — not every function. The value of the trace is that reading it is faster
+ * than reading the code, and that stops being true somewhere around one line per statement.
+ */
+export declare function span<T>(name: string, fields: Record<string, unknown>, fn: () => Promise<T> | T): Promise<T>;
+/**
+ * The synchronous form. Same line, same tree, same cost when off.
+ *
+ * It exists because `reticle init` — the flow every user hits before anything else, and the one
+ * whose slowness they experience personally — is synchronous end to end. An async-only span left
+ * exactly that flow untraceable.
+ */
+export declare function spanSync<T>(name: string, fields: Record<string, unknown>, fn: () => T): T;