@reticlehq/server 2.0.1 → 2.2.0

package/dist/tools/browser-tools.js

@@ -6,9 +6,17 @@ import { sessionIdShape, commandOrThrow } from './tool-kit.js';
 export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
-        description: 'Navigate the connected browser tab to a URL. The SDK reconnects automatically after the page loads. Use reticle_sessions to confirm the new tab is connected before acting.',
+        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). The SDK reconnects automatically after the page loads. Use reticle_sessions to confirm the new tab is connected before acting.',
         inputSchema: {
-            url: z.string().describe('The URL to navigate to.'),
+            url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
+            reload: z
+                .boolean()
+                .optional()
+                .describe('Reload the current page instead of navigating (replaces reticle_refresh).'),
+            hard: z
+                .boolean()
+                .optional()
+                .describe('With reload:true, bypass the browser cache (Cmd+Shift+R). Default: false.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -17,15 +25,31 @@ export const BROWSER_TOOLS = [
             reason: z.string().optional(),
         },
         handler: async (deps, args) => {
+            // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
+            if (args['reload'] === true) {
+                await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
+                    hard: args['hard'] === true,
+                });
+                return { ok: true };
+            }
             const url = asString(args['url']);
             if (url === undefined || url.length === 0)
                 return { ok: false, reason: 'url required' };
