toolfunnel 0.6.0 → 0.7.1

package/tools/tools.register.json

@@ -1,227 +1,227 @@
-{
-  "version": 1,
-  "description": "Tool register for the gateway - built-in demo scripts.",
-  "tools": [
-    {
-      "id": "echo",
-      "name": "Echo",
-      "summary": "Return the provided arguments back unchanged.",
-      "category": "demo",
-      "instructions": "Echoes its structured args back in the result. Pass any JSON value as args and the same value is returned. Useful as a connectivity / round-trip smoke test.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/echo.js"
-      }
-    },
-    {
-      "id": "base64",
-      "name": "Base64 Encode/Decode",
-      "summary": "Encode text to Base64 or decode Base64 back to text.",
-      "category": "encoding",
-      "instructions": "Args: { op: \"encode\"|\"decode\", text: string }. Both args required. encode -> Base64 of the UTF-8 text; decode -> UTF-8 from valid Base64 (malformed input is reported, not mangled).",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/base64.js"
-      }
-    },
-    {
-      "id": "hash",
-      "name": "Hash",
-      "summary": "Compute a cryptographic digest (e.g. sha256) of input text.",
-      "category": "crypto",
-      "instructions": "Args: { algo?: \"sha256\"|\"sha1\"|\"md5\" (default \"sha256\"), text: string }. Returns the lowercase hex digest of the UTF-8 text.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/hash.js"
-      }
-    },
-    {
-      "id": "uuid",
-      "name": "UUID Generator",
-      "summary": "Generate a random RFC 4122 v4 UUID.",
-      "category": "generators",
-      "instructions": "Args: { count?: number (default 1) }. Returns one or more freshly generated v4 UUID strings.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/uuid.js"
-      }
-    },
-    {
-      "id": "json",
-      "name": "JSON Format",
-      "summary": "Validate and pretty-print a JSON string.",
-      "category": "data",
-      "instructions": "Args: { text: string, indent?: number (default 2) }. Parses the input; returns the re-serialised, indented JSON, or a clear parse error.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/json.js"
-      }
-    },
-    {
-      "id": "text-stats",
-      "name": "Text Stats",
-      "summary": "Count characters, words, and lines in a block of text.",
-      "category": "text",
-      "instructions": "Args: { text: string }. Returns { chars, words, lines } computed from the input text.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/text-stats.js"
-      }
-    },
-    {
-      "id": "danger",
-      "name": "Danger Demo",
-      "summary": "Demonstrate a gated, potentially destructive operation.",
-      "category": "demo",
-      "instructions": "A sample tool that represents a destructive action. It is intended to be exercised behind the gate so the gating path can be tested end to end. Pass { confirm: true } to proceed.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/danger.js"
-      }
-    },
-    {
-      "id": "tf_tool_add",
-      "name": "tf_tool_add",
-      "summary": "Register a new tool entry in the gateway tool register.",
-      "category": "management",
-      "instructions": "Add a register entry. Args: { id, name, summary?, category?, instructions?, inputSchema?, invoke:{type:'script',path:'scripts/<file>'}|{type:'shell',command}, scriptText? }. inputSchema is a JSON Schema object for the tool's args - a HOT-promoted tool advertises it verbatim in the top-level tools/list, so author it if the tool may be promoted. If scriptText is given for a script invoke, the body is written to tools/scripts/<basename> first. Change is LIVE (no reconnect). Fails if id already exists.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-tool-add.js"
-      }
-    },
-    {
-      "id": "tf_tool_set",
-      "name": "tf_tool_set",
-      "summary": "Activate, deactivate, promote (hot), hide, or remove a register tool.",
-      "category": "management",
-      "instructions": "Args: { id, action:'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove' }. enable/disable flips the active overlay (default ON) - disabled tools drop from toolfunnel_list_tools. hot/unhot promote/demote on the TOP-LEVEL every-turn surface (tools/list), making it directly callable (default OFF). hide/unhide declutter the MANAGER views only (tf_list + UI) and do NOT change what the AI sees. The id may be a local tool id, an upstream surfaced name, or a meta-tool name. remove deletes the register entry and purges its state key. All LIVE (no restart).",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-tool-set.js"
-      }
-    },
-    {
-      "id": "tf_mcp_add",
-      "name": "tf_mcp_add",
-      "summary": "Register an upstream MCP (and optionally expose some of its tools).",
-      "category": "management",
-      "instructions": "Args: { id, command, args?, env?, transport?='stdio', enabled?=true, description?, expose?:[{tool, as?, category?, enabled?}] }. Adds an upstreams[] entry; each expose[] item adds a curated-direct selection. Curated-direct changes need an aggregator reconnect to surface.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-mcp-add.js"
-      }
-    },
-    {
-      "id": "tf_mcp_set",
-      "name": "tf_mcp_set",
-      "summary": "Enable, disable, or remove an upstream MCP.",
-      "category": "management",
-      "instructions": "Args: { id, action:'enable'|'disable'|'remove' }. enable/disable toggles the upstream; remove deletes it and cascades its expose entries. Reconnect needed for the curated-direct surface to change.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-mcp-set.js"
-      }
-    },
-    {
-      "id": "tf_wrap",
-      "name": "tf_wrap",
-      "summary": "Wrap ONE attached upstream MCP: its tools become the entire surface (transparent passthrough).",
-      "category": "management",
-      "instructions": "Args: {} reports status ({ wrapping, upstreams }). { off:true } clears the wrap. { upstream:'<id>', confirm:true } sets it: that upstream's tools become the ENTIRE advertised surface under their ORIGINAL names, everything else (meta-tools INCLUDED) is hidden and uncallable, and every call still fires the PreToolUse gate. Because the gateway answers both MCP eras, this keeps a legacy-only MCP working with 2026-07-28-era clients. WARNING (why confirm is required): the wrap hides tf_wrap itself, so YOU cannot undo it in-band afterwards - recovery is the config web UI (--ui) or `toolfunnel wrap --off` on a terminal. A running host applies the change live.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-wrap.js"
-      }
-    },
-    {
-      "id": "tf_hook_add",
-      "name": "tf_hook_add",
-      "summary": "Add a hook manifest entry (e.g. a PreToolUse gate).",
-      "category": "management",
-      "instructions": "Args: { id, event, matcher?, command, script?, timeout?, enabled?=true, description?, scriptText? }. id format '<kebab-event>/<name>'. command should use the portable ${HOOKS_DIR} token. If scriptText is given, the script is authored under hooks/scripts/ (path-guarded). enabled is the manifest seed; live toggles live in hooks.state.json.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-hook-add.js"
-      }
-    },
-    {
-      "id": "tf_hook_set",
-      "name": "tf_hook_set",
-      "summary": "Enable, disable, or remove a hook.",
-      "category": "management",
-      "instructions": "Args: { id, action:'enable'|'disable'|'remove' }. enable/disable writes the hooks.state.json overlay (wins over the manifest seed) and mirrors the manifest; remove deletes the manifest entry and purges the overlay key (the script file is left in place).",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-hook-set.js"
-      }
-    },
-    {
-      "id": "tf_list",
-      "name": "tf_list",
-      "summary": "List register tools, upstream MCPs, or hooks with their active state.",
-      "category": "management",
-      "instructions": "Args: { kind:'tools'|'mcps'|'hooks' }. tools -> register briefs + enabled/hidden overlay; mcps -> upstreams + expose selections; hooks -> configured + auto-detected inventory with live enabled state. Read-only.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-list.js"
-      }
-    },
-    {
-      "id": "tf_log",
-      "name": "tf_log",
-      "summary": "Enable, disable, or check the gateway activity/audit log.",
-      "category": "management",
-      "instructions": "Args: { action:'enable'|'disable'|'status', path? }. Toggles ToolFunnel's JSONL audit log (tool runs + gate allow/deny decisions). Default OFF. 'status' returns {enabled,path} + recent count. Like any tool, tf_log can itself be disabled to revoke logging control.",
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-log.js"
-      }
-    },
-    {
-      "id": "tf_pack",
-      "name": "tf_pack",
-      "summary": "Package the LIVE setup into a deployment-ready artifact under <home>/dist/ (portable config home, or a publishable npm package wrapping toolfunnel).",
-      "category": "management",
-      "instructions": "Args: { format?:'home'|'npm' (default 'home'), name?, version?, description?, out?, force? }. Snapshots the current setup - tools + scripts, hot/hidden curation (tools.state.json), upstream references (mcp/expose.json), policy hooks (THE GATE TRAVELS), and identity (toolfunnel.json, rewritten with the pack's name/version; a declared `requires` travels too) - into <home>/dist/<out||name>/, a SEPARATE location from the live config. format 'home' = a portable config home (zip / git init / run via --config-dir). format 'npm' = a publishable package: generated package.json with toolfunnel as a caret DEPENDENCY (depend, never copy), a 2-line bin launcher pointing --config-dir at the bundled home/, and a README stub - then `cd dist/<name> && npm publish`. NEVER ships auth/ or logs/. Refuses a non-empty destination without force:true. out is a folder NAME under dist/, never a path.",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "format": {
-            "type": "string",
-            "enum": [
-              "home",
-              "npm"
-            ],
-            "description": "Artifact type: portable config home (default) or publishable npm package."
-          },
-          "name": {
-            "type": "string",
-            "description": "Pack/package name (default: the home's serverName)."
-          },
-          "version": {
-            "type": "string",
-            "description": "Pack version (default: the home's serverVersion, else 0.1.0)."
-          },
-          "description": {
-            "type": "string",
-            "description": "npm format: the package.json description."
-          },
-          "out": {
-            "type": "string",
-            "description": "Folder NAME under <home>/dist/ (default: name)."
-          },
-          "force": {
-            "type": "boolean",
-            "description": "Overwrite files in an existing non-empty destination."
-          }
-        },
-        "additionalProperties": false
-      },
-      "invoke": {
-        "type": "script",
-        "path": "scripts/tf-pack.js"
-      }
-    }
-  ]
-}
+{
+  "version": 1,
+  "description": "Tool register for the gateway - built-in demo scripts.",
+  "tools": [
+    {
+      "id": "echo",
+      "name": "Echo",
+      "summary": "Return the provided arguments back unchanged.",
+      "category": "demo",
+      "instructions": "Echoes its structured args back in the result. Pass any JSON value as args and the same value is returned. Useful as a connectivity / round-trip smoke test.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/echo.js"
+      }
+    },
+    {
+      "id": "base64",
+      "name": "Base64 Encode/Decode",
+      "summary": "Encode text to Base64 or decode Base64 back to text.",
+      "category": "encoding",
+      "instructions": "Args: { op: \"encode\"|\"decode\", text: string }. Both args required. encode -> Base64 of the UTF-8 text; decode -> UTF-8 from valid Base64 (malformed input is reported, not mangled).",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/base64.js"
+      }
+    },
+    {
+      "id": "hash",
+      "name": "Hash",
+      "summary": "Compute a cryptographic digest (e.g. sha256) of input text.",
+      "category": "crypto",
+      "instructions": "Args: { algo?: \"sha256\"|\"sha1\"|\"md5\" (default \"sha256\"), text: string }. Returns the lowercase hex digest of the UTF-8 text.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/hash.js"
+      }
+    },
+    {
+      "id": "uuid",
+      "name": "UUID Generator",
+      "summary": "Generate a random RFC 4122 v4 UUID.",
+      "category": "generators",
+      "instructions": "Args: { count?: number (default 1) }. Returns one or more freshly generated v4 UUID strings.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/uuid.js"
+      }
+    },
+    {
+      "id": "json",
+      "name": "JSON Format",
+      "summary": "Validate and pretty-print a JSON string.",
+      "category": "data",
+      "instructions": "Args: { text: string, indent?: number (default 2) }. Parses the input; returns the re-serialised, indented JSON, or a clear parse error.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/json.js"
+      }
+    },
+    {
+      "id": "text-stats",
+      "name": "Text Stats",
+      "summary": "Count characters, words, and lines in a block of text.",
+      "category": "text",
+      "instructions": "Args: { text: string }. Returns { chars, words, lines } computed from the input text.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/text-stats.js"
+      }
+    },
+    {
+      "id": "danger",
+      "name": "Danger Demo",
+      "summary": "Demonstrate a gated, potentially destructive operation.",
+      "category": "demo",
+      "instructions": "A sample tool that represents a destructive action. It is intended to be exercised behind the gate so the gating path can be tested end to end. Pass { confirm: true } to proceed.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/danger.js"
+      }
+    },
+    {
+      "id": "tf_tool_add",
+      "name": "tf_tool_add",
+      "summary": "Register a new tool entry in the gateway tool register.",
+      "category": "management",
+      "instructions": "Add a register entry. Args: { id, name, summary?, category?, instructions?, inputSchema?, invoke:{type:'script',path:'scripts/<file>'}|{type:'shell',command}, scriptText? }. inputSchema is a JSON Schema object for the tool's args - a HOT-promoted tool advertises it verbatim in the top-level tools/list, so author it if the tool may be promoted. If scriptText is given for a script invoke, the body is written to tools/scripts/<basename> first. Change is LIVE (no reconnect). Fails if id already exists.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-tool-add.js"
+      }
+    },
+    {
+      "id": "tf_tool_set",
+      "name": "tf_tool_set",
+      "summary": "Activate, deactivate, promote (hot), hide, or remove a register tool.",
+      "category": "management",
+      "instructions": "Args: { id, action:'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove' }. enable/disable flips the active overlay (default ON) - disabled tools drop from toolfunnel_list_tools. hot/unhot promote/demote on the TOP-LEVEL every-turn surface (tools/list), making it directly callable (default OFF). hide/unhide declutter the MANAGER views only (tf_list + UI) and do NOT change what the AI sees. The id may be a local tool id, an upstream surfaced name, or a meta-tool name. remove deletes the register entry and purges its state key. All LIVE (no restart).",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-tool-set.js"
+      }
+    },
+    {
+      "id": "tf_mcp_add",
+      "name": "tf_mcp_add",
+      "summary": "Register an upstream MCP (and optionally expose some of its tools).",
+      "category": "management",
+      "instructions": "Args: { id, command, args?, env?, transport?='stdio', enabled?=true, description?, expose?:[{tool, as?, category?, enabled?}] }. Adds an upstreams[] entry; each expose[] item adds a curated-direct selection. Curated-direct changes need an aggregator reconnect to surface.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-mcp-add.js"
+      }
+    },
+    {
+      "id": "tf_mcp_set",
+      "name": "tf_mcp_set",
+      "summary": "Enable, disable, or remove an upstream MCP.",
+      "category": "management",
+      "instructions": "Args: { id, action:'enable'|'disable'|'remove' }. enable/disable toggles the upstream; remove deletes it and cascades its expose entries. Reconnect needed for the curated-direct surface to change.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-mcp-set.js"
+      }
+    },
+    {
+      "id": "tf_wrap",
+      "name": "tf_wrap",
+      "summary": "Wrap ONE attached upstream MCP: its tools become the entire surface (transparent passthrough).",
+      "category": "management",
+      "instructions": "Args: {} reports status ({ wrapping, upstreams }). { off:true } clears the wrap. { upstream:'<id>', confirm:true } sets it: that upstream's tools become the ENTIRE advertised surface under their ORIGINAL names, everything else (meta-tools INCLUDED) is hidden and uncallable, and every call still fires the PreToolUse gate. Because the gateway answers both MCP eras, this keeps a legacy-only MCP working with 2026-07-28-era clients. WARNING (why confirm is required): the wrap hides tf_wrap itself, so YOU cannot undo it in-band afterwards - recovery is the config web UI (--ui) or `toolfunnel wrap --off` on a terminal. A running host applies the change live.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-wrap.js"
+      }
+    },
+    {
+      "id": "tf_hook_add",
+      "name": "tf_hook_add",
+      "summary": "Add a hook manifest entry (e.g. a PreToolUse gate).",
+      "category": "management",
+      "instructions": "Args: { id, event, matcher?, command, script?, timeout?, enabled?=true, description?, scriptText? }. id format '<kebab-event>/<name>'. command should use the portable ${HOOKS_DIR} token. If scriptText is given, the script is authored under hooks/scripts/ (path-guarded). enabled is the manifest seed; live toggles live in hooks.state.json.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-hook-add.js"
+      }
+    },
+    {
+      "id": "tf_hook_set",
+      "name": "tf_hook_set",
+      "summary": "Enable, disable, or remove a hook.",
+      "category": "management",
+      "instructions": "Args: { id, action:'enable'|'disable'|'remove' }. enable/disable writes the hooks.state.json overlay (wins over the manifest seed) and mirrors the manifest; remove deletes the manifest entry and purges the overlay key (the script file is left in place).",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-hook-set.js"
+      }
+    },
+    {
+      "id": "tf_list",
+      "name": "tf_list",
+      "summary": "List register tools, upstream MCPs, or hooks with their active state.",
+      "category": "management",
+      "instructions": "Args: { kind:'tools'|'mcps'|'hooks' }. tools -> register briefs + enabled/hidden overlay; mcps -> upstreams + expose selections; hooks -> configured + auto-detected inventory with live enabled state. Read-only.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-list.js"
+      }
+    },
+    {
+      "id": "tf_log",
+      "name": "tf_log",
+      "summary": "Enable, disable, or check the gateway activity/audit log.",
+      "category": "management",
+      "instructions": "Args: { action:'enable'|'disable'|'status', path? }. Toggles ToolFunnel's JSONL audit log (tool runs + gate allow/deny decisions). Default OFF. 'status' returns {enabled,path} + recent count. Like any tool, tf_log can itself be disabled to revoke logging control.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-log.js"
+      }
+    },
+    {
+      "id": "tf_pack",
+      "name": "tf_pack",
+      "summary": "Package the LIVE setup into a deployment-ready artifact under <home>/dist/ (portable config home, or a publishable npm package wrapping toolfunnel).",
+      "category": "management",
+      "instructions": "Args: { format?:'home'|'npm' (default 'home'), name?, version?, description?, out?, force? }. Snapshots the current setup - tools + scripts, hot/hidden curation (tools.state.json), upstream references (mcp/expose.json), policy hooks (THE GATE TRAVELS), and identity (toolfunnel.json, rewritten with the pack's name/version; a declared `requires` travels too) - into <home>/dist/<out||name>/, a SEPARATE location from the live config. format 'home' = a portable config home (zip / git init / run via --config-dir). format 'npm' = a publishable package: generated package.json with toolfunnel as a caret DEPENDENCY (depend, never copy), a 2-line bin launcher pointing --config-dir at the bundled home/, and a README stub - then `cd dist/<name> && npm publish`. NEVER ships auth/ or logs/. Refuses a non-empty destination without force:true. out is a folder NAME under dist/, never a path.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "format": {
+            "type": "string",
+            "enum": [
+              "home",
+              "npm"
+            ],
+            "description": "Artifact type: portable config home (default) or publishable npm package."
+          },
+          "name": {
+            "type": "string",
+            "description": "Pack/package name (default: the home's serverName)."
+          },
+          "version": {
+            "type": "string",
+            "description": "Pack version (default: the home's serverVersion, else 0.1.0)."
+          },
+          "description": {
+            "type": "string",
+            "description": "npm format: the package.json description."
+          },
+          "out": {
+            "type": "string",
+            "description": "Folder NAME under <home>/dist/ (default: name)."
+          },
+          "force": {
+            "type": "boolean",
+            "description": "Overwrite files in an existing non-empty destination."
+          }
+        },
+        "additionalProperties": false
+      },
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-pack.js"
+      }
+    }
+  ]
+}

