@reticlehq/server 2.0.0

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

@@ -0,0 +1,89 @@
+/** MCP tool names exposed to the coding agent (plan/05). No free strings. */
+export declare const ReticleTool: {
+    readonly SESSIONS: "reticle_sessions";
+    readonly SNAPSHOT: "reticle_snapshot";
+    readonly QUERY: "reticle_query";
+    readonly INSPECT: "reticle_inspect";
+    readonly ACT: "reticle_act";
+    readonly ACT_SEQUENCE: "reticle_act_sequence";
+    readonly ACT_AND_WAIT: "reticle_act_and_wait";
+    readonly OBSERVE: "reticle_observe";
+    readonly WAIT_FOR: "reticle_wait_for";
+    readonly NETWORK: "reticle_network";
+    readonly CONSOLE: "reticle_console";
+    readonly ANIMATIONS: "reticle_animations";
+    readonly ASSERT: "reticle_assert";
+    readonly BASELINE_SAVE: "reticle_baseline_save";
+    readonly BASELINE_LIST: "reticle_baseline_list";
+    readonly DIFF: "reticle_diff";
+    readonly RECORD_START: "reticle_record_start";
+    readonly RECORD_STOP: "reticle_record_stop";
+    readonly REPLAY: "reticle_replay";
+    readonly EXPLORE: "reticle_explore";
+    readonly NARRATE: "reticle_narrate";
+    readonly CLOCK: "reticle_clock";
+    readonly STATE: "reticle_state";
+    readonly CAPABILITIES: "reticle_capabilities";
+    readonly CONTRACT_SAVE: "reticle_contract_save";
+    readonly DOMAIN: "reticle_domain";
+    readonly FLOW_SAVE: "reticle_flow_save";
+    readonly FLOW_LIST: "reticle_flow_list";
+    readonly FLOW_LOAD: "reticle_flow_load";
+    readonly FLOW_REPLAY: "reticle_flow_replay";
+    /** replay EVERY saved flow → one consolidated suite verdict + prioritized fixes (the loop closer). */
+    readonly FLOW_VERIFY: "reticle_flow_verify";
+    /** persist the human-recorded flow from the live tab. */
+    readonly FLOW_SAVE_RECORDED: "reticle_flow_save_recorded";
+    /** propose (+ opt-in apply) a nearest-match rebind for a drifted flow. */
+    readonly FLOW_HEAL: "reticle_flow_heal";
+    /** structured annotation → compiles into the recording's expect/dynamic/success. */
+    readonly ANNOTATE: "reticle_annotate";
+    /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
+    readonly PROJECT: "reticle_project";
+    /** explicitly record a run outcome (the manual companion to auto-recording). */
+    readonly RUN_RECORD: "reticle_run_record";
+    /** capture a pixel screenshot (CDP/driven browser) → .reticle/visual/<name>.png. */
+    readonly SCREENSHOT: "reticle_screenshot";
+    /** stub/intercept network on the driven page (500, offline, delay) for error/edge-state testing. */
+    readonly NETWORK_MOCK: "reticle_network_mock";
+    /** pin the driven page's viewport to fixed pixels for reproducible visual baselines. */
+    readonly VIEWPORT: "reticle_viewport";
+    /** perceptual-diff the live page against a saved visual baseline. */
+    readonly VISUAL_DIFF: "reticle_visual_diff";
+    /** autonomously click every reachable control + report anomalies (no script). */
+    readonly CRAWL: "reticle_crawl";
+    /** scroll a virtualized list until a queried row mounts, then return it. */
+    readonly SCROLL_TO: "reticle_scroll_to";
+    /** Session lifecycle: tune the presenter session (e.g. idle-end window) for the app's needs. */
+    readonly SESSION: "reticle_session";
+    /** Live-control: end the session (→ ended + push PRESENTER). Handlers live in the tools facet. */
+    readonly END_SESSION: "reticle_end_session";
+    /** Live-control: hand the session back to the human between turns (→ waiting/ask, revivable). */
+    readonly YIELD: "reticle_yield";
+    /** Live-control: clear a pause (→ active). */
+    readonly RESUME: "reticle_resume";
+    /** Live-control: drain the human→agent inbox (explicit poll). */
+    readonly MESSAGES: "reticle_messages";
+    /** Human review: list the mistakes the human pinned to elements, and resolve them once fixed. */
+    readonly REVIEW: "reticle_review";
+    /** First-run readiness: block briefly until the app's SDK connects (smooths the init→connect race). */
+    readonly WAIT_READY: "reticle_wait_ready";
+    /** Navigate the connected browser tab to a URL. */
+    readonly NAVIGATE: "reticle_navigate";
+    /** Reload the connected browser tab (soft or hard). */
+    readonly REFRESH: "reticle_refresh";
+    /** Report running version, latest available, changelog, and breaking changes. */
+    readonly VERSION_INFO: "reticle_version_info";
+    /** Install the latest server version and restart (Claude Code reconnects automatically). */
+    readonly APPLY_UPDATE: "reticle_apply_update";
+    /** Restore the previous server version and restart. */
+    readonly ROLLBACK: "reticle_rollback";
+    /** Export a verification-run artifact (.reticle/runs/<id>.json) — the OEM/CI-consumable verdict. */
+    readonly RUN_EXPORT: "reticle_run_export";
+    /** Lease a fresh isolated headless context from the shared browser pool (one per flow). */
+    readonly LEASE_ACQUIRE: "reticle_lease_acquire";
+    /** Release a previously leased context, freeing the pool slot. */
+    readonly LEASE_RELEASE: "reticle_lease_release";
+};
+export type ReticleTool = (typeof ReticleTool)[keyof typeof ReticleTool];
+//# sourceMappingURL=tool-names.d.ts.map