-            const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
-            return {
-                ok: result.ok === true,
-                ...(typeof result.url === 'string' ? { url: result.url } : {}),
-                ...(typeof result.reason === 'string' ? { reason: result.reason } : {}),
-            };
+            // Record navigate as an action. Its window is usually empty (the page unloads and the SDK
+            // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            session.beginAction(ReticleTool.NAVIGATE, { url });
+            try {
+                const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
+                return {
+                    ok: result.ok === true,
+                    ...(typeof result.url === 'string' ? { url: result.url } : {}),
+                    ...(typeof result.reason === 'string' ? { reason: result.reason } : {}),
+                };
+            }
+            finally {
+                session.finishAction();
+            }
         },
     },
     {

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

@@ -1 +1 @@
-{"version":3,"file":"browser-tools.js","sourceRoot":"","sources":["../../src/tools/browser-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/D,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC;QACE,IAAI,EAAE,WAAW,CAAC,QAAQ;QAC1B,WAAW,EACT,6KAA6K;QAC/K,WAAW,EAAE;YACX,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;YACnD,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;YACf,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC9B;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAClC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;YACxF,MAAM,MAAM,GAAG,CAAC,MAAM,cAAc,CAClC,IAAI,EACJ,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAC3B,cAAc,CAAC,QAAQ,EACvB,EAAE,GAAG,EAAE,CACR,CAAsD,CAAC;YACxD,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE,KAAK,IAAI;gBACtB,GAAG,CAAC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9D,GAAG,CAAC,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxE,CAAC;QACJ,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,OAAO;QACzB,WAAW,EACT,mKAAmK;QACrK,WAAW,EAAE;YACX,IAAI,EAAE,CAAC;iBACJ,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CAAC,uEAAuE,CAAC;YACpF,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;SAChB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE;gBAC9E,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI;aAC5B,CAAC,CAAC;YACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACtB,CAAC;KACF;CACF,CAAC"}
+{"version":3,"file":"browser-tools.js","sourceRoot":"","sources":["../../src/tools/browser-tools.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"contract-tools.d.ts","sourceRoot":"","sources":["../../src/tools/contract-tools.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,EA+DnC,CAAC"}
+{"version":3,"file":"contract-tools.d.ts","sourceRoot":"","sources":["../../src/tools/contract-tools.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,EAoEnC,CAAC"}

package/dist/tools/contract-tools.js

@@ -22,6 +22,11 @@ export const CONTRACT_TOOLS = [
             source: z
                 .string()
                 .describe('live = real-time from the browser; disk = last saved contract.json'),
+            // fromDisk carries when the contract was generated; both paths carry the app's declared governance
+            // (owner/safety/scope) when present. Undeclared, they were stripped on a validating profile — a
+            // governance-gated app lost its policy block, and disk reads lost their freshness stamp.
+            generatedAt: z.number().optional(),
+            governance: z.unknown().optional(),
         },
         handler: async (deps, args) => {
             if (args[FROM_DISK_ARG] === true) {

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

@@ -1 +1 @@
-{"version":3,"file":"contract-tools.js","sourceRoot":"","sources":["../../src/tools/contract-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract-tools.js","sourceRoot":"","sources":["../../src/tools/contract-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAGzF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC;QACE,IAAI,EAAE,WAAW,CAAC,YAAY;QAC9B,WAAW,EACT,yUAAyU;QAC3U,WAAW,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,GAAG,cAAc,EAAE;QAC3E,YAAY,EAAE;YACZ,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC5B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC3B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;YAC1E,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,CAAC,oEAAoE,CAAC;YACjF,mGAAmG;YACnG,gGAAgG;YAChG,yFAAyF;YACzF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAClC,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SACnC;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,IAAI,IAAI,CAAC,aAAa,CAAC,KAAK,IAAI,EAAE,CAAC;gBACjC,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;gBACxD,IAAI,CAAC,CAAC,CAAC,EAAE;oBACP,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,MAAM,KAAK,iBAAiB,CAAC,OAAO;wBACpC,CAAC,CAAC,iHAAiH;wBACnH,CAAC,CAAC,uFAAuF,CAC5F,CAAC;gBACJ,OAAO,EAAE,GAAG,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;YAC3E,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,cAAc,CAC/B,IAAI,EACJ,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAC3B,cAAc,CAAC,YAAY,EAC3B,EAAE,CACH,CAAC;YACF,OAAO,EAAE,GAAI,IAAe,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACjD,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,aAAa;QAC/B,WAAW,EACT,mNAAmN;QACrN,WAAW,EAAE,EAAE,GAAG,cAAc,EAAE;QAClC,YAAY,EAAE;YACZ,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE;YAClB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;YAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;YACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;SACxB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,GAAG,GAAG,MAAM,cAAc,CAC9B,IAAI,EACJ,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAC3B,cAAc,CAAC,YAAY,EAC3B,EAAE,CACH,CAAC;YACF,MAAM,IAAI,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YAC/D,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,QAAQ;gBAChD,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;gBAChC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;aACjC,CAAC;QACJ,CAAC;KACF;CACF,CAAC"}

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

@@ -1 +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"}
+{"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;AA+CpD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAkEhE"}

package/dist/tools/dynamic-tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { runTool } from './invoke-tool.js';
+import { ReticleTool } from './tool-names.js';
 /**
  * On-demand tool loading for MCP — the answer to the per-turn tool-definition tax.
  *
@@ -9,10 +10,10 @@ import { runTool } from './invoke-tool.js';
  *
  * 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.
+ * 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).
@@ -41,7 +42,7 @@ function paramInfo(shape) {
 export function buildDynamicTools(allTools) {
     const byName = new Map(allTools.map((t) => [t.name, t]));
     const reticleTools = {
-        name: 'reticle_tools',
+        name: ReticleTool.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
@@ -70,7 +71,7 @@ export function buildDynamicTools(allTools) {
         },
     };
     const reticleRun = {
-        name: 'reticle_run',
+        name: ReticleTool.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.'),

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

@@ -1 +1 @@
-{"version":3,"file":"dynamic-tools.js","sourceRoot":"","sources":["../../src/tools/dynamic-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C;;;;;;;;;;;;;;;;GAgBG;AAEH,uFAAuF;AACvF,SAAS,aAAa,CAAC,WAAmB;IACxC,MAAM,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;IAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1D,OAAO,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;AACzE,CAAC;AAQD;kFACkF;AAClF,SAAS,SAAS,CAAC,KAAoB;IACrC,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QACpD,IAAI;QACJ,QAAQ,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE;QAC9B,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;KACtC,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAmB;IACnD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzD,MAAM,YAAY,GAAY;QAC5B,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,2SAA2S;QAC7S,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBACjB,QAAQ,EAAE;iBACV,QAAQ,CAAC,4EAA4E,CAAC;SAC1F;QACD,OAAO,EAAE,CAAC,KAAe,EAAE,IAA6B,EAAE,EAAE;YAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACxC,CAAC,CAAE,IAAI,CAAC,OAAO,CAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;gBAChF,CAAC,CAAC,SAAS,CAAC;YACd,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9C,OAAO,OAAO,CAAC,OAAO,CAAC;oBACrB,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;oBACrF,IAAI,EAAE,qFAAqF;iBAC5F,CAAC,CAAC;YACL,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,CAAC;gBACrB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBACrB,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACxB,OAAO,CAAC,KAAK,SAAS;wBACpB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE;wBACpC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;gBAChF,CAAC,CAAC;aACH,CAAC,CAAC;QACL,CAAC;KACF,CAAC;IAEF,MAAM,UAAU,GAAY;QAC1B,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,0MAA0M;QAC5M,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;YACvE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;SACnF;QACD,OAAO,EAAE,KAAK,EAAE,IAAc,EAAE,IAA6B,EAAE,EAAE;YAC/D,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,MAAM,QAAQ,GACZ,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI;gBACvD,CAAC,CAAE,IAAI,CAAC,MAAM,CAA6B;gBAC3C,CAAC,CAAC,EAAE,CAAC;YACT,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO,EAAE,KAAK,EAAE,iBAAiB,IAAI,GAAG,EAAE,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACrF,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC/C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO;oBACL,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;oBAC7D,IAAI,EAAE,IAAI;oBACV,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC;oBACrC,IAAI,EAAE,8CAA8C;iBACrD,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;IAEF,OAAO,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"dynamic-tools.js","sourceRoot":"","sources":["../../src/tools/dynamic-tools.ts"],"names":[],"mappings":"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"}

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

@@ -1 +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,CA0BnD,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"}
+{"version":3,"file":"invoke-tool.d.ts","sourceRoot":"","sources":["../../src/tools/invoke-tool.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAuBlD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAkBnD,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,CAsClB"}

package/dist/tools/invoke-tool.js

@@ -20,19 +20,16 @@ export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.NETWORK,
     ReticleTool.CONSOLE,
     ReticleTool.ANIMATIONS,
-    ReticleTool.BASELINE_SAVE,
-    ReticleTool.DIFF,
-    ReticleTool.RECORD_START,
-    ReticleTool.RECORD_STOP,
+    ReticleTool.BASELINE, // merged save/list/diff — save+diff are live reads
+    ReticleTool.RECORD, // merged start/stop — both live
     ReticleTool.REPLAY,
-    ReticleTool.NARRATE,
     ReticleTool.CLOCK,
     ReticleTool.STATE,
+    ReticleTool.STORAGE,
     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
@@ -44,28 +41,20 @@ 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_DELETE, // sessionId only scopes which project's flow is removed; disk delete
+    ReticleTool.FLOW, // merged list/load/delete — sessionId only scopes the project; all disk-side
     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.SESSION, // merged lifecycle/human-channel family (tune/yield/end/resume/messages/review/narrate)
     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
+    ReticleTool.LEASE, // merged acquire/release — its sessionId is a pool lease id, not a live session
 ]);
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -77,24 +66,46 @@ function isPlainObject(value) {
  * (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 rawSessionId = asString(args['sessionId']);
+    const bound = SESSION_BOUND_TOOLS.has(tool.name);
+    // Resolve the session identity ONCE, up front, for a live-session tool. The lease heartbeat must
+    // target the session the handler will ACTUALLY drive — which, when the agent omits sessionId, is the
+    // auto-selected one, NOT the raw (undefined) arg. Touching the raw arg meant an auto-selected drive
+    // never refreshed its pool lease, so the reaper could reclaim the session mid-operation. Resolve
+    // before the handler so a long ACT_AND_WAIT is protected for its whole duration; on failure leave it
+    // to the handler to throw the canonical no-session error.
+    let session;
+    if (bound) {
+        try {
+            session = deps.sessions.resolve(rawSessionId);
+        }
+        catch {
+            session = undefined;
+        }
+    }
+    const leaseId = session?.id ?? rawSessionId;
+    if (leaseId !== undefined)
+        deps.pool?.touch(leaseId);
     const result = await tool.handler(deps, args);
-    if (!SESSION_BOUND_TOOLS.has(tool.name))
+    if (!bound || !isPlainObject(result))
         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();
+    // Reuse the session resolved above so the health envelope describes the SAME session the handler
+    // drove; only re-resolve if the up-front attempt failed but the handler somehow succeeded.
+    const resolved = session ?? deps.sessions.resolve(rawSessionId);
+    const envelope = {};
+    // The health block is idempotent: add it only when the handler didn't already include a `session`.
+    if (!('session' in result))
+        Object.assign(envelope, healthEnvelope(resolved));
+    // Lease + age-warning are INDEPENDENT of the health block. Previously the `'session' in result`
+    // early-return skipped them whenever a handler returned its own health (which a throttled tab always
+    // does) — so a long-running backgrounded session, the case most likely to leak, never got the
+    // one-time pool-lease reminder or the age cleanup nudge. Splice them regardless.
+    const lease = resolved.takeSessionLease();
     if (lease !== undefined)
         envelope['session_lease'] = lease;
-    const warning = session.ageWarning();
+    const warning = resolved.ageWarning();
     if (warning !== undefined)
         envelope['session_age_warning'] = warning;
-    return { ...result, ...envelope };
+    return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }
 //# sourceMappingURL=invoke-tool.js.map

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

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

@@ -26,6 +26,22 @@ export declare function cleanNavError(err: unknown): string;
  * 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.
  */
+/**
+ * Acquire a leased, SDK-connected context for a caller that is not the lease TOOL (the parallel suite).
+ * Returns the session id plus its release; the caller must release in a finally so a crashed flow never
+ * leaks a pool slot and starves the rest of the suite.
+ */
+export declare function acquireLeasedSession(pool: {
+    acquire: (url: string, opts: {
+        sessionId: string;
+    }) => Promise<{
+        sessionId: string;
+        release: () => Promise<void>;
+    }>;
+}, hasSession: (id: string) => boolean, url: string, projectId?: string): Promise<{
+    sessionId: string;
+    release: () => Promise<void>;
+}>;
 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

@@ -1 +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"}
+{"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;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE;IACJ,OAAO,EAAE,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,KACxB,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC;CACnE,EACD,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,EACnC,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAK9D;AAED,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

@@ -72,6 +72,17 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  * 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.
  */
+/**
+ * Acquire a leased, SDK-connected context for a caller that is not the lease TOOL (the parallel suite).
+ * Returns the session id plus its release; the caller must release in a finally so a crashed flow never
+ * leaks a pool slot and starves the rest of the suite.
+ */
+export async function acquireLeasedSession(pool, hasSession, url, projectId) {
+    const sessionId = newLeaseId();
+    const lease = await pool.acquire(appendReticleParams(url, sessionId, projectId), { sessionId });
+    await waitForLeasedSession(() => hasSession(lease.sessionId));
+    return { sessionId: lease.sessionId, release: () => lease.release() };
+}
 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())

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

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

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

@@ -0,0 +1,43 @@
+import type { ToolDef } from './tool-kit.js';
+/**
+ * Surface consolidation. Tool definitions are re-sent to the model EVERY turn, so the named-def
+ * count is a per-turn tax multiplied by loop length. This merges a family of sibling tools
+ * (`baseline_save`/`baseline_list`/`diff`) into one action-dispatched tool (`reticle_baseline {action}`)
+ * WITHOUT rewriting any handler — each original handler is kept verbatim and selected by `action`, so a
+ * merge cannot change behavior, only the advertised shape.
+ *
+ * The merged input schema is `{ action }` plus the union of the members' fields, each made optional
+ * (different actions need different fields). Every handler already narrows its own args, so validation
+ * strength is unchanged in practice.
+ *
+ * TRADEOFF (deliberate): a merged tool carries NO `outputSchema`, because its members return different
+ * shapes and one schema cannot describe them. Schema-aware clients lose output validation for merged
+ * families. That is why tools whose result contract matters — the 12-tool core hot-set, and hot verbs
+ * like flow_replay/flow_verify/flow_heal that return their own documented verdict shapes — are NOT
+ * merged. Only sibling families whose value is the capability, not the contract, are consolidated.
+ */
+export interface MergeSpec {
+    name: string;
+    description: string;
+    /** action value → the original tool whose handler serves it. */
+    actions: Record<string, ToolDef>;
+}
+/** A merge declared by member NAME, resolved against the assembled tool list. */
+export interface MergePlan {
+    name: string;
+    description: string;
+    /** action value → the existing tool name whose handler serves it. */
+    members: Record<string, string>;
+}
+/**
+ * Apply the consolidation to an assembled tool list: drop each plan's members and each retired name from
+ * the advertised surface, and append one action-dispatched tool per plan. Member ToolDefs stay defined in
+ * their own modules (handlers untouched) — they simply stop being advertised separately, which is the
+ * whole point: the cost is the advertised count, not the code.
+ *
+ * A plan naming a member that does not exist is a build error, not a silent no-op — a typo would
+ * otherwise quietly drop a capability from the surface.
+ */
+export declare function applyMerges(tools: readonly ToolDef[], plans: readonly MergePlan[], retired?: readonly string[]): ToolDef[];
+export declare function mergeTools(spec: MergeSpec): ToolDef;
+//# sourceMappingURL=merge-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merge-tools.d.ts","sourceRoot":"","sources":["../../src/tools/merge-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,eAAe,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAcD,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,GAAE,SAAS,MAAM,EAAO,GAC9B,OAAO,EAAE,CAiBX;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAwBnD"}

package/dist/tools/merge-tools.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+/** The union of member input shapes, every field optional so one schema serves every action. */
+function unionShape(actions) {
+    const shape = {};
+    for (const tool of Object.values(actions)) {
+        for (const [key, schema] of Object.entries(tool.inputSchema)) {
+            // First definition wins; siblings share field names/meanings by construction.
+            shape[key] ??= schema.isOptional() ? schema : schema.optional();
+        }
+    }
+    return shape;
+}
+/**
+ * Apply the consolidation to an assembled tool list: drop each plan's members and each retired name from
+ * the advertised surface, and append one action-dispatched tool per plan. Member ToolDefs stay defined in
+ * their own modules (handlers untouched) — they simply stop being advertised separately, which is the
+ * whole point: the cost is the advertised count, not the code.
+ *
+ * A plan naming a member that does not exist is a build error, not a silent no-op — a typo would
+ * otherwise quietly drop a capability from the surface.
+ */
+export function applyMerges(tools, plans, retired = []) {
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const consumed = new Set(retired);
+    const merged = [];
+    for (const plan of plans) {
+        const actions = {};
+        for (const [action, memberName] of Object.entries(plan.members)) {
+            const member = byName.get(memberName);
+            if (member === undefined) {
+                throw new Error(`applyMerges(${plan.name}): unknown member tool '${memberName}'`);
+            }
+            actions[action] = member;
+            consumed.add(memberName);
+        }
+        merged.push(mergeTools({ name: plan.name, description: plan.description, actions }));
+    }
+    return [...tools.filter((t) => !consumed.has(t.name)), ...merged];
+}
+export function mergeTools(spec) {
+    const actionNames = Object.keys(spec.actions);
+    if (actionNames.length === 0)
+        throw new Error(`mergeTools(${spec.name}): no actions`);
+    return {
+        name: spec.name,
+        description: spec.description,
+        inputSchema: {
+            action: z
+                .enum(actionNames)
+                .describe(`Which operation to run: ${actionNames.join(' | ')}.`),
+            ...unionShape(spec.actions),
+        },
+        handler: (deps, args) => {
+            const action = args['action'];
+            const chosen = typeof action === 'string' ? spec.actions[action] : undefined;
+            if (chosen === undefined) {
+                return Promise.resolve({
+                    error: `unknown action '${String(action)}' for ${spec.name}`,
+                    expected: actionNames,
+                });
+            }
+            return chosen.handler(deps, args);
+        },
+    };
+}
+//# sourceMappingURL=merge-tools.js.map

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

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

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

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