agentfootprint 6.24.0 → 6.25.0

package/README.md

@@ -394,6 +394,37 @@ allocates no queue.
 > 📖 Full semantics (capture policies, backpressure, `'block'` overflow):
 > [footprintjs deferred-observers guide](https://github.com/footprintjs/footPrint/blob/main/docs/guides/observers-deferred.md)
 
+### Lint your tool catalog — before the model picks the wrong twin
+
+Tool routing is an LLM decision driven by names + descriptions — so lint the
+catalog like code and gate it in CI. **Zero stack buy-in**: works on any
+OpenAI / Anthropic / MCP / plain tool list, no agentfootprint runtime needed.
+
+```bash
+npx agentfootprint-lint-tools tools.json --threshold 0.94 --strict
+```
+
+```
+✗ CONFUSABLE 0.9445  get_fcns_database <> influx_get_fcns_database
+    hint: names differ only by 'influx' — make the descriptions say WHEN to choose each
+~ warn  [enum-in-prose] influx_get_port_ranking.metric
+    suggest: "enum": ["avg_iops","peak_iops","mbps"]
+```
+
+Pairwise confusability over what the model reads (embedder pluggable,
+content-hash cached) plus a pluggable structural rule pack
+(missing/short descriptions, says-WHAT-not-WHEN, enums hiding in prose,
+undocumented optional params). The runtime counterpart, `toolChoiceRecorder`
+(`agentfootprint/observe`), scores each live LLM call's tool choice against
+the same geometry and flags narrow margins and proxy disagreements — lazily,
+off the hot path.
+
+> 📖 **[Tool-catalog lint guide](docs/guides/tool-catalog-lint.md)** — 5 minutes
+> from a tools.json to a gated CI check ·
+> [`examples/observability/02`](examples/observability/02-lint-confusable-catalog.ts) ·
+> [`03`](examples/observability/03-lint-fix-and-pass.ts) ·
+> [`04`](examples/observability/04-tool-choice-margins.ts)
+
 ---
 
 ## Quick start — runs offline, no API key

package/bin/agentfootprint-lint-tools.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * agentfootprint-lint-tools — CI gate for tool-catalog confusability
+ * (RFC-002 C3). Humble shell: all behavior lives in src/lib/tool-lint/cli.ts
+ * (unit-tested there); this wrapper only resolves the built module and maps
+ * the returned code onto process.exitCode.
+ *
+ *   npx agentfootprint-lint-tools tools.json
+ *   npx agentfootprint-lint-tools tools.json --threshold 0.94 --strict
+ *
+ * Guide: docs/guides/tool-catalog-lint.md
+ */
+const { runToolLintCli } = await import('../dist/esm/lib/tool-lint/cli.js');
+process.exitCode = await runToolLintCli(process.argv.slice(2));

package/dist/esm/lib/tool-lint/analyze.js

@@ -0,0 +1,235 @@
+/**
+ * analyzeToolCatalog — the tool-catalog confusability lint
+ * (RFC-002 block C1, the adoption front door).
+ *
+ * Pattern: policy layer over `pairwiseSimilarity` (influence-core) — the
+ *          geometry is computed there; thresholds, verdicts, hints and
+ *          the structural rule pack live here. Everything is consumer-
+ *          injectable with our defaults (the plug-and-play meta-pattern).
+ * Role:    `src/lib/tool-lint/`. ZERO stack buy-in — plain
+ *          `{ name, description?, inputSchema? }[]` in, report out.
+ *          `catalogFromTools` adapts the library's own `Tool[]`;
+ *          `coerceCatalog` (cli.ts) normalizes OpenAI/Anthropic/MCP
+ *          shapes.
+ *
+ * ## What is embedded (and why)
+ *
+ * `confusabilityText(tool)` = tokenized name + ': ' + description. The
+ * model differentiates tools by name AND description together, so two
+ * tools with near-identical names and overlapping descriptions ARE the
+ * confusability case (`get_fcns_database` vs `influx_get_fcns_database`)
+ * — embedding only the prose would miss the name signal.
+ *
+ * ## Calibration (RFC-002 §3 — read this before trusting verdicts)
+ *
+ * Absolute cosine ranges are PER-EMBEDDER. The default threshold (0.85)
+ * is a starting point for real sentence embedders. The test/demo
+ * `mockEmbedder` (character-frequency) compresses unrelated prose into
+ * ~0.85–0.97 — with it, use `MOCK_EMBEDDER_CALIBRATION` and trust only
+ * the RELATIVE ordering in `report.similarity.ranked` (the acceptance
+ * fixtures assert ordering, never absolute scores).
+ */
+import { pairwiseSimilarity } from '../influence-core/index.js';
+import { defaultStructuralRules } from './rules.js';
+/** Default `confusabilityThreshold` — a starting point for REAL sentence
+ *  embedders (unrelated tool descriptions typically land 0.3–0.7).
+ *  Calibrate per embedder; meaningless for the mock (see below). */
+export const DEFAULT_CONFUSABILITY_THRESHOLD = 0.85;
+/** Default `watchBand` below the threshold. */
+export const DEFAULT_WATCH_BAND = 0.05;
+/**
+ * Threshold/band calibrated for the char-frequency `mockEmbedder` on
+ * realistic tool prose (seed corpus: the Neo SAN catalog). The mock
+ * compresses unrelated descriptions into ~0.85–0.97 cosine, so expect
+ * false positives even at 0.94 — with the mock, the RELATIVE ordering
+ * of `report.similarity.ranked` is the trustworthy signal; absolute
+ * verdicts are only honest with a real embedder + per-embedder
+ * calibration.
+ */
+export const MOCK_EMBEDDER_CALIBRATION = Object.freeze({
+    confusabilityThreshold: 0.94,
+    watchBand: 0.02,
+});
+/**
+ * Adapt the library's `Tool[]` (from `defineTool` / `Agent.tool`) to the
+ * lint's plain catalog shape. Trivial on purpose: `Tool.schema` already
+ * IS `{ name, description, inputSchema }`.
+ */
+export function catalogFromTools(tools) {
+    return tools.map((tool) => ({
+        name: tool.schema.name,
+        description: tool.schema.description,
+        inputSchema: tool.schema.inputSchema,
+    }));
+}
+/**
+ * The text the confusability analysis embeds for one tool: the name with
+ * `_`/`-`/camelCase boundaries opened into words, then the description.
+ * Exported so consumers can reproduce or replace the construction.
+ */
+export function confusabilityText(tool) {
+    const name = tool.name
+        .replace(/[_-]+/g, ' ')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .trim();
+    const description = tool.description?.trim() ?? '';
+    return description.length > 0 ? `${name}: ${description}` : name;
+}
+/**
+ * Lint a tool catalog: pairwise confusability over what the model reads
+ * (when an embedder is supplied) + the structural rule pack. Returns a
+ * report whose `ok` is the CI gate.
+ *
+ * Duplicate tool names are themselves reported as structural errors
+ * (rule `duplicate-name`, built-in precondition — a catalog where two
+ * tools share a name is broken before any similarity question); the
+ * duplicates are dropped from the similarity analysis (first one wins).
+ */
+export async function analyzeToolCatalog(tools, options = {}) {
+    const confusabilityThreshold = options.confusabilityThreshold ?? DEFAULT_CONFUSABILITY_THRESHOLD;
+    const watchBand = options.watchBand ?? DEFAULT_WATCH_BAND;
+    const rules = options.rules ?? defaultStructuralRules;
+    const failOn = options.failOn ?? 'error';
+    // ── built-in precondition: duplicate names ──
+    const structural = [];
+    const seen = new Set();
+    const unique = [];
+    for (const tool of tools) {
+        if (seen.has(tool.name)) {
+            structural.push({
+                rule: 'duplicate-name',
+                tool: tool.name,
+                severity: 'error',
+                message: 'two tools share this name — the model cannot address them distinctly',
+            });
+        }
+        else {
+            seen.add(tool.name);
+            unique.push(tool);
+        }
+    }
+    // ── structural rule pack ──
+    for (const tool of unique) {
+        for (const rule of rules) {
+            structural.push(...rule.check(tool, unique));
+        }
+    }
+    // ── pairwise confusability (embedder-gated) ──
+    let ranked = [];
+    const confusable = [];
+    const watch = [];
+    const analyzed = options.embedder !== undefined && unique.length >= 2;
+    if (options.embedder !== undefined && unique.length >= 2) {
+        const byName = new Map(unique.map((tool) => [tool.name, tool]));
+        const result = await pairwiseSimilarity({
+            items: unique.map((tool) => ({ id: tool.name, text: confusabilityText(tool) })),
+            embedder: options.embedder,
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        ranked = result.pairs;
+        for (const pair of result.pairs) {
+            if (pair.similarity >= confusabilityThreshold) {
+                confusable.push({
+                    kind: 'confusable',
+                    a: pair.a,
+                    b: pair.b,
+                    similarity: pair.similarity,
+                    // byName lookups are safe: pair ids come from `unique` itself.
+                    hint: differentiationHint(byName.get(pair.a), byName.get(pair.b)),
+                });
+            }
+            else if (pair.similarity >= confusabilityThreshold - watchBand) {
+                watch.push({
+                    kind: 'watch',
+                    a: pair.a,
+                    b: pair.b,
+                    similarity: pair.similarity,
+                    hint: differentiationHint(byName.get(pair.a), byName.get(pair.b)),
+                });
+            }
+        }
+    }
+    const errors = structural.filter((f) => f.severity === 'error').length;
+    const warnings = structural.length - errors;
+    const gateFailures = failOn === 'warn' ? structural.length : errors;
+    return {
+        ok: confusable.length === 0 && gateFailures === 0,
+        toolCount: tools.length,
+        similarity: {
+            analyzed,
+            confusable,
+            watch,
+            ranked,
+            thresholds: { confusabilityThreshold, watchBand },
+        },
+        structural,
+        summary: { confusable: confusable.length, watch: watch.length, errors, warnings },
+    };
+}
+// ── differentiating-axis hint (heuristic, honest) ────────────────────
+const STOPWORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'are',
+    'by',
+    'for',
+    'from',
+    'get',
+    'in',
+    'into',
+    'is',
+    'its',
+    'of',
+    'on',
+    'or',
+    'the',
+    'to',
+    'which',
+    'with',
+]);
+function nameTokens(name) {
+    return name
+        .replace(/[_-]+/g, ' ')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+}
+function descriptionTokens(tool) {
+    return new Set((tool.description ?? '')
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/)
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t)));
+}
+/**
+ * Suggest the DIFFERENTIATING AXIS for a flagged pair. Heuristic: when
+ * the names are near-twins (≤2 distinct tokens), the qualifier IS the
+ * axis — the descriptions must say when to choose each variant. When the
+ * names differ, surface the few description terms each tool does NOT
+ * share, as the place to anchor an explicit choice condition.
+ */
+export function differentiationHint(a, b) {
+    const aTokens = nameTokens(a.name);
+    const bTokens = nameTokens(b.name);
+    const aOnly = aTokens.filter((t) => !bTokens.includes(t));
+    const bOnly = bTokens.filter((t) => !aTokens.includes(t));
+    const shared = aTokens.filter((t) => bTokens.includes(t));
+    if (shared.length >= 2 && aOnly.length + bOnly.length <= 2) {
+        const diff = [...aOnly, ...bOnly].map((t) => `'${t}'`).join(' vs ') || 'nothing — the names match';
+        return (`names differ only by ${diff} — make the descriptions say WHEN to choose each ` +
+            `(different backend/data source? live vs historical? freshness?), ` +
+            `e.g. "Use for …; prefer ${b.name} when …"`);
+    }
+    const aDesc = descriptionTokens(a);
+    const bDesc = descriptionTokens(b);
+    const aDistinct = [...aDesc].filter((t) => !bDesc.has(t)).slice(0, 3);
+    const bDistinct = [...bDesc].filter((t) => !aDesc.has(t)).slice(0, 3);
+    if (aDistinct.length === 0 && bDistinct.length === 0) {
+        return `the descriptions are near-duplicates — rewrite one to state when it, and not ${b.name}, is the right call`;
+    }
+    return (`descriptions overlap heavily; the distinct terms are ` +
+        `${a.name}: [${aDistinct.join(', ')}] vs ${b.name}: [${bDistinct.join(', ')}] — ` +
+        `lead with an explicit choice condition ("use when …") built on those`);
+}
+//# sourceMappingURL=analyze.js.map

