toolfunnel 0.7.1 → 0.8.0

package/src/core/metrics.js

@@ -19,11 +19,19 @@
  * CommonJS only.
  */
 
+// Distinct byTool entries are CAPPED: the key is the tools/call name exactly as the client sent it,
+// including names that never existed, so an unbounded map let a client spraying fresh names grow
+// the gateway's memory for the life of the process. Names seen before the cap keep their own
+// counters; everything after lands in one overflow bucket. Totals stay exact either way.
+const MAX_DISTINCT_TOOLS = 1000;
+const OVERFLOW_KEY = '(other)';
+
 const state = {
   startedAt: new Date().toISOString(),
   calls: 0,
   errors: 0,
   byTool: Object.create(null), // name -> { calls, errors }
+  distinct: 0, // entries in byTool (the overflow bucket counts as one)
 };
 
 /**
@@ -38,9 +46,13 @@ function record(ev) {
     state.calls += 1;
     if (!ok) state.errors += 1;
     let t = state.byTool[tool];
-    if (!t) {
+    if (!t && state.distinct >= MAX_DISTINCT_TOOLS && tool !== OVERFLOW_KEY) {
+      t = state.byTool[OVERFLOW_KEY]; // at the cap: an unseen name counts under the overflow bucket
+      if (!t) { t = { calls: 0, errors: 0 }; state.byTool[OVERFLOW_KEY] = t; state.distinct += 1; }
+    } else if (!t) {
       t = { calls: 0, errors: 0 };
       state.byTool[tool] = t;
+      state.distinct += 1;
     }
     t.calls += 1;
     if (!ok) t.errors += 1;
@@ -55,7 +67,9 @@ function record(ev) {
  */
 function snapshot() {
   try {
-    const byTool = {};
+    // Null-prototype like the source: into a plain {} a key of "__proto__" sets the PROTOTYPE
+    // instead of a property, so that tool's counter silently vanished from /health and the UI.
+    const byTool = Object.create(null);
     for (const k of Object.keys(state.byTool)) {
       byTool[k] = { calls: state.byTool[k].calls, errors: state.byTool[k].errors };
     }
@@ -70,6 +84,7 @@ function reset() {
   state.calls = 0;
   state.errors = 0;
   state.byTool = Object.create(null);
+  state.distinct = 0;
 }
 
 module.exports = { record, snapshot, reset };

package/src/core/output-cap.js

@@ -0,0 +1,31 @@
+'use strict';
+/**
+ * output-cap.js - keep a captured stream within a byte cap.
+ *
+ * A child's output arrives in chunks (64 KiB pipe reads on Windows). Appending a whole chunk and checking the cap
+ * afterwards lets the captured text run past the cap by up to one chunk. takeWithinCap returns the part of a chunk
+ * that still fits, ending on a whole character so a multi-byte UTF-8 character is never split.
+ */
+
+/**
+ * @param {string} text  the decoded chunk
+ * @param {number} used  bytes already captured
+ * @param {number} max   the cap in bytes
+ * @returns {string} the leading part of text whose UTF-8 size fits in max - used
+ */
+function takeWithinCap(text, used, max) {
+  const room = max - used;
+  if (room <= 0) return '';
+  if (Buffer.byteLength(text, 'utf8') <= room) return text;
+  let bytes = 0;
+  let end = 0;
+  for (const ch of text) { // by code point, so a surrogate pair is never split either
+    const n = Buffer.byteLength(ch, 'utf8');
+    if (bytes + n > room) break;
+    bytes += n;
+    end += ch.length;
+  }
+  return text.slice(0, end);
+}
+
+module.exports = { takeWithinCap };

package/src/core/rename-migration.js

@@ -1,13 +1,12 @@
 'use strict';
 
 /**
- * rename-migration.js - keep gates and per-tool state attached across a SURFACED-NAME change
- * (0.7.0; the rename-safety.test.js invariants are the acceptance).
+ * rename-migration.js - keep gates and per-tool state attached across a SURFACED-NAME change.
  *
  * A tool's SURFACED name is the string the PreToolUse gate matches and the tools.state.json
- * key is written against. 0.6.0 let that name change (an expose `as` edit, an enabled flip, a
- * local display-name edit) while the gate matcher and the state key silently kept the OLD
- * string - a deny gate stopped firing and a disabled tool resurrected. The policy here,
+ * key is written against. When that name changes (an expose `as` edit, an enabled flip, a
+ * local display-name edit) and the gate matcher and the state key keep the OLD string, a deny
+ * gate stops firing and a disabled tool comes back. The policy here,
  * MATCHER-MIGRATE-ON-RENAME:
  *
  *   - A WILDCARD matcher ('', '*', unset) fires for every tool name - it already covers the
@@ -36,21 +35,9 @@ function escapeRegex(str) {
   return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-/** Copied exactly from registry.js::atomicWriteJson - crash leaves old file or new, never half. */
-function atomicWriteJson(targetPath, obj) {
-  const dir = path.dirname(targetPath);
-  const base = path.basename(targetPath);
-  const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
-  const data = JSON.stringify(obj, null, 2) + '\n';
-  const fd = fs.openSync(tmp, 'w');
-  try {
-    fs.writeSync(fd, data, 0, 'utf8');
-    fs.fsyncSync(fd);
-  } finally {
-    fs.closeSync(fd);
-  }
-  fs.renameSync(tmp, targetPath);
-}
+// THE atomic writer (temp + fsync + rename, failure-path unlink, stale sweep) - shared by every store.
+// This file's own copy had neither the unlink nor the sweep.
+const { atomicWriteJson, atomicWriteText } = require('./atomic-write');
 
 function readJsonIfPresent(p) {
   try {
@@ -160,4 +147,32 @@ function migrateForStoreFile(storeFilePath, oldName, newName, opts) {
   });
 }
 
-module.exports = { migrateSurfacedName, migrateForStoreFile, escapeRegex };
+/**
+ * The sibling config files a migration may write, derived as migrateForStoreFile does (the store's
+ * grandparent is the config-home root). Exported so a caller can snapshot them BEFORE a migration and
+ * restore them if the write that follows fails - re-running a migration in reverse is not an unwind:
+ * it re-validates, and a pattern hook that matches the NEW name refuses it, leaving the manifest
+ * naming a surface the store does not (rename-rollback.test.js, case A2).
+ */
+function snapshotForStoreFile(storeFilePath) {
+  const root = path.dirname(path.dirname(storeFilePath));
+  const files = [path.join(root, 'hooks', 'hooks.manifest.json'), path.join(root, 'tools', 'tools.state.json')];
+  const snap = [];
+  for (const f of files) {
+    let bytes = null;
+    try { bytes = fs.readFileSync(f); } catch (_e) { bytes = null; } // absent stays absent
+    snap.push({ path: f, bytes });
+  }
+  return snap;
+}
+
+/** Put the snapshotted bytes back exactly (absent files are removed again). Best-effort, never throws. */
+function restoreSnapshot(snap) {
+  for (const { path: f, bytes } of snap || []) {
+    try {
+      if (bytes == null) { if (fs.existsSync(f)) fs.unlinkSync(f); } else { atomicWriteText(f, bytes); }
+    } catch (_e) { /* best-effort - the caller's own error is the story */ }
+  }
+}
+
+module.exports = { migrateSurfacedName, migrateForStoreFile, escapeRegex, snapshotForStoreFile, restoreSnapshot };

package/src/extend/add-hook.md

@@ -88,7 +88,10 @@ Two protocols:
   as the result text with `isError: true`.
 - any other code → non-blocking error (stderr captured, loop continues; never throws).
 
-**B) JSON (advanced)** - honored **only on exit 0**, when stdout parses as a JSON object:
+**B) JSON (advanced)** - honored **only on exit 0**, when stdout is a JSON object carrying protocol
+keys - or ends with one on its own line after other output (a printed startup line is fine). A
+decision that cannot be read (truncated, followed by stray text) **denies**; a printed object that
+is not a decision (a diagnostic dump, a JSON log line) is ignored:
 ```json
 {
   "continue": true,

package/src/extend/create-tool.md

@@ -56,7 +56,7 @@ Field-by-field - these names are fixed (registry.js reads exactly these):
 |---|---|---|
 | `id` | string | Stable unique key, kebab-case. `toolfunnel_run_tool({ name })` and `registry.run(id, args)` look up by this. Never reuse an existing `id`. |
 | `name` | string | Human/model-facing display name. Shown in the manager UI. |
-| `summary` | string | One line. This is ALL that `toolfunnel_list_tools` returns for the tool - keep it tight and discriminating so the model can pick the right tool from the brief alone. |
+| `summary` | string | One line. This is ALL that `toolfunnel_list_tools` returns for the tool - keep it tight and discriminating so the model can pick the right tool from the brief alone. Name every mode the tool has (`encode` / `decode`, `sha256` / `md5`): the listing's filter searches the name and summary only, so a mode that lives only in `instructions` or the schema is never found. |
 | `category` | string | Grouping label (e.g. `demo`, `memory`, `messaging`, `media`). Used by `toolfunnel_list_tools({ category })` to filter. |
 | `instructions` | string | Full usage doc returned by `toolfunnel_tool_instructions({ name })`. Describe the args object, what comes back, and any safety caveats. This is the long-tail payload - be complete here, terse in `summary`. |
 | `inputSchema` | object (optional) | A JSON Schema for the tool's args. **This is what makes the tool a first-class MCP citizen when promoted hot:** the top-level `tools/list` advertises it VERBATIM, so a connected client knows the exact arg shape without reading `instructions`. Omit it and a hot-promoted tool falls back to a free-form `{ "type": "object" }` (callable, but the client gets no arg hints). Must be an object - the register rejects any other shape at authoring time. |

package/src/extend/package.md

@@ -9,7 +9,7 @@ self-documented, a package is just a folder that lists its units and carries the
 
 ## 0. The WHOLE-SETUP path - `tf_pack` (start here)
 
-Since 0.4.0 the fastest way to ship is not per-unit packaging but the **whole setup**: your entire
+The fastest way to ship is not per-unit packaging but the **whole setup**: your entire
 config home (tools + scripts, hot/hidden curation, upstream references, policy hooks, identity) is
 already the product. One call packages it into a deployment-ready artifact under `<home>/dist/`: