toolfunnel 0.7.0 → 0.8.0

package/tools/scripts/text-stats.js

@@ -1,131 +1,131 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * text-stats.js - a safe, dependency-free local text-statistics tool.
- *
- * Purpose
- * -------
- * Count characters, words, lines, and UTF-8 bytes for a string. A handy
- * Tool-Manager utility for sizing prompts, snippets, and payloads. Pure
- * string work - 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: { text: <string> }.
- *   - 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, chars, words, lines, bytes }
- *   failure: { ok:false, error }
- *
- * Counting conventions (documented so callers know exactly what they get):
- *   - chars : JS string length (UTF-16 code units - the same number `"".length`
- *             reports). Documented as such; for ASCII text it equals the visible
- *             character count.
- *   - words : maximal runs of non-whitespace separated by whitespace. The empty
- *             / all-whitespace string has 0 words.
- *   - lines : number of lines. The empty string is 0 lines; otherwise it is the
- *             count of newline-separated segments (a trailing newline does NOT
- *             add a phantom empty final line - `"a\n"` is 1 line, `"a\nb"` is 2).
- *   - bytes : UTF-8 byte length (Buffer.byteLength), the on-the-wire size.
- *
- * Safety invariants (mirror the isolation rule):
- *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
- *   - NEVER throws for ordinary bad input - only well-shaped JSON on stdout.
- */
-
-/**
- * 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)}` };
-  }
-}
-
-/**
- * Count lines per the documented convention: 0 for the empty string, else the
- * number of newline-separated segments WITHOUT counting a phantom trailing
- * empty line. We normalise CRLF/CR to LF first so line counts match what a user
- * sees regardless of the platform that produced the text.
- *
- * @param {string} text
- * @returns {number}
- */
-function countLines(text) {
-  if (text.length === 0) return 0;
-  const normalised = text.replace(/\r\n?/g, '\n');
-  // Trailing newline should not add an empty line: trim a single trailing '\n'
-  // before splitting, then add 1 for the final (now-unterminated) line.
-  const trimmed = normalised.endsWith('\n') ? normalised.slice(0, -1) : normalised;
-  // Each '\n' in `trimmed` separates two lines -> lines = (#newlines) + 1.
-  let newlines = 0;
-  for (let i = 0; i < trimmed.length; i += 1) {
-    if (trimmed.charCodeAt(i) === 10) newlines += 1;
-  }
-  return newlines + 1;
-}
-
-/**
- * Count words: maximal non-whitespace runs. Empty / whitespace-only -> 0.
- *
- * @param {string} text
- * @returns {number}
- */
-function countWords(text) {
-  const trimmed = text.trim();
-  if (trimmed.length === 0) return 0;
-  // Split on any whitespace run; the trim above guarantees no empty edge tokens.
-  return trimmed.split(/\s+/).length;
-}
-
-/**
- * Pure core: given the parsed args, produce the result object. Never throws.
- *
- * @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 { text }' };
-  }
-  const { text } = args;
-  if (typeof text !== 'string') {
-    return { ok: false, error: 'text must be a string' };
-  }
-  return {
-    ok: true,
-    chars: text.length,
-    words: countWords(text),
-    lines: countLines(text),
-    bytes: Buffer.byteLength(text, 'utf8'),
-  };
-}
-
-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';
+
+/**
+ * text-stats.js - a safe, dependency-free local text-statistics tool.
+ *
+ * Purpose
+ * -------
+ * Count characters, words, lines, and UTF-8 bytes for a string. A handy
+ * Tool-Manager utility for sizing prompts, snippets, and payloads. Pure
+ * string work - 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: { text: <string> }.
+ *   - 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, chars, words, lines, bytes }
+ *   failure: { ok:false, error }
+ *
+ * Counting conventions (documented so callers know exactly what they get):
+ *   - chars : JS string length (UTF-16 code units - the same number `"".length`
+ *             reports). Documented as such; for ASCII text it equals the visible
+ *             character count.
+ *   - words : maximal runs of non-whitespace separated by whitespace. The empty
+ *             / all-whitespace string has 0 words.
+ *   - lines : number of lines. The empty string is 0 lines; otherwise it is the
+ *             count of newline-separated segments (a trailing newline does NOT
+ *             add a phantom empty final line - `"a\n"` is 1 line, `"a\nb"` is 2).
+ *   - bytes : UTF-8 byte length (Buffer.byteLength), the on-the-wire size.
+ *
+ * Safety invariants (mirror the isolation rule):
+ *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
+ *   - NEVER throws for ordinary bad input - only well-shaped JSON on stdout.
+ */
+
+/**
+ * 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)}` };
+  }
+}
+
+/**
+ * Count lines per the documented convention: 0 for the empty string, else the
+ * number of newline-separated segments WITHOUT counting a phantom trailing
+ * empty line. We normalise CRLF/CR to LF first so line counts match what a user
+ * sees regardless of the platform that produced the text.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countLines(text) {
+  if (text.length === 0) return 0;
+  const normalised = text.replace(/\r\n?/g, '\n');
+  // Trailing newline should not add an empty line: trim a single trailing '\n'
+  // before splitting, then add 1 for the final (now-unterminated) line.
+  const trimmed = normalised.endsWith('\n') ? normalised.slice(0, -1) : normalised;
+  // Each '\n' in `trimmed` separates two lines -> lines = (#newlines) + 1.
+  let newlines = 0;
+  for (let i = 0; i < trimmed.length; i += 1) {
+    if (trimmed.charCodeAt(i) === 10) newlines += 1;
+  }
+  return newlines + 1;
+}
+
+/**
+ * Count words: maximal non-whitespace runs. Empty / whitespace-only -> 0.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countWords(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return 0;
+  // Split on any whitespace run; the trim above guarantees no empty edge tokens.
+  return trimmed.split(/\s+/).length;
+}
+
+/**
+ * Pure core: given the parsed args, produce the result object. Never throws.
+ *
+ * @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 { text }' };
+  }
+  const { text } = args;
+  if (typeof text !== 'string') {
+    return { ok: false, error: 'text must be a string' };
+  }
+  return {
+    ok: true,
+    chars: text.length,
+    words: countWords(text),
+    lines: countLines(text),
+    bytes: Buffer.byteLength(text, 'utf8'),
+  };
+}
+
+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/scripts/tf-accept-change.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * tf-accept-change.js - the tf_accept_change management tool (tool descriptor approval).
+ *
+ * When an upstream's tool changes its description or schema while the server version stays the
+ * same, the gateway keeps serving the APPROVED descriptor and refuses calls to the tool, returning
+ * which fields changed and this tool as the way to accept (the new text itself is shown only in
+ * `toolfunnel changes` and the UI). The agent is meant to ASK THE USER
+ * first; the call is gated by PreToolUse like every register tool, and so is the in-chat accept a
+ * 2026-07-28 client gets (the gateway gates it as tf_accept_change).
+ *
+ * Contract (same as the other tf-* scripts):
+ *   - Args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS: { upstream, tool, hash }, all required:
+ *       an agent accepts exactly the change the user was shown - one tool, at the hash from the
+ *       refusal (a server that changed again is not approved sight unseen). Accepting several
+ *       at once is for the user: `toolfunnel accept <upstream>` or the UI.
+ *   - Output: ONE JSON line { ok, accepted, pending, error? }; exit 0 either way.
+ *   - The logic lives in the engine (tool-approvals.js acceptInFile), shared with the CLI, the UI
+ *     and the gateway; this script only adapts it. The running gateway applies the accept on the
+ *     next call (it re-reads the file) and its file watcher refreshes the listings.
+ */
+
+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 approvals = srcRequire('mcp/tool-approvals');
+
+const APPROVALS_PATH = path.join(HOME, 'mcp', 'tool-approvals.json');
+
+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 a = parseArgs();
+  if (typeof a.upstream !== 'string' || a.upstream.length === 0) throw new Error('"upstream" (the upstream id) is required');
+  if (typeof a.tool !== 'string' || a.tool.length === 0) throw new Error('"tool" (the changed tool\'s name, from the refusal) is required');
+  if (typeof a.hash !== 'string' || a.hash.length === 0) throw new Error('"hash" (from the refusal) is required');
+  const res = approvals.acceptInFile(APPROVALS_PATH, a.upstream, a.tool, a.hash);
+  const why = approvals.acceptFailure(res, a.upstream, a.tool);
+  if (why) {
+    return {
+      ok: false, accepted: [], pending: res.pending || [],
+      error: why + (res.stale ? '. Call the tool once more to see the current change, and ask the user again.' : ''),
+    };
+  }
+  return { ok: true, accepted: res.accepted, pending: res.pending, note: 'The running gateway applies this from the next call.' };
+}
+
+function main() {
+  let payload;
+  try {
+    payload = run();
+  } catch (err) {
+    payload = { ok: false, accepted: [], pending: [], error: (err && err.message) || String(err) };
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-env.js

@@ -1,43 +1,43 @@
-'use strict';
-
-/**
- * tf-env.js - shared HOME/ENGINE resolution for the tf-* management scripts.
- *
- * A management script runs in one of two layouts:
- *   1. The git-clone original: it lives at <pkg>/tools/scripts/, and TWO dirs up is a root that
- *      holds BOTH the config (tools/ mcp/ hooks/) and the engine code (src/).
- *   2. A copy SEEDED into an external CONFIG HOME (TOOLFUNNEL_HOME / --config-dir - see
- *      src/core/config-home.js): the config sits beside it, but the engine code does NOT.
- *      The gateway that spawned it wrote the process-tree contract into the env:
- *      TOOLFUNNEL_HOME (the resolved absolute home) + TOOLFUNNEL_PKG (the package root).
- *
- * Resolution rules:
- *   - ENGINE: prefer the LOCAL __dirname-derived root whenever it actually contains the engine
- *     (layout 1) so a stale inherited TOOLFUNNEL_PKG can never shadow a real install; else the
- *     env; else the local root anyway (the require failure is then the clearest error).
- *   - HOME:   TOOLFUNNEL_HOME when set (the gateway always sets it), else the local root.
- *
- * Same-dir require ('./tf-env') keeps this working in BOTH layouts - the seeder copies the whole
- * scripts directory, so this file always travels with its callers. Node built-ins only.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const LOCAL_ROOT = path.resolve(__dirname, '..', '..');
-const HAS_LOCAL_ENGINE = fs.existsSync(path.join(LOCAL_ROOT, 'src', 'tools', 'registry.js'));
-
-/** The package root holding the engine code (src/...). */
-const PKG = HAS_LOCAL_ENGINE ? LOCAL_ROOT : (process.env.TOOLFUNNEL_PKG || LOCAL_ROOT);
-
-/** The config home holding tools/ mcp/ hooks/ (the mutable state this script edits). */
-const HOME = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
-  ? path.resolve(process.env.TOOLFUNNEL_HOME.trim())
-  : LOCAL_ROOT;
-
-/** Require an engine module by its src-relative path, e.g. srcRequire('tools/registry'). */
-function srcRequire(rel) {
-  return require(path.join(PKG, 'src', rel));
-}
-
-module.exports = { PKG, HOME, srcRequire };
+'use strict';
+
+/**
+ * tf-env.js - shared HOME/ENGINE resolution for the tf-* management scripts.
+ *
+ * A management script runs in one of two layouts:
+ *   1. The git-clone original: it lives at <pkg>/tools/scripts/, and TWO dirs up is a root that
+ *      holds BOTH the config (tools/ mcp/ hooks/) and the engine code (src/).
+ *   2. A copy SEEDED into an external CONFIG HOME (TOOLFUNNEL_HOME / --config-dir - see
+ *      src/core/config-home.js): the config sits beside it, but the engine code does NOT.
+ *      The gateway that spawned it wrote the process-tree contract into the env:
+ *      TOOLFUNNEL_HOME (the resolved absolute home) + TOOLFUNNEL_PKG (the package root).
+ *
+ * Resolution rules:
+ *   - ENGINE: prefer the LOCAL __dirname-derived root whenever it actually contains the engine
+ *     (layout 1) so a stale inherited TOOLFUNNEL_PKG can never shadow a real install; else the
+ *     env; else the local root anyway (the require failure is then the clearest error).
+ *   - HOME:   TOOLFUNNEL_HOME when set (the gateway always sets it), else the local root.
+ *
+ * Same-dir require ('./tf-env') keeps this working in BOTH layouts - the seeder copies the whole
+ * scripts directory, so this file always travels with its callers. Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCAL_ROOT = path.resolve(__dirname, '..', '..');
+const HAS_LOCAL_ENGINE = fs.existsSync(path.join(LOCAL_ROOT, 'src', 'tools', 'registry.js'));
+
+/** The package root holding the engine code (src/...). */
+const PKG = HAS_LOCAL_ENGINE ? LOCAL_ROOT : (process.env.TOOLFUNNEL_PKG || LOCAL_ROOT);
+
+/** The config home holding tools/ mcp/ hooks/ (the mutable state this script edits). */
+const HOME = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
+  ? path.resolve(process.env.TOOLFUNNEL_HOME.trim())
+  : LOCAL_ROOT;
+
+/** Require an engine module by its src-relative path, e.g. srcRequire('tools/registry'). */
+function srcRequire(rel) {
+  return require(path.join(PKG, 'src', rel));
+}
+
+module.exports = { PKG, HOME, srcRequire };