package/src/core/tool-registry.js

@@ -1,180 +0,0 @@
-'use strict';
-
-/**
- * tool-registry.js - backend-agnostic tool catalogue for the host loop.
- *
- * The host asks the registry for tool definitions to hand to a backend
- * (see ARCHITECTURE.md: `backend.send({ system, messages, tools })`). When the
- * model requests a tool by name, the host executes it here. The registry holds
- * NO host imports so it runs headless under `node --test`.
- *
- * A tool is registered as: register(name, { description, inputSchema, run })
- *   - description: human/model-facing string
- *   - inputSchema: a JSON-schema-ish object describing the input (handed to the backend)
- *   - run(input): the implementation; may be sync or async; its return value is the result
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-class ToolRegistry {
-  constructor() {
-    // name -> { description, inputSchema, run }
-    this._tools = new Map();
-  }
-
-  /**
-   * Register a tool under a unique name.
-   * Throws on a bad shape so misconfiguration is caught at wiring time, not at
-   * model-call time (the loop must never receive a half-formed tool).
-   *
-   * @param {string} name
-   * @param {{ description?: string, inputSchema?: object, run: (input:any)=>any }} def
-   * @returns {ToolRegistry} this (for chaining)
-   */
-  register(name, def) {
-    if (typeof name !== 'string' || name.length === 0) {
-      throw new Error('ToolRegistry.register: name must be a non-empty string');
-    }
-    if (!def || typeof def !== 'object') {
-      throw new Error(`ToolRegistry.register("${name}"): definition object is required`);
-    }
-    if (typeof def.run !== 'function') {
-      throw new Error(`ToolRegistry.register("${name}"): "run" must be a function`);
-    }
-    if (this._tools.has(name)) {
-      throw new Error(`ToolRegistry.register("${name}"): tool already registered`);
-    }
-    this._tools.set(name, {
-      description: typeof def.description === 'string' ? def.description : '',
-      // Default to an open object schema so a tool without a declared schema
-      // still produces a valid definition for the backend.
-      inputSchema:
-        def.inputSchema && typeof def.inputSchema === 'object'
-          ? def.inputSchema
-          : { type: 'object', properties: {} },
-      run: def.run,
-    });
-    return this;
-  }
-
-  /** @param {string} name @returns {boolean} */
-  has(name) {
-    return this._tools.has(name);
-  }
-
-  /**
-   * Execute a registered tool by name. Always returns a Promise so the host
-   * loop can `await` uniformly regardless of whether `run` was sync or async.
-   * Throws a clear error if the tool is unknown (the host turns this into a
-   * tool result / PostToolUse feedback rather than crashing the loop).
-   *
-   * @param {string} name
-   * @param {any} input
-   * @returns {Promise<any>} the tool's result
-   */
-  async execute(name, input) {
-    const tool = this._tools.get(name);
-    if (!tool) {
-      const known = this.list().map((t) => t.name);
-      throw new Error(
-        `ToolRegistry.execute: unknown tool "${name}". ` +
-          `Registered tools: ${known.length ? known.join(', ') : '(none)'}`
-      );
-    }
-    // Await covers both sync return values and returned Promises.
-    return await tool.run(input);
-  }
-
-  /**
-   * Tool definitions array, shaped for handing to a backend:
-   * `[{ name, description, inputSchema }]`. The `run` function is deliberately
-   * omitted - the backend never needs (or should see) the implementation.
-   *
-   * @returns {Array<{ name: string, description: string, inputSchema: object }>}
-   */
-  list() {
-    const out = [];
-    for (const [name, tool] of this._tools) {
-      out.push({
-        name,
-        description: tool.description,
-        inputSchema: tool.inputSchema,
-      });
-    }
-    return out;
-  }
-}
-
-/**
- * makeDemoRegistry - a ToolRegistry preloaded with two demo tools used by the
- * host tests (host.test.js drives the lifecycle through these).
- *
- *   echo               - returns its input unchanged (trivial, deterministic).
- *   readFileSandboxed  - reads a UTF-8 file, but ONLY within `sandboxRoot`,
- *                        rejecting any path that escapes the sandbox. This is
- *                        the same defense-in-depth posture the hook loader's
- *                        writeScript guard uses (HOOK_ENGINE.md §8) - a tool the
- *                        model can call must not become a filesystem escape.
- *
- * @param {object} [opts]
- * @param {string} [opts.sandboxRoot=process.cwd()] absolute root for readFileSandboxed
- * @returns {ToolRegistry}
- */
-function makeDemoRegistry(opts) {
-  const sandboxRoot = path.resolve((opts && opts.sandboxRoot) || process.cwd());
-  const registry = new ToolRegistry();
-
-  registry.register('echo', {
-    description: 'Returns its input unchanged. Useful for testing the tool loop.',
-    inputSchema: {
-      type: 'object',
-      description: 'Any JSON value passed through as-is.',
-      properties: {},
-      additionalProperties: true,
-    },
-    run: (input) => input,
-  });
-
-  registry.register('readFileSandboxed', {
-    description:
-      'Reads a UTF-8 text file located within the sandbox root. ' +
-      'Rejects absolute paths and any relative path that escapes the sandbox.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: {
-          type: 'string',
-          description: 'Path to read, relative to the sandbox root.',
-        },
-      },
-      required: ['path'],
-    },
-    run: (input) => {
-      const requested = input && input.path;
-      if (typeof requested !== 'string' || requested.length === 0) {
-        throw new Error('readFileSandboxed: "path" (non-empty string) is required');
-      }
-      // Reject absolute paths outright; everything must be relative to the sandbox.
-      if (path.isAbsolute(requested)) {
-        throw new Error(
-          `readFileSandboxed: absolute paths are not allowed ("${requested}")`
-        );
-      }
-      // Resolve against the sandbox, then confirm the result is still inside it.
-      const resolved = path.resolve(sandboxRoot, requested);
-      const rel = path.relative(sandboxRoot, resolved);
-      // rel starting with ".." (or an absolute path on a different drive) means escape.
-      if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-        throw new Error(
-          `readFileSandboxed: path escapes sandbox root ("${requested}")`
-        );
-      }
-      return fs.readFileSync(resolved, 'utf8');
-    },
-  });
-
-  return registry;
-}
-
-module.exports = { ToolRegistry, makeDemoRegistry };