toolfunnel 0.7.0 → 0.8.0

package/src/core/matcher.js

@@ -1,100 +1,100 @@
-'use strict';
-
-/**
- * matcher.js - does a hook's matcher string fire for a given tool?
- *
- * Mirrors Claude Code's matcher semantics:
- *   - ""  | undefined | "*"  -> always fire (wildcard).
- *   - otherwise the matcher is a regex, anchored as a FULL match against toolName
- *     (e.g. "Bash|Write|Edit").
- *   - tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) pass
- *     toolName == null/undefined -> always fire (the matcher is ignored).
- *
- * CommonJS only. Zero host imports (core/ must run headless under node --test).
- */
-
-// One compile per distinct matcher string. matches() sits on the gate's hot path (every
-// hook x every tool call), and rebuilding `^(?:Bash|Write|Edit)$` per call was pure waste:
-// RegExp construction is a deterministic function of the string and ours carries no flags
-// (no g/y -> no lastIndex state), so memoising by the string can never change an answer.
-// Invalidation is by construction, not by event: a reloaded manifest's new matcher is a
-// NEW string -> a new key; the old entry just goes unused. Failed compiles memoise too
-// (a malformed matcher answers false without a fresh throw per call). The cap is a
-// backstop against degenerate dynamically-generated matchers: past it the memo resets -
-// worst case is exactly the old per-call compile, never unbounded growth or a wrong fire.
-const COMPILE_CACHE_MAX = 256;
-const compileCache = new Map(); // String(matcher) -> { re: RegExp|null, err: string|null }
-
-/**
- * The memoised compile shared by matches() / matcherError(). Keyed on String(matcher) so a
- * non-string matcher coerces exactly as the template literal always did.
- * @param {*} matcher
- * @returns {{ re: RegExp|null, err: string|null }}
- */
-function compiled(matcher) {
-  const key = String(matcher);
-  let hit = compileCache.get(key);
-  if (hit) return hit;
-  try {
-    hit = { re: new RegExp(`^(?:${key})$`), err: null };
-  } catch (err) {
-    hit = { re: null, err: (err && err.message) || String(err) };
-  }
-  if (compileCache.size >= COMPILE_CACHE_MAX) compileCache.clear();
-  compileCache.set(key, hit);
-  return hit;
-}
-
-/**
- * @param {string|undefined|null} matcher  the hook's matcher string.
- * @param {string|undefined|null} toolName the tool the model requested, or
- *        null/undefined for events without a tool.
- * @returns {boolean} true if the hook should fire for this tool.
- */
-function matches(matcher, toolName) {
-  // Wildcard / unset matcher -> always fire, regardless of tool.
-  if (matcher === undefined || matcher === null || matcher === '' || matcher === '*') {
-    return true;
-  }
-
-  // Tool-less events: there is nothing to match against, so the matcher is
-  // ignored and the hook always fires. This is checked AFTER the wildcard
-  // case so a "*" matcher is handled uniformly, and BEFORE we attempt a regex
-  // (which would otherwise need a string to test).
-  if (toolName === undefined || toolName === null) {
-    return true;
-  }
-
-  // Anything else is a regex, anchored as a full match against toolName.
-  // We wrap in ^(?:...)$ so alternations like "Bash|Write" mean "the whole tool
-  // name is one of these", not "contains one of these".
-  const c = compiled(matcher);
-  if (!c.re) {
-    // A malformed matcher must never throw out of the engine, and matches() cannot
-    // claim a fire it could not evaluate - so this answers false. That is NOT
-    // permission to proceed: callers that gate on the answer must distinguish
-    // "did not match" from "could not be read" via matcherError() (hook-engine
-    // denies the call; hook-loader.addEntry refuses to store the matcher at all).
-    return false;
-  }
-
-  return c.re.test(toolName);
-}
-
-/**
- * Why does this matcher NOT compile? Returns null for a wildcard/unset matcher or one that
- * compiles under the same ^(?:...)$ anchoring matches() applies; otherwise the compile error's
- * message. This is the discriminator between "did not match" and "could not be read":
- * authoring surfaces (hook-loader.addEntry, and through it the UI and tf_hook_add) use it to
- * REFUSE a pattern that can never be evaluated, and hook-engine.fire treats a non-null answer
- * on a tool-bearing event as an unreadable gate and denies the call (matcher-compile.test.js).
- *
- * @param {string|undefined|null} m the hook's matcher string.
- * @returns {string|null} the compile problem, or null when the matcher is usable.
- */
-function matcherError(m) {
-  if (m === undefined || m === null || m === '' || m === '*') return null;
-  return compiled(m).err;
-}
-
-module.exports = { matches, matcherError };
+'use strict';
+
+/**
+ * matcher.js - does a hook's matcher string fire for a given tool?
+ *
+ * Mirrors Claude Code's matcher semantics:
+ *   - ""  | undefined | "*"  -> always fire (wildcard).
+ *   - otherwise the matcher is a regex, anchored as a FULL match against toolName
+ *     (e.g. "Bash|Write|Edit").
+ *   - tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) pass
+ *     toolName == null/undefined -> always fire (the matcher is ignored).
+ *
+ * CommonJS only. Zero host imports (core/ must run headless under node --test).
+ */
+
+// One compile per distinct matcher string. matches() sits on the gate's hot path (every
+// hook x every tool call), and rebuilding `^(?:Bash|Write|Edit)$` per call was pure waste:
+// RegExp construction is a deterministic function of the string and ours carries no flags
+// (no g/y -> no lastIndex state), so memoising by the string can never change an answer.
+// Invalidation is by construction, not by event: a reloaded manifest's new matcher is a
+// NEW string -> a new key; the old entry just goes unused. Failed compiles memoise too
+// (a malformed matcher answers false without a fresh throw per call). The cap is a
+// backstop against degenerate dynamically-generated matchers: past it the memo resets -
+// worst case is exactly the old per-call compile, never unbounded growth or a wrong fire.
+const COMPILE_CACHE_MAX = 256;
+const compileCache = new Map(); // String(matcher) -> { re: RegExp|null, err: string|null }
+
+/**
+ * The memoised compile shared by matches() / matcherError(). Keyed on String(matcher) so a
+ * non-string matcher coerces exactly as the template literal always did.
+ * @param {*} matcher
+ * @returns {{ re: RegExp|null, err: string|null }}
+ */
+function compiled(matcher) {
+  const key = String(matcher);
+  let hit = compileCache.get(key);
+  if (hit) return hit;
+  try {
+    hit = { re: new RegExp(`^(?:${key})$`), err: null };
+  } catch (err) {
+    hit = { re: null, err: (err && err.message) || String(err) };
+  }
+  if (compileCache.size >= COMPILE_CACHE_MAX) compileCache.clear();
+  compileCache.set(key, hit);
+  return hit;
+}
+
+/**
+ * @param {string|undefined|null} matcher  the hook's matcher string.
+ * @param {string|undefined|null} toolName the tool the model requested, or
+ *        null/undefined for events without a tool.
+ * @returns {boolean} true if the hook should fire for this tool.
+ */
+function matches(matcher, toolName) {
+  // Wildcard / unset matcher -> always fire, regardless of tool.
+  if (matcher === undefined || matcher === null || matcher === '' || matcher === '*') {
+    return true;
+  }
+
+  // Tool-less events: there is nothing to match against, so the matcher is
+  // ignored and the hook always fires. This is checked AFTER the wildcard
+  // case so a "*" matcher is handled uniformly, and BEFORE we attempt a regex
+  // (which would otherwise need a string to test).
+  if (toolName === undefined || toolName === null) {
+    return true;
+  }
+
+  // Anything else is a regex, anchored as a full match against toolName.
+  // We wrap in ^(?:...)$ so alternations like "Bash|Write" mean "the whole tool
+  // name is one of these", not "contains one of these".
+  const c = compiled(matcher);
+  if (!c.re) {
+    // A malformed matcher must never throw out of the engine, and matches() cannot
+    // claim a fire it could not evaluate - so this answers false. That is NOT
+    // permission to proceed: callers that gate on the answer must distinguish
+    // "did not match" from "could not be read" via matcherError() (hook-engine
+    // denies the call; hook-loader.addEntry refuses to store the matcher at all).
+    return false;
+  }
+
+  return c.re.test(toolName);
+}
+
+/**
+ * Why does this matcher NOT compile? Returns null for a wildcard/unset matcher or one that
+ * compiles under the same ^(?:...)$ anchoring matches() applies; otherwise the compile error's
+ * message. This is the discriminator between "did not match" and "could not be read":
+ * authoring surfaces (hook-loader.addEntry, and through it the UI and tf_hook_add) use it to
+ * REFUSE a pattern that can never be evaluated, and hook-engine.fire treats a non-null answer
+ * on a tool-bearing event as an unreadable gate and denies the call (matcher-compile.test.js).
+ *
+ * @param {string|undefined|null} m the hook's matcher string.
+ * @returns {string|null} the compile problem, or null when the matcher is usable.
+ */
+function matcherError(m) {
+  if (m === undefined || m === null || m === '' || m === '*') return null;
+  return compiled(m).err;
+}
+
+module.exports = { matches, matcherError };

