toolfunnel 0.7.0 → 0.8.0

package/tools/scripts/tf-wrap.js

@@ -1,103 +1,103 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * tf-wrap.js - gateway-run MANAGEMENT tool: set, clear, or report the PASSTHROUGH wrap.
- *
- * Wrapping turns the gateway into a transparent wrapper for ONE attached upstream MCP: its
- * tools become the ENTIRE advertised surface (under their ORIGINAL names), the meta-tools and
- * every other tool are hidden and uncallable, and every call still fires the PreToolUse gate.
- * Because the gateway answers both MCP eras, this is how a legacy-only (or unmaintained) MCP
- * keeps working with 2026-07-28-era clients.
- *
- * ⚠ SELF-LOCKOUT: the wrap hides ALL ToolFunnel tools - INCLUDING tf_wrap itself. The AI that
- * sets a wrap loses in-band access to undo it. That is why `confirm: true` is REQUIRED to set
- * one. Undo paths that survive the wrap: the config web UI (--ui), or `toolfunnel wrap --off`
- * on a terminal. A running host picks either up live.
- *
- * Contract with the register (`defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if absent).
- *     Shape: {} (status) | { off:true } (clear) | { upstream:'<id>', confirm:true } (set).
- *   - Prints EXACTLY ONE JSON line to stdout and exits 0 - ALWAYS. A logical failure is
- *     reported as { ok:false, error }.
- *
- * Output (stdout), exactly one JSON object:
- *   status: { ok:true, wrapping:(id|null), upstreams:[id...] }
- *   clear:  { ok:true, cleared:true, was:(id|null) }
- *   set:    { ok:true, wrapping:id, warning:'...' }
- *   failure:{ ok:false, error }
- */
-
-const path = require('node:path');
-const { HOME, srcRequire } = require('./tf-env');
-const { loadExposeStore } = srcRequire('mcp/expose-store');
-const { loadToolState, getPassthrough, setPassthrough } = srcRequire('tools/tool-state');
-
-const STATE_PATH = path.join(HOME, 'tools', 'tools.state.json');
-const EXPOSE_PATH = path.join(HOME, 'mcp', 'expose.json');
-
-const LOCKOUT_WARNING =
-  'The wrap hides ALL ToolFunnel tools - including tf_wrap itself. In-band undo is now ' +
-  'impossible for you: recover via the config web UI (--ui) or `toolfunnel wrap --off` on a terminal.';
-
-function parseArgs() {
-  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
-  if (raw === undefined || raw === null || raw === '') return {};
-  const parsed = JSON.parse(raw);
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error('TOOLFUNNEL_TOOL_ARGS must be a JSON object');
-  }
-  return parsed;
-}
-
-function run() {
-  const args = parseArgs();
-
-  if (args.off === true) {
-    const was = getPassthrough(loadToolState(STATE_PATH));
-    setPassthrough(STATE_PATH, null);
-    return { ok: true, cleared: true, was };
-  }
-
-  const store = loadExposeStore(EXPOSE_PATH);
-  const ids = store.listUpstreams().map((u) => u.id);
-
-  if (args.upstream === undefined) {
-    return { ok: true, wrapping: getPassthrough(loadToolState(STATE_PATH)), upstreams: ids };
-  }
-
-  const id = args.upstream;
-  if (typeof id !== 'string' || id.length === 0) {
-    throw new Error('args.upstream must be a non-empty string (an attached upstream id)');
-  }
-  const upstream = store.getUpstream(id);
-  if (!upstream) {
-    throw new Error(`no upstream with id "${id}" - attached: ${ids.join(', ') || '(none)'}`);
-  }
-  if (upstream.enabled === false) {
-    throw new Error(`upstream "${id}" is disabled in mcp/expose.json - enable it first (tf_mcp_set)`);
-  }
-  if (args.confirm !== true) {
-    throw new Error(
-      'confirm:true is required. ' + LOCKOUT_WARNING +
-      ' Call again with { "upstream": "' + id + '", "confirm": true } to proceed.'
-    );
-  }
-
-  setPassthrough(STATE_PATH, id);
-  return { ok: true, wrapping: id, warning: LOCKOUT_WARNING };
-}
-
-function main() {
-  let payload;
-  try {
-    payload = run();
-  } catch (err) {
-    payload = { ok: false, error: (err && err.message) || String(err) };
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-wrap.js - gateway-run MANAGEMENT tool: set, clear, or report the PASSTHROUGH wrap.
+ *
+ * Wrapping turns the gateway into a transparent wrapper for ONE attached upstream MCP: its
+ * tools become the ENTIRE advertised surface (under their ORIGINAL names), the meta-tools and
+ * every other tool are hidden and uncallable, and every call still fires the PreToolUse gate.
+ * Because the gateway answers both MCP eras, this is how a legacy-only (or unmaintained) MCP
+ * keeps working with 2026-07-28-era clients.
+ *
+ * ⚠ SELF-LOCKOUT: the wrap hides ALL ToolFunnel tools - INCLUDING tf_wrap itself. The AI that
+ * sets a wrap loses in-band access to undo it. That is why `confirm: true` is REQUIRED to set
+ * one. Undo paths that survive the wrap: the config web UI (--ui), or `toolfunnel wrap --off`
+ * on a terminal. A running host picks either up live.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if absent).
+ *     Shape: {} (status) | { off:true } (clear) | { upstream:'<id>', confirm:true } (set).
+ *   - Prints EXACTLY ONE JSON line to stdout and exits 0 - ALWAYS. A logical failure is
+ *     reported as { ok:false, error }.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   status: { ok:true, wrapping:(id|null), upstreams:[id...] }
+ *   clear:  { ok:true, cleared:true, was:(id|null) }
+ *   set:    { ok:true, wrapping:id, warning:'...' }
+ *   failure:{ ok:false, error }
+ */
+
+const path = require('node:path');
+const { HOME, srcRequire } = require('./tf-env');
+const { loadExposeStore } = srcRequire('mcp/expose-store');
+const { loadToolState, getPassthrough, setPassthrough } = srcRequire('tools/tool-state');
+
+const STATE_PATH = path.join(HOME, 'tools', 'tools.state.json');
+const EXPOSE_PATH = path.join(HOME, 'mcp', 'expose.json');
+
+const LOCKOUT_WARNING =
+  'The wrap hides ALL ToolFunnel tools - including tf_wrap itself. In-band undo is now ' +
+  'impossible for you: recover via the config web UI (--ui) or `toolfunnel wrap --off` on a terminal.';
+
+function parseArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') return {};
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('TOOLFUNNEL_TOOL_ARGS must be a JSON object');
+  }
+  return parsed;
+}
+
+function run() {
+  const args = parseArgs();
+
+  if (args.off === true) {
+    const was = getPassthrough(loadToolState(STATE_PATH));
+    setPassthrough(STATE_PATH, null);
+    return { ok: true, cleared: true, was };
+  }
+
+  const store = loadExposeStore(EXPOSE_PATH);
+  const ids = store.listUpstreams().map((u) => u.id);
+
+  if (args.upstream === undefined) {
+    return { ok: true, wrapping: getPassthrough(loadToolState(STATE_PATH)), upstreams: ids };
+  }
+
+  const id = args.upstream;
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error('args.upstream must be a non-empty string (an attached upstream id)');
+  }
+  const upstream = store.getUpstream(id);
+  if (!upstream) {
+    throw new Error(`no upstream with id "${id}" - attached: ${ids.join(', ') || '(none)'}`);
+  }
+  if (upstream.enabled === false) {
+    throw new Error(`upstream "${id}" is disabled in mcp/expose.json - enable it first (tf_mcp_set)`);
+  }
+  if (args.confirm !== true) {
+    throw new Error(
+      'confirm:true is required. ' + LOCKOUT_WARNING +
+      ' Call again with { "upstream": "' + id + '", "confirm": true } to proceed.'
+    );
+  }
+
+  setPassthrough(STATE_PATH, id);
+  return { ok: true, wrapping: id, warning: LOCKOUT_WARNING };
+}
+
+function main() {
+  let payload;
+  try {
+    payload = run();
+  } catch (err) {
+    payload = { ok: false, error: (err && err.message) || String(err) };
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/uuid.js

@@ -1,102 +1,102 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * uuid-tool.js - a safe, dependency-free local UUID generator.
- *
- * Purpose
- * -------
- * Generate one or more RFC 4122 v4 UUIDs via the Node built-in
- * `node:crypto.randomUUID()`. Useful from the Tool Manager whenever a fresh
- * identifier is needed. No network, no filesystem, no new deps.
- *
- * Contract with the register (the register's `defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS.
- *   - Args: { count?: <integer> } - how many UUIDs to mint. Defaults to 1.
- *     count is clamped to the range [1, 100] so a runaway request cannot ask
- *     for an unbounded number.
- *   - Prints a SINGLE JSON object to stdout and exits 0 - ALWAYS exit 0, even
- *     on bad input (reported as { ok:false, error }), never a thrown exception.
- *
- * Output (stdout), exactly one JSON object:
- *   success: { ok:true,  uuids: [ "...", ... ] }
- *   failure: { ok:false, error }
- *
- * Safety invariants (mirror the isolation rule):
- *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
- *   - count is hard-capped at 100; a non-integer / out-of-range count is an
- *     error rather than a silent surprise.
- *   - NEVER throws for ordinary bad input - only well-shaped JSON on stdout.
- */
-
-const crypto = require('node:crypto');
-
-const MAX_COUNT = 100;
-
-/**
- * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS.
- * @returns {{ value: any } | { parseError: string }}
- */
-function parseStructuredArgs() {
-  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
-  if (raw === undefined || raw === null || raw === '') {
-    return { value: null };
-  }
-  try {
-    return { value: JSON.parse(raw) };
-  } catch (_err) {
-    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
-  }
-}
-
-/**
- * Pure core: given the parsed args, produce the result object. Never throws.
- *
- * @param {any} args  may be null (treated as { count: 1 })
- * @returns {object} the JSON-serialisable result
- */
-function run(args) {
-  // No args (or null) is valid - default to a single UUID.
-  let count = 1;
-  if (args !== null && args !== undefined) {
-    if (typeof args !== 'object' || Array.isArray(args)) {
-      return { ok: false, error: 'args must be an object { count? }' };
-    }
-    if (args.count !== undefined && args.count !== null) {
-      if (typeof args.count !== 'number' || !Number.isInteger(args.count)) {
-        return { ok: false, error: 'count must be an integer' };
-      }
-      if (args.count < 1) {
-        return { ok: false, error: 'count must be >= 1' };
-      }
-      if (args.count > MAX_COUNT) {
-        return { ok: false, error: `count must be <= ${MAX_COUNT}` };
-      }
-      count = args.count;
-    }
-  }
-  const uuids = [];
-  for (let i = 0; i < count; i += 1) {
-    uuids.push(crypto.randomUUID());
-  }
-  return { ok: true, uuids };
-}
-
-function main() {
-  const parsed = parseStructuredArgs();
-  let payload;
-  if (parsed.parseError) {
-    payload = { ok: false, error: parsed.parseError };
-  } else {
-    try {
-      payload = run(parsed.value);
-    } catch (err) {
-      payload = { ok: false, error: `unexpected error: ${(err && err.message) || String(err)}` };
-    }
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * uuid-tool.js - a safe, dependency-free local UUID generator.
+ *
+ * Purpose
+ * -------
+ * Generate one or more RFC 4122 v4 UUIDs via the Node built-in
+ * `node:crypto.randomUUID()`. Useful from the Tool Manager whenever a fresh
+ * identifier is needed. No network, no filesystem, no new deps.
+ *
+ * Contract with the register (the register's `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS.
+ *   - Args: { count?: <integer> } - how many UUIDs to mint. Defaults to 1.
+ *     count is clamped to the range [1, 100] so a runaway request cannot ask
+ *     for an unbounded number.
+ *   - Prints a SINGLE JSON object to stdout and exits 0 - ALWAYS exit 0, even
+ *     on bad input (reported as { ok:false, error }), never a thrown exception.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true,  uuids: [ "...", ... ] }
+ *   failure: { ok:false, error }
+ *
+ * Safety invariants (mirror the isolation rule):
+ *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
+ *   - count is hard-capped at 100; a non-integer / out-of-range count is an
+ *     error rather than a silent surprise.
+ *   - NEVER throws for ordinary bad input - only well-shaped JSON on stdout.
+ */
+
+const crypto = require('node:crypto');
+
+const MAX_COUNT = 100;
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS.
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: null };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Pure core: given the parsed args, produce the result object. Never throws.
+ *
+ * @param {any} args  may be null (treated as { count: 1 })
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  // No args (or null) is valid - default to a single UUID.
+  let count = 1;
+  if (args !== null && args !== undefined) {
+    if (typeof args !== 'object' || Array.isArray(args)) {
+      return { ok: false, error: 'args must be an object { count? }' };
+    }
+    if (args.count !== undefined && args.count !== null) {
+      if (typeof args.count !== 'number' || !Number.isInteger(args.count)) {
+        return { ok: false, error: 'count must be an integer' };
+      }
+      if (args.count < 1) {
+        return { ok: false, error: 'count must be >= 1' };
+      }
+      if (args.count > MAX_COUNT) {
+        return { ok: false, error: `count must be <= ${MAX_COUNT}` };
+      }
+      count = args.count;
+    }
+  }
+  const uuids = [];
+  for (let i = 0; i < count; i += 1) {
+    uuids.push(crypto.randomUUID());
+  }
+  return { ok: true, uuids };
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } catch (err) {
+      payload = { ok: false, error: `unexpected error: ${(err && err.message) || String(err)}` };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/tools.register.json

@@ -27,7 +27,7 @@
     {
       "id": "hash",
       "name": "Hash",
-      "summary": "Compute a cryptographic digest (e.g. sha256) of input text.",
+      "summary": "Compute a sha256, sha1 or md5 digest 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": {
@@ -82,7 +82,7 @@
     {
       "id": "tf_tool_add",
       "name": "tf_tool_add",
-      "summary": "Register a new tool entry in the gateway tool register.",
+      "summary": "Register a new tool (a script or a shell command) 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": {
@@ -93,7 +93,7 @@
     {
       "id": "tf_tool_set",
       "name": "tf_tool_set",
-      "summary": "Activate, deactivate, promote (hot), hide, or remove a register tool.",
+      "summary": "Enable, disable, 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": {
@@ -123,10 +123,21 @@
         "path": "scripts/tf-mcp-set.js"
       }
     },
+    {
+      "id": "tf_accept_change",
+      "name": "tf_accept_change",
+      "summary": "Accept a tool description change ToolFunnel is holding back - ask the user first.",
+      "category": "management",
+      "instructions": "Args: { upstream, tool, hash }, all required - copy them from the refusal. When an upstream's tool changes its description or schema while the server version stays the same, ToolFunnel keeps serving the approved version and refuses calls to it, naming which fields changed; the user reviews the new text with `toolfunnel changes` or in the UI. ASK THE USER before running this. Only the version the user saw is accepted; to accept several changes at once the user runs `toolfunnel accept <upstream>` or uses the UI. Takes effect from the next call.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-accept-change.js"
+      }
+    },
     {
       "id": "tf_wrap",
       "name": "tf_wrap",
-      "summary": "Wrap ONE attached upstream MCP: its tools become the entire surface (transparent passthrough).",
+      "summary": "Wrap ONE attached upstream MCP: its tools become the entire surface (transparent passthrough). Also reports or clears the wrap.",
       "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": {
@@ -170,7 +181,7 @@
     {
       "id": "tf_log",
       "name": "tf_log",
-      "summary": "Enable, disable, or check the gateway activity/audit log.",
+      "summary": "Enable, disable, or check the status of 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": {