toolfunnel 0.5.0 → 0.7.0

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

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "description": "Tool register for the gateway — built-in demo scripts.",
+  "description": "Tool register for the gateway - built-in demo scripts.",
   "tools": [
     {
       "id": "echo",
@@ -95,7 +95,7 @@
       "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).",
+      "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"
@@ -123,6 +123,17 @@
         "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",
@@ -150,7 +161,7 @@
       "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.",
+      "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"

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 };