@reticlehq/server 2.0.0

package/dist/tools/contract-tools.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { CapabilitiesSchema, ContractReadError, FROM_DISK_ARG, ReticleCommand, } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { asString } from './tools-helpers.js';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { reticleDirPaths, readContract, writeContract } from '../project/reticle-dir.js';
+/**
+ * The capability-contract tools. `reticle_capabilities` reads the live session, or the
+ * git-checked `.reticle/contract.json` when `{ fromDisk:true }`; `reticle_contract_save` persists the
+ * live registry to that file (pretty-printed, stable key order — diffable in PRs).
+ */
+export const CONTRACT_TOOLS = [
+    {
+        name: ReticleTool.CAPABILITIES,
+        description: 'The app-advertised testable surface (reticle.describe): testids, signals, stores, and named flows. Call this first to learn what to assert on without reading source. Pass { fromDisk:true } to read the git-checked .reticle/contract.json instead of the live session (a fresh agent can learn the surface with no browser attached).',
+        inputSchema: { [FROM_DISK_ARG]: z.boolean().optional(), ...sessionIdShape },
+        outputSchema: {
+            testids: z.array(z.string()),
+            signals: z.array(z.string()),
+            stores: z.array(z.string()),
+            flows: z.array(z.object({ name: z.string(), steps: z.array(z.string()) })),
+            source: z
+                .string()
+                .describe('live = real-time from the browser; disk = last saved contract.json'),
+        },
+        handler: async (deps, args) => {
+            if (args[FROM_DISK_ARG] === true) {
+                const r = await readContract(deps.fs, deps.reticleRoot);
+                if (!r.ok)
+                    throw new Error(r.reason === ContractReadError.MISSING
+                        ? 'no .reticle/contract.json on disk — run reticle_contract_save first (or omit fromDisk to read the live session)'
+                        : '.reticle/contract.json is malformed — fix or regenerate it with reticle_contract_save');
+                return { ...r.capabilities, source: 'disk', generatedAt: r.generatedAt };
+            }
+            const caps = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CAPABILITIES, {});
+            return { ...caps, source: 'live' };
+        },
+    },
+    {
+        name: ReticleTool.CONTRACT_SAVE,
+        description: "Persist the app's live capability registry (reticle.describe) to .reticle/contract.json — git-checked, diffable, readable by a fresh agent via reticle_capabilities({ fromDisk:true }). Returns { path, counts }.",
+        inputSchema: { ...sessionIdShape },
+        outputSchema: {
+            saved: z.boolean(),
+            path: z.string(),
+            testidCount: z.number(),
+            signalCount: z.number(),
+        },
+        handler: async (deps, args) => {
+            const res = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CAPABILITIES, {});
+            const caps = CapabilitiesSchema.parse(res);
+            await writeContract(deps.fs, deps.reticleRoot, caps, deps.now);
+            return {
+                saved: true,
+                path: reticleDirPaths(deps.reticleRoot).contract,
+                testidCount: caps.testids.length,
+                signalCount: caps.signals.length,
+            };
+        },
+    },
+];
+//# sourceMappingURL=contract-tools.js.map

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

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

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

@@ -0,0 +1,7 @@
+import type { ToolDef } from './tools.js';
+/**
+ * Build the two dynamic meta-tools over the full tool table. `reticle_run` dispatches through the same
+ * `runTool` chokepoint as a direct call, so session-health splicing and every other invariant hold.
+ */
+export declare function buildDynamicTools(allTools: ToolDef[]): ToolDef[];
+//# sourceMappingURL=dynamic-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-tools.d.ts","sourceRoot":"","sources":["../../src/tools/dynamic-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,YAAY,CAAC;AA8CpD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAkEhE"}