package/dist/tools/tool-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-names.d.ts","sourceRoot":"","sources":["../../src/tools/tool-names.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA+BtB,sGAAsG;;IAEtG,yDAAyD;;IAEzD,0EAA0E;;IAE1E,oFAAoF;;IAEpF,gFAAgF;;IAEhF,gFAAgF;;IAEhF,oFAAoF;;IAEpF,oGAAoG;;IAEpG,wFAAwF;;IAExF,qEAAqE;;IAErE,iFAAiF;;IAEjF,4EAA4E;;IAE5E,gGAAgG;;IAEhG,kGAAkG;;IAElG,iGAAiG;;IAEjG,8CAA8C;;IAE9C,iEAAiE;;IAEjE,iGAAiG;;IAEjG,uGAAuG;;IAEvG,mDAAmD;;IAEnD,uDAAuD;;IAEvD,iFAAiF;;IAEjF,4FAA4F;;IAE5F,uDAAuD;;IAEvD,oGAAoG;;IAEpG,2FAA2F;;IAE3F,kEAAkE;;CAE1D,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC"}

package/dist/tools/tool-names.js

@@ -0,0 +1,88 @@
+/** MCP tool names exposed to the coding agent (plan/05). No free strings. */
+export const ReticleTool = {
+    SESSIONS: 'reticle_sessions',
+    SNAPSHOT: 'reticle_snapshot',
+    QUERY: 'reticle_query',
+    INSPECT: 'reticle_inspect',
+    ACT: 'reticle_act',
+    ACT_SEQUENCE: 'reticle_act_sequence',
+    ACT_AND_WAIT: 'reticle_act_and_wait',
+    OBSERVE: 'reticle_observe',
+    WAIT_FOR: 'reticle_wait_for',
+    NETWORK: 'reticle_network',
+    CONSOLE: 'reticle_console',
+    ANIMATIONS: 'reticle_animations',
+    ASSERT: 'reticle_assert',
+    BASELINE_SAVE: 'reticle_baseline_save',
+    BASELINE_LIST: 'reticle_baseline_list',
+    DIFF: 'reticle_diff',
+    RECORD_START: 'reticle_record_start',
+    RECORD_STOP: 'reticle_record_stop',
+    REPLAY: 'reticle_replay',
+    EXPLORE: 'reticle_explore',
+    NARRATE: 'reticle_narrate',
+    CLOCK: 'reticle_clock',
+    STATE: 'reticle_state',
+    CAPABILITIES: 'reticle_capabilities',
+    CONTRACT_SAVE: 'reticle_contract_save',
+    DOMAIN: 'reticle_domain',
+    FLOW_SAVE: 'reticle_flow_save',
+    FLOW_LIST: 'reticle_flow_list',
+    FLOW_LOAD: 'reticle_flow_load',
+    FLOW_REPLAY: 'reticle_flow_replay',
+    /** replay EVERY saved flow → one consolidated suite verdict + prioritized fixes (the loop closer). */
+    FLOW_VERIFY: 'reticle_flow_verify',
+    /** persist the human-recorded flow from the live tab. */
+    FLOW_SAVE_RECORDED: 'reticle_flow_save_recorded',
+    /** propose (+ opt-in apply) a nearest-match rebind for a drifted flow. */
+    FLOW_HEAL: 'reticle_flow_heal',
+    /** structured annotation → compiles into the recording's expect/dynamic/success. */
+    ANNOTATE: 'reticle_annotate',
+    /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
+    PROJECT: 'reticle_project',
+    /** explicitly record a run outcome (the manual companion to auto-recording). */
+    RUN_RECORD: 'reticle_run_record',
+    /** capture a pixel screenshot (CDP/driven browser) → .reticle/visual/<name>.png. */
+    SCREENSHOT: 'reticle_screenshot',
+    /** stub/intercept network on the driven page (500, offline, delay) for error/edge-state testing. */
+    NETWORK_MOCK: 'reticle_network_mock',
+    /** pin the driven page's viewport to fixed pixels for reproducible visual baselines. */
+    VIEWPORT: 'reticle_viewport',
+    /** perceptual-diff the live page against a saved visual baseline. */
+    VISUAL_DIFF: 'reticle_visual_diff',
+    /** autonomously click every reachable control + report anomalies (no script). */
+    CRAWL: 'reticle_crawl',
+    /** scroll a virtualized list until a queried row mounts, then return it. */
+    SCROLL_TO: 'reticle_scroll_to',
+    /** Session lifecycle: tune the presenter session (e.g. idle-end window) for the app's needs. */
+    SESSION: 'reticle_session',
+    /** Live-control: end the session (→ ended + push PRESENTER). Handlers live in the tools facet. */
+    END_SESSION: 'reticle_end_session',
+    /** Live-control: hand the session back to the human between turns (→ waiting/ask, revivable). */
+    YIELD: 'reticle_yield',
+    /** Live-control: clear a pause (→ active). */
+    RESUME: 'reticle_resume',
+    /** Live-control: drain the human→agent inbox (explicit poll). */
+    MESSAGES: 'reticle_messages',
+    /** Human review: list the mistakes the human pinned to elements, and resolve them once fixed. */
+    REVIEW: 'reticle_review',
+    /** First-run readiness: block briefly until the app's SDK connects (smooths the init→connect race). */
+    WAIT_READY: 'reticle_wait_ready',
+    /** Navigate the connected browser tab to a URL. */
+    NAVIGATE: 'reticle_navigate',
+    /** Reload the connected browser tab (soft or hard). */
+    REFRESH: 'reticle_refresh',
+    /** Report running version, latest available, changelog, and breaking changes. */
+    VERSION_INFO: 'reticle_version_info',
+    /** Install the latest server version and restart (Claude Code reconnects automatically). */
+    APPLY_UPDATE: 'reticle_apply_update',
+    /** Restore the previous server version and restart. */
+    ROLLBACK: 'reticle_rollback',
+    /** Export a verification-run artifact (.reticle/runs/<id>.json) — the OEM/CI-consumable verdict. */
+    RUN_EXPORT: 'reticle_run_export',
+    /** Lease a fresh isolated headless context from the shared browser pool (one per flow). */
+    LEASE_ACQUIRE: 'reticle_lease_acquire',
+    /** Release a previously leased context, freeing the pool slot. */
+    LEASE_RELEASE: 'reticle_lease_release',
+};
+//# sourceMappingURL=tool-names.js.map

