@reticlehq/server 2.0.0

package/dist/tools/read-tools.js

@@ -0,0 +1,329 @@
+/**
+ * Read / record / replay tools — baselines + diff, recordings + replay, narrate, clock, state,
+ * explore. Split out of tools.ts; assembled back via ...READ_TOOLS.
+ */
+import { z } from 'zod';
+import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { replayProgram } from '../flows/replay.js';
+import { diffLines } from '../project/baselines.js';
+import { selectPath, capDepth } 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';
+export const READ_TOOLS = [
+    {
+        name: ReticleTool.BASELINE_SAVE,
+        description: 'Snapshot the current semantic state under a name, to diff against later (regression detection).',
+        inputSchema: {
+            name: z
+                .string()
+                .describe('Label for this baseline snapshot (e.g. "dashboard-initial"). Use the same name in reticle_diff to compare.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            baseline: z.string().describe('Saved baseline name — pass to reticle_diff to compare.'),
+            lineCount: z.number(),
+        },
+        handler: async (deps, args) => {
+            const name = asString(args['name']) ?? 'default';
+            const { lines, route } = await snapshotTree(deps, asString(args['sessionId']));
+            deps.baselines.save({ name, lines, route });
+            return { baseline: name, lineCount: lines.length };
+        },
+    },
+    {
+        name: ReticleTool.BASELINE_LIST,
+        description: 'List saved baseline names.',
+        inputSchema: {},
+        outputSchema: {
+            baselines: z.array(z.string()),
+        },
+        handler: (deps) => Promise.resolve({ baselines: deps.baselines.list() }),
+    },
+    {
+        name: ReticleTool.DIFF,
+        description: 'Diff current semantic state vs a saved baseline: REMOVED/ADDED elements + console-error count. Call reticle_baseline_list to list saved baselines, reticle_baseline_save to create one. Pass `baseline` (name from reticle_baseline_list). Answers "did anything silently go missing/break?".',
+        inputSchema: {
+            baseline: z
+                .string()
+                .describe('Baseline name to compare against. Call reticle_baseline_list to get available names; names are created by reticle_baseline_save.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            baseline: z.string(),
+            removed: z.array(z.string()),
+            added: z.array(z.string()),
+            consoleErrors: z.number(),
+            routeChanged: z.boolean(),
+        },
+        handler: async (deps, args) => {
+            const name = asString(args['baseline']) ?? 'default';
+            const base = deps.baselines.get(name);
+            if (base === undefined)
+                throw new Error(`no baseline named '${name}'`);
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const { lines, route } = await snapshotTree(deps, asString(args['sessionId']));
+            const { removed, added } = diffLines(base.lines, lines);
+            const consoleErrors = session
+                .eventsSince(0)
+                .filter((e) => e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT).length;
+            return { baseline: name, removed, added, consoleErrors, routeChanged: base.route !== route };
+        },
+    },
+    {
+        name: ReticleTool.RECORD_START,
+        description: 'Start recording the event timeline under a name (for replay / a flow report).',
+        inputSchema: {
+            recordingName: z
+                .string()
+                .describe('Identifier for this recording. Pass the same name to reticle_record_stop and reticle_replay.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            recordingName: z.string(),
+            since: z.number(),
+        },
+        handler: (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const name = asString(args['recordingName']) ?? 'default';
+            const cursor = session.elapsed();
+            deps.recordings.start(name, cursor);
+            return Promise.resolve({ recordingName: name, since: cursor });
+        },
+    },
+    {
+        name: ReticleTool.RECORD_STOP,
+        description: 'Stop the recording identified by `recordingName` and return both the reaction report for the span and a compiled, replayable { program: { version, steps:[{tool,args,stable}] } } of the agent acts captured during it.',
+        inputSchema: {
+            recordingName: z
+                .string()
+                .describe('Identifier of an active recording started with reticle_record_start.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            recordingName: z.string(),
+            program: z.unknown(),
+            warning: z.string().optional(),
+        },
+        handler: (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const name = asString(args['recordingName']) ?? 'default';
+            const rec = deps.recordings.stop(name);
+            if (rec === undefined)
+                throw new Error(`no active recording named '${name}'`);
+            const events = session.eventsSince(rec.cursor);
+            const program = {
+                name,
+                version: REPLAY_PROGRAM_VERSION,
+                steps: rec.steps,
+            };
+            deps.recordings.saveCompiled(program);
+            const unstable = rec.steps.filter((s) => !s.stable).length;
+            const report = buildReactionReport(events, session.elapsed() - rec.cursor);
+            return Promise.resolve({
+                recordingName: name,
+                program,
+                ...(unstable > 0
+                    ? {
+                        warning: `${String(unstable)} step(s) not bound to a testid; replay may be brittle (in-session only)`,
+                    }
+                    : {}),
+                ...report,
+                cost: costHint(report, events.length),
+            });
+        },
+    },
+    {
+        name: ReticleTool.REPLAY,
+        description: 'Re-execute a previously recorded program by recordingName. Re-resolves each step to its element by testid (falling back to the stored ref for unstable steps) and runs the actions in order against the live session. Stops at the first failure. Destructive controls require confirmDangerous:true on every replay; confirmation is never persisted. Returns { ok, steps:[{tool,ok,error?,note?}] }.',
+        inputSchema: {
+            recordingName: z
+                .string()
+                .describe('Name of a compiled recording (from reticle_record_stop) to re-execute.'),
+            confirmDangerous: z
+                .boolean()
+                .optional()
+                .describe('Set true to allow destructive controls during this replay only.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            recordingName: z.string(),
+            ok: z.boolean(),
+            steps: z.array(z.object({
+                tool: z.string(),
+                ok: z.boolean(),
+                error: z.string().optional(),
+                note: z.string().optional(),
+            })),
+        },
+        handler: async (deps, args) => {
+            const name = asString(args['recordingName']) ?? 'default';
+            const program = deps.recordings.getCompiled(name);
+            if (program === undefined)
+                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);
+            return { recordingName: name, since, steps, ok: steps.every((s) => s.ok) };
+        },
+    },
+    {
+        name: ReticleTool.NARRATE,
+        description: 'Narrate your intent on the page (presenter HUD) so the human watching sees what you are about to do and why. Use a short sentence before a meaningful action.',
+        inputSchema: {
+            text: z
+                .string()
+                .describe('Short sentence describing your next action, shown on the presenter HUD for the developer watching.'),
+            level: z
+                .string()
+                .optional()
+                .describe('Display severity: info | warn | error. Default: info.'),
+            ...sessionIdShape,
+        },
+        outputSchema: { ok: z.boolean() },
+        handler: async (deps, args) => {
+            const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NARRATE, {
+                text: args['text'],
+                level: args['level'],
+            }));
+            return { ok: true, ...result };
+        },
+    },
+    {
+        name: ReticleTool.CLOCK,
+        description: 'Control a fake clock: { freeze:true } to freeze time, { advanceMs:N } to fast-forward timers (toasts, debounces, auto-dismiss), { reset:true } to restore. Lets you test time-gated UI deterministically.',
+        inputSchema: {
+            freeze: z
+                .boolean()
+                .optional()
+                .describe('Freeze the fake clock. Time stops advancing until advanceMs or reset.'),
+            advanceMs: z
+                .number()
+                .optional()
+                .describe('Fast-forward time by this many milliseconds — triggers debounces, toasts, auto-dismiss timers.'),
+            reset: z.boolean().optional().describe('Restore the real clock.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            ok: z.boolean().optional(),
+            elapsed: z.number().optional(),
+        },
+        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CLOCK, {
+            freeze: args['freeze'],
+            advanceMs: args['advanceMs'],
+            reset: args['reset'],
+        }),
+    },
+    {
+        name: ReticleTool.STATE,
+        description: "Read live framework state without the app pre-broadcasting it. PREFERRED/RELIABLE: `store` reads a registered store (e.g. 'workspace'); omit `store` to read all stores. To avoid paying for a huge store, scope the read: `path` extracts a dot-path sub-tree (e.g. 'captionCache.v3', with numeric array indices), and `depth` collapses anything deeper than N levels to a size marker. A wrong `path` returns { found:false, availableKeys } so it is diagnosable. `ref` attempts a best-effort read of the nearest React component's hook state and is BOUNDED — on failure it returns component: { ok: false, reason: 'component-state-unavailable' }. Without path/depth: returns { stores, storeNames, component? }.",
+        inputSchema: {
+            ref: z
+                .string()
+                .optional()
+                .describe("Element ref — attempts a best-effort read of the nearest React component's hook state."),
+            store: z
+                .string()
+                .optional()
+                .describe("Registered store name (e.g. 'workspace'). Omit to read all stores."),
+            path: z
+                .string()
+                .optional()
+                .describe("Dot-path into the store (e.g. 'captionCache.v3'). Numeric array indices are supported."),
+            depth: z
+                .number()
+                .optional()
+                .describe('Collapse anything deeper than N levels to a size marker — avoids huge outputs for large stores.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            stores: z.record(z.unknown()).optional(),
+            storeNames: z.array(z.string()).optional(),
+            found: z.boolean().optional(),
+            value: z.unknown().optional(),
+            component: z
+                .object({ ok: z.boolean(), reason: z.string().optional(), state: z.unknown().optional() })
+                .optional(),
+        },
+        handler: async (deps, args) => {
+            const store = asString(args['store']);
+            const path = asString(args['path']);
+            const depth = asNumber(args['depth']);
+            // 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, {
+                ref: args['ref'],
+                store,
+                path,
+                depth,
+            });
+            // 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]
+                    : [];
+            // The browser already scoped it in-page (the `found` shape) — pass through, just safe storeNames.
+            if (typeof root.found === 'boolean') {
+                return { ...root, storeNames: names };
+            }
+            if (path === undefined && depth === undefined) {
+                return { ...root, storeNames: names }; // unchanged shape, safe storeNames
+            }
+            // Back-compat: an older browser returned the whole store; scope it here (may already be
+            // size-truncated in transit for a very large store — that is the limitation this fix removes
+            // for current SDKs).
+            const base = store !== undefined ? (root.stores ?? {})[store] : result;
+            const selection = path !== undefined ? selectPath(base, path) : { found: true, value: base };
+            const value = selection.found && depth !== undefined ? capDepth(selection.value, depth) : selection.value;
+            return {
+                store,
+                path,
+                ...selection,
+                value,
+                storeNames: names,
+            };
+        },
+    },
+    {
+        name: ReticleTool.EXPLORE,
+        description: 'Autonomous-exploration helper: list interactive elements (with refs) + current console-error count, so the agent can drive the app and report anomalies.',
+        inputSchema: {
+            scope: z
+                .string()
+                .optional()
+                .describe('CSS selector or element ref to restrict the interactive element list to a subtree.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            interactive: z.array(z.unknown()),
+            consoleErrors: z.number(),
+            hint: z.string(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const result = await session.command(ReticleCommand.SNAPSHOT, {
+                mode: SnapshotMode.INTERACTIVE,
+                scope: args['scope'],
+            });
+            if (!result.ok)
+                throw new Error(result.error ?? 'snapshot failed');
+            const snap = (result.result ?? {});
+            const consoleErrors = session
+                .eventsSince(0)
+                .filter((e) => e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT).length;
+            return {
+                interactive: parseInteractive(snap.tree ?? ''),
+                consoleErrors,
+                hint: 'act on each ref, observe the reaction, and report failed requests / console errors / dead controls',
+            };
+        },
+    },
+];
+//# sourceMappingURL=read-tools.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read-tools.js","sourceRoot":"","sources":["../../src/tools/read-tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAgB,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE3F,MAAM,CAAC,MAAM,UAAU,GAAc;IACnC;QACE,IAAI,EAAE,WAAW,CAAC,aAAa;QAC/B,WAAW,EACT,iGAAiG;QACnG,WAAW,EAAE;YACX,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,CACP,4GAA4G,CAC7G;YACH,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;YACvF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;SACtB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,SAAS,CAAC;YACjD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAC/E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QACrD,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,aAAa;QAC/B,WAAW,EAAE,4BAA4B;QACzC,WAAW,EAAE,EAAE;QACf,YAAY,EAAE;YACZ,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SAC/B;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;KACzE;IACD;QACE,IAAI,EAAE,WAAW,CAAC,IAAI;QACtB,WAAW,EACT,+RAA+R;QACjS,WAAW,EAAE;YACX,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,CACP,kIAAkI,CACnI;YACH,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;YACpB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC5B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC1B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;YACzB,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE;SAC1B;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,SAAS,CAAC;YACrD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,IAAI,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,GAAG,CAAC,CAAC;YACvE,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACnE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAC/E,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACxD,MAAM,aAAa,GAAG,OAAO;iBAC1B,WAAW,CAAC,CAAC,CAAC;iBACd,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,aAAa,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,cAAc,CACjF,CAAC,MAAM,CAAC;YACX,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,IAAI,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;QAC/F,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,YAAY;QAC9B,WAAW,EAAE,+EAA+E;QAC5F,WAAW,EAAE;YACX,aAAa,EAAE,CAAC;iBACb,MAAM,EAAE;iBACR,QAAQ,CACP,8FAA8F,CAC/F;YACH,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;YACzB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;SAClB;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACnE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,SAAS,CAAC;YAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACpC,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QACjE,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,WAAW;QAC7B,WAAW,EACT,yNAAyN;QAC3N,WAAW,EAAE;YACX,aAAa,EAAE,CAAC;iBACb,MAAM,EAAE;iBACR,QAAQ,CAAC,sEAAsE,CAAC;YACnF,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;YACzB,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;YACpB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC/B;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACnE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,SAAS,CAAC;YAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,GAAG,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,GAAG,CAAC,CAAC;YAC9E,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAoB;gBAC/B,IAAI;gBACJ,OAAO,EAAE,sBAAsB;gBAC/B,KAAK,EAAE,GAAG,CAAC,KAAK;aACjB,CAAC;YACF,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;YACtC,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;YAC3D,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;YAC3E,OAAO,OAAO,CAAC,OAAO,CAAC;gBACrB,aAAa,EAAE,IAAI;gBACnB,OAAO;gBACP,GAAG,CAAC,QAAQ,GAAG,CAAC;oBACd,CAAC,CAAC;wBACE,OAAO,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,yEAAyE;qBACtG;oBACH,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,MAAM;gBACT,IAAI,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;aACtC,CAAC,CAAC;QACL,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,MAAM;QACxB,WAAW,EACT,wYAAwY;QAC1Y,WAAW,EAAE;YACX,aAAa,EAAE,CAAC;iBACb,MAAM,EAAE;iBACR,QAAQ,CAAC,wEAAwE,CAAC;YACrF,gBAAgB,EAAE,CAAC;iBAChB,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CAAC,iEAAiE,CAAC;YAC9E,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;YACzB,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;YACf,KAAK,EAAE,CAAC,CAAC,KAAK,CACZ,CAAC,CAAC,MAAM,CAAC;gBACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;gBAChB,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;gBACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;aAC5B,CAAC,CACH;SACF;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,SAAS,CAAC;YAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YAClD,IAAI,OAAO,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,GAAG,CAAC,CAAC;YACpF,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACnE,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,kBAAkB,CAAC,KAAK,IAAI,CAAC,CAAC;YACvF,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAC7E,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,OAAO;QACzB,WAAW,EACT,+JAA+J;QACjK,WAAW,EAAE;YACX,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,CACP,oGAAoG,CACrG;YACH,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,uDAAuD,CAAC;YACpE,GAAG,cAAc;SAClB;QACD,YAAY,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE;QACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,MAAM,GAAG,CAAC,MAAM,cAAc,CAClC,IAAI,EACJ,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAC3B,cAAc,CAAC,OAAO,EACtB;gBACE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;gBAClB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;aACrB,CACF,CAA4B,CAAC;YAC9B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;QACjC,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,KAAK;QACvB,WAAW,EACT,2MAA2M;QAC7M,WAAW,EAAE;YACX,MAAM,EAAE,CAAC;iBACN,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CAAC,uEAAuE,CAAC;YACpF,SAAS,EAAE,CAAC;iBACT,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,gGAAgG,CACjG;YACH,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;YACjE,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;YAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC/B;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CACtB,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,cAAc,CAAC,KAAK,EAAE;YACtE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC;YACtB,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC;YAC5B,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;SACrB,CAAC;KACL;IACD;QACE,IAAI,EAAE,WAAW,CAAC,KAAK;QACvB,WAAW,EACT,8rBAA8rB;QAChsB,WAAW,EAAE;YACX,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,wFAAwF,CACzF;YACH,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,oEAAoE,CAAC;YACjF,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,wFAAwF,CACzF;YACH,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,iGAAiG,CAClG;YACH,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;YACxC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;YAC1C,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;YAC7B,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;YAC7B,SAAS,EAAE,CAAC;iBACT,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;iBACzF,QAAQ,EAAE;SACd;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACpC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACtC,8FAA8F;YAC9F,6FAA6F;YAC7F,2EAA2E;YAC3E,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,IAAI,EACJ,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAC3B,cAAc,CAAC,UAAU,EACzB;gBACE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC;gBAChB,KAAK;gBACL,IAAI;gBACJ,KAAK;aACN,CACF,CAAC;YACF,mFAAmF;YACnF,yFAAyF;YACzF,mGAAmG;YACnG,MAAM,IAAI,GAAG,MAIZ,CAAC;YACF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;gBAC1C,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;gBACnE,CAAC,CAAC,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;oBACjE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;oBACnB,CAAC,CAAC,EAAE,CAAC;YAET,kGAAkG;YAClG,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACpC,OAAO,EAAE,GAAI,IAAgC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;YACrE,CAAC;YAED,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC9C,OAAO,EAAE,GAAI,IAAgC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,mCAAmC;YACzG,CAAC;YAED,wFAAwF;YACxF,6FAA6F;YAC7F,qBAAqB;YACrB,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACvE,MAAM,SAAS,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAC7F,MAAM,KAAK,GACT,SAAS,CAAC,KAAK,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC;YAC9F,OAAO;gBACL,KAAK;gBACL,IAAI;gBACJ,GAAG,SAAS;gBACZ,KAAK;gBACL,UAAU,EAAE,KAAK;aAClB,CAAC;QACJ,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,OAAO;QACzB,WAAW,EACT,0JAA0J;QAC5J,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,oFAAoF,CACrF;YACH,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;YACjC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;YACzB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;SACjB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACnE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE;gBAC5D,IAAI,EAAE,YAAY,CAAC,WAAW;gBAC9B,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;aACrB,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,iBAAiB,CAAC,CAAC;YACnE,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAsB,CAAC;YACxD,MAAM,aAAa,GAAG,OAAO;iBAC1B,WAAW,CAAC,CAAC,CAAC;iBACd,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,aAAa,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,cAAc,CACjF,CAAC,MAAM,CAAC;YACX,OAAO;gBACL,WAAW,EAAE,gBAAgB,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;gBAC9C,aAAa;gBACb,IAAI,EAAE,oGAAoG;aAC3G,CAAC;QACJ,CAAC;KACF;CACF,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * Server-side snapshot delta — return only what CHANGED since the agent's last look.
+ *
+ * Why (grounded): screenshot/Playwright-MCP agents accrue 60–80K tokens of stale accessibility-tree
+ * data over a session and start hallucinating selectors that no longer exist. The agent-facing cost
+ * is the MCP result it reads (not the internal WS payload), so computing the delta here — and
+ * returning only added/removed lines — directly cuts the tokens the model spends AND removes the
+ * stale full-tree that drives hallucination. Reuses the same normalize+diff the baseline layer uses,
+ * so "what changed" means the same thing everywhere.
+ *
+ * Pure decision (`snapshotDelta`) + a small route-invalidated cache (`SnapshotCache`). A route change
+ * invalidates the prior snapshot (a diff across pages would be meaningless), so the next snapshot
+ * returns full — never a misleading cross-page delta.
+ */
+export declare const SnapshotDeltaMode: {
+    readonly FULL: "full";
+    readonly DELTA: "delta";
+    readonly UNCHANGED: "unchanged";
+};
+export type SnapshotDeltaMode = (typeof SnapshotDeltaMode)[keyof typeof SnapshotDeltaMode];
+export interface SnapshotDelta {
+    added: string[];
+    removed: string[];
+    addedCount: number;
+    removedCount: number;
+}
+export type DeltaDecision = {
+    mode: typeof SnapshotDeltaMode.FULL;
+} | {
+    mode: typeof SnapshotDeltaMode.UNCHANGED;
+} | {
+    mode: typeof SnapshotDeltaMode.DELTA;
+    delta: SnapshotDelta;
+};
+/** Pure: decide full vs delta vs unchanged given the previous tree (same route) and the next tree. */
+export declare function snapshotDelta(prevTree: string | undefined, nextTree: string): DeltaDecision;
+/** Per-(session,scope,mode) last-snapshot cache. Route-aware: a route change invalidates the entry. */
+export declare class SnapshotCache {
+    #private;
+    constructor(max?: number);
+    /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
+    recall(key: string, route: string): string | undefined;
+    remember(key: string, route: string, tree: string): void;
+}
+export declare function snapshotCacheKey(sessionId: string, scope: string, mode: string): string;
+export interface SnapshotDeltaOpts {
+    sessionId: string;
+    scope: string;
+    mode: string;
+    diff: boolean;
+}
+/**
+ * Shape a raw snapshot result for the agent: when `diff` is requested and a same-route prior
+ * snapshot exists, return only the delta (or `unchanged`) instead of the full tree. Always updates
+ * the cache. Non-object/errorless results pass through. The cache is the only state; the decision is
+ * the pure `snapshotDelta`.
+ */
+export declare function applySnapshotDelta(raw: unknown, opts: SnapshotDeltaOpts, cache: SnapshotCache): unknown;
+//# sourceMappingURL=snapshot-delta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-delta.d.ts","sourceRoot":"","sources":["../../src/tools/snapshot-delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC;AACX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE3F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,OAAO,iBAAiB,CAAC,IAAI,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,iBAAiB,CAAC,SAAS,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAEnE,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAQ3F;AAID,uGAAuG;AACvG,qBAAa,aAAa;;gBAIZ,GAAG,GAAE,MAA4B;IAI7C,iGAAiG;IACjG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKtD,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;CAOzD;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,aAAa,GACnB,OAAO,CA0BT"}

package/dist/tools/snapshot-delta.js.map

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

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

@@ -0,0 +1,15 @@
+import { type ToolDeps } from './tools.js';
+/** Named error prefix when an invoker is asked for a tool that does not exist. No free strings. */
+export declare const UNKNOWN_TOOL_ERROR = "unknown reticle tool";
+/**
+ * Programmatic, MCP-free dispatch: (toolName, args) -> the same value the MCP handler returns.
+ * This is the seam @reticlehq/test calls instead of standing up a stdio MCP transport.
+ */
+export type ToolInvoker = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Build an invoker over the shipped TOOLS table, bound to one ToolDeps. No stdio, no transport.
+ * Unknown names reject with `${UNKNOWN_TOOL_ERROR}: <name>`; handler errors propagate unwrapped
+ * (the MCP `{ isError, content }` envelope is a transport concern this layer deliberately skips).
+ */
+export declare function createToolInvoker(deps: ToolDeps): ToolInvoker;
+//# sourceMappingURL=tool-invoker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-invoker.d.ts","sourceRoot":"","sources":["../../src/tools/tool-invoker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGlD,mGAAmG;AACnG,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhG;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAS7D"}

package/dist/tools/tool-invoker.js

@@ -0,0 +1,20 @@
+import { TOOLS } from './tools.js';
+import { runTool } from './invoke-tool.js';
+/** Named error prefix when an invoker is asked for a tool that does not exist. No free strings. */
+export const UNKNOWN_TOOL_ERROR = 'unknown reticle tool';
+/**
+ * Build an invoker over the shipped TOOLS table, bound to one ToolDeps. No stdio, no transport.
+ * Unknown names reject with `${UNKNOWN_TOOL_ERROR}: <name>`; handler errors propagate unwrapped
+ * (the MCP `{ isError, content }` envelope is a transport concern this layer deliberately skips).
+ */
+export function createToolInvoker(deps) {
+    const byName = new Map(TOOLS.map((tool) => [tool.name, tool]));
+    return (toolName, args) => {
+        const tool = byName.get(toolName);
+        if (tool === undefined) {
+            return Promise.reject(new Error(`${UNKNOWN_TOOL_ERROR}: ${toolName}`));
+        }
+        return runTool(tool, deps, args);
+    };
+}
+//# sourceMappingURL=tool-invoker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-invoker.js","sourceRoot":"","sources":["../../src/tools/tool-invoker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAiB,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,mGAAmG;AACnG,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAQzD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/D,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,kBAAkB,KAAK,QAAQ,EAAE,CAAC,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,60 @@
+/**
+ * Shared kit for the MCP tool modules — the tool shape, the dependency bag, the common
+ * session-id arg, and the two helpers (commandOrThrow, snapshotTree) every tool group needs. Lives
+ * in its own leaf module (no dependency on any tool array) so the per-group tool files can import it
+ * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
+ */
+import { z } from 'zod';
+import type { SessionManager } from '../session/session.js';
+import type { RealInputProvider } from '../input/real-input.js';
+import type { BaselineStore } from '../project/baselines.js';
+import type { RecordingStore } from '../flows/recordings.js';
+import type { FileSystemPort } from '../project/fs-port.js';
+import type { FlowStore } from '../flows/flows.js';
+import type { ProjectStore } from '../project/project-store.js';
+import type { AnnotationStore } from '../flows/annotation-store.js';
+import type { BrowserPool } from '../pool/browser-pool.js';
+export interface ToolDeps {
+    sessions: SessionManager;
+    /** shared one-browser/N-context pool for headless leases. undefined ⇒ lease tools report unavailable. */
+    pool?: BrowserPool;
+    baselines: BaselineStore;
+    recordings: RecordingStore;
+    /** on-disk anchored-flow store (.reticle/flows/). */
+    flows: FlowStore;
+    /** structured annotations accumulating for the live recording. */
+    annotations: AnnotationStore;
+    /** cross-run outcome memory (.reticle/project.json). */
+    project: ProjectStore;
+    /** optional native-input provider. undefined ⇒ everything stays synthetic. */
+    realInput?: RealInputProvider;
+    /** injected filesystem seam (tests pass a fake/temp-dir adapter). */
+    fs: FileSystemPort;
+    /** absolute .reticle path (index.ts computes cwd()/.reticle). */
+    reticleRoot: string;
+    /** injected clock for the contract's generatedAt stamp. */
+    now: () => number;
+}
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    /**
+     * JSON Schema-compatible output schema for this tool. When present, the MCP server advertises it
+     * in the tools/list response so schema-aware clients (like @reticlehq/cli) can validate outputs and
+     * compose tool calls safely. Also drives TOON encoding for snapshot/query results.
+     */
+    outputSchema?: z.ZodRawShape;
+    handler: (deps: ToolDeps, args: Record<string, unknown>) => Promise<unknown>;
+}
+export declare const sessionIdShape: {
+    sessionId: z.ZodOptional<z.ZodString>;
+};
+/** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
+export declare function commandOrThrow(deps: ToolDeps, sessionId: string | undefined, name: string, args: Record<string, unknown>): Promise<unknown>;
+/** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */
+export declare function snapshotTree(deps: ToolDeps, sessionId: string | undefined): Promise<{
+    lines: string[];
+    route: string;
+}>;
+//# sourceMappingURL=tool-kit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-kit.d.ts","sourceRoot":"","sources":["../../src/tools/tool-kit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,cAAc,CAAC;IACzB,yGAAyG;IACzG,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,aAAa,CAAC;IACzB,UAAU,EAAE,cAAc,CAAC;IAC3B,qDAAqD;IACrD,KAAK,EAAE,SAAS,CAAC;IACjB,kEAAkE;IAClE,WAAW,EAAE,eAAe,CAAC;IAC7B,wDAAwD;IACxD,OAAO,EAAE,YAAY,CAAC;IACtB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,qEAAqE;IACrE,EAAE,EAAE,cAAc,CAAC;IACnB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC;IAC7B,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E;AAED,eAAO,MAAM,cAAc;;CAO1B,CAAC;AAEF,4FAA4F;AAC5F,wBAAsB,cAAc,CAClC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC,CAKlB;AAOD,+FAA+F;AAC/F,wBAAsB,YAAY,CAChC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAM7C"}

package/dist/tools/tool-kit.js

@@ -0,0 +1,33 @@
+/**
+ * Shared kit for the MCP tool modules — the tool shape, the dependency bag, the common
+ * session-id arg, and the two helpers (commandOrThrow, snapshotTree) every tool group needs. Lives
+ * in its own leaf module (no dependency on any tool array) so the per-group tool files can import it
+ * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
+ */
+import { z } from 'zod';
+import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { normalizeLines } from '../project/baselines.js';
+export const sessionIdShape = {
+    sessionId: z
+        .string()
+        .optional()
+        .describe('Active session ID from reticle_sessions. Omit when only one browser session is open — Reticle resolves it automatically.'),
+};
+/** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
+export async function commandOrThrow(deps, sessionId, name, args) {
+    const session = deps.sessions.resolve(sessionId);
+    const result = await session.command(name, args);
+    if (!result.ok)
+        throw new Error(result.error ?? `command '${name}' failed`);
+    return result.result;
+}
+/** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */
+export async function snapshotTree(deps, sessionId) {
+    const session = deps.sessions.resolve(sessionId);
+    const result = await session.command(ReticleCommand.SNAPSHOT, { mode: SnapshotMode.FULL });
+    if (!result.ok)
+        throw new Error(result.error ?? 'snapshot failed');
+    const snap = (result.result ?? {});
+    return { lines: normalizeLines(snap.tree ?? ''), route: snap.status?.route ?? '' };
+}
+//# sourceMappingURL=tool-kit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-kit.js","sourceRoot":"","sources":["../../src/tools/tool-kit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAI/D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA2CzD,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,0HAA0H,CAC3H;CACJ,CAAC;AAEF,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAc,EACd,SAA6B,EAC7B,IAAY,EACZ,IAA6B;IAE7B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,YAAY,IAAI,UAAU,CAAC,CAAC;IAC5E,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAOD,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAc,EACd,SAA6B;IAE7B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3F,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,iBAAiB,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAmB,CAAC;IACrD,OAAO,EAAE,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;AACrF,CAAC"}