package/dist/tools/dynamic-tools.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { runTool } from './invoke-tool.js';
+/**
+ * On-demand tool loading for MCP — the answer to the per-turn tool-definition tax.
+ *
+ * A normal MCP server advertises every tool's full description + schema, and the client re-sends
+ * all of them to the model on EVERY turn. Measured here: Reticle at ~5.6k–14.6k tokens/turn just for
+ * definitions, which dominates a real agent loop and only grows as the tool surface grows.
+ *
+ * The `dynamic` profile advertises just TWO meta-tools (~hundreds of tokens, fixed regardless of
+ * how many real tools exist):
+ *   reticle_tools — discover. No args ⇒ a compact catalog (name + one-line summary) of every tool.
+ *                names:[...] ⇒ full description + params for just those tools, loaded on demand.
+ *   reticle_run   — invoke any tool by name. On a bad/unknown call it returns that tool's params as a
+ *                hint, so the model self-corrects without ever needing the schema up front.
+ *
+ * The model lists once, loads the 2–3 tools it actually needs, and calls them — paying for tool
+ * detail only when used, not every turn. Works with any MCP client (no client-side support needed).
+ */
+/** First sentence (purpose) of a description — keeps the catalog one line per tool. */
+function firstSentence(description) {
+    const nl = description.indexOf('\n');
+    const base = nl >= 0 ? description.slice(0, nl) : description;
+    const dot = base.search(/\.\s/);
+    const sentence = dot >= 0 ? base.slice(0, dot + 1) : base;
+    return sentence.length > 140 ? `${sentence.slice(0, 139)}…` : sentence;
+}
+/** Compact param list from a tool's zod shape — name/required/description (the description already
+ * carries the type and any enum hints, so no JSON-Schema machinery is needed). */
+function paramInfo(shape) {
+    return Object.entries(shape).map(([name, schema]) => ({
+        name,
+        required: !schema.isOptional(),
+        description: schema.description ?? '',
+    }));
+}
+/**
+ * Build the two dynamic meta-tools over the full tool table. `reticle_run` dispatches through the same
+ * `runTool` chokepoint as a direct call, so session-health splicing and every other invariant hold.
+ */
+export function buildDynamicTools(allTools) {
+    const byName = new Map(allTools.map((t) => [t.name, t]));
+    const reticleTools = {
+        name: 'reticle_tools',
+        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn.',
+        inputSchema: {
+            names: z
+                .array(z.string())
+                .optional()
+                .describe('Tool names to load full params for. Omit to list all tools with summaries.'),
+        },
+        handler: (_deps, args) => {
+            const names = Array.isArray(args['names'])
+                ? args['names'].filter((n) => typeof n === 'string')
+                : undefined;
+            if (names === undefined || names.length === 0) {
+                return Promise.resolve({
+                    tools: allTools.map((t) => ({ name: t.name, summary: firstSentence(t.description) })),
+                    next: 'Load params with reticle_tools { names:[…] }, then call reticle_run { tool, args }.',
+                });
+            }
+            return Promise.resolve({
+                tools: names.map((n) => {
+                    const t = byName.get(n);
+                    return t === undefined
+                        ? { name: n, error: 'unknown tool' }
+                        : { name: n, description: t.description, params: paramInfo(t.inputSchema) };
+                }),
+            });
+        },
+    };
+    const reticleRun = {
+        name: 'reticle_run',
+        description: "Invoke any Reticle tool by name (discover names/params first with reticle_tools). On an unknown tool or bad arguments it returns the available names or the tool's params, so you can correct and retry.",
+        inputSchema: {
+            tool: z.string().describe('Tool name to invoke, e.g. reticle_network.'),
+            args: z.record(z.unknown()).optional().describe('Arguments object for that tool.'),
+        },
+        handler: async (deps, args) => {
+            const name = typeof args['tool'] === 'string' ? args['tool'] : '';
+            const callArgs = typeof args['args'] === 'object' && args['args'] !== null
+                ? args['args']
+                : {};
+            const target = byName.get(name);
+            if (target === undefined) {
+                return { error: `unknown tool '${name}'`, available: allTools.map((t) => t.name) };
+            }
+            try {
+                return await runTool(target, deps, callArgs);
+            }
+            catch (error) {
+                return {
+                    error: error instanceof Error ? error.message : String(error),
+                    tool: name,
+                    params: paramInfo(target.inputSchema),
+                    hint: 'fix the arguments and call reticle_run again',
+                };
+            }
+        },
+    };
+    return [reticleTools, reticleRun];
+}
+//# sourceMappingURL=dynamic-tools.js.map

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

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