package/dist/tools/tool-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-names.js","sourceRoot":"","sources":["../../src/tools/tool-names.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,QAAQ,EAAE,kBAAkB;IAC5B,QAAQ,EAAE,kBAAkB;IAC5B,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,iBAAiB;IAC1B,GAAG,EAAE,aAAa;IAClB,YAAY,EAAE,sBAAsB;IACpC,YAAY,EAAE,sBAAsB;IACpC,OAAO,EAAE,iBAAiB;IAC1B,QAAQ,EAAE,kBAAkB;IAC5B,OAAO,EAAE,iBAAiB;IAC1B,OAAO,EAAE,iBAAiB;IAC1B,UAAU,EAAE,oBAAoB;IAChC,MAAM,EAAE,gBAAgB;IACxB,aAAa,EAAE,uBAAuB;IACtC,aAAa,EAAE,uBAAuB;IACtC,IAAI,EAAE,cAAc;IACpB,YAAY,EAAE,sBAAsB;IACpC,WAAW,EAAE,qBAAqB;IAClC,MAAM,EAAE,gBAAgB;IACxB,OAAO,EAAE,iBAAiB;IAC1B,OAAO,EAAE,iBAAiB;IAC1B,KAAK,EAAE,eAAe;IACtB,KAAK,EAAE,eAAe;IACtB,YAAY,EAAE,sBAAsB;IACpC,aAAa,EAAE,uBAAuB;IACtC,MAAM,EAAE,gBAAgB;IACxB,SAAS,EAAE,mBAAmB;IAC9B,SAAS,EAAE,mBAAmB;IAC9B,SAAS,EAAE,mBAAmB;IAC9B,WAAW,EAAE,qBAAqB;IAClC,sGAAsG;IACtG,WAAW,EAAE,qBAAqB;IAClC,yDAAyD;IACzD,kBAAkB,EAAE,4BAA4B;IAChD,0EAA0E;IAC1E,SAAS,EAAE,mBAAmB;IAC9B,oFAAoF;IACpF,QAAQ,EAAE,kBAAkB;IAC5B,gFAAgF;IAChF,OAAO,EAAE,iBAAiB;IAC1B,gFAAgF;IAChF,UAAU,EAAE,oBAAoB;IAChC,oFAAoF;IACpF,UAAU,EAAE,oBAAoB;IAChC,oGAAoG;IACpG,YAAY,EAAE,sBAAsB;IACpC,wFAAwF;IACxF,QAAQ,EAAE,kBAAkB;IAC5B,qEAAqE;IACrE,WAAW,EAAE,qBAAqB;IAClC,iFAAiF;IACjF,KAAK,EAAE,eAAe;IACtB,4EAA4E;IAC5E,SAAS,EAAE,mBAAmB;IAC9B,gGAAgG;IAChG,OAAO,EAAE,iBAAiB;IAC1B,kGAAkG;IAClG,WAAW,EAAE,qBAAqB;IAClC,iGAAiG;IACjG,KAAK,EAAE,eAAe;IACtB,8CAA8C;IAC9C,MAAM,EAAE,gBAAgB;IACxB,iEAAiE;IACjE,QAAQ,EAAE,kBAAkB;IAC5B,iGAAiG;IACjG,MAAM,EAAE,gBAAgB;IACxB,uGAAuG;IACvG,UAAU,EAAE,oBAAoB;IAChC,mDAAmD;IACnD,QAAQ,EAAE,kBAAkB;IAC5B,uDAAuD;IACvD,OAAO,EAAE,iBAAiB;IAC1B,iFAAiF;IACjF,YAAY,EAAE,sBAAsB;IACpC,4FAA4F;IAC5F,YAAY,EAAE,sBAAsB;IACpC,uDAAuD;IACvD,QAAQ,EAAE,kBAAkB;IAC5B,oGAAoG;IACpG,UAAU,EAAE,oBAAoB;IAChC,2FAA2F;IAC3F,aAAa,EAAE,uBAAuB;IACtC,kEAAkE;IAClE,aAAa,EAAE,uBAAuB;CAC9B,CAAC"}

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

