@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,14 @@
+/**
+ * `reticle_lineage` — where a runtime value came from.
+ *
+ * When a verdict is `no`, or a contradiction fires, the next question is always the same. Today an
+ * agent answers it by hand: `reticle_state` for the value, `reticle_network` for the requests,
+ * `reticle_observe` for the window, then correlates the three itself — spending tokens and judgement
+ * on a join the daemon can do once from data it already holds.
+ *
+ * READ-ONLY BY CONSTRUCTION. It produces no verdict, so it is registered in `TOOLS` and deliberately
+ * NOT in the verification set, and nothing on an assert path reaches it. The decision logic lives in
+ * `events/lineage.ts` and is where the honesty rules are argued; this file is the surface.
+ */
+import type { ToolDef } from './tool-kit.js';
+export declare const LINEAGE_TOOLS: ToolDef[];

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

@@ -0,0 +1,64 @@
+/**
+ * `reticle_lineage` — where a runtime value came from.
+ *
+ * When a verdict is `no`, or a contradiction fires, the next question is always the same. Today an
+ * agent answers it by hand: `reticle_state` for the value, `reticle_network` for the requests,
+ * `reticle_observe` for the window, then correlates the three itself — spending tokens and judgement
+ * on a join the daemon can do once from data it already holds.
+ *
+ * READ-ONLY BY CONSTRUCTION. It produces no verdict, so it is registered in `TOOLS` and deliberately
+ * NOT in the verification set, and nothing on an assert path reaches it. The decision logic lives in
+ * `events/lineage.ts` and is where the honesty rules are argued; this file is the surface.
+ */
+import { z } from 'zod';
+import { ReticleTool } from '@reticlehq/core';
+import { traceLineage } from '@reticlehq/engine/question/lineage.js';
+import { asString } from '@reticlehq/core';
+import { cursorSchema } from './args/numeric-bounds.js';
+export const LINEAGE_TOOLS = [
+    {
+        name: ReticleTool.LINEAGE,
+        example: { path: 'user.profile.name' },
+        description: 'Trace BACKWARDS from a runtime value: which state change set it, which signal preceded that, and which request preceded the signal. Read-only — it draws no verdict and changes nothing. The state change is OBSERVED; every link above it is an INFERENCE from timing and says so in its own text. Where several candidates could explain a link it names ALL of them rather than choosing, because timing alone cannot justify the choice — so a chain here is a place to look, never a proven cause. Use it after a `no` verdict or a contradiction, instead of correlating reticle_state, reticle_network and reticle_observe by hand.',
+        inputSchema: {
+            path: z
+                .string()
+                .describe('The state path to trace, e.g. "user.profile.name". Matched as a substring.'),
+            value: z
+                .string()
+                .optional()
+                .describe('Narrow to the change that set THIS value, when the path changed more than once.'),
+            since: cursorSchema
+                .optional()
+                .describe('Only consider events after this cursor (from an act or observe result).'),
+            ...{},
+        },
+        outputSchema: {
+            found: z
+                .boolean()
+                .describe('False when the path was never seen to change — not the same as an empty chain.'),
+            chain: z
+                .array(z.object({
+                kind: z.string(),
+                text: z.string(),
+                observed: z.boolean(),
+                candidates: z.array(z.string()).optional(),
+            }))
+                .describe('Most recent change first. `observed` is true only for events we hold; every join is false.'),
+            note: z
+                .string()
+                .optional()
+                .describe('Why the chain stops where it does, when it stops early.'),
+        },
+        handler: (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = 'number' === typeof args['since'] ? args['since'] : 0;
+            const path = asString(args['path']) ?? '';
+            const value = asString(args['value']);
+            return Promise.resolve(traceLineage(session.eventsSince(since), {
+                path,
+                ...(value === undefined ? {} : { value }),
+            }));
+        },
+    },
+];

