toolfunnel 0.5.0 → 0.6.0

package/tools/tools.register.json

@@ -1,216 +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_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"
+      }
+    }
+  ]
+}