@@ -0,0 +1,12 @@
+/** Small pure helpers shared by the MCP tool handlers. */
+interface InteractiveItem {
+    ref: string;
+    desc: string;
+}
+/** Parse interactive elements (with refs) out of a snapshot tree for exploration. */
+export declare function parseInteractive(tree: string): InteractiveItem[];
+export declare function asString(value: unknown): string | undefined;
+export declare function asNumber(value: unknown): number | undefined;
+export declare function asRecord(value: unknown): Record<string, unknown>;
+export {};
+//# sourceMappingURL=tools-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools-helpers.d.ts","sourceRoot":"","sources":["../../src/tools/tools-helpers.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAE1D,UAAU,eAAe;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CAShE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE3D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE3D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEhE"}

package/dist/tools/tools-helpers.js

@@ -0,0 +1,22 @@
+/** Small pure helpers shared by the MCP tool handlers. */
+/** Parse interactive elements (with refs) out of a snapshot tree for exploration. */
+export function parseInteractive(tree) {
+    const items = [];
+    for (const line of tree.split('\n')) {
+        const match = /\(ref=(e\d+)\)/.exec(line);
+        if (match !== null) {
+            items.push({ ref: match[1] ?? '', desc: line.replace(/\s*\(ref=e\d+\)/, '').trim() });
+        }
+    }
+    return items;
+}
+export function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+export function asNumber(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+export function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+//# sourceMappingURL=tools-helpers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools-helpers.js","sourceRoot":"","sources":["../../src/tools/tools-helpers.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAO1D,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAE,KAAiC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/F,CAAC"}

package/dist/tools/tools.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tools/tools.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,KAAK,OAAO,EAAkC,MAAM,eAAe,CAAC;AAO7E,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAKvD,eAAO,MAAM,KAAK,EAAE,OAAO,EAsR1B,CAAC"}

package/dist/tools/tools.js

@@ -0,0 +1,268 @@
+import { z } from 'zod';
+import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { withSizeCost } from '../session/output-budget.js';
+import { applySnapshotDelta, SnapshotCache } from './snapshot-delta.js';
+import { asString, asNumber } from './tools-helpers.js';
+import { paginateQueryResult } from './query-paginate.js';
+import { CONTRACT_TOOLS } from './contract-tools.js';
+import { DOMAIN_TOOLS } from '../domain/domain-tools.js';
+import { BROWSER_TOOLS } from './browser-tools.js';
+import { FLOW_TOOLS } from '../flows/flow-tools.js';
+import { PROJECT_TOOLS } from '../project/project-tools.js';
+import { RUN_TOOLS } from '../runs/run-tools.js';
+import { VISUAL_TOOLS } from '../visual/visual-tools.js';
+import { CRAWL_TOOLS } from '../crawl/crawl-tools.js';
+import { SCROLL_TOOLS } from '../input/scroll-tools.js';
+import { NETWORK_MOCK_TOOLS } from '../input/network-mock-tools.js';
+import { VIEWPORT_TOOLS } from '../input/viewport-tools.js';
+import { SESSION_TOOLS } from '../session/session-tools.js';
+import { ANNOTATE_TOOLS } from '../flows/annotate-tools.js';
+import { LIVE_CONTROL_TOOLS } from '../session/live-control-tools.js';
+import { UPDATE_TOOLS } from '../update/update-tools.js';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { ACT_TOOLS } from './act-tools.js';
+import { OBSERVE_TOOLS } from './observe-tools.js';
+import { READ_TOOLS } from './read-tools.js';
+import { LEASE_TOOLS } from './lease-tools.js';
+/** Per-server last-snapshot cache backing reticle_snapshot's diff:true delta mode (route-invalidated). */
+const SNAPSHOT_CACHE = new SnapshotCache();
+export const TOOLS = [
+    {
+        name: ReticleTool.SESSIONS,
+        description: 'List connected browser sessions (tab url/title, sessionId, last-seen, health: hidden/focused/throttled, and `realInputAvailable` — true when native CDP/launched real input is driving this tab), plus a `recommendation` pointing to `reticle drive` when a tab is hidden/throttled and may be un-scriptable from here.',
+        inputSchema: {},
+        outputSchema: {
+            sessions: z
+                .array(
+            // Keep in sync with SessionInfo (session.ts) plus the handler-added realInputAvailable/leased.
+            // A strict MCP client validates this against the payload, so an undeclared field is a hard error.
+            z.object({
+                sessionId: z.string(),
+                url: z.string(),
+                projectId: z.string().optional(),
+                title: z.string().optional(),
+                adapters: z.array(z.string()),
+                hasCapabilities: z.boolean(),
+                lastSeenMs: z.number(),
+                throttled: z.boolean(),
+                focused: z.boolean(),
+                hidden: z.boolean(),
+                realInputAvailable: z.boolean().optional(),
+                leased: z.boolean().optional(),
+                stale: z.boolean().optional(),
+                cleanup_suggestion: z.string().optional(),
+                pendingMarks: z.number().optional(),
+                review_suggestion: z.string().optional(),
+                recommendation: z.string().optional(),
+            }))
+                .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
+        },
+        handler: async (deps) => {
+            const provider = deps.realInput;
+            const leasedIds = new Set(deps.pool?.leasedSessionIds() ?? []);
+            const sessions = await Promise.all(deps.sessions.list().map(async (s) => ({
+                ...s,
+                realInputAvailable: provider !== undefined ? await provider.isAvailableFor(s.url) : false,
+                leased: leasedIds.has(s.sessionId),
+            })));
+            return { sessions };
+        },
+    },
+    {
+        name: ReticleTool.SNAPSHOT,
+        description: 'Semantic accessibility snapshot of the page or a subtree. mode: full|interactive|status. Use to see what is on screen right now. The result carries cost:{ bytes, tokens } (estimated) — if it is large, re-scope (pass `scope`) or use mode:interactive/status instead of reading the whole tree. Pass diff:true after your first snapshot to get back ONLY what changed since your last look (mode:delta with added/removed, or mode:unchanged) — far fewer tokens and no stale tree to mis-read; a route change resets it to a full snapshot automatically.',
+        inputSchema: {
+            scope: z
+                .string()
+                .optional()
+                .describe('CSS selector or element ref to restrict the snapshot to a subtree. Omit to snapshot the whole page.'),
+            mode: z
+                .nativeEnum(SnapshotMode)
+                .optional()
+                .describe('full = all elements; interactive = only clickable/focusable elements; status = only route + title. Default: full.'),
+            diff: z
+                .boolean()
+                .optional()
+                .describe('Return only what changed since your last snapshot of the same scope/mode (mode:delta|unchanged). First call (or after a route change) still returns the full tree.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            tree: z
+                .string()
+                .optional()
+                .describe('Indented ARIA tree of every element on the page (or the scoped subtree).'),
+            status: z.object({ route: z.string(), title: z.string().optional() }).optional(),
+            mode: z
+                .string()
+                .optional()
+                .describe('delta | unchanged when diff:true returned a change set.'),
+            delta: z
+                .object({
+                added: z.array(z.string()),
+                removed: z.array(z.string()),
+                addedCount: z.number(),
+                removedCount: z.number(),
+            })
+                .optional()
+                .describe('Only present on a diff:true call that found changes.'),
+            cost: z
+                .object({ bytes: z.number(), tokens: z.number() })
+                .optional()
+                .describe('Estimated size of this result — re-scope if large.'),
+        },
+        handler: (deps, args) => {
+            const sessionId = asString(args['sessionId']);
+            const mode = asString(args['mode']) ?? SnapshotMode.FULL;
+            return commandOrThrow(deps, sessionId, ReticleCommand.SNAPSHOT, {
+                scope: args['scope'],
+                mode,
+            }).then((raw) => withSizeCost(applySnapshotDelta(raw, {
+                sessionId: sessionId ?? 'default',
+                scope: asString(args['scope']) ?? '',
+                mode,
+                diff: args['diff'] === true,
+            }, SNAPSHOT_CACHE)));
+        },
+    },
+    {
+        name: ReticleTool.QUERY,
+        description: 'Find elements by Testing-Library semantics. Pass `by` (role|text|label|placeholder|testid|alt) and `value` (the query string). Returns matching refs + descriptors + visibility. Pass `limit` to cap descriptors (broad role queries can be large) or `count_only:true` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentTestids[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot.',
+        inputSchema: {
+            by: z.string().describe('Query strategy: role | text | label | placeholder | testid | alt'),
+            value: z
+                .string()
+                .describe('Query value for the selected strategy (e.g. by=role value=button, or by=testid value=submit-btn).'),
+            name: z
+                .string()
+                .optional()
+                .describe('Accessible name filter — narrows results when `by` is role and the page has many elements of that role.'),
+            scope: z
+                .string()
+                .optional()
+                .describe('CSS selector or element ref to restrict the search to a subtree.'),
+            limit: z
+                .number()
+                .optional()
+                .describe('Cap the returned descriptors to the first N (cuts tokens on broad queries). If more matched, the result carries total + truncated:true so the trim is never silent — narrow with name/scope.'),
+            count_only: z
+                .boolean()
+                .optional()
+                .describe('Return just { count } (no element descriptors) — use when you only need "how many match?" and not their refs.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            elements: z
+                .array(z.object({
+                ref: z.string(),
+                role: z.string(),
+                name: z.string(),
+                value: z.string().optional(),
+                states: z.array(z.string()),
+                visible: z.boolean(),
+            }))
+                .optional(),
+            count: z.number().optional().describe('Match count — present when count_only is set.'),
+            total: z
+                .number()
+                .optional()
+                .describe('Total matches before `limit` truncation — present only when truncated.'),
+            truncated: z.boolean().optional().describe('True when `limit` dropped some matches.'),
+            hint: z
+                .object({
+                route: z.string(),
+                presentTestids: z.array(z.string()),
+                knownEmptyState: z.boolean(),
+            })
+                .optional()
+                .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
+            cost: z
+                .object({ bytes: z.number(), tokens: z.number() })
+                .optional()
+                .describe('Estimated size of this result — narrow with `name`/`scope`/`limit` if large.'),
+        },
+        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.QUERY, {
+            by: args['by'],
+            value: args['value'],
+            name: args['name'],
+            scope: args['scope'],
+        }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args['limit']), args['count_only'] === true))),
+    },
+    {
+        name: ReticleTool.INSPECT,
+        description: 'Deep info on one element by ref: full a11y props, visibility, box, and (with @reticlehq/react) component stack + source file.',
+        inputSchema: {
+            ref: z.string().describe("Element ref from reticle_snapshot or reticle_query (e.g. 'e42')."),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            ref: z.string(),
+            role: z.string(),
+            name: z.string(),
+            value: z.string().optional(),
+            states: z.array(z.string()),
+            visible: z.boolean(),
+            box: z
+                .object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() })
+                .optional(),
+            // True when another element covers this one's center (z-index/overlay bug — unclickable).
+            occluded: z.boolean().optional(),
+            // Computed style the a11y tree omits: cursor/display/visibility/color so a "present but
+            // unusable" UI bug (dead cursor, invisible, recolored) is observable in one inspect.
+            styles: z
+                .object({
+                color: z.string(),
+                backgroundColor: z.string(),
+                opacity: z.string(),
+                cursor: z.string(),
+                display: z.string(),
+                visibility: z.string(),
+            })
+                .partial()
+                .optional(),
+            // Theme compliance vs the app's design tokens: { colorToken, backgroundToken (null = off-palette),
+            // offTheme, tokenCount }. Kept as unknown — the structured-content serializer can truncate a
+            // large inspect payload's fields to strings, which a strict shape would reject; the full object
+            // is always present in the text content the agent reads.
+            theme: z.unknown().optional(),
+            component: z
+                .object({ name: z.string().optional(), sourceFile: z.string().optional() })
+                .optional(),
+        },
+        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.INSPECT, {
+            ref: args['ref'],
+        }),
+    },
+    // reticle_capabilities (live | fromDisk) + reticle_contract_save. See contract-tools.ts.
+    ...CONTRACT_TOOLS,
+    ...DOMAIN_TOOLS,
+    // reticle_flow_save / reticle_flow_list / reticle_flow_load. See flow-tools.ts.
+    ...FLOW_TOOLS,
+    // reticle_project (read history + diff-vs-last) / reticle_run_record. See project-tools.ts.
+    ...PROJECT_TOOLS,
+    // reticle_run_export — export the verification-run verdict artifact (.reticle/runs/). See run-tools.ts.
+    ...RUN_TOOLS,
+    // reticle_screenshot / reticle_visual_diff — opt-in, CDP-driven. See visual-tools.ts.
+    ...VISUAL_TOOLS,
+    ...NETWORK_MOCK_TOOLS,
+    ...VIEWPORT_TOOLS,
+    // reticle_crawl — autonomous click-everything + anomaly report. See crawl-tools.ts.
+    ...CRAWL_TOOLS,
+    // reticle_scroll_to — reveal a virtualized off-screen row. See scroll-tools.ts.
+    ...SCROLL_TOOLS,
+    // Session lifecycle: reticle_session — tune the presenter session (idle-end). See session-tools.ts.
+    ...SESSION_TOOLS,
+    // reticle_annotate (structured annotation → expect/dynamic/success). See annotate-tools.ts.
+    ...ANNOTATE_TOOLS,
+    // Live-control: reticle_end_session / reticle_resume / reticle_messages. See live-control-tools.ts.
+    ...LIVE_CONTROL_TOOLS,
+    // reticle_navigate / reticle_refresh — browser navigation tools. See browser-tools.ts.
+    ...BROWSER_TOOLS,
+    // reticle_version_info / reticle_apply_update / reticle_rollback — update lifecycle tools.
+    ...UPDATE_TOOLS,
+    ...ACT_TOOLS,
+    ...OBSERVE_TOOLS,
+    ...READ_TOOLS,
+    ...LEASE_TOOLS,
+];
+//# sourceMappingURL=tools.js.map

