@reticlehq/server 2.3.0 → 2.5.0

package/dist/tools/real-input-attempt.js

@@ -0,0 +1,88 @@
+/**
+ * The native-input attempt — everything that decides whether a pointer action is driven through a
+ * real input provider or falls back to the occlusion-honest synthetic path, and WHY.
+ *
+ * Split out of act-tools.ts along its natural seam: the act tools care only about the outcome
+ * (`result` defined = it went native), never about provider availability, box resolution,
+ * drag-target inspection or the reason taxonomy.
+ */
+import { ActionType, InputModeReason, ReticleCommand } from '@reticlehq/core';
+import { isPointerAction } from '../input/real-input.js';
+import { assertDragNotDestructive, assertNotDestructive } from './act-danger.js';
+import { NATIVE_INPUT_ARG } from '@reticlehq/core';
+import { asString, asRecord } from './tools-helpers.js';
+import { commandOrThrow } from './tool-kit.js';
+import { asBox } from './act-helpers.js';
+/** Synthetic outcome with a diagnostic reason (provider configured but native input skipped). */
+function synthetic(reason) {
+    return reason === undefined
+        ? { result: undefined, settled: false }
+        : { result: undefined, settled: false, reason };
+}
+/**
+ * Attempt to drive a pointer action via native input. Returns a synthetic outcome (with a
+ * `reason` when a provider is configured) whenever the synthetic path should run — no matching
+ * page, unresolvable box, declined, etc. A throw inside the provider becomes a synthetic fallback
+ * flagged with `fellBack`. `result` is defined only on a real success.
+ */
+export async function tryRealInput(deps, session, ref, action, args) {
+    const provider = deps.realInput;
+    if (provider === undefined)
+        return synthetic(); // real input not configured — no diagnostic
+    if (!isPointerAction(action))
+        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
+    const inner = asRecord(args['args']);
+    // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
+    // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
+    // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
+    // isTrusted-gated handlers). hover/drag genuinely need native pointer state, so they stay real.
+    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) &&
+        inner[NATIVE_INPUT_ARG] !== true) {
+        return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
+    }
+    if (!(await provider.isAvailableFor(session.url)))
+        return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
+    assertNotDestructive(action, inner, inspected);
+    const box = asBox(inspected);
+    if (box === undefined)
+        return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
+    let toBox;
+    if (action === ActionType.DRAG) {
+        const toRef = asString(inner['toRef']);
+        if (toRef === undefined)
+            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+        const targetInspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, {
+            ref: toRef,
+        });
+        // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
+        // thing being dragged looks.
+        assertDragNotDestructive(inner, inspected, targetInspected);
+        toBox = asBox(targetInspected);
+        if (toBox === undefined)
+            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+    }
+    const performArgs = {};
+    const value = asString(inner['value']);
+    if (value !== undefined)
+        performArgs.value = value;
+    const text = asString(inner['text']);
+    if (text !== undefined)
+        performArgs.text = text;
+    if (toBox !== undefined)
+        performArgs.toBox = toBox;
+    try {
+        const performed = await provider.perform(session.url, action, box, performArgs);
+        if (!performed.performed)
+            return synthetic(InputModeReason.PROVIDER_DECLINED);
+        return { result: { performed: true, center: performed.center, action }, settled: true };
+    }
+    catch {
+        return {
+            result: undefined,
+            settled: false,
+            fellBack: true,
+            reason: InputModeReason.PROVIDER_ERROR,
+        };
+    }
+}

package/dist/tools/reconcile-tools.js

