@reticlehq/server 2.0.0

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"observe-tools.d.ts","sourceRoot":"","sources":["../../src/tools/observe-tools.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,KAAK,OAAO,EAAkC,MAAM,eAAe,CAAC;AAE7E,eAAO,MAAM,aAAa,EAAE,OAAO,EAmSlC,CAAC"}

package/dist/tools/observe-tools.js

@@ -0,0 +1,259 @@
+/**
+ * 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 { z } from 'zod';
+import { ReticleCommand } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { buildReactionReport } from '../events/reaction.js';
+import { evaluatePredicate, waitForPredicate, PredicateSchema } from '../events/predicate.js';
+import { matchNet, matchConsole, isConsoleEvent, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, } from '../events/event-filters.js';
+import { applyEventBudget, costHint, withSizeCost } from '../session/output-budget.js';
+import { healthEnvelope } from '../session/session-health.js';
+import { isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE } from './assert-grade.js';
+import { withControl } from '../session/control-envelope.js';
+import { asString, asNumber } from './tools-helpers.js';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+export const OBSERVE_TOOLS = [
+    {
+        name: ReticleTool.OBSERVE,
+        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()
+                .optional()
+                .describe('Time window to look back. Default: 2000ms. Ignored when `since` is provided.'),
+            since: z
+                .number()
+                .optional()
+                .describe('Cursor from a prior reticle_act or reticle_observe call. Scopes the event window to exactly that span.'),
+            filters: z
+                .array(z.string())
+                .optional()
+                .describe('Event type allowlist: dom | net | route | console | animation | signal. Omit to return all types.'),
+            max_events: z
+                .number()
+                .optional()
+                .describe('Cap the timeline to the most recent N events. Older events are counted in cost.droppedOldest.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            events: z.array(z.unknown()),
+            summary: z.object({
+                total: z.number(),
+                network: z.number(),
+                domAdded: z.number(),
+                domRemoved: z.number(),
+                domChanged: z.number(),
+                routeChanges: z.number(),
+                consoleErrors: z.number(),
+                animations: z.number(),
+                signals: z.number(),
+            }),
+            cost: z.object({
+                events: z.number(),
+                bytes: z.number(),
+                droppedOldest: z.number().optional(),
+                recommendation: z
+                    .string()
+                    .optional()
+                    .describe('Present when the timeline is large — scope your next call (filters/max_events).'),
+            }),
+            session: z
+                .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
+                .optional(),
+        },
+        handler: (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = asNumber(args['since']);
+            const windowMs = asNumber(args['window_ms']) ?? 2000;
+            const events = since !== undefined ? session.eventsSince(since) : session.eventsInWindow(windowMs);
+            const filters = Array.isArray(args['filters']) ? args['filters'] : undefined;
+            const filtered = filters === undefined ? events : events.filter((e) => filters.includes(e.type));
+            // 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);
+            // carry session health — a throttled tab means the observed timeline may be incomplete.
+            return Promise.resolve(withControl(session, {
+                ...report,
+                cost: costHint(report, budgeted.length, droppedOldest),
+                ...healthEnvelope(session),
+            }));
+        },
+    },
+    {
+        name: ReticleTool.WAIT_FOR,
+        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.'),
+            timeout_ms: z.number().optional().describe('Maximum wait in milliseconds. Default: 4000.'),
+            since: z
+                .number()
+                .optional()
+                .describe('Cursor from a prior reticle_act — scopes the wait to events after that act.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            pass: z.boolean(),
+            evidence: z.unknown().optional(),
+            failureReason: z.string().optional(),
+            session: z
+                .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
+                .optional(),
+        },
+        handler: async (deps, args) => {
+            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 verdict = await waitForPredicate(session, predicate, asNumber(args['timeout_ms']) ?? 4000, since);
+            // match reticle_assert — wrap with control + session health (throttle matters most while blocking).
+            return withControl(session, { ...verdict, ...healthEnvelope(session) });
+        },
+    },
+    {
+        name: ReticleTool.ASSERT,
+        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.'),
+            timeout_ms: z
+                .number()
+                .optional()
+                .describe('If > 0, wait up to this many milliseconds before failing. Default: 0 (evaluate once).'),
+            since: z
+                .number()
+                .optional()
+                .describe('Cursor from a prior reticle_act — scopes the assertion to events after that act.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            pass: z.boolean(),
+            evidence: z.unknown().optional(),
+            failureReason: z.string().optional(),
+            advice: z
+                .string()
+                .optional()
+                .describe('Present on a PASSING presence-only assertion — nudges toward a consequence.'),
+            session: z
+                .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
+                .optional(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            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 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 } : {};
+            return withControl(session, { ...verdict, ...advice, ...healthEnvelope(session) });
+        },
+    },
+    {
+        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.',
+        inputSchema: {
+            since: z
+                .number()
+                .optional()
+                .describe('Cursor from a prior reticle_act — scopes the query to requests fired after that act.'),
+            method: z
+                .string()
+                .optional()
+                .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).'),
+            limit: z
+                .number()
+                .optional()
+                .describe('Keep only the most recent N matching calls (older are dropped and counted in droppedOldest) — cuts tokens on a wide window.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            calls: z.array(z.unknown()),
+            total: z
+                .number()
+                .optional()
+                .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(),
+            cost: z.object({ bytes: z.number(), tokens: z.number() }).optional(),
+        },
+        handler: (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = asNumber(args['since']) ?? 0;
+            const method = asString(args['method']);
+            const urlContains = asString(args['urlContains']);
+            const status = asNumber(args['status']);
+            const limit = asNumber(args['limit']);
+            // Completed calls + unresolved in-flight requests (a hung request shows as pending).
+            const allNet = reconcileNet(session.eventsSince(since));
+            const matched = allNet.filter((e) => matchNet(e, method, urlContains, status));
+            // zero-match filter returns what DID fire, not a bare [].
+            if (matched.length === 0 && allNet.length > 0) {
+                return Promise.resolve(withSizeCost({ calls: matched, hint: netEmptyHint(allNet) }));
+            }
+            const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit);
+            const calls = budgeted.map(projectNetCall);
+            return Promise.resolve(withSizeCost(droppedOldest > 0 ? { calls, total: matched.length, droppedOldest } : { calls }));
+        },
+    },
+    {
+        name: ReticleTool.CONSOLE,
+        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()
+                .optional()
+                .describe('Log level filter: error | warn | info | log. Omit to return all levels.'),
+            since: z
+                .number()
+                .optional()
+                .describe('Cursor from a prior reticle_act — scopes the query to log entries after that act.'),
+            limit: z
+                .number()
+                .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.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            logs: z.array(z.unknown()),
+            total: z
+                .number()
+                .optional()
+                .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(), byLevel: z.record(z.number()) }).optional(),
+            cost: z.object({ bytes: z.number(), tokens: z.number() }).optional(),
+        },
+        handler: (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = asNumber(args['since']) ?? 0;
+            const level = asString(args['level']);
+            const limit = asNumber(args['limit']);
+            const allConsole = session.eventsSince(since).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) {
+                return Promise.resolve(withSizeCost({ logs: matched, hint: consoleEmptyHint(allConsole) }));
+            }
+            const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit);
+            const logs = budgeted.map(projectConsoleLog);
+            return Promise.resolve(withSizeCost(droppedOldest > 0 ? { logs, total: matched.length, droppedOldest } : { logs }));
+        },
+    },
+    {
+        name: ReticleTool.ANIMATIONS,
+        description: 'Currently running + recently completed animations with targets/timing.',
+        inputSchema: { ...sessionIdShape },
+        outputSchema: {
+            animations: z.array(z.unknown()),
+        },
+        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.ANIMATIONS, {}),
+    },
+];
+//# sourceMappingURL=observe-tools.js.map

package/dist/tools/observe-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-tools.js","sourceRoot":"","sources":["../../src/tools/observe-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/profiles.d.ts

@@ -0,0 +1,33 @@
+import type { ToolDef } from './tools.js';
+/**
+ * Which MCP tool surface to expose. The advertised tool DEFINITIONS are re-sent to the model on
+ * every turn, so a smaller surface is a per-turn token saving that compounds across a loop —
+ * measured ~14.6k tok/turn at full (48 tools) vs ~half that for core. Fewer tools also makes the
+ * model wander less (fewer turns, higher accuracy). See bench/LAYER-B.md.
+ *
+ *   core     — the verify loop a coding agent actually needs: navigate→look→act→observe→assert,
+ *              WITH direct network + console + state observability (the highest-signal checks).
+ *              ~12 tools. The recommended profile for agent-driven verification.
+ *   standard — core + common extras (inspect, sequences, animations, flows, session lifecycle,
+ *              scroll, baselines, …). For agents that need more than the bare loop.
+ *   hybrid   — THE DEFAULT: core verify+oracle tools advertised directly + 2 meta-tools for on-demand
+ *              reach to everything else. Core accuracy/detection at ~64% less schema tax than full.
+ *   full     — all tools advertised directly. Opt in via RETICLE_TOOL_PROFILE=full for hard-call scripts.
+ */
+export declare const TOOL_PROFILE: {
+    /** dynamic — advertise only 2 meta-tools (reticle_tools + reticle_run); load real tools on demand.
+     *  Fixed ~hundreds of tokens/turn regardless of how many tools exist. See dynamic-tools.ts. */
+    readonly DYNAMIC: "dynamic";
+    /** hybrid — the core verify tools advertised directly (so the agent acts reliably) PLUS the 2
+     *  meta-tools for on-demand reach to every other tool. Core accuracy + full reach at ~core cost. */
+    readonly HYBRID: "hybrid";
+    readonly CORE: "core";
+    readonly STANDARD: "standard";
+    readonly FULL: "full";
+};
+export type ToolProfile = (typeof TOOL_PROFILE)[keyof typeof TOOL_PROFILE];
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/tools/profiles.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY;IACvB;mGAC+F;;IAE/F;wGACoG;;;;;CAK5F,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAQvD,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAa9C,CAAC;AAmCH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,CAWjE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,EAAE,CAK7E"}