package/dist/surface/tools/live-call-text.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The advice, with every name the reader cannot call replaced by one they can.
+ *
+ * Text naming only advertised tools is returned unchanged and pays one scan.
+ */
+export declare function liveCallText(text: string, advertised: ReadonlySet<string>): string;
+/**
+ * The same rewrite, applied to a result's STRING VALUES instead of to its encoded form.
+ *
+ * This exists because the encoded form was the wrong place. The replacements above contain double
+ * quotes -- `reticle_verify { action: "flows" }` -- and splicing those into serialised JSON leaves
+ * them unescaped, so the payload stops parsing. MEASURED: three e2e specs that pass on the parent
+ * commit went red, each reporting an EMPTY session list, because the sessions diagnostic names
+ * `reticle_flow` and the rewrite broke the envelope around the data it was describing. The advice
+ * was corrected and the result became unreadable, which is a worse trade than the advice was worth.
+ *
+ * Values, not keys: a key is a contract with the caller and nothing in a key is advice.
+ *
+ * And not every value is advice either. A field that carries a tool's IDENTITY is an answer to
+ * "which one", not a suggestion about what to call — rewriting it destroys the thing the caller
+ * asked for. `reticle_tools { names: ["reticle_act_sequence"] }` sets `name` to the name it was
+ * asked about, and this rewrote it to `reticle_act`, so a batch query came back with entries the
+ * caller could no longer match to their questions. See `IDENTITY_KEYS`.
+ */
+export declare function liveCallValues(value: unknown, advertised: ReadonlySet<string>): unknown;

package/dist/surface/tools/live-call-text.js