package/dist/esm/lib/tool-lint/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../../../src/lib/tool-lint/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,kBAAkB,EAAuB,MAAM,4BAA4B,CAAC;AACrF,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AASpD;;oEAEoE;AACpE,MAAM,CAAC,MAAM,+BAA+B,GAAG,IAAI,CAAC;AAEpD,+CAA+C;AAC/C,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,CAAC;IACrD,sBAAsB,EAAE,IAAI;IAC5B,SAAS,EAAE,IAAI;CAChB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAsB;IACrD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;QACtB,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;QACpC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;KACrC,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI;SACnB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,IAAI,EAAE,CAAC;IACV,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACnD,OAAO,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACnE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAA6B,EAC7B,UAAqC,EAAE;IAEvC,MAAM,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,IAAI,+BAA+B,CAAC;IACjG,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,sBAAsB,CAAC;IACtD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC;IAEzC,+CAA+C;IAC/C,MAAM,UAAU,GAAwB,EAAE,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,sEAAsE;aAChF,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,6BAA6B;IAC7B,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,IAAI,MAAM,GAA8B,EAAE,CAAC;IAC3C,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IACtE,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QAChE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC;YACtC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/E,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD,CAAC,CAAC;QACH,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;QACtB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,UAAU,IAAI,sBAAsB,EAAE,CAAC;gBAC9C,UAAU,CAAC,IAAI,CAAC;oBACd,IAAI,EAAE,YAAY;oBAClB,CAAC,EAAE,IAAI,CAAC,CAAC;oBACT,CAAC,EAAE,IAAI,CAAC,CAAC;oBACT,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,+DAA+D;oBAC/D,IAAI,EAAE,mBAAmB,CACvB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAgB,EACjC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAgB,CAClC;iBACF,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,IAAI,CAAC,UAAU,IAAI,sBAAsB,GAAG,SAAS,EAAE,CAAC;gBACjE,KAAK,CAAC,IAAI,CAAC;oBACT,IAAI,EAAE,OAAO;oBACb,CAAC,EAAE,IAAI,CAAC,CAAC;oBACT,CAAC,EAAE,IAAI,CAAC,CAAC;oBACT,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,IAAI,EAAE,mBAAmB,CACvB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAgB,EACjC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAgB,CAClC;iBACF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IACvE,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC;IAC5C,MAAM,YAAY,GAAG,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAEpE,OAAO;QACL,EAAE,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,KAAK,CAAC;QACjD,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,UAAU,EAAE;YACV,QAAQ;YACR,UAAU;YACV,KAAK;YACL,MAAM;YACN,UAAU,EAAE,EAAE,sBAAsB,EAAE,SAAS,EAAE;SAClD;QACD,UAAU;QACV,OAAO,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE;KAClF,CAAC;AACJ,CAAC;AAED,wEAAwE;AAExE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,GAAG;IACH,IAAI;IACJ,KAAK;IACL,KAAK;IACL,IAAI;IACJ,KAAK;IACL,MAAM;IACN,KAAK;IACL,IAAI;IACJ,MAAM;IACN,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,OAAO;IACP,MAAM;CACP,CAAC,CAAC;AAEH,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI;SACR,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,WAAW,EAAE;SACb,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAiB;IAC1C,OAAO,IAAI,GAAG,CACZ,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;SACrB,WAAW,EAAE;SACb,KAAK,CAAC,aAAa,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACrD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAc,EAAE,CAAc;IAChE,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1D,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,GACR,CAAC,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,2BAA2B,CAAC;QACxF,OAAO,CACL,wBAAwB,IAAI,mDAAmD;YAC/E,mEAAmE;YACnE,2BAA2B,CAAC,CAAC,IAAI,UAAU,CAC5C,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO,gFAAgF,CAAC,CAAC,IAAI,qBAAqB,CAAC;IACrH,CAAC;IACD,OAAO,CACL,uDAAuD;QACvD,GAAG,CAAC,CAAC,IAAI,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;QACjF,sEAAsE,CACvE,CAAC;AACJ,CAAC"}

