@reticlehq/server 2.3.0 → 2.5.0

package/dist/tools/observe-tools.js

@@ -2,8 +2,10 @@
  * Observe / wait / assert tools — reticle_observe, reticle_wait_for, reticle_assert, reticle_network,
  * reticle_console, reticle_animations. Split out of tools.ts; assembled back via...OBSERVE_TOOLS.
  */
+import { noteEmptyRead } from './observed-nothing.js';
 import { z } from 'zod';
-import { ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS } from '@reticlehq/core';
+import { aliasParam } from './alias-args.js';
+import { CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { buildReactionReport } from '../events/reaction.js';
 import { findContradictions } from '../events/contradictions.js';
@@ -54,11 +56,21 @@ function lastActSourceOnFailure(session, pass) {
  * really do interleave; it is only redundant at this boundary.
  */
 function withoutConstantSessionId(event) {
-    if (typeof event !== 'object' || event === null)
+    if (typeof event !== 'object' || null === event)
         return event;
     const { sessionId: _sessionId, ...rest } = event;
     return rest;
 }
+/**
+ * The console levels, derived from core's console EventTypes — see CONSOLE_LEVELS.
+ *
+ * A free string here filtered by building `console.${level}`, so `level:'ERROR'` or `level:'fatal'`
+ * matched nothing and returned an empty log list. On a page that HAS logs the zero-match hint saves
+ * it (it reports which levels are present), but on a quiet page the answer is identical to a genuine
+ * all-clear. Refusing the value outright is the only reading with no ambiguity.
+ */
+const CONSOLE_LEVEL_LIST = CONSOLE_LEVELS.join(' | ');
+const consoleLevelEnum = z.enum(CONSOLE_LEVELS);
 export const OBSERVE_TOOLS = [
     {
         name: ReticleTool.OBSERVE,
@@ -180,10 +192,12 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.WAIT_FOR,
-        example: { predicate: { kind: 'state', path: 'todos.length', equals: 3 } },
+        example: { predicate: { kind: PredicateKind.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: "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.'),
+            predicate: PredicateSchema.optional().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.'),
+            // Same concept, the neighbouring tool's name. See alias-args.ts.
+            until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
             timeout_ms: z.number().optional().describe('Maximum wait in milliseconds. Default: 4000.'),
             since: z
                 .number()
@@ -218,7 +232,8 @@ export const OBSERVE_TOOLS = [
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const predicate = PredicateSchema.parse(args['predicate']);
+            // `until` is act_and_wait's name for this — see alias-args.ts.
+            const predicate = PredicateSchema.parse(aliasParam(args, 'predicate', ['until'])['predicate']);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
             const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             const verdict = await waitForPredicate(session, predicate, asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS, since);
@@ -234,10 +249,11 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.ASSERT,
-        example: { predicate: { kind: 'signal', name: 'todos:loaded' } },
+        example: { predicate: { kind: PredicateKind.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.'),
+            predicate: PredicateSchema.optional().describe('Predicate to evaluate: { signal }, { net }, { element } or a combination.'),
+            until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
             timeout_ms: z
                 .number()
                 .optional()
@@ -287,7 +303,8 @@ export const OBSERVE_TOOLS = [
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const predicate = PredicateSchema.parse(args['predicate']);
+            // `until` is act_and_wait's name for this — see alias-args.ts.
+            const predicate = PredicateSchema.parse(aliasParam(args, 'predicate', ['until'])['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.lastAct.cursor() ?? 0;
@@ -306,7 +323,7 @@ export const OBSERVE_TOOLS = [
                     : assertsDerivedIpcStatus(predicate)
                         ? { advice: DERIVED_IPC_STATUS_ADVICE }
                         : {};
-            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since);
+            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since, verdict.inconclusive);
             return withControl(session, {
                 ...decision,
                 ...verdict,
@@ -374,7 +391,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 ok = 'boolean' === typeof args['ok'] ? args['ok'] : undefined;
             const limit = asNumber(args['limit']);
             const buffer = bufferEnvelope(session);
             // Completed calls + unresolved in-flight requests (a hung request shows as pending).
@@ -385,18 +402,21 @@ export const OBSERVE_TOOLS = [
             }));
             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) {
+            if (0 === matched.length && allNet.length > 0) {
                 return withSizeCost({ calls: matched, hint: netEmptyHint(allNet), ...buffer });
             }
             // 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({
+            // A zero-match FILTER already reports what did fire (netEmptyHint above). Zero calls at all
+            // fell through as a bare `[]`, which is indistinguishable from an observer that is not
+            // recording — and those need opposite responses. Say the look happened.
+            return withSizeCost(noteEmptyRead({
                 calls,
                 ...(droppedOldest > 0 ? { total: matched.length, droppedOldest } : {}),
                 ...bodiesNotCaptured(calls),
                 ...buffer,
-            });
+            }, 'calls', { noun: 'network calls' }));
         },
     },
     {
@@ -404,10 +424,9 @@ export const OBSERVE_TOOLS = [
         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
-                .string()
+            level: consoleLevelEnum
                 .optional()
-                .describe('Log level filter: error | warn | info | log. Omit to return all levels.'),
+                .describe(`Log level filter: ${CONSOLE_LEVEL_LIST}. Omit to return all levels.`),
             since: z
                 .number()
                 .optional()
@@ -451,15 +470,19 @@ export const OBSERVE_TOOLS = [
             })).filter(isConsoleEvent);
             const matched = allConsole.filter((e) => matchConsole(e, level));
             // zero matches at this level → report what levels ARE present (not a bare []).
-            if (matched.length === 0 && allConsole.length > 0) {
+            if (0 === matched.length && allConsole.length > 0) {
                 return withSizeCost({ logs: matched, hint: consoleEmptyHint(allConsole), ...buffer });
             }
             // 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 logs = budgeted.map(projectConsoleLog);
-            return withSizeCost(droppedOldest > 0
+            // Say the look HAPPENED when it found nothing. A quiet page and a dead console observer both
+            // produced `{ logs: [] }`, and "no console errors" is the claim agents lean on most — see
+            // observed-nothing.ts, whose own header names this exact case and which every other array-
+            // returning read here was already wired to.
+            return withSizeCost(noteEmptyRead(droppedOldest > 0
                 ? { logs, total: matched.length, droppedOldest, ...buffer }
-                : { logs, ...buffer });
+                : { logs, ...buffer }, 'logs', { noun: 'console lines' }));
         },
     },
     {
@@ -469,6 +492,17 @@ export const OBSERVE_TOOLS = [
         outputSchema: {
             animations: z.array(z.unknown()),
         },
-        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.ANIMATIONS, {}),
+        handler: async (deps, args) => {
+            const result = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.ANIMATIONS, {});
+            // A page with nothing animating and an observer that is not watching both return `[]`, and the
+            // second means the run should not be trusted. Say the look happened.
+            return isPlainRecord(result)
+                ? noteEmptyRead(result, 'animations', { noun: 'animations running or completed' })
+                : result;
+        },
     },
 ];
+/** Narrow a command result to something noteEmptyRead can annotate. */
+function isPlainRecord(value) {
+    return 'object' === typeof value && value !== null && !Array.isArray(value);
+}

package/dist/tools/observed-nothing.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Say that the look HAPPENED, when the look found nothing.
+ *
+ * A quiet page and a dead observer produce the same JSON: `[]`. Reported across seven tools in a
+ * field sweep — network with 0 calls, console with 0 logs, reconcile comparing 0, crawl with 0 steps,
+ * an empty message inbox — none of which could be told apart from the observer not working. Those
+ * need opposite responses: one means "the app did nothing", the other means "stop trusting this run".
+ *
+ * One shared shape rather than a field per tool: an empty read states the window it watched. "I
+ * watched 2000ms and saw nothing" is a finding. `[]` is an absence of information wearing the same
+ * clothes as one.
+ */
+interface EmptyReadContext {
+    /** The observation window, when the read has one. */
+    windowMs?: number;
+    /** What was being counted, in the agent's words: "console lines", "network calls". */
+    noun: string;
+}
+/**
+ * Add `observed: true` and a note when `key` holds an EMPTY array. Returns the result untouched
+ * otherwise — including when it is a refusal, where "I observed nothing" would be actively
+ * misleading on top of an error that already explains itself.
+ */
+export declare function noteEmptyRead(result: Record<string, unknown>, key: string, context: EmptyReadContext): Record<string, unknown>;
+export {};

package/dist/tools/observed-nothing.js

@@ -0,0 +1,33 @@
+/**
+ * Say that the look HAPPENED, when the look found nothing.
+ *
+ * A quiet page and a dead observer produce the same JSON: `[]`. Reported across seven tools in a
+ * field sweep — network with 0 calls, console with 0 logs, reconcile comparing 0, crawl with 0 steps,
+ * an empty message inbox — none of which could be told apart from the observer not working. Those
+ * need opposite responses: one means "the app did nothing", the other means "stop trusting this run".
+ *
+ * One shared shape rather than a field per tool: an empty read states the window it watched. "I
+ * watched 2000ms and saw nothing" is a finding. `[]` is an absence of information wearing the same
+ * clothes as one.
+ */
+/**
+ * Add `observed: true` and a note when `key` holds an EMPTY array. Returns the result untouched
+ * otherwise — including when it is a refusal, where "I observed nothing" would be actively
+ * misleading on top of an error that already explains itself.
+ */
+export function noteEmptyRead(result, key, context) {
+    if ('string' === typeof result['error'])
+        return result;
+    const value = result[key];
+    if (!Array.isArray(value) || value.length > 0)
+        return result;
+    if (result['note'] !== undefined)
+        return result;
+    const window = context.windowMs === undefined ? '' : ` over the last ${String(context.windowMs)}ms`;
+    return {
+        ...result,
+        // The distinction the field sweep could not make: this is a RESULT, not a failure to look.
+        observed: true,
+        note: `no ${context.noun}${window} — the observation ran and found none, which is a result, not a missing reading`,
+    };
+}

package/dist/tools/query-paginate.js

@@ -19,7 +19,7 @@
  * number that is silently wrong. `count` survives because it is a scalar. Trust it over the array.
  */
 export function paginateQueryResult(result, limit, countOnly) {
-    if (typeof result !== 'object' || result === null)
+    if (typeof result !== 'object' || null === result)
         return result;
     const record = result;
     const elements = record['elements'];
@@ -28,7 +28,7 @@ export function paginateQueryResult(result, limit, countOnly) {
     const counted = record['count'];
     // Older browser SDKs (and the zero-match hint path) may not carry `count`; fall back rather than
     // report nothing, but never prefer the array when the browser told us the real number.
-    const total = typeof counted === 'number' ? counted : elements.length;
+    const total = 'number' === typeof counted ? counted : elements.length;
     const truncatedOnWire = total > elements.length;
     if (countOnly) {
         const { elements: _dropped, ...rest } = record;

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

@@ -0,0 +1,18 @@
+/**
+ * Accepting the element-query shape the rest of the surface teaches.
+ *
+ * `reticle_query` asks for a strategy and a value — `{ by: 'text', value: 'Deploy' }`. Every
+ * predicate asks for named fields — `{ text: 'Deploy' }`, `{ testid: 'submit' }` — and that is where
+ * an agent meets element queries most often (`act_and_wait { until: { kind:'element', query } }`,
+ * `reticle_assert`, `wait_for`). Carrying the predicate's spelling to `reticle_query` earns
+ * `-32602: Unknown parameter for reticle_query: text`.
+ *
+ * It is a small thing that lands in an expensive place: of the sessions that called any tool in a
+ * day, HALF made exactly one call and stopped. A rejected first call is a bounced session, and the
+ * agent has no way to know the rejection was about spelling rather than the page.
+ *
+ * Translation only — `by`/`value` remain the tool's contract, an explicit pair always wins, and a
+ * call carrying neither shape is left alone so the schema error still explains itself rather than
+ * being replaced by a confident wrong query.
+ */
+export declare function normalizeQueryArgs(args: Record<string, unknown>): Record<string, unknown>;

package/dist/tools/query-shape.js

@@ -0,0 +1,39 @@
+/**
+ * Accepting the element-query shape the rest of the surface teaches.
+ *
+ * `reticle_query` asks for a strategy and a value — `{ by: 'text', value: 'Deploy' }`. Every
+ * predicate asks for named fields — `{ text: 'Deploy' }`, `{ testid: 'submit' }` — and that is where
+ * an agent meets element queries most often (`act_and_wait { until: { kind:'element', query } }`,
+ * `reticle_assert`, `wait_for`). Carrying the predicate's spelling to `reticle_query` earns
+ * `-32602: Unknown parameter for reticle_query: text`.
+ *
+ * It is a small thing that lands in an expensive place: of the sessions that called any tool in a
+ * day, HALF made exactly one call and stopped. A rejected first call is a bounced session, and the
+ * agent has no way to know the rejection was about spelling rather than the page.
+ *
+ * Translation only — `by`/`value` remain the tool's contract, an explicit pair always wins, and a
+ * call carrying neither shape is left alone so the schema error still explains itself rather than
+ * being replaced by a confident wrong query.
+ */
+/** Most specific first: the order Reticle prefers anchors everywhere else (testid is gold). */
+const FIELD_TO_STRATEGY = [
+    ['testid', 'testid'],
+    ['label', 'label'],
+    ['placeholder', 'placeholder'],
+    ['alt', 'alt'],
+    ['text', 'text'],
+    ['role', 'role'],
+];
+export function normalizeQueryArgs(args) {
+    // An explicit pair is the contract; never second-guess it.
+    if ('string' === typeof args['by'] && 'string' === typeof args['value'])
+        return args;
+    for (const [field, strategy] of FIELD_TO_STRATEGY) {
+        const value = args[field];
+        if ('string' === typeof value && value.length > 0) {
+            // `name` stays as-is: with role it is the accessible-name filter the predicate also uses.
+            return { ...args, by: strategy, value };
+        }
+    }
+    return args;
+}

package/dist/tools/read-tools.js

@@ -2,18 +2,43 @@
  * Read / record / replay tools — baselines + diff, recordings + replay, narrate, clock, state,
  * explore. Split out of tools.ts; assembled back via...READ_TOOLS.
  */
+import { resolveAnnotateTarget } from '../flows/annotate-target.js';
 import { z } from 'zod';
 import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { proposeConsequences } from '../oracles/propose-consequences.js';
 import { replayProgram } from '../flows/replay.js';
 import { diffLines } from '../project/baselines.js';
-import { selectPath, capDepth } from '../session/state-select.js';
+import { selectPath, capDepth, projectComponentState } from '../session/state-select.js';
 import { costHint } from '../session/output-budget.js';
 import { buildReactionReport } from '../events/reaction.js';
 import { asString, asNumber, parseInteractive } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../session/session-health.js';
+/**
+ * What record-stop says about a step that compiled to no anchor at all.
+ *
+ * `stable: false` does not mean "brittle". It means the compiler found no testid, no accessible
+ * role+name and no component/source, so the step is bound to a live `ref` — a handle that dies with
+ * the session. The replayer already states this outcome in full (see DEGRADED_STEP_REASON): the step
+ * can never resolve on replay.
+ *
+ * The old wording here — "replay may be brittle (in-session only)" — described a fatal condition as
+ * a quality note, so the agent saved the flow and learned the truth several calls later, as an
+ * unhealable `anchor_degraded` drift at flow_verify, by which point nothing on screen points back
+ * to the element that needed the attribute. Capture time is the only moment the fix is cheap: the
+ * element is still on the page and the human is still in the loop.
+ */
+function unanchoredWarning(count) {
+    return (`${String(count)} step(s) not bound to a testid, an accessible role+name, or a component — ` +
+        'they are pinned to a live ref, so they will replay in THIS session and can never resolve in ' +
+        'another one. Add a data-testid to those elements and record the flow again, or accept that ' +
+        'this recording is single-session only.');
+}
+/** Severities the presenter HUD can render. */
+const HUD_LEVELS = ['info', 'warn', 'error'];
+const HUD_LEVEL_LIST = HUD_LEVELS.join(' | ');
+const hudLevelEnum = z.enum(HUD_LEVELS);
 export const READ_TOOLS = [
     {
         name: ReticleTool.BASELINE_SAVE,
@@ -64,7 +89,11 @@ export const READ_TOOLS = [
             buffer: z.unknown().optional(),
         },
         handler: async (deps, args) => {
-            const name = asString(args['baseline']) ?? 'default';
+            // `name` too: the merged reticle_baseline family made this required field optional, and the
+            // SIBLING that creates a baseline calls it `name` — its description even says to reuse it
+            // here. So `{ action:"diff", name:"x" }` is a valid call that used to look up 'default' and
+            // report "no baseline named 'default'", naming something the caller never mentioned.
+            const name = asString(args['baseline']) ?? asString(args['name']) ?? 'default';
             const base = deps.baselines.get(name);
             if (base === undefined)
                 throw new Error(`no baseline named '${name}'`);
@@ -127,10 +156,17 @@ export const READ_TOOLS = [
         },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const name = asString(args['recordingName']) ?? 'default';
+            // The recording actually RUNNING when there is exactly one, not the literal name `default` —
+            // the same defaulting that made `annotate` report "no steps" against a recording full of them.
+            // With several running, `default` stays the documented answer rather than a guess.
+            const name = resolveAnnotateTarget(asString(args['recordingName']), deps.recordings.active());
             const rec = deps.recordings.stop(name);
-            if (rec === undefined)
-                throw new Error(`no active recording named '${name}'`);
+            if (rec === undefined) {
+                const active = deps.recordings.active();
+                throw new Error(0 === active.length
+                    ? `no active recording named '${name}' — none is in progress`
+                    : `no active recording named '${name}'; in progress: ${active.map((r) => `'${r}'`).join(', ')}`);
+            }
             const events = session.eventsSince(rec.cursor);
             const program = {
                 name,
@@ -147,7 +183,7 @@ export const READ_TOOLS = [
                 program,
                 ...(unstable > 0
                     ? {
-                        warning: `${String(unstable)} step(s) not bound to a testid; replay may be brittle (in-session only)`,
+                        warning: unanchoredWarning(unstable),
                     }
                     : {}),
                 ...(proposedConsequences.length > 0 ? { proposedConsequences } : {}),
@@ -186,7 +222,7 @@ export const READ_TOOLS = [
                 throw new Error(`no compiled recording named '${name}'`);
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const since = session.elapsed();
-            const steps = await replayProgram(session, program, args['confirmDangerous'] === true);
+            const steps = await replayProgram(session, program, true === args['confirmDangerous']);
             return { recordingName: name, since, steps, ok: steps.every((s) => s.ok) };
         },
     },
@@ -197,10 +233,11 @@ export const READ_TOOLS = [
             text: z
                 .string()
                 .describe('Short sentence describing your next action, shown on the presenter HUD for the developer watching.'),
-            level: z
-                .string()
+            // Derived, like every other advertised vocabulary here: a free string let a typo through to
+            // a HUD that then rendered an unknown severity.
+            level: hudLevelEnum
                 .optional()
-                .describe('Display severity: info | warn | error. Default: info.'),
+                .describe(`Display severity: ${HUD_LEVEL_LIST}. Default: info.`),
             ...sessionIdShape,
         },
         outputSchema: { ok: z.boolean() },
@@ -227,9 +264,11 @@ export const READ_TOOLS = [
             reset: z.boolean().optional().describe('Restore the real clock.'),
             ...sessionIdShape,
         },
+        // The command returns `{ frozen }`. It used to declare `{ ok, elapsed }` — neither of which any
+        // clock code path produces — and MCP strips undeclared fields from structuredContent, so a
+        // successful freeze and a failed one both validated to `{}` and became indistinguishable.
         outputSchema: {
-            ok: z.boolean().optional(),
-            elapsed: z.number().optional(),
+            frozen: z.boolean().optional(),
         },
         handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CLOCK, {
             freeze: args['freeze'],
@@ -270,8 +309,26 @@ export const READ_TOOLS = [
             store: z.string().optional(),
             path: z.string().optional(),
             availableKeys: z.array(z.string()).optional(),
+            // Present only when `availableKeys` is a SAMPLE. Declared for the same reason as the truncation
+            // report below: a capped list of 50 keys with no count reads as a complete one, so an agent
+            // concludes the key it wants is absent when it is merely past the cap.
+            totalKeys: z.number().optional(),
             component: z
-                .object({ ok: z.boolean(), reason: z.string().optional(), state: z.unknown().optional() })
+                .object({
+                ok: z.boolean(),
+                reason: z.string().optional(),
+                state: z.unknown().optional(),
+                // The component name and the projected hook VALUES — declared so a schema-strict client
+                // keeps them (they were the point of passing `ref` at all).
+                component: z.string().optional(),
+                hooks: z.array(z.unknown()).optional(),
+                // Present only when effect hooks were projected out. Declared for the same reason as the
+                // store truncation report below: a shortened list with no marker reads as a complete one.
+                truncation: z
+                    .object({ droppedItems: z.number(), note: z.string() })
+                    .optional()
+                    .describe('Present only when effect hooks were dropped — `hooks` is a projection.'),
+            })
                 .optional(),
             // Truncation report — present ONLY when a transport cap trimmed the value. Declared so a
             // schema-strict client on the `full` profile KEEPS it: this is a false-green GUARD, and dropping
@@ -294,23 +351,31 @@ export const READ_TOOLS = [
             // Forward path/depth so a CURRENT browser SDK scopes the read IN-PAGE, before the transport —
             // the value never gets size-truncated in transit. (An older SDK ignores them and returns the
             // whole store; we then scope server-side below as a back-compat fallback.)
-            const result = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.STATE_READ, {
+            const raw = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.STATE_READ, {
                 ref: args['ref'],
                 store,
                 path,
                 depth,
             });
+            // Project the component hook read BEFORE anything else touches it: React hands back the raw
+            // fiber hook list, whose effect entries are chained null-filled internals an agent cannot act
+            // on (measured: 2632 -> 1459 bytes on a five-state/three-effect component). Done here rather
+            // than in the SDK so an older browser build gets the same projection. The drop is disclosed
+            // on `component.truncation`.
+            const result = 'object' === typeof raw && null !== raw && 'component' in raw
+                ? { ...raw, component: projectComponentState(raw.component) }
+                : raw;
             // Normalize storeNames to a string[] regardless of how the wire delivered it — the
             // outputSchema requires an array, and a non-array here makes MCP reject the whole result
             // (so the agent gets nothing instead of the state). Defensive: a string becomes a 1-element array.
             const root = result;
             const names = Array.isArray(root.storeNames)
-                ? root.storeNames.filter((n) => typeof n === 'string')
-                : typeof root.storeNames === 'string' && root.storeNames.length > 0
+                ? root.storeNames.filter((n) => 'string' === typeof n)
+                : 'string' === typeof root.storeNames && root.storeNames.length > 0
                     ? [root.storeNames]
                     : [];
             // The browser already scoped it in-page (the `found` shape) — pass through, just safe storeNames.
-            if (typeof root.found === 'boolean') {
+            if ('boolean' === typeof root.found) {
                 return { ...root, storeNames: names };
             }
             if (path === undefined && depth === undefined) {
@@ -368,7 +433,7 @@ export const READ_TOOLS = [
                 // The walk stops at its node cap and returns a document-order prefix, so an inventory taken
                 // from a big page is a floor, not a census — and this is the tool crawl's description points
                 // agents at first for "a non-destructive list of what is here".
-                ...(snap.truncated === true ? { truncated: true } : {}),
+                ...(true === snap.truncated ? { truncated: true } : {}),
                 consoleErrors,
                 hint: 'act on each ref, observe the reaction, and report failed requests / console errors / dead controls',
                 // Buffer-honesty: the console-error count spans the whole buffer, which evicts — signal it.
@@ -408,13 +473,13 @@ export const READ_TOOLS = [
             const area = asString(args['area']);
             const key = asString(args['key']);
             const result = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.STORAGE_READ, area !== undefined ? { area } : {});
-            const data = (typeof result === 'object' && result !== null ? result : {});
+            const data = ('object' === typeof result && result !== null ? result : {});
             if (key === undefined)
                 return data;
             // Look up the key in the scoped area, or across all three areas when none was named.
             const areas = area !== undefined ? [data] : [data['local'], data['session'], data['cookies']];
             for (const a of areas) {
-                if (typeof a === 'object' && a !== null && key in a) {
+                if ('object' === typeof a && a !== null && key in a) {
                     return { area, key, value: String(a[key]), found: true };
                 }
             }

package/dist/tools/real-input-attempt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 } from '@reticlehq/core';
+import type { Session } from '../session/session.js';
+import { type ToolDeps } from './tool-kit.js';
+interface RealActResult {
+    /** Defined only on a successful native action; `undefined` means the synthetic path runs. */
+    result: unknown;
+    settled: boolean;
+    /** Set when a provider was available but threw — surfaces the fallback to the agent. */
+    fellBack?: boolean;
+    /** Why we went synthetic despite a configured provider (field bug #2: never a silent fallback). */
+    reason?: InputModeReason;
+}
+/**
+ * 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 declare function tryRealInput(deps: ToolDeps, session: Session, ref: string, action: ActionType, args: Record<string, unknown>): Promise<RealActResult>;
+export {};