package/dist/tools/error-recovery.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Actionable error recovery. Every tool error the agent hits should answer "what do I do next?", not
+ * just "what went wrong". This pure mapping turns a known error message into a concrete recovery hint
+ * the agent (or the human, via the agent) can act on — so the first 5 minutes never dead-end on a
+ * cryptic "no session connected". Spliced onto the error envelope at the MCP boundary (mcp.ts).
+ *
+ * Conservative by design: an unrecognized error returns `undefined` (no invented advice). Matching is
+ * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
+ * baseline stores). No clock, no IO — unit-testable in isolation.
+ */
+/** The recovery hints, named so they are not free strings and can be asserted in tests. */
+export declare const RECOVERY: {
+    readonly NO_SESSION: string;
+    readonly MULTIPLE_SESSIONS: string;
+    readonly UNKNOWN_SESSION: "That sessionId is not connected. Call reticle_sessions for the current ids and retry with a valid one.";
+    readonly THROTTLED: string;
+    readonly MISSING_BASELINE: string;
+    readonly MISSING_RECORDING: string;
+    readonly TOKEN_REQUIRED: string;
+};
+/** The actionable next move for a known error message, or undefined when none is recognized. */
+export declare function recoveryFor(message: string): string | undefined;
+/** The error envelope sent to the agent: the message, plus a recovery hint when one is known. */
+interface ErrorPayload {
+    error: string;
+    recovery?: string;
+}
+/** Build the tool-error payload spliced at the MCP boundary — `recovery` is added only when known. */
+export declare function buildErrorPayload(message: string): ErrorPayload;
+export {};
+//# sourceMappingURL=error-recovery.d.ts.map

package/dist/tools/error-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-recovery.d.ts","sourceRoot":"","sources":["../../src/tools/error-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2FAA2F;AAC3F,eAAO,MAAM,QAAQ;;;;;;;;CAuBX,CAAC;AAaX,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK/D;AAED,iGAAiG;AACjG,UAAU,YAAY;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAG/D"}

package/dist/tools/error-recovery.js

@@ -0,0 +1,52 @@
+/**
+ * Actionable error recovery. Every tool error the agent hits should answer "what do I do next?", not
+ * just "what went wrong". This pure mapping turns a known error message into a concrete recovery hint
+ * the agent (or the human, via the agent) can act on — so the first 5 minutes never dead-end on a
+ * cryptic "no session connected". Spliced onto the error envelope at the MCP boundary (mcp.ts).
+ *
+ * Conservative by design: an unrecognized error returns `undefined` (no invented advice). Matching is
+ * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
+ * baseline stores). No clock, no IO — unit-testable in isolation.
+ */
+/** The recovery hints, named so they are not free strings and can be asserted in tests. */
+export const RECOVERY = {
+    NO_SESSION: 'No app is connected to Reticle. Ask the human to start their app in dev with @reticlehq/browser ' +
+        'enabled, then run `reticle status` to confirm a session appears. If the app is running but no ' +
+        'session shows, the SDK is not reaching the bridge — check the dev server is up and using the ' +
+        'configured Reticle port.',
+    MULTIPLE_SESSIONS: 'Several tabs are connected. Call reticle_sessions to list them, then pass an explicit sessionId to ' +
+        'target the one you mean.',
+    UNKNOWN_SESSION: 'That sessionId is not connected. Call reticle_sessions for the current ids and retry with a valid one.',
+    THROTTLED: 'The target tab is backgrounded/throttled, so actions may silently no-op. Ask the human to bring ' +
+        'the tab to the front, or run `reticle drive <url>` for a guaranteed scriptable context.',
+    MISSING_BASELINE: 'That baseline does not exist yet. Call reticle_baseline_list to see saved names, or reticle_baseline_save ' +
+        'to capture one before diffing against it.',
+    MISSING_RECORDING: 'No recording by that name is in progress. Start one with reticle_record_start before annotating, ' +
+        'stopping, or saving it.',
+    TOKEN_REQUIRED: 'The bridge binds beyond localhost and requires a pairing token. Set the same token in the SDK ' +
+        'init (@reticlehq/core) and the Reticle server config, then reconnect.',
+};
+/** Ordered match rules; the first hit wins. Substrings track the thrown messages they recover. */
+const RULES = [
+    { match: /no browser session connected/i, hint: RECOVERY.NO_SESSION },
+    { match: /multiple sessions connected/i, hint: RECOVERY.MULTIPLE_SESSIONS },
+    { match: /no connected session with id/i, hint: RECOVERY.UNKNOWN_SESSION },
+    { match: /throttled|backgrounded/i, hint: RECOVERY.THROTTLED },
+    { match: /no baseline named/i, hint: RECOVERY.MISSING_BASELINE },
+    { match: /no (?:active|compiled) recording named/i, hint: RECOVERY.MISSING_RECORDING },
+    { match: /pairing token is required/i, hint: RECOVERY.TOKEN_REQUIRED },
+];
+/** The actionable next move for a known error message, or undefined when none is recognized. */
+export function recoveryFor(message) {
+    for (const rule of RULES) {
+        if (rule.match.test(message))
+            return rule.hint;
+    }
+    return undefined;
+}
+/** Build the tool-error payload spliced at the MCP boundary — `recovery` is added only when known. */
+export function buildErrorPayload(message) {
+    const recovery = recoveryFor(message);
+    return recovery !== undefined ? { error: message, recovery } : { error: message };
+}
+//# sourceMappingURL=error-recovery.js.map

