@reticlehq/server 2.14.0 → 3.2.0

package/dist/tools/tool-kit.js

@@ -1,114 +0,0 @@
-/**
- * Shared kit for the MCP tool modules — the tool shape, the dependency bag, the common
- * session-id arg, and the two helpers (commandOrThrow, snapshotTree) every tool group needs. Lives
- * in its own leaf module (no dependency on any tool array) so the per-group tool files can import it
- * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
- */
-import { z } from 'zod';
-import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
-import { normalizeLines } from '../project/baselines.js';
-/**
- * The optional inline intent, on every tool that draws a verdict.
- *
- * One field, carrying either prose or the id of an intent already declared, because the surface is
- * the scarce thing and a second field for the reference case would double the cost of the idea to
- * make one of its two uses marginally more explicit. Told apart by the ledger — see
- * `intent/inline-intent.ts`.
- *
- * The first sentence is what a lean surface advertises, so it carries both readings; the rest is for
- * the profiles that send the whole description.
- */
-export const intentArg = z
-    .string()
-    .optional()
-    .describe('What this change is meant to make true — as a durable statement ABOUT THE PRODUCT, or the id of an intent you already declared. ' +
-    'Write it so a teammate who was not here understands it in six months: name the behaviour, not this run. ' +
-    'GOOD: "a filtered issue queue is a shareable link — the filter is in the URL". ' +
-    'BAD: "P1 step 5", "drive 2 of 2", "same as before the fix", "the board renders cleanly" — these name a session, ' +
-    'a step number or nothing checkable, and the person reading them later has none of that context. ' +
-    'This is shared memory: it is pooled per project and later agents read it back to avoid re-deriving what you just established. ' +
-    'Recorded in .reticle/intent.json, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
-export const sessionIdShape = {
-    sessionId: z
-        .string()
-        .optional()
-        .describe('OMIT THIS unless you mean a specific tab — Reticle scopes to your project, prefers the active one, and refuses rather than guesses when ambiguous. Pass an id from reticle_sessions only to target a particular tab. The previous wording ("omit when only ONE session is open") was wrong and cost real turns: with three sessions connected — an app plus two pool leases — resolution is still unambiguous, but that sentence sent the agent off to list and filter sessions by hand before every single call.'),
-};
-/**
- * Every key `runTool` splices onto a session-bound result, as a closed list.
- *
- * These are wire strings and were inlined at the splice sites, which is exactly how four of them
- * came to be spliced and never declared. `sessionEnvelopeShape` is derived from this object and
- * `envelope-keys-declared.test.ts` fails if a member is missing from it, so the two cannot drift.
- *
- * Each of these is a channel that exists BECAUSE the agent had no other way to learn the fact.
- * Undeclared, a schema-strict client validating `structuredContent` drops it, and the channel is
- * indistinguishable from never having been built.
- */
-export const EnvelopeKey = {
-    /** Session health — which tab, how fresh. */
-    SESSION: 'session',
-    /** One-shot pool-lease reminder. */
-    SESSION_LEASE: 'session_lease',
-    /** One-shot "these sessions are old, clean them up". */
-    SESSION_AGE_WARNING: 'session_age_warning',
-    /** The delivered-once human-in-the-loop guidance envelope. Losing it is a safety failure. */
-    CONTROL: 'control',
-    /**
-     * Rides alongside `session` whenever the tab is THROTTLED. It was declared on `reticle_act`'s
-     * schema and nowhere else, so on a validating profile every other session-bound tool silently
-     * dropped it — a throttled tab, where drives can no-op, returned a healthy-looking result.
-     */
-    WARNING: 'warning',
-    /** One-shot "ask the human how this went". */
-    FEEDBACK_PROMPT: 'feedback_prompt',
-    /** One-shot "a newer Reticle exists". */
-    UPDATE_AVAILABLE: 'update_available',
-    /**
-     * "You have driven this page N times without asking for a verdict."
-     *
-     * The largest known lever on the metric this product is judged by: verdict-less sessions
-     * overwhelmingly never call a verdict-producing tool at all. It was spliced undeclared, so on a
-     * validating client the nudge was built, fired, and thrown away before any agent saw it.
-     */
-    VERIFY_NEXT: 'verify_next',
-    /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
-    FEEDBACK_INVITE: 'feedback_invite',
-    /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
-    VERSION_SKEW: 'version_skew',
-    /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
-    FEEDBACK_UNDELIVERED: 'feedback_undelivered',
-};
-/**
- * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
- * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
- * validation) keeps them instead of silently dropping them.
- *
- * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
- * whole release, and every key that went missing was a channel nobody could see was missing.
- */
-export const sessionEnvelopeShape = Object.fromEntries(Object.values(EnvelopeKey).map((key) => [
-    key,
-    // `warning` is the one with a narrower type; the rest are opaque envelopes the client forwards.
-    EnvelopeKey.WARNING === key ? z.string().optional() : z.unknown().optional(),
-]));
-/** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
-export async function commandOrThrow(deps, sessionId, 
-// ReticleCommand, not string: the union already exists and every caller passes a member. Typed as
-// `string` a sessionId/name swap compiled cleanly and failed at runtime with a stringly error.
-name, args) {
-    const session = deps.sessions.resolve(sessionId);
-    const result = await session.command(name, args);
-    if (!result.ok)
-        throw new Error(result.error ?? `command '${name}' failed`);
-    return result.result;
-}
-/** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */
-export async function snapshotTree(deps, sessionId) {
-    const session = deps.sessions.resolve(sessionId);
-    const result = await session.command(ReticleCommand.SNAPSHOT, { mode: SnapshotMode.FULL });
-    if (!result.ok)
-        throw new Error(result.error ?? 'snapshot failed');
-    const snap = (result.result ?? {});
-    return { lines: normalizeLines(snap.tree ?? ''), route: snap.status?.route ?? '' };
-}

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

@@ -1,112 +0,0 @@
-/** MCP tool names exposed to the coding agent. No free strings. The three that appear in a persisted
- *  flow (ACT / ACT_SEQUENCE / ACT_AND_WAIT) come from core's FlowStepTool — one source shared with the
- *  browser recorder and the flow schema, so a rename can't desync the recorder from the replayer. */
-export declare const ReticleTool: {
-    readonly SESSIONS: "reticle_sessions";
-    readonly SNAPSHOT: "reticle_snapshot";
-    readonly QUERY: "reticle_query";
-    readonly INSPECT: "reticle_inspect";
-    readonly ACT: "reticle_act";
-    readonly ACT_SEQUENCE: "reticle_act_sequence";
-    readonly ACT_AND_WAIT: "reticle_act_and_wait";
-    readonly OBSERVE: "reticle_observe";
-    readonly LINEAGE: "reticle_lineage";
-    readonly WAIT_FOR: "reticle_wait_for";
-    readonly NETWORK: "reticle_network";
-    readonly CONSOLE: "reticle_console";
-    readonly ANIMATIONS: "reticle_animations";
-    readonly ASSERT: "reticle_assert";
-    readonly RECONCILE: "reticle_reconcile";
-    readonly BASELINE_SAVE: "reticle_baseline_save";
-    readonly BASELINE_LIST: "reticle_baseline_list";
-    readonly DIFF: "reticle_diff";
-    readonly RECORD_START: "reticle_record_start";
-    readonly RECORD_STOP: "reticle_record_stop";
-    readonly REPLAY: "reticle_replay";
-    readonly EXPLORE: "reticle_explore";
-    readonly NARRATE: "reticle_narrate";
-    readonly CLOCK: "reticle_clock";
-    readonly STATE: "reticle_state";
-    readonly STORAGE: "reticle_storage";
-    readonly CAPABILITIES: "reticle_capabilities";
-    readonly CONTRACT_SAVE: "reticle_contract_save";
-    readonly DOMAIN: "reticle_domain";
-    readonly FLOW_SAVE: "reticle_flow_save";
-    readonly FLOW_LIST: "reticle_flow_list";
-    readonly FLOW_LOAD: "reticle_flow_load";
-    readonly FLOW_DELETE: "reticle_flow_delete";
-    readonly FLOW_REPLAY: "reticle_flow_replay";
-    /** replay EVERY saved flow → one consolidated suite verdict + prioritized fixes (the loop closer). */
-    readonly FLOW_VERIFY: "reticle_flow_verify";
-    /** persist the human-recorded flow from the live tab. */
-    readonly FLOW_SAVE_RECORDED: "reticle_flow_save_recorded";
-    /** propose (+ opt-in apply) a nearest-match rebind for a drifted flow. */
-    readonly FLOW_HEAL: "reticle_flow_heal";
-    /** structured annotation → compiles into the recording's expect/dynamic/success. */
-    readonly ANNOTATE: "reticle_annotate";
-    readonly AFFECTED: "reticle_affected";
-    readonly COVERAGE: "reticle_coverage";
-    readonly VERIFY_CHANGE: "reticle_verify_change";
-    /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
-    readonly INTENT: "reticle_intent";
-    /** what THIS run has established, proved, and not yet discharged — pulled when memory is gone. */
-    readonly CONTEXT: "reticle_context";
-    readonly VERIFY: "reticle_verify";
-    /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
-    readonly PROJECT: "reticle_project";
-    /** The team's shared memory, read on demand — see memory/memory-tools.ts. */
-    readonly MEMORY: "reticle_memory";
-    /** explicitly record a run outcome (the manual companion to auto-recording). */
-    readonly RUN_RECORD: "reticle_run_record";
-    /** capture a pixel screenshot (CDP/driven browser) →.reticle/visual/<name>.png. */
-    readonly SCREENSHOT: "reticle_screenshot";
-    /** stub/intercept network on the driven page (500, offline, delay) for error/edge-state testing. */
-    readonly NETWORK_MOCK: "reticle_network_mock";
-    /** pin the driven page's viewport to fixed pixels for reproducible visual baselines. */
-    readonly VIEWPORT: "reticle_viewport";
-    /** perceptual-diff the live page against a saved visual baseline. */
-    readonly VISUAL_DIFF: "reticle_visual_diff";
-    /** autonomously click every reachable control + report anomalies (no script). */
-    readonly CRAWL: "reticle_crawl";
-    /** scroll a virtualized list until a queried row mounts, then return it. */
-    readonly SCROLL_TO: "reticle_scroll_to";
-    /** Session lifecycle: tune the presenter session (e.g. idle-end window) for the app's needs.
-     * Member of the consolidated reticle_session {action:"tune"} — no longer advertised alone. */
-    readonly SESSION_TUNE: "reticle_session_tune";
-    /** Live-control: end the session (→ ended + push PRESENTER). Handlers live in the tools facet. */
-    readonly END_SESSION: "reticle_end_session";
-    /** Live-control: hand the session back to the human between turns (→ waiting/ask, revivable). */
-    readonly YIELD: "reticle_yield";
-    /** Live-control: clear a pause (→ active). */
-    readonly RESUME: "reticle_resume";
-    /** Live-control: drain the human→agent inbox (explicit poll). */
-    readonly MESSAGES: "reticle_messages";
-    /** Human review: list the mistakes the human pinned to elements, and resolve them once fixed. */
-    readonly REVIEW: "reticle_review";
-    /** First-run readiness: block briefly until the app's SDK connects (smooths the init→connect race). */
-    readonly WAIT_READY: "reticle_wait_ready";
-    /** Navigate the connected browser tab to a URL. */
-    readonly NAVIGATE: "reticle_navigate";
-    /** Reload the connected browser tab (soft or hard). */
-    readonly REFRESH: "reticle_refresh";
-    /** Export a verification-run artifact (.reticle/runs/<id>.json) — the OEM/CI-consumable verdict. */
-    readonly RUN_EXPORT: "reticle_run_export";
-    /** Consolidated families — one action-dispatched tool per family; members below stay
-     * defined (handlers intact) but are no longer advertised separately. */
-    readonly BASELINE: "reticle_baseline";
-    readonly SESSION: "reticle_session";
-    readonly RECORD: "reticle_record";
-    readonly FLOW: "reticle_flow";
-    readonly LEASE: "reticle_lease";
-    /** Lease a fresh isolated headless context from the shared browser pool (one per flow). */
-    readonly LEASE_ACQUIRE: "reticle_lease_acquire";
-    /** Release a previously leased context, freeing the pool slot. */
-    readonly LEASE_RELEASE: "reticle_lease_release";
-    /** Meta: discover tool definitions on demand instead of paying for all of them every turn. */
-    readonly TOOLS: "reticle_tools";
-    /** Meta: invoke any tool by name — the escape hatch that keeps a trimmed profile a trim, not a removal. */
-    readonly RUN: "reticle_run";
-    /** Report that Reticle itself failed — the agent's only way to tell us what to fix. */
-    readonly FEEDBACK: "reticle_feedback";
-};
-export type ReticleTool = (typeof ReticleTool)[keyof typeof ReticleTool];

package/dist/tools/tool-names.js

@@ -1,112 +0,0 @@
-import { FlowStepTool } from '@reticlehq/core';
-/** MCP tool names exposed to the coding agent. No free strings. The three that appear in a persisted
- *  flow (ACT / ACT_SEQUENCE / ACT_AND_WAIT) come from core's FlowStepTool — one source shared with the
- *  browser recorder and the flow schema, so a rename can't desync the recorder from the replayer. */
-export const ReticleTool = {
-    SESSIONS: 'reticle_sessions',
-    SNAPSHOT: 'reticle_snapshot',
-    QUERY: 'reticle_query',
-    INSPECT: 'reticle_inspect',
-    ACT: FlowStepTool.ACT,
-    ACT_SEQUENCE: FlowStepTool.ACT_SEQUENCE,
-    ACT_AND_WAIT: FlowStepTool.ACT_AND_WAIT,
-    OBSERVE: 'reticle_observe',
-    LINEAGE: 'reticle_lineage',
-    WAIT_FOR: 'reticle_wait_for',
-    NETWORK: 'reticle_network',
-    CONSOLE: 'reticle_console',
-    ANIMATIONS: 'reticle_animations',
-    ASSERT: 'reticle_assert',
-    RECONCILE: 'reticle_reconcile',
-    BASELINE_SAVE: 'reticle_baseline_save',
-    BASELINE_LIST: 'reticle_baseline_list',
-    DIFF: 'reticle_diff',
-    RECORD_START: 'reticle_record_start',
-    RECORD_STOP: 'reticle_record_stop',
-    REPLAY: 'reticle_replay',
-    EXPLORE: 'reticle_explore',
-    NARRATE: 'reticle_narrate',
-    CLOCK: 'reticle_clock',
-    STATE: 'reticle_state',
-    STORAGE: 'reticle_storage',
-    CAPABILITIES: 'reticle_capabilities',
-    CONTRACT_SAVE: 'reticle_contract_save',
-    DOMAIN: 'reticle_domain',
-    FLOW_SAVE: 'reticle_flow_save',
-    FLOW_LIST: 'reticle_flow_list',
-    FLOW_LOAD: 'reticle_flow_load',
-    FLOW_DELETE: 'reticle_flow_delete',
-    FLOW_REPLAY: 'reticle_flow_replay',
-    /** replay EVERY saved flow → one consolidated suite verdict + prioritized fixes (the loop closer). */
-    FLOW_VERIFY: 'reticle_flow_verify',
-    /** persist the human-recorded flow from the live tab. */
-    FLOW_SAVE_RECORDED: 'reticle_flow_save_recorded',
-    /** propose (+ opt-in apply) a nearest-match rebind for a drifted flow. */
-    FLOW_HEAL: 'reticle_flow_heal',
-    /** structured annotation → compiles into the recording's expect/dynamic/success. */
-    ANNOTATE: 'reticle_annotate',
-    AFFECTED: 'reticle_affected',
-    COVERAGE: 'reticle_coverage',
-    VERIFY_CHANGE: 'reticle_verify_change',
-    /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
-    INTENT: 'reticle_intent',
-    /** what THIS run has established, proved, and not yet discharged — pulled when memory is gone. */
-    CONTEXT: 'reticle_context',
-    VERIFY: 'reticle_verify',
-    /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
-    PROJECT: 'reticle_project',
-    /** The team's shared memory, read on demand — see memory/memory-tools.ts. */
-    MEMORY: 'reticle_memory',
-    /** explicitly record a run outcome (the manual companion to auto-recording). */
-    RUN_RECORD: 'reticle_run_record',
-    /** capture a pixel screenshot (CDP/driven browser) →.reticle/visual/<name>.png. */
-    SCREENSHOT: 'reticle_screenshot',
-    /** stub/intercept network on the driven page (500, offline, delay) for error/edge-state testing. */
-    NETWORK_MOCK: 'reticle_network_mock',
-    /** pin the driven page's viewport to fixed pixels for reproducible visual baselines. */
-    VIEWPORT: 'reticle_viewport',
-    /** perceptual-diff the live page against a saved visual baseline. */
-    VISUAL_DIFF: 'reticle_visual_diff',
-    /** autonomously click every reachable control + report anomalies (no script). */
-    CRAWL: 'reticle_crawl',
-    /** scroll a virtualized list until a queried row mounts, then return it. */
-    SCROLL_TO: 'reticle_scroll_to',
-    /** Session lifecycle: tune the presenter session (e.g. idle-end window) for the app's needs.
-     * Member of the consolidated reticle_session {action:"tune"} — no longer advertised alone. */
-    SESSION_TUNE: 'reticle_session_tune',
-    /** Live-control: end the session (→ ended + push PRESENTER). Handlers live in the tools facet. */
-    END_SESSION: 'reticle_end_session',
-    /** Live-control: hand the session back to the human between turns (→ waiting/ask, revivable). */
-    YIELD: 'reticle_yield',
-    /** Live-control: clear a pause (→ active). */
-    RESUME: 'reticle_resume',
-    /** Live-control: drain the human→agent inbox (explicit poll). */
-    MESSAGES: 'reticle_messages',
-    /** Human review: list the mistakes the human pinned to elements, and resolve them once fixed. */
-    REVIEW: 'reticle_review',
-    /** First-run readiness: block briefly until the app's SDK connects (smooths the init→connect race). */
-    WAIT_READY: 'reticle_wait_ready',
-    /** Navigate the connected browser tab to a URL. */
-    NAVIGATE: 'reticle_navigate',
-    /** Reload the connected browser tab (soft or hard). */
-    REFRESH: 'reticle_refresh',
-    /** Export a verification-run artifact (.reticle/runs/<id>.json) — the OEM/CI-consumable verdict. */
-    RUN_EXPORT: 'reticle_run_export',
-    /** Consolidated families — one action-dispatched tool per family; members below stay
-     * defined (handlers intact) but are no longer advertised separately. */
-    BASELINE: 'reticle_baseline',
-    SESSION: 'reticle_session',
-    RECORD: 'reticle_record',
-    FLOW: 'reticle_flow',
-    LEASE: 'reticle_lease',
-    /** Lease a fresh isolated headless context from the shared browser pool (one per flow). */
-    LEASE_ACQUIRE: 'reticle_lease_acquire',
-    /** Release a previously leased context, freeing the pool slot. */
-    LEASE_RELEASE: 'reticle_lease_release',
-    /** Meta: discover tool definitions on demand instead of paying for all of them every turn. */
-    TOOLS: 'reticle_tools',
-    /** Meta: invoke any tool by name — the escape hatch that keeps a trimmed profile a trim, not a removal. */
-    RUN: 'reticle_run',
-    /** Report that Reticle itself failed — the agent's only way to tell us what to fix. */
-    FEEDBACK: 'reticle_feedback',
-};

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

@@ -1,222 +0,0 @@
-import type { ToolDef } from './tools.js';
-/**
- * There is ONE tool surface. This is not a menu.
- *
- * The advertised tool DEFINITIONS are re-sent to the model on every turn, so the surface is a
- * per-turn cost that compounds across a loop, and fewer tools also makes the model wander less.
- * What ships is the verify loop (navigate→look→act→observe→assert, with direct network + console +
- * state) advertised directly, plus two meta-tools — `reticle_tools` to discover and `reticle_run` to
- * invoke — that keep every other tool exactly one call away. Nothing is unreachable; the cold tail
- * just is not re-sent every turn.
- *
- * Five profiles were tried. Four are gone, each for a measured reason rather than a taste:
- *
- * `core` was BYTE-IDENTICAL to the default — 16 tools, 18,183 bytes, the same list. One behaviour
- * behind two names is how "I set it and nothing changed" becomes a support question with no answer.
- *
- * `standard` advertised 17 more tools directly for ~3,500 extra tokens EVERY TURN, buying only the
- * removal of an occasional `reticle_run` hop. Nothing about that was characterisable as a use case.
- *
- * `dynamic` advertised the 2 meta-tools and nothing else. Not one harness, app or bench ever
- * selected it, and this repo's own measurement (bench/agent-loop-and-replay.md) says a pure
- * on-demand surface does NOT hold accuracy with a generic model: "it needs the hot-set schemas.
- * On-demand is for the cold tail, not the hot path." An option that is unused and measured-worse is
- * a trap, not a choice — it looks like a 4,000-token saving and costs correctness.
- *
- * ALL is what remains, and it is deliberately NOT a profile: it is a verification switch. It is the
- * only mode that advertises `outputSchema`, which is what makes the MCP layer validate tool OUTPUT —
- * the check that caught `reticle_verify_change` returning a payload its own schema rejected. It
- * cannot be folded into the default: measured, carrying output schemas on the 16-tool surface costs
- * 18,183 -> 41,117 bytes, 2.26x, +5,733 tokens per turn. And it cannot simply be deleted without
- * losing that defect class. So it stays, named for what it is, and no user is asked to pick it.
- *
- * Sizes are NOT restated here — not as a current figure, not as a historical one. Four generations
- * of this comment got them wrong. They live in surface-sizes.test.ts, which reads them off the real
- * surface. (The numbers above are the two measurements that JUSTIFY a decision, which is a different
- * job from documenting the current size; both were taken with a fresh daemon per reading.)
- */
-export declare const TOOL_SURFACE: {
-    /** What every user gets: the verify loop, plus the 2 meta-tools that reach everything else. */
-    readonly DEFAULT: "default";
-    /** Every tool advertised directly, WITH output schemas. A verification switch — see above. */
-    readonly ALL: "all";
-    /**
-     * The smallest surface that can still produce a VERDICT. Not a profile — a cost switch.
-     *
-     * Measured on the wire: a verification that names its own target costs one `act_and_wait` call,
-     * and 5,480 of its 5,909 tokens are the advertised surface re-sent for that single turn. The
-     * answers cost 430. So on the path where the caller already knows what to assert, almost the
-     * entire bill is the menu, and the menu is the thing to cut.
-     *
-     * Deliberately NOT the default, and now MEASURED rather than inherited. Run over the same 30-bug
-     * set that the default surface scores 23/27 detection and 2/29 false alarms on:
-     *
-     *   detection      24/28   (held)
-     *   FALSE ALARMS   7/30    (was 2/29 — TRIPLED)
-     *   tokens         113,599 per run (was 179,959 — 37% cheaper)
-     *
-     * The five new false alarms are not scattered. They are `mutation-leak` and
-     * `generate-blast-filter` (state), `kpi-deploys-tamper` (business-logic), `debounce-broken`
-     * (timing) and `route-stuck-deployments` (routing) — precisely the classes whose evidence lives in
-     * `reticle_state`, `reticle_network` and `reticle_observe`, which this surface does not advertise.
-     * Strip the observation tools and the model stops observing: it reaches for the verdict without
-     * the evidence and calls a healthy build broken.
-     *
-     * So the retired `dynamic` finding is confirmed, with a sharper mechanism than "accuracy drops".
-     * 37% of the tokens is not worth trading for the one metric this product actually wins on, and
-     * this must not become the default on the strength of the token number alone.
-     *
-     * It remains correct for a caller who has ALREADY decided what to assert — there the assertion
-     * supplies the evidence the surface would otherwise have to go and find.
-     */
-    readonly VERIFY: "verify";
-    /**
-     * EXPERIMENTAL, opt-in, and UNDER MEASUREMENT. Not a recommendation, and not on a path to becoming
-     * the default until it has a number of its own.
-     *
-     * It exists because of the finding recorded on VERIFY above, read forwards instead of backwards.
-     * That surface cut the bill 37% and TRIPLED false alarms, and the five new false alarms were not
-     * scattered: every one of them was a defect whose evidence lives in `reticle_state`,
-     * `reticle_network` or `reticle_observe`. So the token saving and the accuracy loss came from two
-     * different cuts, and only one of them has to be paid for. `lean` keeps every observation tool and
-     * cuts the rest.
-     *
-     * What stays, and why each one is not a candidate for removal:
-     *   SNAPSHOT / QUERY   look. Without them the agent cannot name an element it did not already know.
-     *   STATE / NETWORK / CONSOLE / OBSERVE   the four evidence tools. Dropping these is the MEASURED
-     *                      cause of the tripled false-alarm rate. They are the point of the profile.
-     *   ACT_AND_WAIT       the only tool that acts AND returns a verdict. Omitting `until` makes it
-     *                      act-then-settle, which is what `reticle_act` does, so `act` is redundant here.
-     *   ASSERT             the only way to get a verdict WITHOUT acting. `act_and_wait` requires an
-     *                      `action`, so this is a capability it genuinely cannot express, not a synonym.
-     *
-     * What goes, and what it costs (one `reticle_run` hop each — `unadvertisedToolHelp` hands the agent
-     * the exact call, so a dropped name never comes back as "not found"):
-     *   ACT                subsumed: `act_and_wait` with `until` omitted is act-then-settle.
-     *   WAIT_FOR           subsumed: `act_and_wait { until }` takes the same PredicateSchema.
-     *   ACT_SEQUENCE       batching is a cost optimisation on top of a surface built to be cheap.
-     *   NAVIGATE           once per run, not once per turn — the wrong thing to pay for every turn.
-     *   SESSIONS           the CLI answers this (`reticle status`) without spending any turn budget.
-     *   INSPECT            fix-side, not verdict-side: it is called once a bug is FOUND, so its hop is
-     *                      paid once per finding rather than once per turn. Nothing else maps a node to
-     *                      a source file, which is why it is a hop and not a deletion.
-     *   SESSION            the lease block and the pause hint name it in prose, which is what made it
-     *                      load-bearing on the default surface. Under a trimmed surface the
-     *                      unadvertised-tool help turns that into a working `reticle_run` call.
-     *   FEEDBACK           the one drop with a KNOWN CEILING: an unadvertised feedback channel collects
-     *                      little to nothing, so a long-lived profile must not ship without it. Acceptable
-     *                      only because this profile is opt-in and short-lived by construction; if it
-     *                      ever stops being an experiment, feedback comes back first.
-     */
-    readonly LEAN: "lean";
-};
-export type ToolSurface = (typeof TOOL_SURFACE)[keyof typeof TOOL_SURFACE];
-/**
- * The switch that turns on the full, output-schema-carrying surface. A boolean, not a menu.
- *
- * Named for what it does rather than which "profile" it selects, because the previous name invited
- * users to shop among alternatives that did not meaningfully differ.
- */
-export declare const ADVERTISE_ALL_ENV = "RETICLE_ADVERTISE_ALL_TOOLS";
-/**
- * The retired setting, still read so nobody's shell profile breaks.
- *
- * Every value it ever accepted resolves to something sensible: `full` to the ALL surface, everything
- * else to the default. Silently honouring them would repeat the original sin, so `describeToolSurface`
- * says the setting retired and what was used instead.
- */
-export declare const TOOL_PROFILE_ENV = "RETICLE_TOOL_PROFILE";
-export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
-/**
- * The extended surface: what `all` advertises BEYOND the default set.
- *
- * `all` used to mean "every tool in the registry", and that is no longer allowed to be true. Cursor
- * enforces a limit of 40 tools across every connected MCP server COMBINED, so a server advertising
- * 48 by itself can push a user's other servers out or be dropped wholesale. The budget is a count,
- * so no amount of trimming parameter prose buys anything back — only advertising fewer names does.
- *
- * That is true of the COUNT cap and false of everything else, which is worth separating here before
- * somebody reads it as "prose is free". Measured against two competitor MCP servers on the same
- * agent loop: this server advertises the FEWEST tools of the three and ships the HEAVIEST schema
- * block, and 83% of that weight is parameter descriptions, not tool descriptions. The block is
- * re-sent every turn, so it is multiplied by turn count before one byte of evidence is counted, and
- * it was most of the gap in that run.
- *
- * Which does NOT license trimming by eye. Those descriptions are what make a tool get called
- * correctly, and one malformed call costs a whole extra turn — more than the bytes saved. The
- * outcome to measure is turn count and error rate, not size.
- *
- * Everything omitted stays in the registry, stays catalogued by `reticle_tools`, and stays callable
- * by name through `reticle_run { tool, args }`. The cost is one discovery hop on the cold tail, which
- * is the same trade the default surface has always made, applied one level further out.
- *
- * What it costs that is NOT free: `all` is the only surface that carries `outputSchema`, which is
- * what makes the MCP layer validate tool OUTPUT — the check that once caught `reticle_verify_change`
- * returning a payload its own schema rejected. The tools left off this list no longer get that
- * validation from the wire. That defect class is now uncovered for them, and it is written down here
- * rather than discovered later.
- *
- * Chosen as the capabilities an agent plausibly reaches for once the verify loop is not enough:
- * orientation, the record/replay flow loop, visual evidence, and the three fault-injection controls.
- */
-export declare const EXTENDED_TOOL_NAMES: ReadonlySet<string>;
-/**
- * The lean surface: look, observe, act-with-a-verdict, assert. Pinned by lean-surface.test.ts,
- * because an experiment whose independent variable drifts mid-flight measures nothing. Every
- * inclusion and every exclusion is argued at TOOL_SURFACE.LEAN.
- *
- * ## MEASURED: it is cheaper and less correct. Do not promote it to the default.
- *
- * Run as its own arm of the fix-and-verify benchmark — same five bugs, same model, same budget, the
- * full surface as its control:
- *
- * | | full surface | lean |
- * |---|---|---|
- * | bugs fixed | **5/5** | **3/5** |
- * | FALSE GREENS | **0** | **1** |
- *
- * The false green is the finding, and it is the first this benchmark has ever produced. On
- * `broken-form-validation` the lean agent finished in SIX turns and 62k tokens — the cheapest cell
- * of the whole run, a fifth of what the full surface spent — edited the file, took one snapshot,
- * and ended with a hypothetical walkthrough: "Enter spaces + valid name -> spaces are trimmed,
- * valid part is used. VERDICT: FIXED". The submit button was still enabled for a whitespace-only
- * service. It reasoned about what its own code would now do instead of driving it, which is exactly
- * the failure this product exists to catch, produced by our own surface.
- *
- * The other loss has the same root from the other side. On `cross-component-regression` the agent
- * called `reticle_tools` three times and `reticle_run` eight, saying "since Reticle isn't
- * connecting, let me see what reticle_tools offers" — it spent the run hunting for capabilities
- * this surface does not advertise instead of using them, and never fixed the bug.
- *
- * That is the same result the `verify` surface already recorded — dropping the observation tools
- * TRIPLED false alarms — arriving from the other direction: strip the surface and the agent stops
- * verifying, then claims anyway. The known ceiling written here was that `reticle_feedback` goes
- * uncollected. This is a bigger one and it was not predicted.
- *
- * It stays opt-in and it stays measured. The one thing it genuinely bought — the ceiling-bound cell
- * halved, 30 turns to 14 — is not worth a verdict that lies, because the product is the verdict.
- */
-export declare const LEAN_TOOL_NAMES: ReadonlySet<string>;
-/**
- * Which surface is live.
- *
- * `explicit` is the programmatic override (tests, `advertisedTools` callers). Otherwise the ALL
- * switch decides, and the retired setting is honoured last so an old shell profile still works.
- */
-export declare function resolveToolSurface(explicit?: string): ToolSurface;
-/** The live surface plus what chose it — see describeToolSurface. */
-export interface ToolSurfaceOrigin {
-    active: ToolSurface;
-    source: string;
-}
-/**
- * Which surface is live, and what chose it.
- *
- * These settings are read by the DAEMON at startup, never by the client, so exporting one in an
- * agent's environment while a daemon is already running changes nothing at all — which is exactly
- * the observation that produced a "standard and full advertise the same tools" report. Documenting
- * that was not enough; the setting failing to take has to be VISIBLE, so this rides along in the
- * reticle_tools catalog.
- */
-export declare function describeToolSurface(active: ToolSurface, requested?: string): ToolSurfaceOrigin;
-export declare function filterTools(tools: ToolDef[], surface: ToolSurface): ToolDef[];