package/dist/esm/lib/tool-lint/cli.js

@@ -0,0 +1,198 @@
+/**
+ * Tool-lint CLI core (RFC-002 block C3 — the CI gate).
+ *
+ * Pattern: humble shell — `bin/agentfootprint-lint-tools.mjs` is a
+ *          3-line wrapper; ALL behavior (arg parsing, catalog coercion,
+ *          report, exit code) lives here so it is unit-testable without
+ *          spawning a process.
+ * Role:    `src/lib/tool-lint/`. Reads ONE JSON file of tools, prints a
+ *          report, returns the process exit code:
+ *            0 — report.ok
+ *            1 — findings failed the gate (!ok)
+ *            2 — usage / input error (bad flags, unreadable file,
+ *                unrecognized JSON shape)
+ *
+ * ## Embedder & gating honesty
+ *
+ * The CLI has no way to receive a consumer embedder, so it uses the
+ * built-in deterministic mock (char-frequency, offline, dependency-free)
+ * for the similarity RANKING — and, by default, does NOT gate on it:
+ * without `--threshold`, similarity is report-only (relative ordering +
+ * watch hints) and the exit code reflects structural findings alone.
+ * Pass `--threshold` to make confusable pairs fail the gate — you own
+ * the calibration at that point (start from
+ * `MOCK_EMBEDDER_CALIBRATION.confusabilityThreshold` = 0.94). For real
+ * embedder gating, use `analyzeToolCatalog` from
+ * `agentfootprint/observe` in a small script instead.
+ */
+import { readFile } from 'node:fs/promises';
+import { mockEmbedder } from '../../memory/embedding/mockEmbedder.js';
+import { analyzeToolCatalog, MOCK_EMBEDDER_CALIBRATION } from './analyze.js';
+import { formatToolCatalogReport } from './format.js';
+const USAGE = `usage: agentfootprint-lint-tools <tools.json> [options]
+
+  <tools.json>          JSON file with your tool catalog. Accepted shapes:
+                          [{ name, description, inputSchema? }]          (plain / MCP tool)
+                          { tools: [...] }                               (MCP tools/list result)
+                          [{ type: 'function', function: {...} }]       (OpenAI)
+                          [{ name, description, input_schema }]         (Anthropic)
+
+  --threshold <num>     gate on confusable pairs at this cosine (mock-embedder
+                        starting point: ${MOCK_EMBEDDER_CALIBRATION.confusabilityThreshold}). Without it, similarity is
+                        REPORT-ONLY and only structural findings gate.
+  --watch-band <num>    advisory band below the threshold (default ${MOCK_EMBEDDER_CALIBRATION.watchBand} with --threshold)
+  --strict              structural warnings also fail the gate
+  --no-similarity       skip the similarity analysis entirely
+  --top <n>             ranked pairs to print (default 10)
+  --json                print the full report as JSON instead of text
+
+exit codes: 0 ok · 1 findings failed the gate · 2 usage/input error`;
+/**
+ * Normalize any of the recognized tool-list JSON shapes to the lint's
+ * plain catalog. Throws (with a shape description) on unrecognized
+ * input — the CLI maps that to exit code 2.
+ */
+export function coerceCatalog(json) {
+    // { tools: [...] } — MCP `tools/list` result envelope.
+    const list = Array.isArray(json)
+        ? json
+        : json !== null &&
+            typeof json === 'object' &&
+            Array.isArray(json.tools)
+            ? json.tools
+            : undefined;
+    if (list === undefined) {
+        throw new Error('expected a JSON array of tools or { tools: [...] }');
+    }
+    return list.map((raw, index) => {
+        if (raw === null || typeof raw !== 'object') {
+            throw new Error(`tools[${index}] is not an object`);
+        }
+        const entry = raw;
+        // OpenAI: { type: 'function', function: { name, description, parameters } }
+        const fn = entry.type === 'function' && entry.function !== null && typeof entry.function === 'object'
+            ? entry.function
+            : entry;
+        const name = fn.name;
+        if (typeof name !== 'string' || name.length === 0) {
+            throw new Error(`tools[${index}] has no string 'name'`);
+        }
+        const description = typeof fn.description === 'string' ? fn.description : undefined;
+        // inputSchema (MCP/ours) | input_schema (Anthropic) | parameters (OpenAI)
+        const schema = fn.inputSchema ?? fn.input_schema ?? fn.parameters;
+        const inputSchema = schema !== null && typeof schema === 'object'
+            ? schema
+            : undefined;
+        return {
+            name,
+            ...(description !== undefined ? { description } : {}),
+            ...(inputSchema !== undefined ? { inputSchema } : {}),
+        };
+    });
+}
+function parseArgs(argv) {
+    let file;
+    let threshold;
+    let watchBand;
+    let strict = false;
+    let similarity = true;
+    let top = 10;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const numberFlag = (name) => {
+            const value = Number(argv[++i]);
+            if (!Number.isFinite(value))
+                throw new Error(`${name} expects a number`);
+            return value;
+        };
+        if (arg === '--threshold')
+            threshold = numberFlag('--threshold');
+        else if (arg === '--watch-band')
+            watchBand = numberFlag('--watch-band');
+        else if (arg === '--strict')
+            strict = true;
+        else if (arg === '--no-similarity')
+            similarity = false;
+        else if (arg === '--top')
+            top = numberFlag('--top');
+        else if (arg === '--json')
+            json = true;
+        else if (arg === '--help' || arg === '-h')
+            throw new Error(USAGE);
+        else if (arg.startsWith('-'))
+            throw new Error(`unknown flag '${arg}'\n\n${USAGE}`);
+        else if (file === undefined)
+            file = arg;
+        else
+            throw new Error(`unexpected extra argument '${arg}'\n\n${USAGE}`);
+    }
+    if (file === undefined)
+        throw new Error(USAGE);
+    return {
+        file,
+        ...(threshold !== undefined ? { threshold } : {}),
+        ...(watchBand !== undefined ? { watchBand } : {}),
+        strict,
+        similarity,
+        top,
+        json,
+    };
+}
+/**
+ * Run the lint CLI. Returns the exit code (never calls `process.exit` —
+ * the bin wrapper assigns it to `process.exitCode`).
+ */
+export async function runToolLintCli(argv, io = {
+    // eslint-disable-next-line no-console
+    stdout: (line) => console.log(line),
+    // eslint-disable-next-line no-console
+    stderr: (line) => console.error(line),
+}) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        io.stderr(error.message);
+        return 2;
+    }
+    let catalog;
+    try {
+        catalog = coerceCatalog(JSON.parse(await readFile(args.file, 'utf8')));
+    }
+    catch (error) {
+        io.stderr(`agentfootprint-lint-tools: ${args.file}: ${error.message}`);
+        return 2;
+    }
+    // Without --threshold the mock-embedder similarity is REPORT-ONLY:
+    // rank pairs at an unreachable threshold (no 'confusable'/'watch'
+    // verdicts) so only the relative-ordering section prints.
+    const gateOnSimilarity = args.threshold !== undefined;
+    const threshold = args.threshold ?? Infinity;
+    const watchBand = args.watchBand ?? (gateOnSimilarity ? MOCK_EMBEDDER_CALIBRATION.watchBand : 0);
+    const report = await analyzeToolCatalog(catalog, {
+        ...(args.similarity ? { embedder: mockEmbedder() } : {}),
+        confusabilityThreshold: threshold,
+        watchBand,
+        failOn: args.strict ? 'warn' : 'error',
+    });
+    if (args.json) {
+        io.stdout(JSON.stringify(report, null, 2));
+    }
+    else {
+        if (args.similarity) {
+            io.stdout(gateOnSimilarity
+                ? '⚠ similarity uses the built-in deterministic mock embedder — you own the ' +
+                    'calibration of --threshold (cosine ranges are per-embedder; mock compresses ' +
+                    'prose to ~0.85–0.97). Trust relative ordering first.'
+                : 'ℹ similarity is REPORT-ONLY (no --threshold): ranked pairs below are the ' +
+                    'relative-ordering view from the built-in mock embedder. Pass --threshold ' +
+                    `(mock starting point ${MOCK_EMBEDDER_CALIBRATION.confusabilityThreshold}) to gate on confusable pairs.`);
+            io.stdout('');
+        }
+        io.stdout(formatToolCatalogReport(report, { topPairs: args.top }));
+    }
+    return report.ok ? 0 : 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/esm/lib/tool-lint/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../../src/lib/tool-lint/cli.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/tool-lint/format.js