package/dist/tools/error-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-recovery.js","sourceRoot":"","sources":["../../src/tools/error-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2FAA2F;AAC3F,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,UAAU,EACR,kGAAkG;QAClG,gGAAgG;QAChG,+FAA+F;QAC/F,0BAA0B;IAC5B,iBAAiB,EACf,qGAAqG;QACrG,0BAA0B;IAC5B,eAAe,EACb,wGAAwG;IAC1G,SAAS,EACP,kGAAkG;QAClG,yFAAyF;IAC3F,gBAAgB,EACd,4GAA4G;QAC5G,2CAA2C;IAC7C,iBAAiB,EACf,mGAAmG;QACnG,yBAAyB;IAC3B,cAAc,EACZ,gGAAgG;QAChG,uEAAuE;CACjE,CAAC;AAEX,kGAAkG;AAClG,MAAM,KAAK,GAAiE;IAC1E,EAAE,KAAK,EAAE,+BAA+B,EAAE,IAAI,EAAE,QAAQ,CAAC,UAAU,EAAE;IACrE,EAAE,KAAK,EAAE,8BAA8B,EAAE,IAAI,EAAE,QAAQ,CAAC,iBAAiB,EAAE;IAC3E,EAAE,KAAK,EAAE,+BAA+B,EAAE,IAAI,EAAE,QAAQ,CAAC,eAAe,EAAE;IAC1E,EAAE,KAAK,EAAE,yBAAyB,EAAE,IAAI,EAAE,QAAQ,CAAC,SAAS,EAAE;IAC9D,EAAE,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,CAAC,gBAAgB,EAAE;IAChE,EAAE,KAAK,EAAE,yCAAyC,EAAE,IAAI,EAAE,QAAQ,CAAC,iBAAiB,EAAE;IACtF,EAAE,KAAK,EAAE,4BAA4B,EAAE,IAAI,EAAE,QAAQ,CAAC,cAAc,EAAE;CACvE,CAAC;AAEF,gGAAgG;AAChG,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACjD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAQD,sGAAsG;AACtG,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACpF,CAAC"}

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

@@ -0,0 +1,23 @@
+import type { ToolDef, ToolDeps } from './tools.js';
+/**
+ * The live-session tools whose result MUST carry the
+ * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
+ * can never return a healthy-looking result from any of these. `runTool` is the single choke point
+ * (mcp.ts + tool-invoker.ts) that splices health on; the guard test asserts the set is exhaustive.
+ */
+export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
+/**
+ * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write
+ * disk (capabilities/contract/flow/project), drain a buffer, or steer session lifecycle. They are
+ * exempt from the health splice ON PURPOSE. Kept explicit so the guard test can force every new
+ * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
+ */
+export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
+/**
+ * The single entry point both the MCP server and the programmatic invoker call instead of
+ * `tool.handler` directly. Runs the handler, then — for a live-session tool returning a plain
+ * object that did not already include `session` — splices the health envelope on. Idempotent
+ * (handlers that already add health are left untouched) and never alters non-object results.
+ */
+export declare function runTool(tool: ToolDef, deps: ToolDeps, args: Record<string, unknown>): Promise<unknown>;
+//# sourceMappingURL=invoke-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-tool.d.ts","sourceRoot":"","sources":["../../src/tools/invoke-tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CA0BlD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAyBnD,CAAC;AAMH;;;;;GAKG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC,CAelB"}

package/dist/tools/invoke-tool.js