@@ -0,0 +1,191 @@
+import { ReticleTool } from '@reticlehq/core';
+import { mergedNameRedirect } from './merged-name-redirect.js';
+/**
+ * Rewrite advice so every tool it names is one the reader was actually given.
+ *
+ * `surface-vocabulary.ts` made the BRIEFING derive its tool names from the advertised set, on the
+ * reasoning that naming a tool the agent lacks should be unrepresentable rather than merely tested
+ * for. That reasoning stops at the briefing. Everything attached to a RESULT -- a recovery, a
+ * `recommendation`, a `next_action`, a `note` -- is a static string written once, and those are
+ * what an agent reads under failure, which is exactly when it can least afford a dead end.
+ *
+ * MEASURED on the nine-tool surface: the no-session diagnosis, the command-timeout recovery and the
+ * multiple-sessions refusal all routed to `reticle_run` or `reticle_lease`, and that surface
+ * advertises neither. The timeout recovery even explained that `reticle_lease` "is not advertised
+ * under the default profile, so it is reached through reticle_run" -- correct about the lease,
+ * wrong about the hatch, and confident enough that a reader would not think to doubt it.
+ *
+ * Applied at the MCP boundary rather than at each string, because the next such string is written
+ * by somebody who does not know this rule exists.
+ */
+/**
+ * Advice that cannot be rewritten, only replaced.
+ *
+ * A merged name has somewhere to go -- `reticle_sessions` IS `reticle_session { action: "list" }`.
+ * The dispatch hatch does not: a surface that drops `reticle_run` and `reticle_lease` has no tool
+ * that opens a browser, so renaming would produce a sentence that is well-formed and still a lie.
+ * The CLI is the one escape hatch that survives every surface, because it is not a tool.
+ */
+const NO_TOOL_EQUIVALENT = [
+    {
+        needs: [ReticleTool.RUN, ReticleTool.LEASE],
+        // `\\?"` throughout: this runs over the SERIALISED result, where every quote is escaped. The
+        // first version matched only the unescaped shape, passed its unit test, and changed nothing at
+        // all in the live daemon -- found by re-driving the real MCP server rather than by the suite.
+        // The backticks are part of the match, not decoration around it. The shipped constant reads
+        // ``with `reticle_run { \u2026 }` (a human can equivalently run `reticle drive <url>`)``, and a
+        // pattern that stopped at `}` left the closing backtick sitting between it and the parenthetical
+        // \u2014 so the optional group could not match, the clause survived, and the replacement landed
+        // inside the original quoting. What an agent read was the human-equivalent clause twice over,
+        // with backticks nested three deep.
+        pattern: /`?reticle_run\s*\{\s*tool:\s*\\?"reticle_lease\\?"[^}]*\}`?(\s*\([^)]*\))?(\s*[-\u2014]+\s*reticle_lease is[^.]*\.)?/g,
+        instead: 'the CLI: `reticle open <url>` (a human can equivalently run `reticle drive <url>`)',
+    },
+    {
+        needs: [ReticleTool.LEASE],
+        // The bare cross-reference, left behind once the call above is gone.
+        pattern: /\breticle_lease\s*\{[^}]*\}/g,
+        instead: '`reticle open <url>`',
+    },
+    {
+        needs: [ReticleTool.FLOW],
+        // Saved-flow management is not on every surface and has no CLI. `verify { action: "flows" }`
+        // names every saved flow in its summary, which is what the advice was reaching for.
+        pattern: /\breticle_flow\s*\{[^}]*\}/g,
+        instead: 'reticle_verify { action: "flows" }, which names every saved flow',
+    },
+    /*
+     * Saving a flow is the PAYOFF the results keep advertising, and the default surface cannot do it.
+     *
+     * MEASURED while driving a real install: a passing `reticle_act` answered `keep: "… keep it as a
+     * regression flow with reticle_flow_save { saveAs: '<name>' }"`, and the `no-flow-intent` gap said
+     * to "save it again with intent". Calling it returns "reticle_flow_save exists in this build but
+     * is not reachable on this tool surface … there is no dispatch tool here to route through". Three
+     * separate results told the agent to do the one thing the surface withholds.
+     *
+     * `explore` is the reachable equivalent: it drives and RECORDS what it drove, which is what
+     * "keep this as a regression flow" was reaching for.
+     */
+    {
+        needs: [ReticleTool.RECORD, ReticleTool.FLOW_SAVE],
+        // The pair, first: rewriting the two names separately leaves "record one with X then X".
+        pattern: /\breticle_record\b\s*(?:\{[^}]*\})?(?:\s*start\/stop)?\s*(?:and|then|→|->|,\s*then)\s*\breticle_flow_save\b\s*(?:\{[^}]*\})?/g,
+        instead: 'reticle_verify { action: "explore", persona }, which drives it and records the flow',
+    },
+    /*
+     * Kept SHORT on purpose. This lands inside tool descriptions, which are re-sent on every turn of
+     * every session, and the longer two-route version cost 67 bytes there against a budget measured
+     * in whole-session terms — for advice that is read once, on a first run.
+     *
+     * `explore` needs ANTHROPIC_API_KEY and says so itself when it is missing, naming the fallback in
+     * the same breath ("flows are recorded by your own coding agent through the MCP tools"). That
+     * error is now recognised as ours, so the reader who hits it gets the next step instead of an
+     * invitation to file a defect report. One hop, and every hop is honest.
+     */
+    {
+        needs: [ReticleTool.FLOW_SAVE],
+        pattern: /\breticle_flow_save\b\s*(?:\{[^}]*\})?/g,
+        instead: 'reticle_verify { action: "explore", persona }',
+    },
+    {
+        needs: [ReticleTool.RECORD],
+        pattern: /\breticle_record\b\s*(?:\{[^}]*\})?/g,
+        instead: 'reticle_verify { action: "explore", persona }',
+    },
+];
+/** `reticle_session { action: "list" }` for a name that merged; the bare tool for one that did not. */
+function replacementFor(name, advertised) {
+    const redirect = mergedNameRedirect(name);
+    if (redirect === undefined)
+        return undefined;
+    // A redirect into a tool this surface also lacks is no better than the name we started with.
+    if (!advertised.has(redirect.tool))
+        return undefined;
+    return redirect.action === undefined
+        ? redirect.tool
+        : `${redirect.tool} { action: "${redirect.action}" }`;
+}
+/** Every `reticle_*` token in a piece of prose. */
+const TOOL_TOKEN = /\breticle_[a-z_]+\b/g;
+/**
+ * The advice, with every name the reader cannot call replaced by one they can.
+ *
+ * Text naming only advertised tools is returned unchanged and pays one scan.
+ */
+export function liveCallText(text, advertised) {
+    // The hatch is whole-phrase, so it runs FIRST: token rewriting would otherwise strip the inner
+    // `reticle_lease` and leave `reticle_run { tool: "..." }` pointing at nothing.
+    let out = text;
+    for (const { needs, pattern, instead } of NO_TOOL_EQUIVALENT) {
+        // Gated per entry: a surface keeping `reticle_flow` but dropping `reticle_lease` should have
+        // its flow advice left exactly as written.
+        if (needs.every((name) => advertised.has(name)))
+            continue;
+        out = out.replace(pattern, instead);
+    }
+    /**
+     * A sentence explaining where a name WENT keeps that name, even though it is unreachable.
+     *
+     * These messages open with their own subject — "reticle_act_sequence was merged into reticle_act",
+     * "reticle_refresh no longer exists" — and the rewrite is precisely a rule for replacing
+     * unreachable names, so it replaced the subject too. Asking about `reticle_act_sequence` answered
+     * "reticle_act no longer exists", which is false: `reticle_act` is a tool, and the one thing the
+     * reader needed to know was which name had moved.
+     *
+     * Only the leading token, and only in front of those two phrases. Every other mention in the same
+     * sentence — including the tool to call INSTEAD — is still rewritten, which is the whole job.
+     */
+    const explainsItsSubject = /^(reticle_[a-z_]+)(?= (?:was merged into|no longer exists))/.exec(out);
+    const subject = explainsItsSubject?.[1];
+    return out.replace(TOOL_TOKEN, (name, offset) => {
+        if (name === subject && 0 === offset)
+            return name;
+        if (advertised.has(name))
+            return name;
+        return replacementFor(name, advertised) ?? name;
+    });
+}
+/**
+ * Keys whose STRING value names a thing rather than advising a call.
+ *
+ * `name` is what the caller asked about and has to match their question against; `tool` is the
+ * already-resolved answer to "call this instead", so redirecting it a second time can only move it
+ * away from the answer. Deliberately two names and not a pattern: every other string in a result is
+ * prose, and prose is exactly what the rewrite is for.
+ */
+const IDENTITY_KEYS = new Set(['name', 'tool']);
+/**
+ * The same rewrite, applied to a result's STRING VALUES instead of to its encoded form.
+ *
+ * This exists because the encoded form was the wrong place. The replacements above contain double
+ * quotes -- `reticle_verify { action: "flows" }` -- and splicing those into serialised JSON leaves
+ * them unescaped, so the payload stops parsing. MEASURED: three e2e specs that pass on the parent
+ * commit went red, each reporting an EMPTY session list, because the sessions diagnostic names
+ * `reticle_flow` and the rewrite broke the envelope around the data it was describing. The advice
+ * was corrected and the result became unreadable, which is a worse trade than the advice was worth.
+ *
+ * Values, not keys: a key is a contract with the caller and nothing in a key is advice.
+ *
+ * And not every value is advice either. A field that carries a tool's IDENTITY is an answer to
+ * "which one", not a suggestion about what to call — rewriting it destroys the thing the caller
+ * asked for. `reticle_tools { names: ["reticle_act_sequence"] }` sets `name` to the name it was
+ * asked about, and this rewrote it to `reticle_act`, so a batch query came back with entries the
+ * caller could no longer match to their questions. See `IDENTITY_KEYS`.
+ */
+export function liveCallValues(value, advertised) {
+    if ('string' === typeof value)
+        return liveCallText(value, advertised);
+    if (Array.isArray(value))
+        return value.map((each) => liveCallValues(each, advertised));
+    if (null !== value && 'object' === typeof value) {
+        const out = {};
+        for (const [key, each] of Object.entries(value)) {
+            out[key] =
+                IDENTITY_KEYS.has(key) && 'string' === typeof each
+                    ? each
+                    : liveCallValues(each, advertised);
+        }
+        return out;
+    }
+    return value;
+}

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

