toolfunnel 0.5.0 → 0.6.0

package/tools/scripts/tf-tool-add.js

@@ -1,129 +1,134 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * tf-tool-add.js — a first-party MANAGEMENT tool that ADDS a register entry.
- *
- * Purpose
- * -------
- * The write-side counterpart to the read-only status / inventory tools: it lets
- * the manager surface a NEW tool in the register at runtime (no reconnect — the
- * running gateway watches tools.register.json and hot-reloads its register on
- * change). Optionally it also writes the host-local script the new entry invokes,
- * so a single call can create both the register entry AND its backing script
- * atomically.
- *
- * This is a "gateway-run" tool: it mutates ToolFunnel's OWN config (the register
- * and, optionally, a script under the scripts root). It runs through the same
- * register -> resolveExecution -> gated run path as any other script tool, so
- * the PreToolUse gate still applies to invoking it.
- *
- * Contract with the register (registry.js `defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} / absent => null).
- *   - Args: { id, name, summary?, category?, instructions?, inputSchema?,
- *             invoke: { type:'script'|'shell', path?|command? },
- *             scriptText? }
- *       inputSchema (a JSON Schema object) is what a HOT-promoted tool advertises verbatim in
- *       the top-level tools/list — dropping it here was the gap between "your own tools" and
- *       "your own tools AND schemas".
- *       When scriptText is a string AND invoke.type === 'script', the script is
- *       written first (registry.writeScript), THEN the entry is added.
- *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even on
- *     a logical error (reported as { ok:false, error }), never a thrown exception.
- *
- * Output (stdout), exactly one JSON object:
- *   success: { ok:true, ...<the added register entry>, scriptPath?: "<abs path>" }
- *   failure: { ok:false, error }
- *
- * Safety invariants:
- *   - Touches ONLY files inside the toolfunnel root, resolved from THIS script's
- *     own location (__dirname) — never a caller-supplied absolute path. The
- *     register's writeScript guards path-escape (basename + inside-root check).
- *   - NO network. Writes are atomic (temp + fsync + rename) via the register module.
- *   - NEVER throws for ordinary bad input — only well-shaped JSON on stdout.
- */
-
-const path = require('node:path');
-// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
-const { HOME, srcRequire } = require('./tf-env');
-const { loadRegistry } = srcRequire('tools/registry');
-
-const ROOT = HOME;
-const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
-const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
-
-/**
- * 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, add the register entry (and optionally write
- * its backing script first). Throws are caught by main() and surfaced as
- * { ok:false, error }; loadRegistry / writeScript / add all throw on bad shape.
- *
- * @param {any} args
- * @returns {object} the JSON-serialisable result
- */
-function run(args) {
-  if (!args || typeof args !== 'object' || Array.isArray(args)) {
-    return {
-      ok: false,
-      error: 'args must be an object { id, name, summary?, category?, instructions?, inputSchema?, invoke, scriptText? }',
-    };
-  }
-  const { id, name, summary, category, instructions, inputSchema, invoke, scriptText } = args;
-
-  // Build a clean register entry (only carry through the optional fields when
-  // present so the persisted entry stays tidy). registry.add validates shape.
-  const entry = { id, name, invoke };
-  if (summary !== undefined) entry.summary = summary;
-  if (category !== undefined) entry.category = category;
-  if (instructions !== undefined) entry.instructions = instructions;
-  if (inputSchema !== undefined) entry.inputSchema = inputSchema; // validated by registry.add
-
-
-  const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
-
-  // When a script body is supplied for a script invoke, write it FIRST so the
-  // entry never references a missing file once add() succeeds.
-  let scriptPath;
-  if (typeof scriptText === 'string' && invoke && invoke.type === 'script') {
-    scriptPath = registry.writeScript(invoke.path, scriptText);
-  }
-
-  const added = registry.add(entry);
-  const result = { ok: true, ...added };
-  if (scriptPath) result.scriptPath = scriptPath;
-  return result;
-}
-
-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: (err && err.message) || String(err) };
-    }
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-tool-add.js - a first-party MANAGEMENT tool that ADDS a register entry.
+ *
+ * Purpose
+ * -------
+ * The write-side counterpart to the read-only status / inventory tools: it lets
+ * the manager surface a NEW tool in the register at runtime (no reconnect - the
+ * running gateway watches tools.register.json and hot-reloads its register on
+ * change). Optionally it also writes the host-local script the new entry invokes,
+ * so a single call can create both the register entry AND its backing script
+ * atomically.
+ *
+ * This is a "gateway-run" tool: it mutates ToolFunnel's OWN config (the register
+ * and, optionally, a script under the scripts root). It runs through the same
+ * register -> resolveExecution -> gated run path as any other script tool, so
+ * the PreToolUse gate still applies to invoking it.
+ *
+ * Contract with the register (registry.js `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} / absent => null).
+ *   - Args: { id, name, summary?, category?, instructions?, inputSchema?,
+ *             invoke: { type:'script'|'shell', path?|command? },
+ *             scriptText? }
+ *       inputSchema (a JSON Schema object) is what a HOT-promoted tool advertises verbatim in
+ *       the top-level tools/list - dropping it here was the gap between "your own tools" and
+ *       "your own tools AND schemas".
+ *       When scriptText is a string AND invoke.type === 'script', the script is
+ *       written first (registry.writeScript), THEN the entry is added.
+ *   - Prints a SINGLE JSON object to stdout and exits 0 - ALWAYS exit 0, even on
+ *     a logical error (reported as { ok:false, error }), never a thrown exception.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true, ...<the added register entry>, scriptPath?: "<abs path>" }
+ *   failure: { ok:false, error }
+ *
+ * Safety invariants:
+ *   - Touches ONLY files inside the toolfunnel root, resolved from THIS script's
+ *     own location (__dirname) - never a caller-supplied absolute path. The
+ *     register's writeScript guards path-escape (basename + inside-root check).
+ *   - NO network. Writes are atomic (temp + fsync + rename) via the register module.
+ *   - NEVER throws for ordinary bad input - only well-shaped JSON on stdout.
+ */
+
+const path = require('node:path');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadRegistry } = srcRequire('tools/registry');
+
+const ROOT = HOME;
+const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
+const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
+
+/**
+ * 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, add the register entry (and optionally write
+ * its backing script first). Throws are caught by main() and surfaced as
+ * { ok:false, error }; loadRegistry / writeScript / add all throw on bad shape.
+ *
+ * @param {any} args
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return {
+      ok: false,
+      error: 'args must be an object { id, name, summary?, category?, instructions?, inputSchema?, mode?, invoke?, scriptText? }',
+    };
+  }
+  const { id, name, summary, category, instructions, inputSchema, mode, invoke, scriptText } = args;
+
+  // Build a clean register entry (only carry through the optional fields when
+  // present so the persisted entry stays tidy). registry.add validates shape.
+  // `mode` MUST ride along: a reference-mode tool has NO invoke at all, and dropping the field
+  // here made the agent path reject every reference tool with "entry.invoke is required" while
+  // the UI path accepted them.
+  const entry = { id, name };
+  if (invoke !== undefined) entry.invoke = invoke;
+  if (mode !== undefined) entry.mode = mode;
+  if (summary !== undefined) entry.summary = summary;
+  if (category !== undefined) entry.category = category;
+  if (instructions !== undefined) entry.instructions = instructions;
+  if (inputSchema !== undefined) entry.inputSchema = inputSchema; // validated by registry.add
+
+
+  const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
+
+  // When a script body is supplied for a script invoke, write it FIRST so the
+  // entry never references a missing file once add() succeeds.
+  let scriptPath;
+  if (typeof scriptText === 'string' && invoke && invoke.type === 'script') {
+    scriptPath = registry.writeScript(invoke.path, scriptText);
+  }
+
+  const added = registry.add(entry);
+  const result = { ok: true, ...added };
+  if (scriptPath) result.scriptPath = scriptPath;
+  return result;
+}
+
+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: (err && err.message) || String(err) };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-tool-set.js

@@ -1,142 +1,142 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * tf-tool-set.js — a first-party MANAGEMENT tool that toggles or removes a tool.
- *
- * Purpose
- * -------
- * The state-side counterpart to tf-tool-add: it flips a tool's ACTIVE/DISABLED
- * overlay flag (enable / disable) or fully removes a tool (drops the register
- * entry AND clears its state overlay). Register/state edits are visible to the
- * meta-tools on the next call — no reconnect.
- *
- * This is a "gateway-run" tool: it mutates ToolFunnel's OWN config (the per-tool
- * state overlay, and for `remove`, the register too). It runs through the same
- * gated run path as any other script tool.
- *
- * Contract with the register (registry.js `defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} / absent => null).
- *   - Args: { id, action: 'enable' | 'disable' | 'hot' | 'unhot' | 'hide' | 'unhide' | 'remove' }.
- *       enable/disable -> setToolEnabled(state, id, bool)  (overlay merge; preserves hidden/hot)
- *       hot/unhot      -> setToolHot(state, id, bool)      (overlay merge; preserves enabled/hidden)
- *                         — promote/demote the tool on the TOP-LEVEL every-turn surface (the matrix).
- *       hide/unhide    -> setToolHidden(state, id, bool)   (overlay merge; preserves enabled/hot)
- *                         — declutter the MANAGER views only (tf_list + the UI); does NOT change
- *                           what the connected AI sees (the lean list / top-level surface).
- *       remove         -> registry.remove(id) AND clearToolState(state, id)
- *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even on
- *     a logical error (reported as { ok:false, error }), never a thrown exception.
- *
- * Output (stdout), exactly one JSON object:
- *   enable/disable: { ok:true, id, action, enabled, state }
- *   hot/unhot:      { ok:true, id, action, hot, state }
- *   hide/unhide:    { ok:true, id, action, hidden, state }
- *   remove:         { ok:true, id, action, removed:true, state }
- *   failure:        { ok:false, error }
- *   (`state` is the resulting overlay map after the operation.)
- *
- * Safety invariants:
- *   - Touches ONLY config files inside the toolfunnel root, resolved from THIS
- *     script's own location (__dirname) — never a caller-supplied path.
- *   - NO network. Writes are atomic (temp + fsync + rename) via the store modules.
- *   - NEVER throws for ordinary bad input — only well-shaped JSON on stdout.
- */
-
-const path = require('node:path');
-// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
-const { HOME, srcRequire } = require('./tf-env');
-const { loadRegistry } = srcRequire('tools/registry');
-const { setToolEnabled, setToolHot, setToolHidden, clearToolState } = srcRequire('tools/tool-state');
-
-const ROOT = HOME;
-const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
-const STATE_PATH = path.join(ROOT, 'tools', 'tools.state.json');
-const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
-
-/**
- * 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, perform the requested state/register change.
- * Throws are caught by main() and surfaced as { ok:false, error }; registry.remove
- * throws on an unknown id, setToolEnabled/clearToolState throw on a bad id.
- *
- * @param {any} args
- * @returns {object} the JSON-serialisable result
- */
-function run(args) {
-  if (!args || typeof args !== 'object' || Array.isArray(args)) {
-    return { ok: false, error: "args must be an object { id, action: 'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove' }" };
-  }
-  const { id, action } = args;
-  if (typeof id !== 'string' || id.length === 0) {
-    return { ok: false, error: 'id must be a non-empty string' };
-  }
-
-  if (action === 'enable' || action === 'disable') {
-    const enabled = action === 'enable';
-    const state = setToolEnabled(STATE_PATH, id, enabled);
-    return { ok: true, id, action, enabled, state };
-  }
-
-  if (action === 'hot' || action === 'unhot') {
-    // Promote (hot) / demote (unhot) the tool on the TOP-LEVEL every-turn surface. Keyed by the
-    // surfaced name (a local id, an upstream surfaced name, or a meta-tool name) — the same key the
-    // server's matrix assembler reads. The id is NOT verified against the register here: an upstream
-    // surfaced name or a meta-tool name is a legitimate key with no register entry.
-    const hot = action === 'hot';
-    const state = setToolHot(STATE_PATH, id, hot);
-    return { ok: true, id, action, hot, state };
-  }
-
-  if (action === 'hide' || action === 'unhide') {
-    // Declutter the MANAGER views (tf_list + the UI) only — hide/unhide does NOT change the lean list
-    // or the top-level surface the connected AI sees. Same id-not-verified policy as hot/unhot.
-    const hidden = action === 'hide';
-    const state = setToolHidden(STATE_PATH, id, hidden);
-    return { ok: true, id, action, hidden, state };
-  }
-
-  if (action === 'remove') {
-    // Drop the register entry first (throws on unknown id), then clear any overlay.
-    const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
-    registry.remove(id);
-    const state = clearToolState(STATE_PATH, id);
-    return { ok: true, id, action, removed: true, state };
-  }
-
-  return { ok: false, error: "action must be one of 'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove'" };
-}
-
-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: (err && err.message) || String(err) };
-    }
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-tool-set.js - a first-party MANAGEMENT tool that toggles or removes a tool.
+ *
+ * Purpose
+ * -------
+ * The state-side counterpart to tf-tool-add: it flips a tool's ACTIVE/DISABLED
+ * overlay flag (enable / disable) or fully removes a tool (drops the register
+ * entry AND clears its state overlay). Register/state edits are visible to the
+ * meta-tools on the next call - no reconnect.
+ *
+ * This is a "gateway-run" tool: it mutates ToolFunnel's OWN config (the per-tool
+ * state overlay, and for `remove`, the register too). It runs through the same
+ * gated run path as any other script tool.
+ *
+ * Contract with the register (registry.js `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} / absent => null).
+ *   - Args: { id, action: 'enable' | 'disable' | 'hot' | 'unhot' | 'hide' | 'unhide' | 'remove' }.
+ *       enable/disable -> setToolEnabled(state, id, bool)  (overlay merge; preserves hidden/hot)
+ *       hot/unhot      -> setToolHot(state, id, bool)      (overlay merge; preserves enabled/hidden)
+ *                         - promote/demote the tool on the TOP-LEVEL every-turn surface (the matrix).
+ *       hide/unhide    -> setToolHidden(state, id, bool)   (overlay merge; preserves enabled/hot)
+ *                         - declutter the MANAGER views only (tf_list + the UI); does NOT change
+ *                           what the connected AI sees (the lean list / top-level surface).
+ *       remove         -> registry.remove(id) AND clearToolState(state, id)
+ *   - Prints a SINGLE JSON object to stdout and exits 0 - ALWAYS exit 0, even on
+ *     a logical error (reported as { ok:false, error }), never a thrown exception.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   enable/disable: { ok:true, id, action, enabled, state }
+ *   hot/unhot:      { ok:true, id, action, hot, state }
+ *   hide/unhide:    { ok:true, id, action, hidden, state }
+ *   remove:         { ok:true, id, action, removed:true, state }
+ *   failure:        { ok:false, error }
+ *   (`state` is the resulting overlay map after the operation.)
+ *
+ * Safety invariants:
+ *   - Touches ONLY config files inside the toolfunnel root, resolved from THIS
+ *     script's own location (__dirname) - never a caller-supplied path.
+ *   - NO network. Writes are atomic (temp + fsync + rename) via the store modules.
+ *   - NEVER throws for ordinary bad input - only well-shaped JSON on stdout.
+ */
+
+const path = require('node:path');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadRegistry } = srcRequire('tools/registry');
+const { setToolEnabled, setToolHot, setToolHidden, clearToolState } = srcRequire('tools/tool-state');
+
+const ROOT = HOME;
+const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
+const STATE_PATH = path.join(ROOT, 'tools', 'tools.state.json');
+const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
+
+/**
+ * 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, perform the requested state/register change.
+ * Throws are caught by main() and surfaced as { ok:false, error }; registry.remove
+ * throws on an unknown id, setToolEnabled/clearToolState throw on a bad id.
+ *
+ * @param {any} args
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, error: "args must be an object { id, action: 'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove' }" };
+  }
+  const { id, action } = args;
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, error: 'id must be a non-empty string' };
+  }
+
+  if (action === 'enable' || action === 'disable') {
+    const enabled = action === 'enable';
+    const state = setToolEnabled(STATE_PATH, id, enabled);
+    return { ok: true, id, action, enabled, state };
+  }
+
+  if (action === 'hot' || action === 'unhot') {
+    // Promote (hot) / demote (unhot) the tool on the TOP-LEVEL every-turn surface. Keyed by the
+    // surfaced name (a local id, an upstream surfaced name, or a meta-tool name) - the same key the
+    // server's matrix assembler reads. The id is NOT verified against the register here: an upstream
+    // surfaced name or a meta-tool name is a legitimate key with no register entry.
+    const hot = action === 'hot';
+    const state = setToolHot(STATE_PATH, id, hot);
+    return { ok: true, id, action, hot, state };
+  }
+
+  if (action === 'hide' || action === 'unhide') {
+    // Declutter the MANAGER views (tf_list + the UI) only - hide/unhide does NOT change the lean list
+    // or the top-level surface the connected AI sees. Same id-not-verified policy as hot/unhot.
+    const hidden = action === 'hide';
+    const state = setToolHidden(STATE_PATH, id, hidden);
+    return { ok: true, id, action, hidden, state };
+  }
+
+  if (action === 'remove') {
+    // Drop the register entry first (throws on unknown id), then clear any overlay.
+    const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
+    registry.remove(id);
+    const state = clearToolState(STATE_PATH, id);
+    return { ok: true, id, action, removed: true, state };
+  }
+
+  return { ok: false, error: "action must be one of 'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove'" };
+}
+
+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: (err && err.message) || String(err) };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-wrap.js

@@ -0,0 +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();