package/src/core/metrics.js

@@ -1,75 +1,90 @@
-'use strict';
-
-/**
- * metrics.js - in-memory, per-process tool-call counters (lightweight observability).
- *
- * A privileged gateway should be able to answer "what has run through me, and how often did it
- * fail?" without standing up a metrics stack. This is the zero-dependency MVP of that: process-
- * lifetime counters incremented at the single tools/call chokepoint and surfaced via the HTTP
- * `/health` endpoint and the admin UI. It is NOT persistent (counts reset when the host restarts)
- * and NOT a substitute for the JSONL audit log (src/core/logger.js, which records individual events
- * to disk when enabled) - the two are complementary: the log is the durable per-event record, this
- * is the cheap live aggregate.
- *
- * Design rules (same discipline as logger.js):
- *   - Zero dependencies. Plain objects + integers.
- *   - record() / snapshot() NEVER throw - instrumentation must never break a tool call.
- *   - In-memory only; no files, no timers, no network.
- *
- * CommonJS only.
- */
-
-const state = {
-  startedAt: new Date().toISOString(),
-  calls: 0,
-  errors: 0,
-  byTool: Object.create(null), // name -> { calls, errors }
-};
-
-/**
- * record - count one tools/call outcome. `ok:false` (an isError result - a tool failure OR a
- * PreToolUse denial, which both surface as an error envelope) increments the error counters.
- * @param {{ tool?:string, ok?:boolean }} ev
- */
-function record(ev) {
-  try {
-    const tool = ev && typeof ev.tool === 'string' && ev.tool.length > 0 ? ev.tool : 'unknown';
-    const ok = !(ev && ev.ok === false);
-    state.calls += 1;
-    if (!ok) state.errors += 1;
-    let t = state.byTool[tool];
-    if (!t) {
-      t = { calls: 0, errors: 0 };
-      state.byTool[tool] = t;
-    }
-    t.calls += 1;
-    if (!ok) t.errors += 1;
-  } catch (_e) {
-    /* instrumentation must never break the caller */
-  }
-}
-
-/**
- * snapshot - a fresh, mutation-safe copy of the counters for /health + the UI. NEVER throws.
- * @returns {{ startedAt:string, calls:number, errors:number, byTool:Object<string,{calls:number,errors:number}> }}
- */
-function snapshot() {
-  try {
-    const byTool = {};
-    for (const k of Object.keys(state.byTool)) {
-      byTool[k] = { calls: state.byTool[k].calls, errors: state.byTool[k].errors };
-    }
-    return { startedAt: state.startedAt, calls: state.calls, errors: state.errors, byTool };
-  } catch (_e) {
-    return { startedAt: state.startedAt, calls: 0, errors: 0, byTool: {} };
-  }
-}
-
-/** reset - zero the counters (tests). The startedAt stamp is left as the process start. */
-function reset() {
-  state.calls = 0;
-  state.errors = 0;
-  state.byTool = Object.create(null);
-}
-
-module.exports = { record, snapshot, reset };
+'use strict';
+
+/**
+ * metrics.js - in-memory, per-process tool-call counters (lightweight observability).
+ *
+ * A privileged gateway should be able to answer "what has run through me, and how often did it
+ * fail?" without standing up a metrics stack. This is the zero-dependency MVP of that: process-
+ * lifetime counters incremented at the single tools/call chokepoint and surfaced via the HTTP
+ * `/health` endpoint and the admin UI. It is NOT persistent (counts reset when the host restarts)
+ * and NOT a substitute for the JSONL audit log (src/core/logger.js, which records individual events
+ * to disk when enabled) - the two are complementary: the log is the durable per-event record, this
+ * is the cheap live aggregate.
+ *
+ * Design rules (same discipline as logger.js):
+ *   - Zero dependencies. Plain objects + integers.
+ *   - record() / snapshot() NEVER throw - instrumentation must never break a tool call.
+ *   - In-memory only; no files, no timers, no network.
+ *
+ * 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)
+};
+
+/**
+ * record - count one tools/call outcome. `ok:false` (an isError result - a tool failure OR a
+ * PreToolUse denial, which both surface as an error envelope) increments the error counters.
+ * @param {{ tool?:string, ok?:boolean }} ev
+ */
+function record(ev) {
+  try {
+    const tool = ev && typeof ev.tool === 'string' && ev.tool.length > 0 ? ev.tool : 'unknown';
+    const ok = !(ev && ev.ok === false);
+    state.calls += 1;
+    if (!ok) state.errors += 1;
+    let t = state.byTool[tool];
+    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;
+  } catch (_e) {
+    /* instrumentation must never break the caller */
+  }
+}
+
+/**
+ * snapshot - a fresh, mutation-safe copy of the counters for /health + the UI. NEVER throws.
+ * @returns {{ startedAt:string, calls:number, errors:number, byTool:Object<string,{calls:number,errors:number}> }}
+ */
+function snapshot() {
+  try {
+    // 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 };
+    }
+    return { startedAt: state.startedAt, calls: state.calls, errors: state.errors, byTool };
+  } catch (_e) {
+    return { startedAt: state.startedAt, calls: 0, errors: 0, byTool: {} };
+  }
+}
+
+/** reset - zero the counters (tests). The startedAt stamp is left as the process start. */
+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 };