@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { projectForRoot } from '../../memory/project/project-for-root.js';
+import { coverageRegressed, observabilityOf } from '@reticlehq/engine/evidence/observability.js';
+import { foldFeatureCapture } from './feature-capture.js';
+import { foldToolHitRate } from './tool-hit-rate.js';
+import { allSessionIntents } from '../../memory/intent/open-intents.js';
+import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { asString } from '@reticlehq/core';
+import { exercisedCount } from './gaps/coverage-identity.js';
+import { commandOrThrow, sessionIdShape } from './tool-kit.js';
+/**
+ * `reticle_coverage` — which interactive controls this session has driven, and which it has not.
+ *
+ * Every other read here answers a question the agent already thought to ask, which bounds
+ * verification by the agent's imagination — the documented weak link. This answers the one question
+ * that tells the agent whether to STOP: an agent that exercised 4 of 17 controls and believes it
+ * verified the page is exactly the confident-and-wrong case Reticle exists to prevent, and nothing
+ * in the tool surface previously contradicted it.
+ *
+ * Note this is NOT the existing `blindSpots` coverage, which is about what the layer could not SEE
+ * (closed shadow roots, cross-origin frames). This is about what the agent did not TOUCH. Both are
+ * honesty signals; they answer different questions and neither substitutes for the other.
+ *
+ * Unadvertised by every profile: it costs nothing per turn and is reached through `reticle_run`.
+ */
+/** Refs as the snapshot tree spells them: `(ref=e12)`. The tree format is ours, so this is exact. */
+const REF_IN_TREE = /\(ref=(e\d+)\)/g;
+/** The label a tree line carries before its ref, e.g. `- button "Archive" (ref=e9)`. */
+const LINE_WITH_REF = /^\s*-\s*(.+?)\s*\(ref=(e\d+)\)/;
+/** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
+export function parseControls(tree) {
+    const controls = [];
+    const seen = new Set();
+    for (const line of tree.split('\n')) {
+        const match = LINE_WITH_REF.exec(line);
+        if (null === match)
+            continue;
+        const [, label, ref] = match;
+        if (label === undefined || ref === undefined || seen.has(ref))
+            continue;
+        seen.add(ref);
+        controls.push({ ref, label });
+    }
+    // A ref can appear on a line this regex does not shape (nested formatting); count it regardless,
+    // because under-reporting the denominator would overstate coverage — the one direction that lies.
+    for (const match of tree.matchAll(REF_IN_TREE)) {
+        const ref = match[1];
+        if (ref !== undefined && !seen.has(ref)) {
+            seen.add(ref);
+            controls.push({ ref, label: '' });
+        }
+    }
+    return controls;
+}
+/**
+ * Build the coverage tool over the dispatchable tool table.
+ *
+ * The table arrives as a thunk rather than an import: `tools.ts` assembles it FROM this module, so
+ * importing it back would close a cycle whose failure mode is a load-order-dependent crash rather
+ * than an error anyone sees while writing it. The thunk is called inside the handler, long after the
+ * table exists. It carries the merged names — the ones `reticle_run` will actually accept — because
+ * a tool that merged into a parent is not something an agent can call or a maintainer can cut.
+ */
+export function buildCoverageTools(toolNames) {
+    return [
+        {
+            name: ReticleTool.COVERAGE,
+            description: 'Which interactive controls you have driven this session, and which you have NOT. Returns { total, exercised, untouched:[{ref,label}], alsoDroveGone? } over the controls currently on the page. Use it to decide whether verification is finished: an untouched list that still holds the controls your change affects means you are not done. This is about what you did not TOUCH — distinct from the `coverage` field on an action result, which reports what the layer could not SEE.',
+            example: {},
+            inputSchema: { ...sessionIdShape },
+            outputSchema: {
+                total: z.number(),
+                exercised: z.number(),
+                untouched: z.array(z.object({ ref: z.string(), label: z.string() })),
+                alsoDroveGone: z
+                    .number()
+                    .optional()
+                    .describe('Controls you drove that are no longer on the page — usually because the action SUCCEEDED and removed them (archive/delete/submit/navigate). Counted separately so `exercised: 0` never appears immediately after real work.'),
+                instrumentationGaps: z
+                    .array(z.unknown())
+                    .optional()
+                    .describe('What this app still cannot tell Reticle, as of your most recent verdict — each entry is { kind, missing, cost, fix, source?, ref? }. These are not controls you skipped; they are checks this app CANNOT answer until it is instrumented, so driving the untouched list will not close them. Apply each `fix` and re-verify: the gap disappears from this list when the app can answer, and every later verdict on this app gets stronger. OMITTED when nothing is missing.'),
+                unproven: z
+                    .boolean()
+                    .optional()
+                    .describe('True when verification is NOT finished for a reason driving more controls cannot fix — instrumentationGaps is non-empty. Present only when true, so its absence is not a claim.'),
+                observability: z
+                    .object({ driven: z.number(), observable: z.number(), percent: z.number().optional() })
+                    .optional()
+                    .describe('Of the controls you DROVE, how many Reticle could fully observe. `untouched` above is work left for you; this is work left in the APP, and driving more controls does not move it. `percent` is OMITTED when nothing was driven, because 0/0 is not 100%.'),
+                featureUse: z
+                    .object({
+                    observed: z.boolean(),
+                    truncated: z.boolean().optional(),
+                    context: z.unknown().optional(),
+                    intents: z.unknown().optional(),
+                    missed: z.unknown().optional(),
+                })
+                    .optional()
+                    .describe('Whether this session used `reticle_context` and `reticle_intent` at all, and what it cost when it did not: `context` counts the calls and what followed each one, `intents` the ledger, `missed` the verdicts drawn against an empty ledger and the reads that re-fetched a fact already established. `observed:false` means nothing was recorded for this session — NOT that nothing was used. An instrument for deciding whether those two features earn their place; nothing here is a fault of yours.'),
+                toolHitRate: z
+                    .object({
+                    observed: z.boolean(),
+                    cells: z.unknown().optional(),
+                    called: z.unknown().optional(),
+                    neverCalled: z.unknown().optional(),
+                })
+                    .optional()
+                    .describe('Which Reticle tools THIS session called, and how reachable each one was: `called` lists every tool with its call count, `neverCalled` the rest of the table, and both carry a `tier` — `default` (advertised to every agent), `extended` (advertised only on the full surface) or `run-only` (reachable solely by naming it to reticle_run). `cells` counts each tier on both sides. `observed:false` means nothing was recorded for this session, NOT that nothing was called. THREE LIMITS, all load-bearing: this is ONE session, so it is evidence about this run and is not a hit rate — a hit rate is a distribution over many sessions. A never-called tool is not a useless tool; one used once a month in an emergency looks identical here to one nobody has ever called, so frequency alone cannot decide a cut. And the counts describe how this run went, never how it should have gone — nothing here is a fault of yours.'),
+                observabilityRegressed: z
+                    .object({ was: z.number(), now: z.number() })
+                    .optional()
+                    .describe('This project has previously reached a HIGHER observability than this run did. Usually means an assertion or an instrumented path was removed — the cheapest way to stop a gap firing is to stop asserting the thing that revealed it. Present only when a drop is real and the run was large enough to compare.'),
+            },
+            handler: async (deps, args) => {
+                const sessionId = asString(args['sessionId']);
+                const session = deps.sessions.resolve(sessionId);
+                // INTERACTIVE mode is already the "controls only" view, so the denominator is the page's own
+                // notion of what can be driven rather than a second, drifting definition maintained here.
+                const result = await commandOrThrow(deps, sessionId, ReticleCommand.SNAPSHOT, {
+                    mode: SnapshotMode.INTERACTIVE,
+                });
+                const tree = asString(result['tree']) ?? '';
+                // Matched by ref AND by label — see coverage-identity. A ref dies with the next re-render, so
+                // on a framework that replaces nodes this reported `exercised: 0` however much work was done.
+                // `droveGone` keeps the other honesty: archive/delete/submit remove their own control, so a
+                // drive that WORKED must not read as no coverage at all.
+                const { exercised, droveGone, untouched } = exercisedCount(parseControls(tree), session.actedRefs(), session.actedLabels());
+                // The other half of "am I done?". `untouched` answers what you did not DRIVE; this answers
+                // what this app cannot ANSWER, which no amount of further driving will change. Reporting the
+                // first without the second is how an agent finishes a pass believing it verified something the
+                // app was never able to confirm.
+                const gaps = session.gaps?.open() ?? [];
+                // Folded here rather than given a tool of its own: this is already the "am I done, and what is
+                // this verdict worth" read, and a number nobody has a reason to ask for separately is one
+                // nobody ever sees. It is a fold over the journal and the intent ledger plus the one thing
+                // neither records — see surface/tools/feature-capture.ts.
+                const featureUse = foldFeatureCapture({
+                    calls: session.capture.calls(),
+                    dropped: session.capture.dropped,
+                    actions: await session.readJournalActions(),
+                    intents: await allSessionIntents(deps, sessionId),
+                    finalActions: session.actionCount,
+                });
+                // Same fold, same reason, one level out: which of the whole tool table this session reached
+                // for, crossed with how reachable each name was. See surface/tools/tool-hit-rate.ts for what it can
+                // and cannot establish — the limits matter more than usual, because this is the number a
+                // decision to DELETE tools would be made on.
+                const toolHitRate = foldToolHitRate({
+                    calls: session.capture?.toolCalls(),
+                    allTools: toolNames(),
+                });
+                // The number, and the floor under it, together. A coverage figure that can only ever be
+                // reported and never contradicted is one an agent learns to satisfy rather than to earn.
+                const observability = observabilityOf(session.actedRefs(), gaps);
+                const project = projectForRoot(deps, sessionRoot(deps, sessionId));
+                const best = await project.bestObservability();
+                const regressed = coverageRegressed(best, observability);
+                if (observability.percent !== undefined) {
+                    await project.raiseObservability(observability.percent);
+                }
+                return {
+                    total: parseControls(tree).length,
+                    exercised,
+                    untouched,
+                    ...(droveGone > 0 ? { alsoDroveGone: droveGone } : {}),
+                    ...(gaps.length > 0 ? { instrumentationGaps: gaps, unproven: true } : {}),
+                    observability,
+                    ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
+                    featureUse,
+                    toolHitRate,
+                };
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,17 @@
+import type { ToolDef } from './tool-kit.js';
+import { type ToolSurfaceOrigin } from './tool-surface.js';
+/**
+ * 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.
+ */
+export declare function buildDynamicTools(allTools: ToolDef[], profile?: ToolSurfaceOrigin, 
+/**
+ * What this surface can actually INVOKE. Defaults to everything, which is true wherever
+ * `reticle_run` is advertised — it reaches any tool in the registry by name.
+ *
+ * Passed only by a surface that ships no dispatch hatch. Cataloguing a tool nothing can call is
+ * worse than hiding it: MEASURED on the nine-tool surface, this listed 66 names of which 57 were
+ * uninvokable, and the agent that found `reticle_lease` in it called it four times, failed four
+ * times, and then abandoned the product for the rest of the run.
+ */
+callable?: ReadonlySet<string>): ToolDef[];

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

@@ -0,0 +1,282 @@
+import { z } from 'zod';
+import { runTool } from './invoke-tool.js';
+import { buildErrorPayload } from './error-recovery.js';
+import { mergedNameRedirect, mergedNameMessage, retiredToolNames } from './merged-name-redirect.js';
+import { CATALOGUE_SUMMARY_LENGTH, firstSentence } from './first-sentence.js';
+import { takeVersionSkewOnto } from '../../command/version/version-nudge.js';
+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';
+/** Compact param list from a tool's zod shape — name/required/description (the description already
+ * carries the type and any enum hints, so no JSON-Schema machinery is needed). */
+function paramInfo(shape) {
+    return Object.entries(shape).map(([name, schema]) => ({
+        name,
+        required: !schema.isOptional(),
+        description: schema.description ?? '',
+    }));
+}
+/**
+ * The one wording for "you named a parameter that does not exist", shared by both checks in
+ * `reticle_run` — the one over the WRAPPED tool's `args`, and the one over reticle_run's own
+ * top-level keys. Two spellings of the same refusal is how one of them ends up not existing.
+ */
+function unknownParamsError(toolName, unknown) {
+    return `unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')} — NOT applied, so any result would be an answer to a different question`;
+}
+/** What to write instead — the one parameter reticle_tools declares, and the no-argument form. */
+const TOOLS_ARG_HINT = 'name the tools you want in `names`: reticle_tools { names: ["reticle_act_and_wait"] } — or call it with no arguments for the full catalog';
+/** The keys not declared by `shape`, in call order. */
+function unknownKeys(args, shape) {
+    const declared = new Set(Object.keys(shape));
+    return Object.keys(args).filter((key) => !declared.has(key));
+}
+/**
+ * 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.
+ */
+export function buildDynamicTools(allTools, profile, 
+/**
+ * What this surface can actually INVOKE. Defaults to everything, which is true wherever
+ * `reticle_run` is advertised — it reaches any tool in the registry by name.
+ *
+ * Passed only by a surface that ships no dispatch hatch. Cataloguing a tool nothing can call is
+ * worse than hiding it: MEASURED on the nine-tool surface, this listed 66 names of which 57 were
+ * uninvokable, and the agent that found `reticle_lease` in it called it four times, failed four
+ * times, and then abandoned the product for the rest of the run.
+ */
+callable) {
+    const reachable = callable === undefined ? allTools : allTools.filter((tool) => callable.has(tool.name));
+    const byName = new Map(reachable.map((t) => [t.name, t]));
+    const registered = new Map(allTools.map((tool) => [tool.name, tool]));
+    /**
+     * A name the catalogue cannot hand back as a callable tool.
+     *
+     * A redirect wins, because the capability moved and the old name is how an older instruction
+     * still asks for it. A name that is a real tool on a surface that cannot call it is the other
+     * case: `unknown tool` is what a typo gets, and a headline capability must not get the same
+     * sentence (#977). A name in neither set is a typo.
+     */
+    const explainAbsent = (name) => {
+        const moved = mergedNameRedirect(name);
+        if (moved !== undefined) {
+            return {
+                error: mergedNameMessage(name, moved),
+                tool: moved.tool,
+                ...(moved.action === undefined ? {} : { action: moved.action }),
+            };
+        }
+        if (callable !== undefined && registered.has(name)) {
+            return {
+                error: `${name} is a Reticle tool and this surface cannot call it. Restart the daemon with ` +
+                    `${ADVERTISE_ALL_ENV}=1, then call reticle_run { tool: "${name}", args }.`,
+                tool: name,
+            };
+        }
+        return { error: 'unknown tool' };
+    };
+    // The profile is a DAEMON-startup decision, so an agent that exported RETICLE_TOOL_PROFILE into its
+    // own environment sees no change and has, until now, no way to tell. Reported with the catalog.
+    const profileBlock = profile === undefined
+        ? {}
+        : {
+            profile: {
+                ...profile,
+                // No surface advertises the whole registry, so wherever an unadvertised tail exists,
+                // `reticle_run` is the route to it. Wording that implies otherwise sends an agent away
+                // from the only tool that can reach half the registry.
+                note: callable === undefined
+                    ? `The surface is read once at daemon startup: set ${ADVERTISE_ALL_ENV}=1 and restart the daemon, or it has no effect. No surface advertises every tool: the advertised count is capped because editors budget tools across all connected MCP servers. Every tool listed here is callable through reticle_run { tool, args } whether or not it is advertised.`
+                    : 'This surface advertises everything it can call, so this list IS the product and every name in it is callable directly. There is no hidden tail and no dispatch hatch to reach one.',
+            },
+        };
+    const toolsShape = {
+        names: z
+            .array(z.string())
+            .optional()
+            .describe('Tool names to load full params for. Omit to list all tools with summaries.'),
+    };
+    const reticleTools = {
+        name: ReticleTool.TOOLS,
+        // The "invoke them with reticle_run" half is true only where reticle_run exists. On a closed
+        // surface it is the first thing an agent reads about this tool and it names a tool that is not
+        // there, so it is said only where it can be acted on.
+        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools.' +
+            (callable === undefined
+                ? ' Then invoke them with reticle_run.'
+                : ' Every tool it lists is callable directly by name.') +
+            ' This avoids paying for every tool definition on every turn.' +
+            // The flow workflow is taught ONLY where it can be followed. Three of its four calls —
+            // reticle_record, reticle_flow_save, reticle_verify { action: "heal" } — are in the merged table but are not
+            // advertised, and a closed surface has no dispatch hatch to reach them, so naming them here
+            // hands the reader a four-step recipe of which one step works. Replaying flows that already
+            // exist is reachable either way, via reticle_verify, so that half is still offered.
+            (callable === undefined
+                ? ' To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_verify{action:"flows"} (and reticle_verify { action: "heal" } on drift). Load those names when you want to save or re-run a flow.'
+                : ' Flows that already exist replay with reticle_verify { action: "flows" }. RECORDING a new one is not reachable from this surface; start the daemon with RETICLE_ADVERTISE_ALL_TOOLS=1 if you need to build one.'),
+        inputSchema: toolsShape,
+        handler: (_deps, args) => {
+            // The discovery tool declared one parameter and checked none, so a call that misnamed it had
+            // the key dropped and came back with the WHOLE catalogue — a well-formed answer to a question
+            // nobody asked, and one the caller cannot tell from the answer it wanted. Same check and same
+            // wording as reticle_run's, because two spellings of one refusal is how one of them rots.
+            const stray = unknownKeys(args, toolsShape);
+            if (stray.length > 0) {
+                return Promise.resolve({
+                    error: unknownParamsError(ReticleTool.TOOLS, stray),
+                    params: paramInfo(toolsShape),
+                    hint: TOOLS_ARG_HINT,
+                });
+            }
+            const names = Array.isArray(args['names'])
+                ? args['names'].filter((n) => 'string' === typeof n)
+                : undefined;
+            if (names === undefined || 0 === names.length) {
+                // The COUNT is stated, not just implied by the array length. An agent that can see 18 tools
+                // has no way to know whether that is all of them; being told the registry holds more is what
+                // turns "these are the tools" into "these are the tools I was shown".
+                const catalog = reachable.map((t) => ({
+                    name: t.name,
+                    summary: firstSentence(t.description, CATALOGUE_SUMMARY_LENGTH),
+                }));
+                // Names that USED to be tools, against the call that replaces each. Instructions written
+                // against an earlier release are a permanent fact of the product — `reticle_crawl` is still
+                // named by guidance in the wild — and without this the catalogue is silent about them: the
+                // old name is simply absent, which reads as "no such capability" rather than "renamed".
+                // Reaching the new name then costs an error string, or never happens.
+                const retired = retiredToolNames();
+                return Promise.resolve({
+                    total: catalog.length,
+                    tools: catalog,
+                    retired,
+                    ...profileBlock,
+                    // Two sentences for two different surfaces, because one sentence was wrong on one of
+                    // them. This told every reader to "call reticle_run { tool, args }" — and on a closed
+                    // surface reticle_run is not advertised OR callable, so the instruction resolves to
+                    // "Tool reticle_run not found". It also contradicted the profile note directly above it,
+                    // which already said there is no dispatch hatch. An agent reading both cannot tell which
+                    // half of one answer to believe, and the one it acted on was the wrong one.
+                    next: callable === undefined
+                        ? `All ${catalog.length} tools above are callable, advertised or not. Load full params with reticle_tools { names:[…] }, then call reticle_run { tool, args }. \`retired\` maps names that are no longer tools to the call that replaced each.`
+                        : `All ${catalog.length} tools above are advertised and callable directly by name — there is no dispatch hatch on this surface. Load full params with reticle_tools { names:[…] }. \`retired\` maps names that are no longer tools to the call that replaced each.`,
+                });
+            }
+            // The grammar rides ONLY on a `names:[…]` reply that asked for a tool taking a predicate, so
+            // no turn pays for it in the catalog or in the advertised schema. The lean tool surface says
+            // "call reticle_tools for the full field grammar of a kind"; this is where that lands.
+            const carriesPredicate = names.some((n) => Object.values(byName.get(n)?.inputSchema ?? {}).some((schema) => isPredicateParam(schema)));
+            return Promise.resolve({
+                tools: names.map((n) => {
+                    const t = byName.get(n);
+                    if (t !== undefined)
+                        return { name: n, description: t.description, params: paramInfo(t.inputSchema) };
+                    // `reticle_run` has answered a merged name with its replacement for a while; the tool
+                    // asked to DISCOVER tools still said "unknown tool", which is the wrong answer in the one
+                    // place an agent goes to resolve a name it is unsure of. Same redirect, same derivation.
+                    return { name: n, ...explainAbsent(n) };
+                }),
+                ...(carriesPredicate ? { predicateGrammar: predicateGrammar() } : {}),
+            });
+        },
+    };
+    const runShape = {
+        tool: z.string().describe('Tool name to invoke, e.g. reticle_network.'),
+        args: z.record(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
+        // against every app it was tried on: it took this key, dropped it, resolved by the daemon's cwd
+        // project, and failed with "no browser session for project X" while naming the very session it
+        // had been given.
+        sessionId: z
+            .string()
+            .optional()
+            .describe('Target tab for the invoked tool. Forwarded to it — an explicit args.sessionId wins.'),
+    };
+    const reticleRun = {
+        name: ReticleTool.RUN,
+        description: "Invoke any Reticle tool by name (discover names/params first with reticle_tools). On an unknown tool or bad arguments it returns the available names or the tool's params, so you can correct and retry.",
+        inputSchema: runShape,
+        handler: async (deps, args) => {
+            // reticle_run's OWN parameters, checked first and with the same wording as the inner check.
+            // It refused an unknown key inside `args` and silently dropped one beside them: an agent that
+            // wrote `reticle_run { tool, args, sessionId }` — the shape it uses on every other tool — had
+            // its sessionId ignored and got a confident answer about whichever session auto-selection
+            // picked. Every other tool on the surface refuses this; the escape hatch has to as well.
+            const strayTop = unknownKeys(args, runShape);
+            if (strayTop.length > 0) {
+                return {
+                    error: unknownParamsError(ReticleTool.RUN, strayTop),
+                    hint: `pass them inside args: reticle_run { tool, args: { ${strayTop.join(', ')}: … } } if the target tool declares them`,
+                };
+            }
+            const name = 'string' === typeof args['tool'] ? args['tool'] : '';
+            const given = 'object' === typeof args['args'] && args['args'] !== null
+                ? args['args']
+                : {};
+            const aimed = args['sessionId'];
+            const target = byName.get(name);
+            if (target === undefined) {
+                // A non-zero count here means our advertised surface is confusing the agent — it reached for
+                // something it believed existed. That is a docs/naming defect, and it was invisible.
+                //
+                // The NAME goes with it: the count says the surface confused someone, the name says which
+                // capability they expected. It was already in hand here and thrown away, so the one place
+                // the product could learn what agents want was discarding it. Safe — a name from our own
+                // tool namespace, never app data.
+                getSessionMetrics().recordUnknownTool(name);
+                // ...and for 22 of those names the capability DOES exist, it just moved when tools merged.
+                // Answering "unknown tool" there is simply wrong; see merged-name-redirect.
+                const absent = explainAbsent(name);
+                if ('unknown tool' !== absent.error)
+                    return absent;
+                return { error: `unknown tool '${name}'`, available: reachable.map((t) => t.name) };
+            }
+            // The outer aim, forwarded ONLY to a tool that declares a session — injecting it into one that
+            // does not would trip the unknown-key check below and refuse a call the caller got right. An
+            // inner args.sessionId wins as the more specific instruction, and an absent aim stays absent so
+            // auto-selection still applies.
+            const callArgs = 'string' === typeof aimed &&
+                given['sessionId'] === undefined &&
+                undefined !== target.inputSchema['sessionId']
+                ? { ...given, sessionId: aimed }
+                : given;
+            // The escape hatch is where a typo is MOST likely, because an unadvertised tool's parameters
+            // are not in front of the agent at all — and it is the one path the SDK's own validation never
+            // sees, since `reticle_run`'s own args (`tool`, `args`) are perfectly valid. Left unchecked,
+            // `reticle_run { tool: "reticle_clock", args: { action: "freeze" } }` returned
+            // `{"frozen":false}`: a well-formed answer to a question nobody asked.
+            const unknown = unknownKeys(callArgs, target.inputSchema);
+            if (unknown.length > 0) {
+                return {
+                    error: unknownParamsError(name, unknown),
+                    tool: name,
+                    params: paramInfo(target.inputSchema),
+                    ...(target.example === undefined ? {} : { example: target.example }),
+                    hint: 'fix the arguments and call reticle_run again',
+                };
+            }
+            try {
+                return await runTool(target, deps, callArgs);
+            }
+            catch (error) {
+                // The SAME payload the direct tool path builds — recovery included. Answering every failure
+                // with "fix the arguments" threw that away, and under the default profile nearly every tool
+                // is reached through here: a stale ref, a paused session, a missing pairing token all came
+                // back as the agent's arguments being wrong, which is advice that spends the retry.
+                const message = error instanceof Error ? error.message : String(error);
+                return { ...takeVersionSkewOnto(buildErrorPayload(message)), tool: name };
+            }
+        },
+    };
+    // The server instructions say, verbatim, "reticle_tools lists it, reticle_run calls it" — naming
+    // these two meta-tools as reachable through EACH OTHER, same as everything else on the surface.
+    // `byName` was built from `allTools` before either was constructed, so it never held them:
+    // `reticle_run { tool: "reticle_tools" }` — the exact discovery path the instructions document —
+    // answered "unknown tool 'reticle_tools'" (#876). Registered here, after both exist, so the
+    // dispatch this closure reads from (`byName.get`, evaluated lazily on each call) can find them.
+    byName.set(ReticleTool.TOOLS, reticleTools);
+    byName.set(ReticleTool.RUN, reticleRun);
+    return [reticleTools, reticleRun];
+}

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

@@ -0,0 +1,116 @@
+/**
+ * Actionable error recovery. Every tool error the agent hits should answer "what do I do next?", not
+ * just "what went wrong". This pure mapping turns a known error message into a concrete recovery hint
+ * the agent (or the human, via the agent) can act on — so the first 5 minutes never dead-end on a
+ * cryptic "no session connected". Spliced onto the error envelope at the MCP boundary (mcp.ts).
+ *
+ * Conservative by design: an unrecognized error returns `undefined` (no invented advice). Matching is
+ * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
+ * baseline stores). No clock, no IO — unit-testable in isolation.
+ */
+import { RefusalReason } from '@reticlehq/core';
+/** The recovery hints, named so they are not free strings and can be asserted in tests. */
+export declare const RECOVERY: {
+    readonly NO_SESSION: string;
+    readonly MULTIPLE_SESSIONS: string;
+    readonly UNKNOWN_SESSION: "That sessionId is not connected. Call reticle_sessions for the current ids and retry with a valid one.";
+    readonly THROTTLED: string;
+    readonly MISSING_BASELINE: string;
+    readonly MISSING_RECORDING: string;
+    readonly STALE_REF: string;
+    readonly STALE_REF_AFTER_EDIT: string;
+    readonly INVALID_NAME: string;
+    /**
+     * The call was well-formed and the SELECTOR missed. Nothing about the arguments was wrong, so the
+     * BAD_ARGUMENTS answer ("re-read that tool's parameters") sends the reader to the one place that
+     * holds no answer — measured live on a `target: { testid }` that simply was not on the page yet.
+     *
+     * The error text already names the two moves that work, so this adds the fact the text cannot
+     * carry: which of them to reach for, and that nothing was acted on.
+     */
+    readonly TARGET_MISSED: string;
+    /**
+     * The selector was underspecified, which is the caller's to fix and the same class as a miss.
+     *
+     * It reached the feedback ask for a punctuation reason: the text ends "pass an explicit `ref` from
+     * reticle_query.", and the catch-all excludes a `reticle_*` name followed by `.` so a module path
+     * in a stack trace stays an unanticipated crash. A tool named at the END of a sentence is
+     * indistinguishable from one under that rule, so the whole message fell through and told the
+     * caller their own ambiguous query might be a defect worth a root-cause report.
+     */
+    readonly AMBIGUOUS_TARGET: string;
+    readonly NO_SUCH_OPTION: string;
+    readonly BAD_ARGUMENTS: string;
+    readonly WRONG_TARGET: string;
+    readonly NOT_EDITABLE: string;
+    /**
+     * Written as the ARGUMENT OBJECT the caller has to send, not as a dotted path.
+     *
+     * Measured on a benchmark run that spent its entire budget here: the refusal said "retry with
+     * args.confirmDangerous=true", and the agent went looking for a parameter by that name, could not
+     * find one at the top level of the schema, and re-read the tool list rather than retrying. The
+     * flag IS documented — inside the `args` object's own description — so a dotted path pointing at
+     * something that is not a top-level parameter is the whole distance between a one-line retry and
+     * a lost budget.
+     *
+     * The classifier is also wider than "destructive": it matches `deploy` and `publish`, so an
+     * ordinary "New deploy" button trips it. Naming a real trigger word here keeps that from reading
+     * as a malfunction on an app where nothing is being deleted.
+     */
+    readonly CONFIRM_DANGEROUS: string;
+    readonly UNSUPPORTED_SURFACE: string;
+    readonly HOVER_NEEDS_POINTER: string;
+    readonly TOKEN_REQUIRED: string;
+    readonly SCOPE_MISMATCH: string;
+    readonly SESSION_GONE: string;
+    readonly COMMAND_TIMEOUT: string;
+    readonly FLOW_STEP_MISSING: string;
+    readonly NO_POOL: string;
+    /**
+     * The two ways a platform answer can refuse a drive. Neither is a fault, and both were telling the
+     * agent that a perfectly understood refusal might be a defect in Reticle — which is how a person
+     * who deliberately switched the harness off gets a bug report filed about their own decision.
+     */
+    readonly HARNESS_OFF: string;
+};
+/**
+ * The actionable next move for a known error message, or undefined when none is recognized.
+ *
+ * A message that already carries its own next action gets NO second one. The no-session diagnosis
+ * inspects the machine and says which of three causes this actually is; pairing that with the
+ * generic "ask the human to start their app" produced a result that contradicted itself — the error
+ * saying a server is running and the recovery saying to go start one.
+ */
+export declare function recoveryFor(message: string): string | undefined;
+/**
+ * WHY a tool refused, as one of the six buckets in core's `RefusalReason`.
+ *
+ * Reads the SAME rules `buildErrorPayload` reads, in the same order, so the reason we report and the
+ * advice the agent got can never describe different things. Anything unrecognised is `other`, which
+ * is the bucket that says the classifier has a blind spot — and a growing `other` is a finding about
+ * this table rather than about anybody's app.
+ */
+export declare function refusalReasonFor(rawMessage: string): RefusalReason;
+/**
+ * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
+ * where Reticle failed in a way nobody anticipated — the single highest-value moment to hear from the
+ * agent, and until now the moment where the agent worked around us in silence and we learned nothing.
+ *
+ * Deliberately NOT attached when a recovery hint matched: there the agent has a concrete next move,
+ * and diverting it into filing a report about a failure we already understand costs a turn and tells
+ * us nothing new.
+ */
+export declare const FEEDBACK_ASK: string;
+/** The error envelope sent to the agent: the message, plus a recovery hint when one is known. */
+interface ErrorPayload {
+    error: string;
+    recovery?: string;
+    feedback?: string;
+}
+/**
+ * Build the tool-error payload spliced at the MCP boundary. `recovery` is added when the error is
+ * known; the feedback ask is added when it is NOT — the two are mutually exclusive by design, so the
+ * agent always gets exactly one next move.
+ */
+export declare function buildErrorPayload(rawMessage: string): ErrorPayload;
+export {};