@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,254 @@
+/**
+ * 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 { type ProjectId, ReticleCommand } from '@reticlehq/core';
+import type { SessionManager } from '../../portal/session/session-manager.js';
+import type { RealInputProvider } from '../../portal/input/real-input.js';
+import type { BaselineStore } from '../../memory/project/baselines.js';
+import type { RecordingStore } from '../../language/flows/recording/tape/recordings.js';
+import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import type { ArtifactRoot } from '../../memory/project/artifact-root.js';
+import type { FlowStore } from '../../language/flows/flows.js';
+import type { ProjectStore } from '../../memory/project/project-store.js';
+import type { AnnotationStore } from '../../language/flows/stores/annotation-store.js';
+import { SnapshotCache } from './read/snapshot-delta.js';
+import type { BrowserPool } from '../../portal/pool/browser-pool.js';
+import type { ChromiumProbe } from '../../command/cli/doctor/browser/chromium-hint.js';
+export interface ToolDeps<Ext = unknown> {
+    sessions: SessionManager;
+    /** shared one-browser/N-context pool for headless leases. undefined ⇒ lease tools report unavailable. */
+    pool?: BrowserPool;
+    /**
+     * Probe for a launchable Chromium, so the lease path can refuse at the FIRST call with the install
+     * fix rather than failing several calls in with a message that reads as "the app is not running".
+     * Optional: absent ⇒ no preflight — every existing test construction of ToolDeps keeps working, and
+     * the fake-pool lease tests are deliberately runnable without a real Chromium.
+     */
+    browserProbe?: () => Promise<ChromiumProbe>;
+    baselines: BaselineStore;
+    recordings: RecordingStore;
+    /** on-disk anchored-flow store (.reticle/flows/). */
+    flows: FlowStore;
+    /**
+     * The credential this machine already holds for the linked project, if it is linked.
+     *
+     * INJECTED rather than read here. `reticle link` files a project-scoped key in
+     * `~/.reticle/credentials.json`, and the harness needs it so that somebody who has signed in and
+     * linked is not also asked to export a key by hand. Resolving it inside the tool surface would
+     * make `tools` reach into `memory/cloud`, which the directory guard refused — and it was right
+     * to: this is a port, and the daemon already resolves exactly this for cloud sync.
+     *
+     * Absent ⇒ nothing is linked, or the caller is an embedder with no filesystem. Never an error.
+     */
+    linkedCloud?: () => Promise<{
+        url: string;
+        apiKey: string;
+    } | null>;
+    /** structured annotations accumulating for the live recording. */
+    annotations: AnnotationStore;
+    /**
+     * This CLIENT's snapshot baselines, backing `diff: true`.
+     *
+     * Per MCP attach, never per daemon: the baseline is "the tree we last sent YOU", and one daemon
+     * serves every agent on the machine. Shared, the second agent to look at a session was answered
+     * `unchanged` against a page it had never been sent. Absent ⇒ the module-level fallback in
+     * `tools.ts`, which keeps every existing `ToolDeps` construction working unchanged.
+     */
+    snapshots?: SnapshotCache;
+    /** cross-run outcome memory (.reticle/project.json). */
+    project: ProjectStore;
+    /** optional native-input provider. undefined ⇒ everything stays synthetic. */
+    realInput?: RealInputProvider;
+    /** injected filesystem seam (tests pass a fake/temp-dir adapter). */
+    fs: FileSystemPort;
+    /** absolute.reticle path (index.ts computes cwd/.reticle). The FALLBACK, not the answer. */
+    reticleRoot: string;
+    /**
+     * Which `.reticle` a SESSION's artifacts belong in, resolved per call.
+     *
+     * `reticleRoot` above is fixed at construction from the daemon's own `process.cwd()`, which is a
+     * statement about where the daemon was launched and was being read as a statement about which
+     * project is being verified. Those are usually not the same tree: an editor starts a user-scoped
+     * MCP server wherever it likes, so flows landed outside the repo they verify, or died on
+     * `mkdir '/.reticle'`.
+     *
+     * Optional because every existing construction of ToolDeps predates it and because a consumer
+     * embedding this engine may not have a filesystem to search. Absent ⇒ `reticleRoot`, which is
+     * exactly today's behaviour.
+     */
+    artifactRootFor?: (projectId: ProjectId | undefined) => ArtifactRoot;
+    /**
+     * A verification run just landed — wake cloud sync instead of waiting for its next tick.
+     *
+     * The run itself is pushed immediately on this path, but everything AROUND it — the impact
+     * counters, the flows it exercised, flake and intent — moves only on the timer. That is what
+     * produced a dashboard showing a fresh run beside stale numbers, which reads as a sync bug and is
+     * really just two different clocks. Waking the loop here makes the run and its context arrive
+     * together.
+     *
+     * Optional: absent ⇒ the timer alone, which is exactly today's behaviour.
+     */
+    onRunPersisted?: () => void;
+    /**
+     * This daemon's OWN project id, derived from the directory it was started in.
+     *
+     * Optional because a daemon above an uninitialised directory has none, and because every existing
+     * test construction of ToolDeps predates it. Absence means "cannot tell", which must never be
+     * treated as a mismatch.
+     */
+    projectId?: ProjectId;
+    /** injected clock for the contract's generatedAt stamp. */
+    now: () => number;
+    /**
+     * The port this daemon's bridge listens on.
+     *
+     * Needed wherever a message has to name the OTHER half of a port mismatch — the commonest reason
+     * a leased tab loads the app and never dials in. Optional so every existing test construction of
+     * ToolDeps keeps working; absent falls back to the default port.
+     */
+    bridgePort?: number;
+    /**
+     * A consumer's OWN dependencies, carried through untouched.
+     *
+     * Nothing in this package reads it. It exists so a consumer embedding the engine can add tools of
+     * its own — answering out of a store this package has never heard of — without either widening the
+     * fields above with a stranger's vocabulary or forking to get a handle through.
+     *
+     * The type parameter, rather than `unknown`, is what keeps the seam typed: a consumer writes
+     * `ToolDef<TheirExt>` once and their handlers see their own type. Casting out of `unknown` in every
+     * handler is how a typed seam quietly becomes an untyped one.
+     *
+     * Optional, and defaulted to `unknown`, so every existing construction of this bag — and every test
+     * that builds one — is unchanged.
+     */
+    ext?: Ext;
+}
+export interface ToolDef<Ext = unknown> {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    /**
+     * JSON Schema-compatible output schema for this tool. When present, the MCP server advertises it
+     * in the tools/list response so schema-aware clients (like @reticlehq/cli) can validate outputs and
+     * compose tool calls safely. Also drives TOON encoding for snapshot/query results.
+     */
+    outputSchema?: z.ZodRawShape;
+    /**
+     * One concrete, valid call — the shape, not the prose.
+     *
+     * A schema tells an agent the FIELD NAMES; it does not tell it how they compose, and under a lean
+     * profile only the first sentence of the description survives. So an agent reads "execute one
+     * action against a ref", sees `ref` / `action` / `args`, and guesses `{ action, testid }`. The
+     * guess fails inside the MCP SDK's own validation — BEFORE this package's error handling runs — so
+     * what comes back is a raw zod dump: the validator's internal state, naming no field and showing
+     * no correct shape. Two of those round trips cost more than the lean snapshot saves, which means
+     * arg-guessing quietly refunds the entire token advantage.
+     *
+     * Rendered into the advertised description, so it survives the terse profiles where it matters
+     * most. `tool-examples.test.ts` parses every one of these against its OWN inputSchema, because an
+     * example that does not validate is worse than none at all.
+     */
+    example?: Record<string, unknown>;
+    /**
+     * Declared method-style, not as a property, and that is load-bearing rather than stylistic.
+     *
+     * Under `strictFunctionTypes` a property holding a function has CONTRAVARIANT parameters, so
+     * `ToolDef<TheirExt>` and `ToolDef<unknown>` become mutually unassignable and a consumer composing
+     * `[...TOOLS, ...theirTools]` needs a cast — as does every internal helper that then touches the
+     * array. Method-style parameters are checked bivariantly, which collapses all of that.
+     *
+     * The unsoundness bivariance admits is that a handler written against `ToolDeps<TheirExt>` could be
+     * handed a bag carrying no `ext` at all. That costs nothing here, because `ext` is optional by
+     * design: any handler reading it already has to survive `undefined`.
+     */
+    handler(deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * 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 declare const intentArg: z.ZodOptional<z.ZodString>;
+export declare const sessionIdShape: {
+    sessionId: z.ZodOptional<z.ZodString>;
+};
+/**
+ * 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 declare const EnvelopeKey: {
+    /** Session health — which tab, how fresh. */
+    readonly SESSION: "session";
+    /** One-shot pool-lease reminder. */
+    readonly SESSION_LEASE: "session_lease";
+    /** One-shot "these sessions are old, clean them up". */
+    readonly SESSION_AGE_WARNING: "session_age_warning";
+    /** The delivered-once human-in-the-loop guidance envelope. Losing it is a safety failure. */
+    readonly 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.
+     */
+    readonly WARNING: "warning";
+    /** One-shot "ask the human how this went". */
+    readonly FEEDBACK_PROMPT: "feedback_prompt";
+    /** One-shot "a newer Reticle exists". */
+    readonly 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.
+     */
+    readonly VERIFY_NEXT: "verify_next";
+    /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
+    readonly FEEDBACK_INVITE: "feedback_invite";
+    /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
+    readonly VERSION_SKEW: "version_skew";
+    /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
+    readonly FEEDBACK_UNDELIVERED: "feedback_undelivered";
+};
+export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
+/**
+ * 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 declare const sessionEnvelopeShape: z.ZodRawShape;
+/** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
+export declare function commandOrThrow(deps: ToolDeps, sessionId: string | undefined, name: ReticleCommand, args: Record<string, unknown>): Promise<unknown>;
+/** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */
+export declare function snapshotTree(deps: ToolDeps, sessionId: string | undefined): Promise<{
+    lines: string[];
+    route: string;
+}>;
+/**
+ * One client's snapshot baselines.
+ *
+ * Lives here rather than in the `tools.ts` barrel, which sits at the file-size cap, and rather than
+ * having the MCP layer reach into `read/` for the class — this kit is what the surface already
+ * imports. See `ToolDeps.snapshots` for why a daemon-wide store cannot be correct.
+ */
+export declare const newSnapshotCache: () => SnapshotCache;

package/dist/surface/tools/tool-kit.js

@@ -0,0 +1,123 @@
+/**
+ * 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 '../../memory/project/baselines.js';
+import { SnapshotCache } from './read/snapshot-delta.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 ?? '' };
+}
+/**
+ * One client's snapshot baselines.
+ *
+ * Lives here rather than in the `tools.ts` barrel, which sits at the file-size cap, and rather than
+ * having the MCP layer reach into `read/` for the class — this kit is what the surface already
+ * imports. See `ToolDeps.snapshots` for why a daemon-wide store cannot be correct.
+ */
+export const newSnapshotCache = () => new SnapshotCache();

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

@@ -0,0 +1,195 @@
+import type { ToolDef } from './tool-kit.js';
+/**
+ * There is ONE tool surface. This is not a menu.
+ *
+ * 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.
+ *
+ * ALL is deliberately NOT a profile: it is a verification switch, 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. Carrying output schemas on the
+ * default surface more than doubles its bytes, so it cannot be folded in, and deleting it loses that
+ * defect class. So it stays, and no user is asked to pick it.
+ *
+ * Surface sizes are NOT quoted in comments here. They live in surface-sizes.test.ts, which reads them
+ * off the real surface.
+ */
+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: one `act_and_wait`, plus the meta-tools.
+     * Not a profile — a cost switch. On the path where the caller already knows what to assert, almost
+     * the entire bill is the menu rather than the answer, so the menu is the thing to cut, and the
+     * assertion supplies the evidence the surface would otherwise have to go and find.
+     *
+     * NAMED CEILING: it drops the evidence tools, and that TRIPLES false alarms. The new ones are
+     * precisely the defect classes whose evidence lives in `reticle_state`, `reticle_network` and
+     * `reticle_observe` — strip the observation tools and the model stops observing, reaching for the
+     * verdict without the evidence and calling a healthy build broken. Deliberately not the default;
+     * the token saving does not buy that.
+     */
+    readonly VERIFY: "verify";
+    /**
+     * The same capabilities as `default` under ten names instead of seventeen, by merging inside the
+     * core hot-set: look (snapshot/query/inspect/state), observe (observe/network/console), assert
+     * (assert/wait_for), and sessions folded into session. NOTHING is dropped — every tool `default`
+     * advertises stays reachable, which is the difference between this and `verify`. It is the surface
+     * `resolveToolSurface` falls back to.
+     *
+     * NAMED CEILING: a merged tool's input schema is the UNION of its members' fields with every field
+     * optional, so the model sees `by`, `value`, `ref`, `mode` and `path` on one `reticle_look` with
+     * nothing saying which action takes which, and a wrong-field call VALIDATES instead of being
+     * refused. Accuracy is unmeasured; a token number alone never promotes a surface.
+     */
+    readonly MERGED: "merged";
+    /**
+     * EXPERIMENTAL, opt-in. It keeps every observation tool and cuts the rest, because the token saving
+     * and the accuracy loss recorded on VERIFY above came from two different cuts and only one of them
+     * has to be paid for.
+     *
+     * 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           NAMED CEILING: an unadvertised feedback channel collects little to nothing,
+     *                      so a long-lived profile must not ship without it. Acceptable only while this
+     *                      profile is opt-in; if it 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` is NOT "every tool in the registry". 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.
+ *
+ * Prose is not free elsewhere, though: most of this server's schema weight is parameter descriptions
+ * rather than tool descriptions, and the whole block is re-sent every turn, multiplied by turn count
+ * before one byte of evidence is counted.
+ *
+ * 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.
+ *
+ * NAMED CEILING — measured against the full surface as its control on the fix-and-verify benchmark:
+ * it is cheaper and less correct, fixing 3 of the 5 bugs the full surface fixes, and it produced that
+ * benchmark's first FALSE GREEN. On `broken-form-validation` the lean agent edited the file, took one
+ * snapshot, and ended on a hypothetical walkthrough ("spaces are trimmed, valid part is used.
+ * VERDICT: FIXED") against a submit button that was still enabled for a whitespace-only service: it
+ * reasoned about what its own code would now do instead of driving it.
+ *
+ * The other loss has the same root from the other side. On `cross-component-regression` the agent
+ * spent the run calling `reticle_tools` and `reticle_run` hunting for capabilities this surface does
+ * not advertise, and never fixed the bug. Strip the surface and the agent stops verifying, then
+ * claims anyway — the same result the `verify` surface records from the other direction.
+ *
+ * So it stays opt-in and stays measured, and it does not become the default: the turns it saves are
+ * worth less than a verdict that lies, because the product IS the verdict.
+ */
+export declare const LEAN_TOOL_NAMES: ReadonlySet<string>;
+export declare const MERGED_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.
+ *
+ * THE FALLBACK IS `merged`: it advertises nine tools where `default` advertises nineteen, and reaches
+ * the rest of the registry the way every surface does — by name, through the meta-tool. Behind an
+ * env var read by the DAEMON at startup it was unreachable in practice, because an agent exporting
+ * one sees no change and has no way to tell.
+ *
+ * `default` is kept as a NAME so the A/B that justified `merged` can still be run — the bench arms it
+ * by passing `explicit`. Accuracy outranks tokens here: a cheaper surface that verifies less is a
+ * loss at any price, so the arm that proves this one does not lose accuracy stays runnable.
+ */
+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. Documenting that is
+ * not enough — a 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;
+/**
+ * The names a daemon started RIGHT NOW advertises, meta-tools included.
+ *
+ * Derived, never listed: whatever `resolveToolSurface` answers is what this describes. A hardcoded
+ * vocabulary is how `buildServerInstructions` came to brief every agent reaching Reticle through
+ * `reticle mcp` — the proxy briefs without passing a surface — to call `reticle_snapshot`,
+ * `reticle_query` and `reticle_wait_for` while being served a surface that has none of them. An agent
+ * that tries a tool it was shown, fails, and tries again abandons the product. Pinned by
+ * surface-coherence.test.ts.
+ */
+export declare function defaultAdvertisedNames(): readonly string[];
+export declare function filterTools(tools: ToolDef[], surface: ToolSurface): ToolDef[];