@reticlehq/server 2.14.0 → 3.2.0

package/dist/tools/contract-tools.js

@@ -1,98 +0,0 @@
-import { z } from 'zod';
-import { sessionRoot } from '../project/session-root.js';
-import { CapabilitiesSchema, ContractReadError, FROM_DISK_ARG, ReticleCommand, } from '@reticlehq/core';
-import { ReticleTool } from './tool-names.js';
-import { asString } from './tools-helpers.js';
-import { sessionIdShape, commandOrThrow } from './tool-kit.js';
-import { reticleDirPaths, readContract, writeContract } from '../project/reticle-dir.js';
-/**
- * The capability-contract tools. `reticle_capabilities` reads the live session, or the
- * git-checked `.reticle/contract.json` when `{ fromDisk:true }`; `reticle_contract_save` persists the
- * live registry to that file (pretty-printed, stable key order — diffable in PRs).
- */
-/**
- * Refuse to persist one project's surface into another project's repo.
- *
- * `writeContract` writes to the DAEMON's `.reticle/`, which is the directory the daemon was started
- * in — not the session's project. A daemon started above several apps therefore saves app A's
- * testids into app B's checkout, reports `saved: true`, and hands back a path that looks right. A
- * contract is git-checked and diffable, so that is a change somebody commits.
- *
- * Refuse rather than redirect: a session advertises a projectId, not a project DIRECTORY, so there
- * is no honest way to work out where the correct `.reticle/` lives. Naming both ids and stopping is
- * the whole of what can be said truthfully.
- *
- * Silence is not a mismatch. An unstamped build carries no projectId, and a daemon above an
- * uninitialised directory has none either; neither is evidence of two projects.
- */
-function assertSameProject(deps, sessionId) {
-    const mine = deps.projectId;
-    const theirs = deps.sessions.resolve(sessionId).projectId;
-    if (mine === undefined || theirs === undefined || mine === theirs)
-        return;
-    throw new Error(`refusing to save: this session belongs to project '${theirs}', but this daemon writes to ` +
-        `project '${mine}' (.reticle/ in the directory it was started in). Saving would put one ` +
-        "app's testable surface into another app's git-checked contract. Run a daemon from " +
-        `'${theirs}'s own directory and save there.`);
-}
-export const CONTRACT_TOOLS = [
-    {
-        name: ReticleTool.CAPABILITIES,
-        description: 'The app-advertised testable surface (reticle.describe): testids, signals, stores, and named flows. Call this first to learn what to assert on without reading source. Pass { fromDisk:true } to read the git-checked .reticle/contract.json instead of the live session (a fresh agent can learn the surface with no browser attached).',
-        // Every core tool carries one, so an agent reading the surface never has to guess the shape.
-        // `fromDisk` is the example deliberately: it is the call that works with nothing attached, which
-        // is the state a fresh agent is actually in when it first reads this list.
-        example: { [FROM_DISK_ARG]: true },
-        inputSchema: { [FROM_DISK_ARG]: z.boolean().optional(), ...sessionIdShape },
-        outputSchema: {
-            testids: z.array(z.string()),
-            signals: z.array(z.string()),
-            stores: z.array(z.string()),
-            flows: z.array(z.object({ name: z.string(), steps: z.array(z.string()) })),
-            source: z
-                .string()
-                .describe('live = real-time from the browser; disk = last saved contract.json'),
-            // fromDisk carries when the contract was generated; both paths carry the app's declared governance
-            // (owner/safety/scope) when present. Undeclared, they were stripped on a validating profile — a
-            // governance-gated app lost its policy block, and disk reads lost their freshness stamp.
-            generatedAt: z.number().optional(),
-            governance: z.unknown().optional(),
-        },
-        handler: async (deps, args) => {
-            if (true === args[FROM_DISK_ARG]) {
-                const r = await readContract(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
-                if (!r.ok)
-                    throw new Error(r.reason === ContractReadError.MISSING
-                        ? 'no .reticle/contract.json on disk — run reticle_contract_save first (or omit fromDisk to read the live session)'
-                        : '.reticle/contract.json is malformed — fix or regenerate it with reticle_contract_save');
-                return { ...r.capabilities, source: 'disk', generatedAt: r.generatedAt };
-            }
-            const caps = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CAPABILITIES, {});
-            return { ...caps, source: 'live' };
-        },
-    },
-    {
-        name: ReticleTool.CONTRACT_SAVE,
-        description: "Persist the app's live capability registry (reticle.describe) to .reticle/contract.json — git-checked, diffable, readable by a fresh agent via reticle_capabilities({ fromDisk:true }). Returns { path, counts }.",
-        inputSchema: { ...sessionIdShape },
-        outputSchema: {
-            saved: z.boolean(),
-            path: z.string(),
-            testidCount: z.number(),
-            signalCount: z.number(),
-        },
-        handler: async (deps, args) => {
-            const res = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CAPABILITIES, {});
-            const caps = CapabilitiesSchema.parse(res);
-            assertSameProject(deps, asString(args['sessionId']));
-            const root = sessionRoot(deps, asString(args['sessionId']));
-            await writeContract(deps.fs, root, caps, deps.now);
-            return {
-                saved: true,
-                path: reticleDirPaths(root).contract,
-                testidCount: caps.testids.length,
-                signalCount: caps.signals.length,
-            };
-        },
-    },
-];