package/dist/tools/tools.js.map

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

package/dist/update/update-checker.d.ts

@@ -0,0 +1,20 @@
+interface UpdateManifest {
+    currentVersion: string;
+    latestVersion?: string;
+    updateAvailable: boolean;
+    lastChecked: string;
+    changelog?: string;
+    breakingChanges?: string[];
+    /** The version that was running before the last update — used for rollback. */
+    previousVersion?: string;
+}
+export declare function loadManifest(): UpdateManifest | null;
+export declare function saveManifest(manifest: UpdateManifest): void;
+/**
+ * Returns the current update manifest, refreshing from the npm registry when the cache
+ * is older than UpdateCheckIntervalMs. Never throws — falls back to the cached manifest
+ * (or a safe "no update" default) when the registry is unreachable.
+ */
+export declare function checkForUpdate(currentVersion: string, now: () => number): Promise<UpdateManifest>;
+export {};
+//# sourceMappingURL=update-checker.d.ts.map

package/dist/update/update-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-checker.d.ts","sourceRoot":"","sources":["../../src/update/update-checker.ts"],"names":[],"mappings":"AAWA,UAAU,cAAc;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAUD,wBAAgB,YAAY,IAAI,cAAc,GAAG,IAAI,CAQpD;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAG3D;AAgCD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,MAAM,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAiCzB"}