@@ -0,0 +1,68 @@
+import type { ToolDef } from './tool-kit.js';
+/**
+ * Surface consolidation. Tool definitions are re-sent to the model EVERY turn, so the named-def
+ * count is a per-turn tax multiplied by loop length. This merges a family of sibling tools
+ * (`baseline_save`/`baseline_list`/`diff`) into one action-dispatched tool (`reticle_baseline {action}`)
+ * WITHOUT rewriting any handler — each original handler is kept verbatim and selected by `action`, so a
+ * merge cannot change behavior, only the advertised shape.
+ *
+ * The merged input schema is `{ action }` plus the union of the members' fields, each made optional
+ * (different actions need different fields). Every handler already narrows its own args, so validation
+ * strength is unchanged in practice.
+ *
+ * TRADEOFF (deliberate): a merged tool carries NO `outputSchema`, because its members return different
+ * shapes and one schema cannot describe them. Schema-aware clients lose output validation for merged
+ * families. That is why tools whose result contract matters — the 12-tool core hot-set, and hot verbs
+ * like flow_replay/flow_verify/flow_heal that return their own documented verdict shapes — are NOT
+ * merged. Only sibling families whose value is the capability, not the contract, are consolidated.
+ */
+interface MergeSpec {
+    name: string;
+    description: string;
+    /** action value → the original tool whose handler serves it. */
+    actions: Record<string, ToolDef>;
+    /** A concrete call, carried through to the merged def (see ToolDef.example). */
+    example?: Record<string, unknown>;
+    /**
+     * The action a bare call means. Omit where there is no obvious one.
+     *
+     * MEASURED, and it is the difference between a surface an agent uses and one it abandons. An
+     * agent's first two moves are zero-argument: "is anything connected?" then "what is on the page?".
+     * Merging turned both into `{action}` calls that refused a bare invocation, so the first move
+     * answered `unknown action 'undefined'`, the agent concluded the app was not wired, and it fixed
+     * all five benchmark bugs by reading source instead — 84 drive calls on the unmerged surface
+     * against 0, and one false green it reached in eight turns without ever opening the app.
+     *
+     * So a family whose common case is obvious names it, and a family whose name implies no single
+     * member does NOT — see `reticle_verify`, where one member really clicks and a wrong guess would
+     * drive the app instead of reading it.
+     */
+    defaultAction?: string;
+}
+/** A merge declared by member NAME, resolved against the assembled tool list. */
+export interface MergePlan {
+    name: string;
+    description: string;
+    /** action value → the existing tool name whose handler serves it. */
+    members: Record<string, string>;
+    /**
+     * A concrete call for the merged tool. Merging discards the members' own examples — the schema is
+     * a union and theirs are per-member — so a merged tool that reaches the core surface has no
+     * example at all unless the plan states one.
+     */
+    example?: Record<string, unknown>;
+    /** What a bare call means. See MergeSpec.defaultAction for the measurement behind this. */
+    defaultAction?: string;
+}
+/**
+ * Apply the consolidation to an assembled tool list: drop each plan's members and each retired name from
+ * the advertised surface, and append one action-dispatched tool per plan. Member ToolDefs stay defined in
+ * their own modules (handlers untouched) — they simply stop being advertised separately, which is the
+ * whole point: the cost is the advertised count, not the code.
+ *
+ * A plan naming a member that does not exist is a build error, not a silent no-op — a typo would
+ * otherwise quietly drop a capability from the surface.
+ */
+export declare function applyMerges(tools: readonly ToolDef[], plans: readonly MergePlan[], retired?: readonly string[]): ToolDef[];
+export declare function mergeTools(spec: MergeSpec): ToolDef;
+export {};

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

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+/** The field the merged tool dispatches on. A member may not declare one of its own — see below. */
+const DISCRIMINATOR = 'action';
+/** The union of member input shapes, every field optional so one schema serves every action. */
+function unionShape(actions) {
+    const shape = {};
+    for (const tool of Object.values(actions)) {
+        for (const [key, schema] of Object.entries(tool.inputSchema)) {
+            // First definition wins; siblings share field names/meanings by construction.
+            shape[key] ??= schema.isOptional() ? schema : schema.optional();
+        }
+    }
+    return shape;
+}
+/**
+ * A member that declares `action` itself cannot be merged, and the failure was SILENT.
+ *
+ * The merged schema is `{ action: enum(...), ...unionShape(members) }` — the union spreads SECOND,
+ * so a member's own `action` field replaced the dispatch enum. The handler then read `args.action`
+ * expecting a member name, got `'click'`, and answered `unknown action 'click'` for every call. The
+ * tool would have advertised, validated and refused everything.
+ *
+ * Nothing shipped this: it was found while merging `reticle_act` (whose `action` is the DOM action:
+ * click/fill/press) into a family, which is exactly the shape that triggers it. It throws at module
+ * load like the unknown-member error above, because both are the same class of mistake — a plan that
+ * silently produces a surface nobody can call.
+ */
+function refuseDiscriminatorCollision(name, actions) {
+    for (const [action, tool] of Object.entries(actions)) {
+        if (DISCRIMINATOR in tool.inputSchema) {
+            throw new Error(`mergeTools(${name}): member '${tool.name}' (action '${action}') declares its own ` +
+                `'${DISCRIMINATOR}' parameter, which would overwrite the dispatch discriminator and make ` +
+                `every call to ${name} unroutable. Rename the member's parameter or leave it unmerged.`);
+        }
+    }
+}
+/**
+ * Apply the consolidation to an assembled tool list: drop each plan's members and each retired name from
+ * the advertised surface, and append one action-dispatched tool per plan. Member ToolDefs stay defined in
+ * their own modules (handlers untouched) — they simply stop being advertised separately, which is the
+ * whole point: the cost is the advertised count, not the code.
+ *
+ * A plan naming a member that does not exist is a build error, not a silent no-op — a typo would
+ * otherwise quietly drop a capability from the surface.
+ */
+export function applyMerges(tools, plans, retired = []) {
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const consumed = new Set(retired);
+    const merged = [];
+    for (const plan of plans) {
+        const actions = {};
+        for (const [action, memberName] of Object.entries(plan.members)) {
+            const member = byName.get(memberName);
+            if (member === undefined) {
+                throw new Error(`applyMerges(${plan.name}): unknown member tool '${memberName}'`);
+            }
+            actions[action] = member;
+            consumed.add(memberName);
+        }
+        merged.push(mergeTools({
+            name: plan.name,
+            description: plan.description,
+            actions,
+            ...(plan.example === undefined ? {} : { example: plan.example }),
+            ...(plan.defaultAction === undefined ? {} : { defaultAction: plan.defaultAction }),
+        }));
+    }
+    return [...tools.filter((t) => !consumed.has(t.name)), ...merged];
+}
+/**
+ * The dispatch parameter: required where a bare call means nothing, optional where it means the
+ * default. Optional is what lets `reticle_look {}` answer instead of refusing, which is the whole
+ * reason a merged surface is usable at all.
+ */
+function discriminatorSchema(actionNames, defaultAction) {
+    const values = z.enum(actionNames);
+    if (defaultAction === undefined)
+        return values.describe('Which operation to run.');
+    return values.describe(`Which operation to run. Omit for "${defaultAction}".`).optional();
+}
+export function mergeTools(spec) {
+    const actionNames = Object.keys(spec.actions);
+    if (0 === actionNames.length)
+        throw new Error(`mergeTools(${spec.name}): no actions`);
+    refuseDiscriminatorCollision(spec.name, spec.actions);
+    if (spec.defaultAction !== undefined && !(spec.defaultAction in spec.actions)) {
+        throw new Error(`mergeTools(${spec.name}): defaultAction '${spec.defaultAction}' is not one of its actions`);
+    }
+    return {
+        name: spec.name,
+        description: spec.description,
+        ...(spec.example === undefined ? {} : { example: spec.example }),
+        inputSchema: {
+            [DISCRIMINATOR]: discriminatorSchema(actionNames, spec.defaultAction),
+            ...unionShape(spec.actions),
+        },
+        handler: (deps, args) => {
+            const named = args[DISCRIMINATOR];
+            const action = 'string' === typeof named ? named : spec.defaultAction;
+            const chosen = action === undefined ? undefined : spec.actions[action];
+            if (chosen === undefined) {
+                return Promise.resolve({
+                    error: `unknown action '${String(action)}' for ${spec.name}`,
+                    expected: actionNames,
+                });
+            }
+            return chosen.handler(deps, args);
+        },
+    };
+}