package/dist/tools/coverage-tools.d.ts

@@ -1,18 +0,0 @@
-import type { ToolDef } from './tools.js';
-interface Control {
-    ref: string;
-    label: string;
-}
-/** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
-export declare function parseControls(tree: string): Control[];
-/**
- * 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 declare function buildCoverageTools(toolNames: () => readonly string[]): ToolDef[];
-export {};

package/dist/tools/coverage-tools.js

@@ -1,175 +0,0 @@
-import { z } from 'zod';
-import { coverageRegressed, observabilityOf } from '../honesty/observability.js';
-import { foldFeatureCapture } from '../honesty/feature-capture.js';
-import { foldToolHitRate } from '../honesty/tool-hit-rate.js';
-import { allSessionIntents } from '../intent/open-intents.js';
-import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
-import { ReticleTool } from './tool-names.js';
-import { asString } from './tools-helpers.js';
-import { exercisedCount } from './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 honesty/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 honesty/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 best = await deps.project.bestObservability();
-                const regressed = coverageRegressed(best, observability);
-                if (observability.percent !== undefined) {
-                    await deps.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/tools/dynamic-tools.d.ts

@@ -1,7 +0,0 @@
-import type { ToolDef } from './tools.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): ToolDef[];

package/dist/tools/dynamic-tools.js

@@ -1,257 +0,0 @@
-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 { takeVersionSkewOnto } from '../version/version-nudge.js';
-import { ReticleTool } from './tool-names.js';
-import { ADVERTISE_ALL_ENV } from './tool-surface.js';
-import { getSessionMetrics } from '../telemetry/session-metrics.js';
-import { isPredicateParam, predicateGrammar } from '../events/predicate-eval.js';
-/**
- * On-demand tool loading for MCP — the answer to the per-turn tool-definition tax.
- *
- * A normal MCP server advertises every tool's full description + schema, and the client re-sends
- * all of them to the model on EVERY turn. Measured here: Reticle at ~5.6k–14.6k tokens/turn just for
- * definitions, which dominates a real agent loop and only grows as the tool surface grows.
- *
- * The `dynamic` profile advertises just TWO meta-tools (~hundreds of tokens, fixed regardless of
- * how many real tools exist):
- * reticle_tools — discover. No args ⇒ a compact catalog (name + one-line summary) of every tool.
- * names:[...] ⇒ full description + params for just those tools, loaded on demand.
- * reticle_run — invoke any tool by name. On a bad/unknown call it returns that tool's params as a
- * hint, so the model self-corrects without ever needing the schema up front.
- *
- * The model lists once, loads the 2–3 tools it actually needs, and calls them — paying for tool
- * detail only when used, not every turn. Works with any MCP client (no client-side support needed).
- */
-/** First sentence (purpose) of a description — keeps the catalog one line per tool. */
-function firstSentence(description) {
-    const nl = description.indexOf('\n');
-    const base = nl >= 0 ? description.slice(0, nl) : description;
-    const dot = base.search(/\.\s/);
-    const sentence = dot >= 0 ? base.slice(0, dot + 1) : base;
-    return sentence.length > 140 ? `${sentence.slice(0, 139)}…` : sentence;
-}
-/** 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) {
-    const byName = new Map(allTools.map((t) => [t.name, t]));
-    // 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,
-                // This used to say `full` carries no meta-tools because it advertised everything
-                // directly. That stopped being true when the advertised surface was capped: no surface
-                // advertises the whole registry any more, so BOTH meta-tools are on every surface and
-                // reticle_run is always the way to the tail. The old wording would now send an agent
-                // away from the only tool that can reach half the registry.
-                note: `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.`,
-            },
-        };
-    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,
-        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. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. 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_flow_heal on drift). Load those names when you want to save or re-run a flow.',
-        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 = allTools.map((t) => ({
-                    name: t.name,
-                    summary: firstSentence(t.description),
-                }));
-                // 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,
-                    next: `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.`,
-                });
-            }
-            // 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.
-                    const moved = mergedNameRedirect(n);
-                    return moved === undefined
-                        ? { name: n, error: 'unknown tool' }
-                        : {
-                            name: n,
-                            error: mergedNameMessage(n, moved),
-                            tool: moved.tool,
-                            ...(moved.action === undefined ? {} : { action: moved.action }),
-                        };
-                }),
-                ...(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 across 6 of 6
-        // apps: 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 moved = mergedNameRedirect(name);
-                if (moved !== undefined) {
-                    return {
-                        error: mergedNameMessage(name, moved),
-                        tool: moved.tool,
-                        ...(moved.action === undefined ? {} : { action: moved.action }),
-                    };
-                }
-                return { error: `unknown tool '${name}'`, available: allTools.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];
-}