@@ -0,0 +1,61 @@
+/**
+ * formatToolCatalogReport — human-readable rendering of a lint report.
+ *
+ * Pattern: pure presenter. One report → one string; used verbatim by the
+ *          CLI (`agentfootprint-lint-tools`) and the examples so output
+ *          stays byte-identical across surfaces.
+ * Role:    `src/lib/tool-lint/` leaf. No I/O.
+ */
+export function formatToolCatalogReport(report, options = {}) {
+    const topPairs = options.topPairs ?? 10;
+    const maxWatch = options.maxWatch ?? 10;
+    const lines = [];
+    const { similarity, structural, summary } = report;
+    lines.push(`tool-catalog lint — ${report.toolCount} tools · ` +
+        `${summary.confusable} confusable · ${summary.watch} watch · ` +
+        `${summary.errors} errors · ${summary.warnings} warnings`);
+    if (similarity.analyzed) {
+        lines.push('', `confusability (threshold ${similarity.thresholds.confusabilityThreshold}, ` +
+            `watch band ${similarity.thresholds.watchBand}):`);
+        if (similarity.confusable.length === 0 && similarity.watch.length === 0) {
+            lines.push('  no pairs at or near the threshold');
+        }
+        for (const pair of similarity.confusable) {
+            lines.push(`  ✗ CONFUSABLE ${pair.similarity.toFixed(4)}  ${pair.a} <> ${pair.b}`);
+            lines.push(`      hint: ${pair.hint}`);
+        }
+        for (const pair of similarity.watch.slice(0, maxWatch)) {
+            lines.push(`  ~ watch      ${pair.similarity.toFixed(4)}  ${pair.a} <> ${pair.b}`);
+            lines.push(`      hint: ${pair.hint}`);
+        }
+        if (similarity.watch.length > maxWatch) {
+            lines.push(`  … and ${similarity.watch.length - maxWatch} more watch pairs (see report.similarity.watch)`);
+        }
+        if (topPairs > 0 && similarity.ranked.length > 0) {
+            lines.push('', `  most-similar pairs (relative ordering — top ${topPairs}):`);
+            for (const pair of similarity.ranked.slice(0, topPairs)) {
+                lines.push(`    ${pair.similarity.toFixed(4)}  ${pair.a} <> ${pair.b}`);
+            }
+        }
+    }
+    else {
+        lines.push('', 'confusability: skipped (no embedder supplied — structural rules only)');
+    }
+    if (structural.length > 0) {
+        lines.push('', 'structural findings:');
+        for (const finding of structural) {
+            const where = finding.param ? `${finding.tool}.${finding.param}` : finding.tool;
+            const mark = finding.severity === 'error' ? '✗' : '~';
+            lines.push(`  ${mark} ${finding.severity.padEnd(5)} [${finding.rule}] ${where}`);
+            lines.push(`      ${finding.message}`);
+            if (finding.suggestion)
+                lines.push(`      suggest: ${finding.suggestion}`);
+        }
+    }
+    else {
+        lines.push('', 'structural findings: none');
+    }
+    lines.push('', report.ok ? 'RESULT: ok' : 'RESULT: FAIL');
+    return lines.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/esm/lib/tool-lint/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../../src/lib/tool-lint/format.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/tool-lint/index.js

@@ -0,0 +1,23 @@
+/**
+ * tool-lint — the tool-catalog confusability lint (RFC-002 tier 1,
+ * blocks C1–C3).
+ *
+ * Build-time, CI-gateable, framework-agnostic: a plain
+ * `{ name, description?, inputSchema? }[]` in (any OpenAI / Anthropic /
+ * LangChain / MCP tool list coerces to it), a report with a CI-gateable
+ * `ok` out. The embedding geometry comes from influence-core
+ * (`pairwiseSimilarity`); this module is the policy layer — thresholds,
+ * verdicts, hints, and the pluggable structural rule pack.
+ *
+ * Surfaces:
+ *   - `analyzeToolCatalog(tools, opts)` — the API (C1)
+ *   - `defaultStructuralRules` + rule factories — the rule pack (C2)
+ *   - `runToolLintCli` / bin `agentfootprint-lint-tools` — the gate (C3)
+ *
+ * Front-door guide: docs/guides/tool-catalog-lint.md
+ */
+export { analyzeToolCatalog, catalogFromTools, confusabilityText, differentiationHint, DEFAULT_CONFUSABILITY_THRESHOLD, DEFAULT_WATCH_BAND, MOCK_EMBEDDER_CALIBRATION, } from './analyze.js';
+export { defaultStructuralRules, descriptionRule, enumInProseRule, optionalParamRule, saysWhatNotWhenRule, DEFAULT_OMISSION_CUES, DEFAULT_WHEN_CUES, } from './rules.js';
+export { formatToolCatalogReport } from './format.js';
+export { coerceCatalog, runToolLintCli } from './cli.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/tool-lint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/tool-lint/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,+BAA+B,EAC/B,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,GAIlB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAA4B,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAsB,MAAM,UAAU,CAAC"}