@@ -0,0 +1,99 @@
+import { healthEnvelope } from '../session/session-health.js';
+import { asString } from './tools-helpers.js';
+import { ReticleTool } from './tool-names.js';
+/**
+ * The live-session tools whose result MUST carry the
+ * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
+ * can never return a healthy-looking result from any of these. `runTool` is the single choke point
+ * (mcp.ts + tool-invoker.ts) that splices health on; the guard test asserts the set is exhaustive.
+ */
+export const SESSION_BOUND_TOOLS = new Set([
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.ACT,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.OBSERVE,
+    ReticleTool.WAIT_FOR,
+    ReticleTool.ASSERT,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.ANIMATIONS,
+    ReticleTool.BASELINE_SAVE,
+    ReticleTool.DIFF,
+    ReticleTool.RECORD_START,
+    ReticleTool.RECORD_STOP,
+    ReticleTool.REPLAY,
+    ReticleTool.NARRATE,
+    ReticleTool.CLOCK,
+    ReticleTool.STATE,
+    ReticleTool.EXPLORE,
+    ReticleTool.CRAWL,
+    ReticleTool.SCROLL_TO,
+    ReticleTool.NAVIGATE,
+    ReticleTool.REFRESH,
+]);
+/**
+ * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write
+ * disk (capabilities/contract/flow/project), drain a buffer, or steer session lifecycle. They are
+ * exempt from the health splice ON PURPOSE. Kept explicit so the guard test can force every new
+ * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
+ */
+export const SESSION_EXEMPT_TOOLS = new Set([
+    ReticleTool.CAPABILITIES, // has a fromDisk mode with no live session
+    ReticleTool.CONTRACT_SAVE, // persists the registry to disk
+    ReticleTool.FLOW_SAVE, // sessionId only scopes the write to the app's flow subdir; disk-side
+    ReticleTool.FLOW_LIST, // sessionId only scopes which project's flows are listed; disk read
+    ReticleTool.FLOW_LOAD, // sessionId only scopes which project's flow is read; disk read
+    ReticleTool.FLOW_REPLAY, // returns its own FlowReplayResult contract (+ auto-records a run)
+    ReticleTool.FLOW_VERIFY, // returns its own SuiteVerdict contract (replays the whole suite)
+    ReticleTool.FLOW_SAVE_RECORDED, // reads the recording buffer, writes disk
+    ReticleTool.FLOW_HEAL, // returns its own FlowHealResult contract
+    ReticleTool.PROJECT, // reads .reticle/project.json
+    ReticleTool.RUN_RECORD, // writes .reticle/project.json
+    ReticleTool.RUN_EXPORT, // reads .reticle/runs/<id>.json (verification-run artifact)
+    ReticleTool.END_SESSION, // live-control lifecycle
+    ReticleTool.YIELD, // live-control lifecycle (hand back to the human between turns)
+    ReticleTool.RESUME, // live-control lifecycle
+    ReticleTool.MESSAGES, // drains the human→agent inbox
+    ReticleTool.REVIEW, // lists/resolves human review marks; own contract, no live-DOM read
+    ReticleTool.SESSION, // tunes the presenter session (idle-end); own contract
+    ReticleTool.SCREENSHOT, // own contract; provider-driven, not a live-DOM-health read
+    ReticleTool.VISUAL_DIFF, // own contract (matched/ratio/region)
+    ReticleTool.NETWORK_MOCK, // own contract (applied/count); provider-driven, not a live-DOM read
+    ReticleTool.VIEWPORT, // own contract (applied/width/height); provider-driven, not a live-DOM read
+    ReticleTool.ANNOTATE, // annotates a recording's steps; pure disk-side metadata, no live DOM read
+    ReticleTool.LEASE_RELEASE, // its sessionId is a pool lease id, not a live session; no health splice
+]);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The single entry point both the MCP server and the programmatic invoker call instead of
+ * `tool.handler` directly. Runs the handler, then — for a live-session tool returning a plain
+ * object that did not already include `session` — splices the health envelope on. Idempotent
+ * (handlers that already add health are left untouched) and never alters non-object results.
+ */
+export async function runTool(tool, deps, args) {
+    // Heartbeat: any tool call targeting a leased session keeps its pool lease alive, so the
+    // LeaseReaper only reclaims genuinely orphaned (crashed/hung-agent) leases.
+    const targetSession = asString(args['sessionId']);
+    if (targetSession !== undefined)
+        deps.pool?.touch(targetSession);
+    const result = await tool.handler(deps, args);
+    if (!SESSION_BOUND_TOOLS.has(tool.name))
+        return result;
+    if (!isPlainObject(result) || 'session' in result)
+        return result;
+    const session = deps.sessions.resolve(asString(args['sessionId']));
+    const envelope = { ...healthEnvelope(session) };
+    const lease = session.takeSessionLease();
+    if (lease !== undefined)
+        envelope['session_lease'] = lease;
+    const warning = session.ageWarning();
+    if (warning !== undefined)
+        envelope['session_age_warning'] = warning;
+    return { ...result, ...envelope };
+}
+//# sourceMappingURL=invoke-tool.js.map

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

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

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