@@ -28,17 +28,17 @@ async function capturedBodies(session, since, urlContains) {
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
-        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
         if (urlContains !== undefined && !url.includes(urlContains))
             continue;
         total += 1;
         const raw = event.data['responseBody'];
-        if (typeof raw !== 'string' || raw.length === 0)
+        if (typeof raw !== 'string' || 0 === raw.length)
             continue;
         // A capped body is not an absent one. Recover the records that closed before the cut rather than
         // reporting nothing about the page with the most data on it.
         const salvaged = salvageJson(raw);
-        if (salvaged.values.length === 0)
+        if (0 === salvaged.values.length)
             continue;
         bodies.push(...salvaged.values);
         withBody += 1;
@@ -79,11 +79,11 @@ export const RECONCILE_TOOLS = [
             const { bodies, withBody, total, truncated } = await capturedBodies(session, since, asString(args['urlContains']));
             // An empty result over data that was never read is the exact false green this tool exists to
             // prevent, so the two cases are reported differently and neither is silent.
-            if (bodies.length === 0) {
+            if (0 === bodies.length) {
                 return withControl(session, {
                     mismatches: [],
                     compared: 0,
-                    note: total === 0
+                    note: 0 === total
                         ? 'no responses in this window matched — nothing was compared'
                         : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. Enable it where your app calls connect(): \`reticle.connect({ captureNetworkBodies: true })\`, then re-run`,
                 });
@@ -92,7 +92,7 @@ export const RECONCILE_TOOLS = [
                 mode: SnapshotMode.FULL,
             });
             const tree = snapshot.tree;
-            const mismatches = reconcile(bodies, typeof tree === 'string' ? tree : '');
+            const mismatches = reconcile(bodies, 'string' === typeof tree ? tree : '');
             // A truncated body is declared whether or not anything was found in it: "no mismatches" over a
             // partially-read payload is a weaker statement than over a whole one, and the difference is
             // exactly the kind of omission this layer exists to refuse.
@@ -100,7 +100,7 @@ export const RECONCILE_TOOLS = [
                 ? {
                     note: `${String(truncated)} of ${String(withBody)} response(s) exceeded the body cap and were read only up to the cut — records after it were not compared`,
                 }
-                : mismatches.length === 0
+                : 0 === mismatches.length
                     ? {
                         note: `compared ${String(withBody)} response(s); nothing on screen contradicts them`,
                     }

package/dist/tools/reload-result.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What `navigate { reload: true }` reports.
+ *
+ * It answered a bare `{ ok: true }`, while the URL branch of the same tool returns `confirmed: false`
+ * plus a note — because `ok` means the browser accepted the instruction, not that the page arrived.
+ * Identical semantics, one branch disclosing them and one not, and the silent one is the path most
+ * likely to need the caveat: a reload tears the SDK down, and a caller that acts on `ok: true` hits
+ * the window before it comes back.
+ *
+ * The permanent session loss reported alongside this is fixed separately — session-continuity.ts
+ * remembers the id in sessionStorage so a reload rejoins the SAME session instead of appearing as a
+ * new one. This is the remaining half: saying that the page is not back yet.
+ */
+export declare function reloadResult(reconnected?: boolean): Record<string, unknown>;

package/dist/tools/reload-result.js

@@ -0,0 +1,29 @@
+/**
+ * What `navigate { reload: true }` reports.
+ *
+ * It answered a bare `{ ok: true }`, while the URL branch of the same tool returns `confirmed: false`
+ * plus a note — because `ok` means the browser accepted the instruction, not that the page arrived.
+ * Identical semantics, one branch disclosing them and one not, and the silent one is the path most
+ * likely to need the caveat: a reload tears the SDK down, and a caller that acts on `ok: true` hits
+ * the window before it comes back.
+ *
+ * The permanent session loss reported alongside this is fixed separately — session-continuity.ts
+ * remembers the id in sessionStorage so a reload rejoins the SAME session instead of appearing as a
+ * new one. This is the remaining half: saying that the page is not back yet.
+ */
+/** The reload's own disclosure — the same shape and the same advice the URL branch gives. */
+const RELOAD_NOTE = 'ok means the reload was DISPATCHED, not that the page came back — the SDK is torn down by the ' +
+    'reload itself, so nothing here can see the new document yet. Call reticle_sessions to confirm ' +
+    'the session reconnected before acting; the session id is preserved across a reload, so it will ' +
+    'be the same one.';
+/**
+ * What a CONFIRMED reload says. The page re-announced itself under the same id before this returned,
+ * so the next call is safe — which is the whole reason the tool now waits instead of advising.
+ */
+const RELOAD_RECONNECTED_NOTE = 'the page came back and re-announced itself under the same session id, so this session is live ' +
+    'again — no re-selection needed. Anything captured before the reload is gone with the old document.';
+export function reloadResult(reconnected = false) {
+    return reconnected
+        ? { ok: true, confirmed: true, note: RELOAD_RECONNECTED_NOTE }
+        : { ok: true, confirmed: false, note: RELOAD_NOTE };
+}

package/dist/tools/snapshot-delta.d.ts

@@ -18,13 +18,13 @@ export declare const SnapshotDeltaMode: {
     readonly UNCHANGED: "unchanged";
 };
 export type SnapshotDeltaMode = (typeof SnapshotDeltaMode)[keyof typeof SnapshotDeltaMode];
-export interface SnapshotDelta {
+interface SnapshotDelta {
     added: string[];
     removed: string[];
     addedCount: number;
     removedCount: number;
 }
-export type DeltaDecision = {
+type DeltaDecision = {
     mode: typeof SnapshotDeltaMode.FULL;
 } | {
     mode: typeof SnapshotDeltaMode.UNCHANGED;
@@ -43,9 +43,7 @@ export declare class SnapshotCache {
     remember(key: string, route: string, tree: string): void;
 }
 export declare function snapshotCacheKey(sessionId: string, scope: string, mode: string): string;
-/** Said out loud when a diff was computed over a capped tree, so "unchanged" cannot mean "nothing happened". */
-export declare const CAPPED_DIFF_NOTE = "this diff covers only the first N nodes of the page (the snapshot hit its cap), so \"unchanged\" means \"unchanged in the part that was captured\" \u2014 narrow with `scope` to see the rest";
-export interface SnapshotDeltaOpts {
+interface SnapshotDeltaOpts {
     sessionId: string;
     scope: string;
     mode: string;
@@ -58,3 +56,4 @@ export interface SnapshotDeltaOpts {
  * the pure `snapshotDelta`.
  */
 export declare function applySnapshotDelta(raw: unknown, opts: SnapshotDeltaOpts, cache: SnapshotCache): unknown;
+export {};

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

@@ -35,6 +35,14 @@ export interface ToolDeps {
     reticleRoot: string;
     /** 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;
 }
 export interface ToolDef {
     name: string;

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

@@ -0,0 +1,83 @@
+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";
+};
+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>;
+/**
+ * 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[];

package/dist/tools/tool-surface.js

@@ -0,0 +1,204 @@
+import { ReticleTool } from './tool-names.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 const TOOL_SURFACE = {
+    /** What every user gets: the verify loop, plus the 2 meta-tools that reach everything else. */
+    DEFAULT: 'default',
+    /** Every tool advertised directly, WITH output schemas. A verification switch — see above. */
+    ALL: 'all',
+};
+/**
+ * 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 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 const TOOL_PROFILE_ENV = 'RETICLE_TOOL_PROFILE';
+const RETIRED_PROFILE_VALUES = {
+    full: TOOL_SURFACE.ALL,
+    hybrid: TOOL_SURFACE.DEFAULT,
+    core: TOOL_SURFACE.DEFAULT,
+    standard: TOOL_SURFACE.DEFAULT,
+    dynamic: TOOL_SURFACE.DEFAULT,
+};
+// The set an agent needs to verify a change end-to-end. Tool DEFINITIONS are re-sent every turn, so
+// this set is a per-turn cost, and every name in it has to earn its place.
+//
+// MEASURED per-turn `tools/list` cost, off the real wire (spawn `mcp`, read tools/list, measure the
+// serialized result), with a FRESH DAEMON per reading — the setting is read by the daemon at startup,
+// so a loop that reuses one daemon measures the first surface every time and looks like proof that
+// the setting does nothing. That happened while taking this very reading.
+//
+//   default    18,183 B  ~4,546 tok/turn    16 tools
+//   all       127,903 B ~31,976 tok/turn    48 tools
+//
+// Treat these as the SHAPE of the gap and re-measure before quoting one; counts are asserted in
+// surface-sizes.test.ts, never from this comment.
+//
+// Where the cost sits on the default surface: inputSchema is 76% of the payload (parameter
+// descriptions are half of that), tool descriptions are 12%, outputSchema ~0 because it is dropped.
+// So the next real saving is in parameter prose, not in dropping more tools.
+//
+// There is a floor, though: an 8-tool cut (dropping act/navigate/wait_for/sessions) was MEASURED to
+// regress real-agent accuracy 5/5 -> 3/5, because the model loses scaffolding and wanders on harder
+// flows. Direct network/console stay (far more discoverable than observe-with-filters -> fewer turns,
+// better verdicts).
+//
+// Evidence status: the 5/5 figure came from a single gpt-4o run and is STALE as a justification.
+// Current-model evidence is indirect but real — the cost-delta run (bench/fix-loop/COST-DELTA.md)
+// drove this surface on a current model and fixed 4/4 cells with ~25% FEWER tool calls than the
+// baseline. A formal A/B against a leaner surface on a current model is still UNRUN.
+// See bench/agent-loop-and-replay.md.
+export const CORE_TOOL_NAMES = new Set([
+    ReticleTool.SESSIONS,
+    ReticleTool.NAVIGATE,
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.ACT,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.OBSERVE,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.WAIT_FOR,
+    ReticleTool.ASSERT,
+    ReticleTool.STATE,
+    // INSPECT is what turns a finding into an EDIT: it maps a DOM node to `src/App.tsx:104`. Finding a
+    // bug is half the job; knowing which file to open is the half that makes the agent useful, and it
+    // is the one capability here with no substitute in any other verification tool. It sat in
+    // `standard`, so under the default profile an agent had to already know it existed and reach it
+    // through reticle_run — which, observed over a drive of the whole surface, means it never gets called.
+    // The measured floor that justifies a lean core was about CUTTING to 8 (accuracy 5/5 → 3/5), not
+    // about holding at 12; one tool of schema tax to close the find→fix loop is the right trade.
+    ReticleTool.INSPECT,
+    // FEEDBACK is in every profile for the same reason INSPECT is: a tool an agent has to already know
+    // about, and reach through reticle_run, is a tool that never gets called. That is fatal here in a way
+    // it is not elsewhere — an unadvertised feedback channel collects nothing, which is indistinguishable
+    // from not having built one. It is also the cheapest tool on the surface to carry (three params) and
+    // the only one whose whole purpose is telling us which of the other fifteen are failing.
+    ReticleTool.FEEDBACK,
+    // SESSION is here because the product ORDERS the agent to call it. The session lease block is
+    // spliced onto the first result of every session ("call reticle_session {action:'yield'}"), and
+    // the pause hint is spliced onto every refusal while a human has the session paused, where
+    // {action:"resume"} is the only exit. Both were naming a tool the default surface did not
+    // advertise: an agent that obeyed got `unknown tool`, and an agent that did not left the panel
+    // reading "live" after it had stopped driving — which is the state the whole handback protocol
+    // exists to prevent.
+    //
+    // Measured cost: ~1.3 KB of prose (455 B description + ~780 B of parameter descriptions) on a
+    // surface whose prose is ~23.7 KB, so roughly +5%, a few hundred tokens a turn. The alternative —
+    // deleting the instruction from the lease and the pause hint — deletes the handback protocol,
+    // because there is nowhere else those two calls are ever named.
+    ReticleTool.SESSION,
+]);
+/** Is the truthy form of a boolean env var set? `1`, `true`, `yes` — anything else is off. */
+function envFlagOn(raw) {
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return '1' === value || 'true' === value || 'yes' === value || 'on' === value;
+}
+/**
+ * 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 function resolveToolSurface(explicit) {
+    if (explicit === TOOL_SURFACE.ALL)
+        return TOOL_SURFACE.ALL;
+    if (explicit === TOOL_SURFACE.DEFAULT)
+        return TOOL_SURFACE.DEFAULT;
+    const retiredExplicit = explicit === undefined ? undefined : RETIRED_PROFILE_VALUES[explicit];
+    if (retiredExplicit !== undefined)
+        return retiredExplicit;
+    if (envFlagOn(process.env[ADVERTISE_ALL_ENV]))
+        return TOOL_SURFACE.ALL;
+    const retiredEnv = RETIRED_PROFILE_VALUES[process.env[TOOL_PROFILE_ENV] ?? ''];
+    return retiredEnv ?? TOOL_SURFACE.DEFAULT;
+}
+/**
+ * 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 function describeToolSurface(active, requested) {
+    const retired = requested ?? process.env[TOOL_PROFILE_ENV];
+    if (retired !== undefined && retired in RETIRED_PROFILE_VALUES) {
+        return {
+            active,
+            source: `${TOOL_PROFILE_ENV}=${retired} is RETIRED — there is one tool surface now; using '${active}' (set ${ADVERTISE_ALL_ENV}=1 for the full, schema-carrying surface)`,
+        };
+    }
+    if (retired !== undefined && 0 < retired.length) {
+        return {
+            active,
+            source: `${TOOL_PROFILE_ENV} is RETIRED and '${retired}' was never one of its values; using '${active}'`,
+        };
+    }
+    const flag = process.env[ADVERTISE_ALL_ENV];
+    if (envFlagOn(flag)) {
+        return { active, source: `${ADVERTISE_ALL_ENV} set in the DAEMON's environment at startup` };
+    }
+    // "unset" and "set to 0" are different facts, and only one of them means "you did not ask for it".
+    // Reporting the second as the first is how somebody spends an afternoon on a switch that IS being
+    // read and is simply off.
+    return flag === undefined || 0 === flag.length
+        ? {
+            active,
+            source: `the one tool surface (${ADVERTISE_ALL_ENV} unset when the daemon started)`,
+        }
+        : { active, source: `the one tool surface (${ADVERTISE_ALL_ENV}='${flag}' is off)` };
+}
+export function filterTools(tools, surface) {
+    // CORE_TOOL_NAMES is what it always really was: the set advertised directly. It was never the
+    // interesting thing about the `core` PROFILE, whose only distinction was a second name for this.
+    if (surface === TOOL_SURFACE.DEFAULT)
+        return tools.filter((t) => CORE_TOOL_NAMES.has(t.name));
+    return tools;
+}

package/dist/tools/tools-helpers.js

@@ -11,13 +11,13 @@ export function parseInteractive(tree) {
     return items;
 }
 export function asString(value) {
-    return typeof value === 'string' ? value : undefined;
+    return 'string' === typeof value ? value : undefined;
 }
 export function asNumber(value) {
-    return typeof value === 'number' ? value : undefined;
+    return 'number' === typeof value ? value : undefined;
 }
 export function asRecord(value) {
-    return typeof value === 'object' && value !== null ? value : {};
+    return 'object' === typeof value && value !== null ? value : {};
 }
 /**
  * A `{ file, line }` source location off an untrusted result payload, or undefined.
@@ -27,15 +27,15 @@ export function asRecord(value) {
  * worse than no location at all — it looks like an answer.
  */
 export function sourceOf(value) {
-    if (value === null || typeof value !== 'object')
+    if (null === value || typeof value !== 'object')
         return undefined;
     const record = value;
     const file = record['file'];
     const line = record['line'];
-    if (typeof file !== 'string' || file.length === 0 || typeof line !== 'number')
+    if (typeof file !== 'string' || 0 === file.length || typeof line !== 'number')
         return undefined;
     const out = { file, line };
-    if (typeof record['column'] === 'number')
+    if ('number' === typeof record['column'])
         out.column = record['column'];
     return out;
 }

package/dist/tools/tools.d.ts

@@ -1,3 +1,18 @@
 import { type ToolDef } from './tool-kit.js';
+import { type MergePlan } from './merge-tools.js';
 export type { ToolDef, ToolDeps } from './tool-kit.js';
+/**
+ * surface consolidation. Tool defs are re-sent EVERY turn, so the advertised count is a per-turn
+ * tax multiplied by loop length. Sibling families collapse into one action-dispatched tool; the member
+ * handlers stay defined above and are simply no longer advertised separately.
+ *
+ * Guardrail (from the plan): the 12-tool core hot-set keeps its EXACT names and shapes and is never
+ * merged — sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state.
+ */
+export declare const MERGE_PLANS: MergePlan[];
+/**
+ * Retired from the MCP surface entirely (capability preserved elsewhere, per the plan):
+ * - run_record: auto-recording on flow_replay already persists run outcomes.
+ */
+export declare const RETIRED_FROM_SURFACE: string[];
 export declare const TOOLS: ToolDef[];