@reticlehq/server 2.2.0 → 2.3.0

package/dist/tools/lease-tools.js

@@ -94,7 +94,7 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
 export const LEASE_TOOLS = [
     {
         name: ReticleTool.LEASE_ACQUIRE,
-        description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease_release when the flow is done.',
+        description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done.',
         inputSchema: {
             url: z
                 .string()
@@ -120,7 +120,7 @@ export const LEASE_TOOLS = [
                 throw new Error(POOL_UNAVAILABLE);
             const url = asString(args['url']);
             if (url === undefined || url.length === 0)
-                throw new Error('reticle_lease_acquire requires a url');
+                throw new Error('reticle_lease{action:"acquire"} requires a url');
             const projectId = asString(args['projectId']);
             const sessionId = newLeaseId();
             const navUrl = appendReticleParams(url, sessionId, projectId);
@@ -153,7 +153,9 @@ export const LEASE_TOOLS = [
         name: ReticleTool.LEASE_RELEASE,
         description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
         inputSchema: {
-            sessionId: z.string().describe('The leased sessionId returned by reticle_lease_acquire.'),
+            sessionId: z
+                .string()
+                .describe('The leased sessionId returned by reticle_lease{action:"acquire"}.'),
         },
         outputSchema: {
             released: z.boolean(),
@@ -165,11 +167,10 @@ export const LEASE_TOOLS = [
                 throw new Error(POOL_UNAVAILABLE);
             const sessionId = asString(args['sessionId']);
             if (sessionId === undefined || sessionId.length === 0) {
-                throw new Error('reticle_lease_release requires a sessionId');
+                throw new Error('reticle_lease{action:"release"} requires a sessionId');
             }
             await pool.release(sessionId);
             return { released: true, leased: pool.activeCount() };
         },
     },
 ];
-//# sourceMappingURL=lease-tools.js.map

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

@@ -40,4 +40,3 @@ export interface MergePlan {
  */
 export declare function applyMerges(tools: readonly ToolDef[], plans: readonly MergePlan[], retired?: readonly string[]): ToolDef[];
 export declare function mergeTools(spec: MergeSpec): ToolDef;
-//# sourceMappingURL=merge-tools.d.ts.map

package/dist/tools/merge-tools.js

@@ -63,4 +63,3 @@ export function mergeTools(spec) {
         },
     };
 }
-//# sourceMappingURL=merge-tools.js.map

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

@@ -1,3 +1,2 @@
 import { type ToolDef } from './tool-kit.js';
 export declare const OBSERVE_TOOLS: ToolDef[];
-//# sourceMappingURL=observe-tools.d.ts.map

package/dist/tools/observe-tools.js

@@ -6,12 +6,14 @@ import { z } from 'zod';
 import { ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { buildReactionReport } from '../events/reaction.js';
+import { findContradictions } from '../events/contradictions.js';
 import { evaluatePredicate, waitForPredicate, PredicateSchema } from '../events/predicate.js';
 import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, } from '../events/event-filters.js';
 import { applyEventBudget, costHint, withSizeCost, DEFAULT_QUERY_LIMIT, } from '../session/output-budget.js';
 import { healthEnvelope, bufferEnvelope } from '../session/session-health.js';
-import { isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE } from './assert-grade.js';
-import { buildCoverageStatement, blindSpotsFromState } from '../honesty/blind-spots.js';
+import { assertsDerivedIpcStatus, DERIVED_IPC_STATUS_ADVICE, isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE, } from './assert-grade.js';
+import { assertVerdict } from './assert-verdict.js';
+import { bodiesNotCaptured } from '../honesty/uncaptured-bodies.js';
 import { withControl } from '../session/control-envelope.js';
 import { asString, asNumber } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow } from './tool-kit.js';
@@ -39,18 +41,39 @@ const bufferOutputShape = {
 function lastActSourceOnFailure(session, pass) {
     if (pass)
         return {};
-    const source = session.lastActSource();
+    const source = session.lastAct.source();
     return source === undefined ? {} : { source };
 }
+/**
+ * Drop `sessionId` from an event in a response the caller scoped to ONE session.
+ *
+ * The caller passed that id in the request, so echoing it on every event is the request quoted back
+ * once per row. Measured on a live app it was 25% of a four-event `reticle_observe` payload, and it
+ * grows linearly with the timeline — a fifty-event window spends ~2.5KB restating a fact the caller
+ * supplied. The id stays on the wire between SDK and bridge, where events from different sessions
+ * really do interleave; it is only redundant at this boundary.
+ */
+function withoutConstantSessionId(event) {
+    if (typeof event !== 'object' || event === null)
+        return event;
+    const { sessionId: _sessionId, ...rest } = event;
+    return rest;
+}
 export const OBSERVE_TOOLS = [
     {
         name: ReticleTool.OBSERVE,
+        example: { since: 0 },
         description: 'Return the timeline of everything the app did in a window (DOM/network/route/console/animation/signal), with a summary. Use after an action. Pass `max_events` to cap the timeline to the most recent N (older events are dropped and counted in cost.droppedOldest). Every result carries a `cost:{events,bytes}` hint so you can self-budget your next call.',
         inputSchema: {
             window_ms: z
                 .number()
+                .positive()
+                // A non-positive window silently produced a FUTURE cursor, so the tool returned zero events
+                // and echoed the nonsense value back — indistinguishable from a genuinely quiet page. An
+                // agent that fumbles this argument gets a clean "nothing happened" instead of being told the
+                // question was malformed, which is the exact confusion this layer exists to refuse.
                 .optional()
-                .describe('Time window to look back. Default: 2000ms. Ignored when `since` is provided.'),
+                .describe('Time window to look back, in ms (must be > 0). Default: 2000. Ignored when `since` is provided.'),
             since: z
                 .number()
                 .optional()
@@ -71,6 +94,7 @@ export const OBSERVE_TOOLS = [
                 'type (e.g. "net.request"). Omit to return all types.'),
             max_events: z
                 .number()
+                .nonnegative()
                 .optional()
                 .describe('Cap the timeline to the most recent N events. Older events are counted in cost.droppedOldest.'),
             ...sessionIdShape,
@@ -91,6 +115,17 @@ export const OBSERVE_TOOLS = [
                 animations: z.number(),
                 signals: z.number(),
             }),
+            // Cross-channel disagreement in this window. Omitted when there is none, so a clean action
+            // costs zero tokens and a contradiction is impossible to scroll past.
+            contradictions: z
+                .array(z.object({
+                kind: z.string(),
+                claim: z.string(),
+                counter: z.string(),
+                detail: z.string(),
+            }))
+                .optional()
+                .describe('Channels that DISAGREE about this action — e.g. the UI advanced while its request failed. Each is a false green: the screen looks right and the app is wrong.'),
             cost: z.object({
                 events: z.number(),
                 bytes: z.number(),
@@ -121,9 +156,22 @@ export const OBSERVE_TOOLS = [
             // Output budget: cap to the most recent N (no silent caps — droppedOldest is surfaced in cost).
             const { events: budgeted, droppedOldest } = applyEventBudget(filtered, asNumber(args['max_events']));
             const report = buildReactionReport(budgeted, windowMs);
+            // Run over the FILTERED-but-unbudgeted window: a contradiction must not vanish because the
+            // timeline was capped for tokens. Detection is cheap; the events are already in hand.
+            // The act that opened this window is not in `args` — observe is a separate call — so its action
+            // and in-target mutation count are read back off the session. Without them the "this click did
+            // nothing" check is unreachable on the ordinary act-then-observe flow, which is most of them.
+            // Only when the act actually falls inside the window being judged — judging a click with a
+            // window that starts after it would accuse a control of doing nothing during a period it was
+            // never asked about.
+            const actCursor = session.lastAct.cursor();
+            const judgingTheAct = actCursor !== undefined && actCursor >= since;
+            const contradictions = findContradictions(filtered, judgingTheAct ? session.lastAct.effect() : {});
             // carry session health — a throttled tab means the observed timeline may be incomplete.
             return withControl(session, {
                 ...report,
+                events: report.events.map(withoutConstantSessionId),
+                ...(contradictions.length > 0 ? { contradictions } : {}),
                 cost: costHint(report, budgeted.length, droppedOldest),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
@@ -132,9 +180,10 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.WAIT_FOR,
+        example: { predicate: { kind: 'state', path: 'todos.length', equals: 3 } },
         description: 'Block until a predicate is satisfied (or already true in the recent buffer), else time out. Returns matching evidence or a near-miss diagnosis. By default it only counts events since your last act, so a signal buffered BEFORE the action can never fake a pass; pass `since` (an observe/act cursor) to widen or narrow that window explicitly.',
         inputSchema: {
-            predicate: PredicateSchema.describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
+            predicate: PredicateSchema.describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "net", ok: false } (assert on the OUTCOME — the honest field for IPC, which has no status code), { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
             timeout_ms: z.number().optional().describe('Maximum wait in milliseconds. Default: 4000.'),
             since: z
                 .number()
@@ -171,7 +220,7 @@ export const OBSERVE_TOOLS = [
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const predicate = PredicateSchema.parse(args['predicate']);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
-            const since = asNumber(args['since']) ?? session.lastActCursor() ?? 0;
+            const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             const verdict = await waitForPredicate(session, predicate, asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS, since);
             // match reticle_assert — wrap with control + session health (throttle matters most while blocking)
             // and the buffer envelope, so a verdict reached over an evicted window says so.
@@ -185,6 +234,7 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.ASSERT,
+        example: { predicate: { kind: 'signal', name: 'todos:loaded' } },
         description: 'Evaluate a predicate (optionally waiting up to timeout_ms). Returns { pass, evidence, failureReason? }. The end of every verify loop. Prefer a { signal } or { net } consequence over { element }/{ text } presence — a passing presence-only assertion returns `advice` because a wrong/healed element can fake it. By default it only counts events since your last act, so a stale buffered signal can never fake a pass; pass `since` (an observe/act cursor) to set the window explicitly.',
         inputSchema: {
             predicate: PredicateSchema.describe('Predicate to evaluate: { signal }, { net }, { element } or a combination.'),
@@ -240,40 +290,27 @@ export const OBSERVE_TOOLS = [
             const predicate = PredicateSchema.parse(args['predicate']);
             const timeout = asNumber(args['timeout_ms']) ?? 0;
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
-            const since = asNumber(args['since']) ?? session.lastActCursor() ?? 0;
+            const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             const verdict = timeout > 0
                 ? await waitForPredicate(session, predicate, timeout, since)
                 : await evaluatePredicate(session, predicate, since);
             // A GREEN presence-only assertion is the dangerous case (a wrong element can fake it) — nudge
             // toward a consequence. Never on a failing verdict (moot) or when a signal/net is asserted.
-            const advice = verdict.pass && isPresenceOnlyAssertion(predicate) ? { advice: PRESENCE_ONLY_ADVICE } : {};
-            // A verdict reached over an evicted buffer can be a FALSE NEGATIVE: "no console error" may
-            // simply mean the error aged out. reticle_console has always disclosed this on the same window;
-            // the verdict path — the one an agent actually gates on — did not. Omitted when nothing dropped.
-            // Coverage, on the verdict an agent actually gates on.
-            //
-            // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked
-            // per SESSION, not per assertion window. So a cross-origin iframe seen once marks every later
-            // verdict in that session partial, including ones about a region it cannot affect. That errs
-            // toward over-warning, which is the correct direction for an honesty signal — the failure this
-            // guards against is a green that implies coverage it never had, and the opposite error (a
-            // needless caveat) costs the agent a sentence.
-            //
-            // act_and_wait has always disclosed this; plain assert did not — so a GREEN assert on a page
-            // with a cross-origin iframe or a closed shadow root read as "the page is correct" when the
-            // honest claim is "nothing failed in the part I could see". That is the false-green shape this
-            // project exists to prevent, sitting on the most-used verdict path. Omitted entirely when
-            // coverage is full, so an intact page pays nothing and the field's PRESENCE is the warning.
-            const spots = blindSpotsFromState(session.blindSpots());
-            const statement = buildCoverageStatement(spots);
-            const coverage = statement.coverage === 'partial'
-                ? {
-                    coverage: statement.note ?? 'partial',
-                    coverage_spots: statement.spots.map((sp) => ({ kind: sp.kind, count: sp.count })),
-                }
-                : {};
+            // Two nudges, both only on a GREEN verdict (a failing one is moot): a presence-only assertion
+            // a wrong element can fake, and an assertion pinned to a status Reticle derived rather than one
+            // a server sent. Neither blocks — the assertion still passes; they steer the next one.
+            const advice = !verdict.pass
+                ? {}
+                : isPresenceOnlyAssertion(predicate)
+                    ? { advice: PRESENCE_ONLY_ADVICE }
+                    : assertsDerivedIpcStatus(predicate)
+                        ? { advice: DERIVED_IPC_STATUS_ADVICE }
+                        : {};
+            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since);
             return withControl(session, {
+                ...decision,
                 ...verdict,
+                ...(contradictions.length > 0 ? { contradictions } : {}),
                 ...advice,
                 ...coverage,
                 ...lastActSourceOnFailure(session, verdict.pass),
@@ -284,7 +321,8 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.NETWORK,
-        description: 'Filtered list of network calls. Fast path for "did POST /x return 200?". A zero-match filter returns a `hint` { totalInWindow, present[] } of the calls that DID fire, so a miss is diagnosable.',
+        example: { urlContains: '/api/todos', method: 'POST' },
+        description: 'Filtered list of network calls. Fast path for "did POST /x return 200?". A zero-match filter returns a `hint` { totalInWindow, present[] } of the calls that DID fire, so a miss is diagnosable. Desktop IPC (`ipc://`) has no status code — the 200/500 there is derived, so filter on `ok` for those.',
         inputSchema: {
             since: z
                 .number()
@@ -304,8 +342,13 @@ export const OBSERVE_TOOLS = [
                 .describe('HTTP method filter: GET | POST | PUT | DELETE | PATCH etc.'),
             urlContains: z.string().optional().describe('Substring that the request URL must contain.'),
             status: z.number().optional().describe('HTTP status code filter (e.g. 200, 404, 500).'),
+            ok: z
+                .boolean()
+                .optional()
+                .describe('Outcome filter: false keeps only calls that FAILED, true only those that succeeded. The filter to use for desktop IPC (`ipc://`), whose status code is derived. A still-pending call matches neither.'),
             limit: z
                 .number()
+                .nonnegative()
                 .optional()
                 .describe('Keep only the most recent N matching calls (older are dropped and counted in droppedOldest) — cuts tokens on a wide window. Defaults to 200 when omitted; pass a higher number for more, or scope with since/until.'),
             ...sessionIdShape,
@@ -318,6 +361,10 @@ export const OBSERVE_TOOLS = [
                 .describe('Total matches before `limit` — present only when capped.'),
             droppedOldest: z.number().optional().describe('How many older matches `limit` dropped.'),
             hint: z.object({ totalInWindow: z.number(), present: z.array(z.string()) }).optional(),
+            bodiesNotCaptured: z
+                .string()
+                .optional()
+                .describe('Present when a POST/PUT/PATCH was returned and body capture is OFF — an absent body means unseen, not empty. Carries the one-line fix.'),
             cost: z.object({ bytes: z.number(), tokens: z.number() }).optional(),
             ...bufferOutputShape,
         },
@@ -327,6 +374,7 @@ export const OBSERVE_TOOLS = [
             const method = asString(args['method']);
             const urlContains = asString(args['urlContains']);
             const status = asNumber(args['status']);
+            const ok = typeof args['ok'] === 'boolean' ? args['ok'] : undefined;
             const limit = asNumber(args['limit']);
             const buffer = bufferEnvelope(session);
             // Completed calls + unresolved in-flight requests (a hung request shows as pending).
@@ -335,7 +383,7 @@ export const OBSERVE_TOOLS = [
                 until: asNumber(args['until']),
                 actionId: asString(args['actionId']),
             }));
-            const matched = allNet.filter((e) => matchNet(e, method, urlContains, status));
+            const matched = allNet.filter((e) => matchNet(e, method, urlContains, status, ok));
             // zero-match filter returns what DID fire, not a bare [].
             if (matched.length === 0 && allNet.length > 0) {
                 return withSizeCost({ calls: matched, hint: netEmptyHint(allNet), ...buffer });
@@ -343,13 +391,17 @@ export const OBSERVE_TOOLS = [
             // Default the cap so an omitted `limit` can't dump a whole flooded session (since defaults to 0).
             const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit ?? DEFAULT_QUERY_LIMIT);
             const calls = budgeted.map(projectNetCall);
-            return withSizeCost(droppedOldest > 0
-                ? { calls, total: matched.length, droppedOldest, ...buffer }
-                : { calls, ...buffer });
+            return withSizeCost({
+                calls,
+                ...(droppedOldest > 0 ? { total: matched.length, droppedOldest } : {}),
+                ...bodiesNotCaptured(calls),
+                ...buffer,
+            });
         },
     },
     {
         name: ReticleTool.CONSOLE,
+        example: { level: 'error' },
         description: 'Console/error log. Fast path for "were there any errors during this flow?". When a level filter matches nothing, returns a `hint` { totalInWindow, byLevel } so 0 errors is distinguishable from a silent page.',
         inputSchema: {
             level: z
@@ -370,6 +422,7 @@ export const OBSERVE_TOOLS = [
                 .describe('Keep only log entries attributed to this action — "what did action N log".'),
             limit: z
                 .number()
+                .nonnegative()
                 .optional()
                 .describe('Keep only the most recent N matching entries (older are dropped and counted in droppedOldest) — cuts tokens when a page spams the console. Defaults to 200 when omitted; pass a higher number for more, or scope with since/until.'),
             ...sessionIdShape,
@@ -419,4 +472,3 @@ export const OBSERVE_TOOLS = [
         handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.ANIMATIONS, {}),
     },
 ];
-//# sourceMappingURL=observe-tools.js.map

package/dist/tools/profiles.d.ts

@@ -6,7 +6,7 @@ import type { ToolDef } from './tools.js';
  *
  * MEASURED surface sizes (assert them with profile-reachability.test.ts rather than trusting prose —
  * every count previously written here was wrong, and the token figures below derive from those counts):
- *   core 14 · standard 32 · hybrid 14 · full 41 · dynamic 2
+ *   core 15 · standard 32 · hybrid 15 · full 43 · dynamic 2
  * core and hybrid are both 14 because a trimmed profile now also advertises the two meta-tools, which
  * is what keeps an un-advertised tool reachable through reticle_run.
  *
@@ -35,4 +35,3 @@ export declare const TOOL_PROFILE_ENV = "RETICLE_TOOL_PROFILE";
 export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
 export declare function resolveToolProfile(explicit?: string): ToolProfile;
 export declare function filterTools(tools: ToolDef[], profile: ToolProfile): ToolDef[];
-//# sourceMappingURL=profiles.d.ts.map

package/dist/tools/profiles.js

@@ -6,7 +6,7 @@ import { ReticleTool } from './tool-names.js';
  *
  * MEASURED surface sizes (assert them with profile-reachability.test.ts rather than trusting prose —
  * every count previously written here was wrong, and the token figures below derive from those counts):
- *   core 14 · standard 32 · hybrid 14 · full 41 · dynamic 2
+ *   core 15 · standard 32 · hybrid 15 · full 43 · dynamic 2
  * core and hybrid are both 14 because a trimmed profile now also advertises the two meta-tools, which
  * is what keeps an un-advertised tool reachable through reticle_run.
  *
@@ -32,22 +32,37 @@ export const TOOL_PROFILE = {
 };
 export const TOOL_PROFILE_ENV = 'RETICLE_TOOL_PROFILE';
 // The set an agent needs to verify a change end-to-end. Tool DEFINITIONS are re-sent every turn, so a
-// smaller surface compounds. Measured per-turn surface cost (bench/first-drive, o200k proxy):
-// core 6,479 tok · standard 13,951 · full 20,441 — the hybrid default is far cheaper per turn than
-// advertising everything. STALE: these were measured against a 12/40/56-tool surface that no longer
-// exists (it is now 14/32/41 after the merge and the escape-hatch change), so treat the ratio as
-// directional and the absolute numbers as needing a re-measure before they are quoted anywhere.
+// smaller surface compounds.
+//
+// MEASURED per-turn `tools/list` cost — the bytes an MCP client re-sends EVERY turn — taken off the
+// real wire (spawn `mcp`, read tools/list, measure the serialized result), not estimated:
+//
+//   dynamic     2 tools    1,531 B   ~383 tok/turn
+//   core       15 tools   14,104 B  ~3,526 tok/turn
+//   hybrid     15 tools   14,104 B  ~3,526 tok/turn
+//   standard   32 tools   26,769 B  ~6,692 tok/turn
+//   full       43 tools  105,061 B ~26,265 tok/turn
+//
+// These REPLACE the previous figures (core 6,479 / standard 13,951 / full 20,441), which the comment
+// itself flagged as stale. Two of the three moved in opposite directions, which is why re-measuring
+// mattered: the lean profiles got much CHEAPER because they now drop the advertised outputSchema,
+// while `full` got much more EXPENSIVE because it still carries it — the gap between lean and full is
+// 7.4x, not the ~3x the old numbers implied.
+//
+// Where the remaining cost sits, on the hybrid default: inputSchema is 76% of the payload (parameter
+// descriptions are half of that), tool descriptions are 12%, and outputSchema is already ~0. 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. These 12 are the lean sweet spot. Direct network/console stay (far more discoverable than
-// observe-with-filters → fewer turns, better verdicts).
+// 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 original 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 hybrid default on a current model and fixed 4/4 cells with
-// ~25% FEWER tool calls than the baseline. A formal core-vs-hybrid A/B on a current model is
-// still UNRUN; do not quote the 5/5 number as if it were current. See bench/agent-loop-and-replay.md.
+// 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 hybrid default on a current model and fixed 4/4 cells with ~25% FEWER tool calls than
+// the baseline. A formal core-vs-hybrid A/B on a current model is still UNRUN; do not quote the 5/5
+// number as if it were current. See bench/agent-loop-and-replay.md.
 export const CORE_TOOL_NAMES = new Set([
     ReticleTool.SESSIONS,
     ReticleTool.NAVIGATE,
@@ -61,11 +76,24 @@ export const CORE_TOOL_NAMES = new Set([
     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 full 43-tool drive, 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,
 ]);
 const STANDARD_TOOL_NAMES = new Set([
     ...CORE_TOOL_NAMES,
     ReticleTool.ACT_SEQUENCE,
-    ReticleTool.INSPECT,
     ReticleTool.NETWORK,
     ReticleTool.CONSOLE,
     ReticleTool.ANIMATIONS,
@@ -109,4 +137,3 @@ export function filterTools(tools, profile) {
         return tools.filter((t) => STANDARD_TOOL_NAMES.has(t.name));
     return tools;
 }
-//# sourceMappingURL=profiles.js.map

package/dist/tools/query-paginate.d.ts

@@ -19,4 +19,3 @@
  * number that is silently wrong. `count` survives because it is a scalar. Trust it over the array.
  */
 export declare function paginateQueryResult(result: unknown, limit: number | undefined, countOnly: boolean): unknown;
-//# sourceMappingURL=query-paginate.d.ts.map

package/dist/tools/query-paginate.js

@@ -45,4 +45,3 @@ export function paginateQueryResult(result, limit, countOnly) {
         return { ...record, total, truncated: true };
     return result;
 }
-//# sourceMappingURL=query-paginate.js.map

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

@@ -1,3 +1,2 @@
 import { type ToolDef } from './tool-kit.js';
 export declare const READ_TOOLS: ToolDef[];
-//# sourceMappingURL=read-tools.d.ts.map

package/dist/tools/read-tools.js

@@ -21,11 +21,13 @@ export const READ_TOOLS = [
         inputSchema: {
             name: z
                 .string()
-                .describe('Label for this baseline snapshot (e.g. "dashboard-initial"). Use the same name in reticle_diff to compare.'),
+                .describe('Label for this baseline snapshot (e.g. "dashboard-initial"). Use the same name in reticle_baseline{action:"diff"} to compare.'),
             ...sessionIdShape,
         },
         outputSchema: {
-            baseline: z.string().describe('Saved baseline name — pass to reticle_diff to compare.'),
+            baseline: z
+                .string()
+                .describe('Saved baseline name — pass to reticle_baseline{action:"diff"} to compare.'),
             lineCount: z.number(),
         },
         handler: async (deps, args) => {
@@ -46,11 +48,11 @@ export const READ_TOOLS = [
     },
     {
         name: ReticleTool.DIFF,
-        description: 'Diff current semantic state vs a saved baseline: REMOVED/ADDED elements + console-error count. Call reticle_baseline_list to list saved baselines, reticle_baseline_save to create one. Pass `baseline` (name from reticle_baseline_list). Answers "did anything silently go missing/break?".',
+        description: 'Diff current semantic state vs a saved baseline: REMOVED/ADDED elements + console-error count. Call reticle_baseline{action:"list"} to list saved baselines, reticle_baseline{action:"save"} to create one. Pass `baseline` (name from reticle_baseline{action:"list"}). Answers "did anything silently go missing/break?".',
         inputSchema: {
             baseline: z
                 .string()
-                .describe('Baseline name to compare against. Call reticle_baseline_list to get available names; names are created by reticle_baseline_save.'),
+                .describe('Baseline name to compare against. Call reticle_baseline{action:"list"} to get available names; names are created by reticle_baseline{action:"save"}.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -90,7 +92,7 @@ export const READ_TOOLS = [
         inputSchema: {
             recordingName: z
                 .string()
-                .describe('Identifier for this recording. Pass the same name to reticle_record_stop and reticle_replay.'),
+                .describe('Identifier for this recording. Pass the same name to reticle_record{action:"stop"} and reticle_replay.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -111,7 +113,7 @@ export const READ_TOOLS = [
         inputSchema: {
             recordingName: z
                 .string()
-                .describe('Identifier of an active recording started with reticle_record_start.'),
+                .describe('Identifier of an active recording started with reticle_record{action:"start"}.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -160,7 +162,7 @@ export const READ_TOOLS = [
         inputSchema: {
             recordingName: z
                 .string()
-                .describe('Name of a compiled recording (from reticle_record_stop) to re-execute.'),
+                .describe('Name of a compiled recording (from reticle_record{action:"stop"}) to re-execute.'),
             confirmDangerous: z
                 .boolean()
                 .optional()
@@ -237,6 +239,7 @@ export const READ_TOOLS = [
     },
     {
         name: ReticleTool.STATE,
+        example: { depth: 2 },
         description: "Read live framework state without the app pre-broadcasting it. PREFERRED/RELIABLE: `store` reads a registered store (e.g. 'workspace'); omit `store` to read all stores. To avoid paying for a huge store, scope the read: `path` extracts a dot-path sub-tree (e.g. 'captionCache.v3', with numeric array indices), and `depth` collapses anything deeper than N levels to a size marker. A wrong `path` returns { found:false, availableKeys } so it is diagnosable. `ref` attempts a best-effort read of the nearest React component's hook state and is BOUNDED — on failure it returns component: { ok: false, reason: 'component-state-unavailable' }. Without path/depth: returns { stores, storeNames, component? }.",
         inputSchema: {
             ref: z
@@ -419,4 +422,3 @@ export const READ_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=read-tools.js.map

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

@@ -0,0 +1,2 @@
+import { type ToolDef } from './tool-kit.js';
+export declare const RECONCILE_TOOLS: ToolDef[];