@@ -0,0 +1,31 @@
+/**
+ * Lease tools — the agent-facing surface of the BrowserPool.
+ *
+ * `reticle_lease_acquire` opens a fresh isolated headless context navigated to the app URL and returns
+ * the sessionId the app's SDK will register (stamped via __reticle_session so the lease and the session
+ * correlate 1:1). This is the "one of 10 flows" entry point: 10 agents acquire 10 leases, the pool
+ * keeps them in ONE browser, capped and queued. `reticle_lease_release` frees the slot.
+ *
+ * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
+ */
+import type { ToolDef } from './tool-kit.js';
+/**
+ * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
+ * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
+ */
+export declare function appendReticleParams(url: string, session: string, projectId?: string): string;
+/**
+ * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
+ * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
+ * of an internals-leaking wall of text.
+ */
+export declare function cleanNavError(err: unknown): string;
+/**
+ * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
+ * is immediately usable (the page navigates first, then connects a moment later — without this wait
+ * an agent's very next call could race and hit "no connected session"). Returns whether it connected
+ * in time. `isConnected`, `sleeper`, and `attempts` are injected so this is fast to unit-test.
+ */
+export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
+export declare const LEASE_TOOLS: ToolDef[];
+//# sourceMappingURL=lease-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lease-tools.d.ts","sourceRoot":"","sources":["../../src/tools/lease-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,eAAe,CAAC;AAMvD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB5F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAclD;AAeD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,OAAO,EAC1B,OAAO,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAS,EAC9C,QAAQ,GAAE,MAA6B,EACvC,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,eAAO,MAAM,WAAW,EAAE,OAAO,EAuFhC,CAAC"}

package/dist/tools/lease-tools.js