package/dist/update/update-checker.js

@@ -0,0 +1,94 @@
+import * as fs from 'node:fs';
+import * as https from 'node:https';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { UpdateCheckIntervalMs } from '@reticlehq/core';
+import { log } from '../log.js';
+const RETICLE_HOME = join(homedir(), '.reticle');
+const MANIFEST_PATH = join(RETICLE_HOME, 'update-manifest.json');
+const NPM_REGISTRY = 'https://registry.npmjs.org/@reticlehq/core/latest';
+export function loadManifest() {
+    if (!fs.existsSync(MANIFEST_PATH))
+        return null;
+    try {
+        const raw = fs.readFileSync(MANIFEST_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveManifest(manifest) {
+    fs.mkdirSync(RETICLE_HOME, { recursive: true });
+    fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2), 'utf8');
+}
+function isCacheFresh(manifest, now) {
+    const checked = new Date(manifest.lastChecked).getTime();
+    return now() - checked < UpdateCheckIntervalMs;
+}
+function fetchNpmInfo() {
+    return new Promise((resolve, reject) => {
+        const req = https.get(NPM_REGISTRY, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                body += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch (err) {
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+            res.on('error', reject);
+        });
+        req.setTimeout(5000, () => {
+            req.destroy();
+            reject(new Error('npm registry request timed out'));
+        });
+        req.on('error', reject);
+    });
+}
+/**
+ * Returns the current update manifest, refreshing from the npm registry when the cache
+ * is older than UpdateCheckIntervalMs. Never throws — falls back to the cached manifest
+ * (or a safe "no update" default) when the registry is unreachable.
+ */
+export async function checkForUpdate(currentVersion, now) {
+    const cached = loadManifest();
+    if (cached !== null && cached.currentVersion === currentVersion && isCacheFresh(cached, now)) {
+        return cached;
+    }
+    try {
+        const info = await fetchNpmInfo();
+        const updateAvailable = info.version !== currentVersion;
+        const manifest = {
+            currentVersion,
+            latestVersion: info.version,
+            updateAvailable,
+            lastChecked: new Date(now()).toISOString(),
+            ...(info.reticle?.changelog !== undefined ? { changelog: info.reticle.changelog } : {}),
+            ...(info.reticle?.breakingChanges !== undefined
+                ? { breakingChanges: info.reticle.breakingChanges }
+                : {}),
+            ...(cached?.previousVersion !== undefined ? { previousVersion: cached.previousVersion } : {}),
+        };
+        saveManifest(manifest);
+        return manifest;
+    }
+    catch (err) {
+        log('reticle_update_check_failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        if (cached !== null)
+            return { ...cached, currentVersion };
+        return {
+            currentVersion,
+            updateAvailable: false,
+            lastChecked: new Date(now()).toISOString(),
+        };
+    }
+}
+//# sourceMappingURL=update-checker.js.map