package/dist/surface/tools/merged-name-redirect.d.ts

@@ -0,0 +1,36 @@
+interface MergedNameRedirect {
+    /** The tool to call instead. */
+    tool: string;
+    /** The action that selects the old behaviour, when the name was merged rather than retired. */
+    action?: string;
+    /** Why there is no direct replacement, for a retired name. */
+    note?: string;
+}
+/** Where `name` went, or undefined when it is a live tool or not ours. */
+export declare function mergedNameRedirect(name: string): MergedNameRedirect | undefined;
+/**
+ * Every retired name against the call that replaces it — the tombstones, as one block.
+ *
+ * The redirect above answers an agent that already guessed the old name. This answers the one that
+ * is reading the surface to find out what exists, and is the case a redirect cannot reach: nothing
+ * in the catalogue says `reticle_crawl` became `reticle_verify { action: "crawl" }`, so instructions
+ * written against an earlier release lead either to an error string or to nothing at all.
+ *
+ * Derived from the same two declarations as `BY_OLD_NAME`, for the same reason: a hand-written
+ * migration list is one merge away from being wrong, and wrong is worse than absent here — the agent
+ * retries into it.
+ */
+export declare function retiredToolNames(): Readonly<Record<string, string>>;
+/** The sentence handed to an agent that called `name`. */
+export declare function mergedNameMessage(name: string, redirect: MergedNameRedirect, 
+/**
+ * Is the tool it moved INTO advertised on this surface? Pass it and the reader is told the one
+ * route that works here. Omit it only where the surface is genuinely unknown.
+ *
+ * The message used to end "through reticle_run if it is not advertised under this profile" for
+ * everybody. On the nine-tool surface that is two errors in one clause: the target IS advertised,
+ * and `reticle_run` is neither advertised nor callable there — so the sentence sent an agent that
+ * had just been handed a working call off to a tool that answers "not found".
+ */
+targetAdvertised?: boolean): string;
+export {};