@@ -0,0 +1,164 @@
+/**
+ * Lease tools — the agent-facing surface of the BrowserPool.
+ *
+ * `reticle_lease_acquire` opens a fresh isolated headless context navigated to the app URL and returns
+ * the sessionId the app's SDK will register (stamped via __reticle_session so the lease and the session
+ * correlate 1:1). This is the "one of 10 flows" entry point: 10 agents acquire 10 leases, the pool
+ * keeps them in ONE browser, capped and queued. `reticle_lease_release` frees the slot.
+ *
+ * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
+ */
+import { z } from 'zod';
+import { RETICLE_URL_PARAM } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { asString } from './tools-helpers.js';
+const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
+/**
+ * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
+ * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
+ */
+export function appendReticleParams(url, session, projectId) {
+    try {
+        const u = new URL(url);
+        u.searchParams.set(RETICLE_URL_PARAM.SESSION, session);
+        if (projectId !== undefined && projectId.length > 0) {
+            u.searchParams.set(RETICLE_URL_PARAM.PROJECT, projectId);
+        }
+        return u.toString();
+    }
+    catch {
+        const sep = url.includes('?') ? '&' : '?';
+        const proj = projectId !== undefined && projectId.length > 0
+            ? `&${RETICLE_URL_PARAM.PROJECT}=${encodeURIComponent(projectId)}`
+            : '';
+        return `${url}${sep}${RETICLE_URL_PARAM.SESSION}=${encodeURIComponent(session)}${proj}`;
+    }
+}
+/**
+ * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
+ * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
+ * of an internals-leaking wall of text.
+ */
+export function cleanNavError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // Strip ANSI color codes (ESC[…m) Playwright emits — built via fromCharCode to keep the
+    // control character out of a regex literal (no-control-regex).
+    const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+    const firstLine = (msg.split('\n')[0] ?? msg).replace(ansi, '');
+    const netCode = /net::[A-Z_]+/.exec(firstLine);
+    if (netCode !== null)
+        return netCode[0];
+    if (/timeout/i.test(firstLine))
+        return 'navigation timed out';
+    return firstLine
+        .replace(/^page\.goto:\s*/, '')
+        .replace(/\s+at\s+https?:\/\/\S+.*$/, '')
+        .trim()
+        .slice(0, 100);
+}
+/** A fresh, collision-resistant lease id. Uses crypto at the I/O boundary (not pure logic). */
+function newLeaseId() {
+    const uuid = typeof globalThis.crypto?.randomUUID === 'function'
+        ? globalThis.crypto.randomUUID()
+        : `${String(Date.now())}-${String(performance.now())}`;
+    return `lease-${uuid}`;
+}
+const LEASE_READY_ATTEMPTS = 100;
+const LEASE_READY_POLL_MS = 100;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
+ * is immediately usable (the page navigates first, then connects a moment later — without this wait
+ * an agent's very next call could race and hit "no connected session"). Returns whether it connected
+ * in time. `isConnected`, `sleeper`, and `attempts` are injected so this is fast to unit-test.
+ */
+export async function waitForLeasedSession(isConnected, sleeper = sleep, attempts = LEASE_READY_ATTEMPTS, pollMs = LEASE_READY_POLL_MS) {
+    for (let i = 0; i < attempts; i++) {
+        if (isConnected())
+            return true;
+        await sleeper(pollMs);
+    }
+    return isConnected();
+}
+export const LEASE_TOOLS = [
+    {
+        name: ReticleTool.LEASE_ACQUIRE,
+        description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease_release when the flow is done.',
+        inputSchema: {
+            url: z
+                .string()
+                .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard).'),
+            projectId: z
+                .string()
+                .optional()
+                .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
+        },
+        outputSchema: {
+            sessionId: z.string(),
+            url: z.string(),
+            ready: z
+                .boolean()
+                .describe('Whether the leased tab connected — false ⇒ the app may not embed @reticlehq/core.'),
+            leased: z.number().describe('How many contexts are currently leased from the pool.'),
+            queued: z.number().describe('How many acquires are waiting for a free slot.'),
+            hint: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const pool = deps.pool;
+            if (pool === undefined)
+                throw new Error(POOL_UNAVAILABLE);
+            const url = asString(args['url']);
+            if (url === undefined || url.length === 0)
+                throw new Error('reticle_lease_acquire requires a url');
+            const projectId = asString(args['projectId']);
+            const sessionId = newLeaseId();
+            const navUrl = appendReticleParams(url, sessionId, projectId);
+            let lease;
+            try {
+                lease = await pool.acquire(navUrl, { sessionId });
+            }
+            catch (err) {
+                // A raw page.goto failure is noisy and leaks the internal URL params — surface a clean,
+                // actionable message instead.
+                throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err)})`);
+            }
+            // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
+            const ready = await waitForLeasedSession(() => deps.sessions.get(lease.sessionId) !== undefined);
+            return {
+                sessionId: lease.sessionId,
+                url,
+                ready,
+                leased: pool.activeCount(),
+                queued: pool.queuedCount(),
+                ...(ready
+                    ? {}
+                    : {
+                        hint: `leased tab did not connect — is ${url} running with @reticlehq/core enabled?`,
+                    }),
+            };
+        },
+    },
+    {
+        name: ReticleTool.LEASE_RELEASE,
+        description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
+        inputSchema: {
+            sessionId: z.string().describe('The leased sessionId returned by reticle_lease_acquire.'),
+        },
+        outputSchema: {
+            released: z.boolean(),
+            leased: z.number(),
+        },
+        handler: async (deps, args) => {
+            const pool = deps.pool;
+            if (pool === undefined)
+                throw new Error(POOL_UNAVAILABLE);
+            const sessionId = asString(args['sessionId']);
+            if (sessionId === undefined || sessionId.length === 0) {
+                throw new Error('reticle_lease_release requires a sessionId');
+            }
+            await pool.release(sessionId);
+            return { released: true, leased: pool.activeCount() };
+        },
+    },
+];
+//# sourceMappingURL=lease-tools.js.map

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

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