package/dist/tools/profiles.js

@@ -0,0 +1,105 @@
+import { ReticleTool } from './tool-names.js';
+/**
+ * Which MCP tool surface to expose. The advertised tool DEFINITIONS are re-sent to the model on
+ * every turn, so a smaller surface is a per-turn token saving that compounds across a loop —
+ * measured ~14.6k tok/turn at full (48 tools) vs ~half that for core. Fewer tools also makes the
+ * model wander less (fewer turns, higher accuracy). See bench/LAYER-B.md.
+ *
+ *   core     — the verify loop a coding agent actually needs: navigate→look→act→observe→assert,
+ *              WITH direct network + console + state observability (the highest-signal checks).
+ *              ~12 tools. The recommended profile for agent-driven verification.
+ *   standard — core + common extras (inspect, sequences, animations, flows, session lifecycle,
+ *              scroll, baselines, …). For agents that need more than the bare loop.
+ *   hybrid   — THE DEFAULT: core verify+oracle tools advertised directly + 2 meta-tools for on-demand
+ *              reach to everything else. Core accuracy/detection at ~64% less schema tax than full.
+ *   full     — all tools advertised directly. Opt in via RETICLE_TOOL_PROFILE=full for hard-call scripts.
+ */
+export const TOOL_PROFILE = {
+    /** dynamic — advertise only 2 meta-tools (reticle_tools + reticle_run); load real tools on demand.
+     *  Fixed ~hundreds of tokens/turn regardless of how many tools exist. See dynamic-tools.ts. */
+    DYNAMIC: 'dynamic',
+    /** hybrid — the core verify tools advertised directly (so the agent acts reliably) PLUS the 2
+     *  meta-tools for on-demand reach to every other tool. Core accuracy + full reach at ~core cost. */
+    HYBRID: 'hybrid',
+    CORE: 'core',
+    STANDARD: 'standard',
+    FULL: 'full',
+};
+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 — but there is a floor: an 8-tool cut (dropping act/navigate/
+// wait_for/sessions) was MEASURED to regress real-agent accuracy from 5/5 to 3/5, because the
+// model loses scaffolding and wanders (more turns) on harder flows. These 12 are the lean sweet
+// spot that holds 5/5 in a real gpt-4o loop. Direct network/console stay (far more discoverable
+// than observe-with-filters → fewer turns, better verdicts). See bench/LAYER-B.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,
+]);
+const STANDARD_TOOL_NAMES = new Set([
+    ...CORE_TOOL_NAMES,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.INSPECT,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.ANIMATIONS,
+    ReticleTool.FLOW_SAVE,
+    ReticleTool.FLOW_LIST,
+    ReticleTool.FLOW_LOAD,
+    ReticleTool.FLOW_REPLAY,
+    ReticleTool.FLOW_VERIFY,
+    ReticleTool.FLOW_HEAL,
+    ReticleTool.SESSION,
+    ReticleTool.END_SESSION,
+    ReticleTool.YIELD,
+    ReticleTool.RESUME,
+    ReticleTool.MESSAGES,
+    ReticleTool.REVIEW,
+    ReticleTool.WAIT_READY,
+    ReticleTool.SCROLL_TO,
+    ReticleTool.CRAWL,
+    ReticleTool.RECORD_START,
+    ReticleTool.RECORD_STOP,
+    ReticleTool.REPLAY,
+    ReticleTool.EXPLORE,
+    ReticleTool.BASELINE_SAVE,
+    ReticleTool.BASELINE_LIST,
+    ReticleTool.CONTRACT_SAVE,
+    ReticleTool.NETWORK_MOCK,
+    ReticleTool.VIEWPORT,
+]);
+export function resolveToolProfile(explicit) {
+    const raw = explicit ?? process.env[TOOL_PROFILE_ENV];
+    if (raw === TOOL_PROFILE.DYNAMIC)
+        return TOOL_PROFILE.DYNAMIC;
+    if (raw === TOOL_PROFILE.HYBRID)
+        return TOOL_PROFILE.HYBRID;
+    if (raw === TOOL_PROFILE.CORE)
+        return TOOL_PROFILE.CORE;
+    if (raw === TOOL_PROFILE.STANDARD)
+        return TOOL_PROFILE.STANDARD;
+    if (raw === TOOL_PROFILE.FULL)
+        return TOOL_PROFILE.FULL;
+    // Default: hybrid — the core verify+oracle tools advertised directly (no detection loss, verified
+    // 10/10 on the regression bench) PLUS the 2 meta-tools for on-demand reach to every other tool. ~64%
+    // less per-turn schema than `full` at the same accuracy. Explicit `full` still opts into all tools.
+    return TOOL_PROFILE.HYBRID;
+}
+export function filterTools(tools, profile) {
+    if (profile === TOOL_PROFILE.CORE)
+        return tools.filter((t) => CORE_TOOL_NAMES.has(t.name));
+    if (profile === TOOL_PROFILE.STANDARD)
+        return tools.filter((t) => STANDARD_TOOL_NAMES.has(t.name));
+    return tools;
+}
+//# sourceMappingURL=profiles.js.map