package/dist/surface/tools/merged-name-redirect.js

@@ -0,0 +1,107 @@
+/**
+ * Where a merged or retired tool's old name went.
+ *
+ * Twenty-two names exported from `ReticleTool` are no longer tools: `reticle_record_start` became
+ * `reticle_record { action: "start" }`, `reticle_diff` became `reticle_baseline { action: "diff" }`,
+ * and three were retired outright. Confirmed live in a field sweep, they all answered `unknown tool`
+ * — which is the wrong answer, because the capability exists and only moved. An agent trained on an
+ * earlier release, or reading the merged tool's own description (which names every action), reaches
+ * for exactly these.
+ *
+ * DERIVED from `MERGE_PLANS`, `MERGED_SURFACE_PLANS` and `RETIRED_FROM_SURFACE` rather than written out, so the next merge is
+ * covered the day it lands instead of the day someone notices.
+ */
+import { MERGE_PLANS, MERGED_SURFACE_PLANS, RETIRED_FROM_SURFACE } from './tools.js';
+import { ReticleTool } from '@reticlehq/core';
+/** Retired names, and where the capability actually lives now. */
+const RETIRED_NOTE = {
+    [ReticleTool.REFRESH]: {
+        tool: ReticleTool.NAVIGATE,
+        note: 'reloading was absorbed into reticle_navigate { reload: true }',
+    },
+    [ReticleTool.RUN_RECORD]: {
+        tool: ReticleTool.PROJECT,
+        note: 'run outcomes are persisted automatically by reticle_flow_replay; read them with reticle_project',
+    },
+    [ReticleTool.WAIT_READY]: {
+        tool: ReticleTool.SESSIONS,
+        note: 'waiting is implicit — the first live call already blocks until the session is ready',
+    },
+};
+const BY_OLD_NAME = (() => {
+    const map = new Map();
+    // BOTH plan lists. This read `MERGE_PLANS` alone, and the surface merges — the ones that fold
+    // snapshot/query/inspect/state into `reticle_look` and network/console into `reticle_observe` —
+    // live in their own list. So on the surface where those names are ACTUALLY gone, the redirect knew
+    // nothing about them and the SDK answered `Tool reticle_snapshot not found`: the exact "this tool
+    // does not exist" that this whole file exists to stop an agent believing. Two hand-maintained
+    // lists that had to agree, and the one nobody updated was the one the reader hit.
+    for (const plan of [...MERGE_PLANS, ...MERGED_SURFACE_PLANS]) {
+        for (const [action, oldName] of Object.entries(plan.members)) {
+            map.set(oldName, { tool: plan.name, action });
+        }
+    }
+    for (const name of RETIRED_FROM_SURFACE) {
+        const known = RETIRED_NOTE[name];
+        if (known !== undefined)
+            map.set(name, known);
+    }
+    // The one merge no plan can describe. `reticle_act` absorbs `reticle_act_sequence` by the SHAPE of
+    // the call — a `steps` array — rather than by an `action`, because `act` already owns that
+    // parameter name (see act-merged.ts). Having no plan entry, it had no tombstone either, and was
+    // the last merged name still answering "not found" after every other one had a redirect. Set here
+    // rather than in RETIRED_NOTE because it is not retired: it is merged, and the distinction is what
+    // the reader needs.
+    map.set(ReticleTool.ACT_SEQUENCE, {
+        tool: ReticleTool.ACT,
+        note: 'a sequence is now reticle_act { steps: [...] } — the same call, routed on the steps array',
+    });
+    return map;
+})();
+/** Where `name` went, or undefined when it is a live tool or not ours. */
+export function mergedNameRedirect(name) {
+    return BY_OLD_NAME.get(name);
+}
+/**
+ * Every retired name against the call that replaces it — the tombstones, as one block.
+ *
+ * The redirect above answers an agent that already guessed the old name. This answers the one that
+ * is reading the surface to find out what exists, and is the case a redirect cannot reach: nothing
+ * in the catalogue says `reticle_crawl` became `reticle_verify { action: "crawl" }`, so instructions
+ * written against an earlier release lead either to an error string or to nothing at all.
+ *
+ * Derived from the same two declarations as `BY_OLD_NAME`, for the same reason: a hand-written
+ * migration list is one merge away from being wrong, and wrong is worse than absent here — the agent
+ * retries into it.
+ */
+export function retiredToolNames() {
+    const tombstones = {};
+    for (const [old, redirect] of BY_OLD_NAME) {
+        tombstones[old] =
+            redirect.action === undefined
+                ? `retired; ${redirect.note ?? `use ${redirect.tool}`}`
+                : `retired; use ${redirect.tool} { action: "${redirect.action}" }`;
+    }
+    return tombstones;
+}
+/** The sentence handed to an agent that called `name`. */
+export function mergedNameMessage(name, redirect, 
+/**
+ * Is the tool it moved INTO advertised on this surface? Pass it and the reader is told the one
+ * route that works here. Omit it only where the surface is genuinely unknown.
+ *
+ * The message used to end "through reticle_run if it is not advertised under this profile" for
+ * everybody. On the nine-tool surface that is two errors in one clause: the target IS advertised,
+ * and `reticle_run` is neither advertised nor callable there — so the sentence sent an agent that
+ * had just been handed a working call off to a tool that answers "not found".
+ */
+targetAdvertised) {
+    if (redirect.action === undefined) {
+        return `${name} no longer exists — ${redirect.note ?? `use ${redirect.tool}`}.`;
+    }
+    const call = `Call ${redirect.tool} { action: "${redirect.action}", ... }`;
+    if (true === targetAdvertised)
+        return `${name} was merged into ${redirect.tool}. ${call}.`;
+    return (`${name} was merged into ${redirect.tool}. ${call} — ` +
+        `through reticle_run if it is not advertised under this profile.`);
+}