package/dist/tools/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/tools/profiles.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,15 @@
+/**
+ * Token-efficiency for reticle_query: a `by=role value=button` on a busy page can return dozens of
+ * element descriptors the agent must read in full. This trims the result the AGENT sees — the most
+ * expensive part of a tool call is the bytes that land in its context.
+ *
+ * - count_only: drop the elements array entirely, return just `count` (the agent often only needs
+ *   "how many?" — e.g. "are there 3 rows now?").
+ * - limit: keep the first N descriptors, report `total` + `truncated:true` so the trim is never
+ *   silent (the agent knows to narrow with name/scope rather than assume it saw everything).
+ *
+ * Pure and result-shape-tolerant: anything that is not a `{ elements: [...] }` object passes
+ * through untouched (a thrown-error envelope, a zero-match hint result, etc.).
+ */
+export declare function paginateQueryResult(result: unknown, limit: number | undefined, countOnly: boolean): unknown;
+//# sourceMappingURL=query-paginate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-paginate.d.ts","sourceRoot":"","sources":["../../src/tools/query-paginate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,EAAE,OAAO,GACjB,OAAO,CAiBT"}

package/dist/tools/query-paginate.js

@@ -0,0 +1,31 @@
+/**
+ * Token-efficiency for reticle_query: a `by=role value=button` on a busy page can return dozens of
+ * element descriptors the agent must read in full. This trims the result the AGENT sees — the most
+ * expensive part of a tool call is the bytes that land in its context.
+ *
+ * - count_only: drop the elements array entirely, return just `count` (the agent often only needs
+ *   "how many?" — e.g. "are there 3 rows now?").
+ * - limit: keep the first N descriptors, report `total` + `truncated:true` so the trim is never
+ *   silent (the agent knows to narrow with name/scope rather than assume it saw everything).
+ *
+ * Pure and result-shape-tolerant: anything that is not a `{ elements: [...] }` object passes
+ * through untouched (a thrown-error envelope, a zero-match hint result, etc.).
+ */
+export function paginateQueryResult(result, limit, countOnly) {
+    if (typeof result !== 'object' || result === null)
+        return result;
+    const record = result;
+    const elements = record['elements'];
+    if (!Array.isArray(elements))
+        return result;
+    const total = elements.length;
+    if (countOnly) {
+        const { elements: _dropped, ...rest } = record;
+        return { ...rest, count: total };
+    }
+    if (limit !== undefined && limit >= 0 && total > limit) {
+        return { ...record, elements: elements.slice(0, limit), total, truncated: true };
+    }
+    return result;
+}
+//# sourceMappingURL=query-paginate.js.map

package/dist/tools/query-paginate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-paginate.js","sourceRoot":"","sources":["../../src/tools/query-paginate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAe,EACf,KAAyB,EACzB,SAAkB;IAElB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IACjE,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,OAAO,MAAM,CAAC;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;IAE9B,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAC/C,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC;IAED,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,KAAK,EAAE,CAAC;QACvD,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACnF,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"read-tools.d.ts","sourceRoot":"","sources":["../../src/tools/read-tools.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,OAAO,EAAgD,MAAM,eAAe,CAAC;AAE3F,eAAO,MAAM,UAAU,EAAE,OAAO,EAwW/B,CAAC"}