agentfootprint 6.24.0 → 6.25.0

package/dist/types/lib/tool-lint/analyze.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 type { Tool } from '../../core/tools.js';
+import type { AnalyzeToolCatalogOptions, CatalogTool, ToolCatalogReport } from './types.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 declare const DEFAULT_CONFUSABILITY_THRESHOLD = 0.85;
+/** Default `watchBand` below the threshold. */
+export declare 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 declare const MOCK_EMBEDDER_CALIBRATION: Readonly<{
+    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 declare function catalogFromTools(tools: readonly Tool[]): readonly CatalogTool[];
+/**
+ * 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 declare function confusabilityText(tool: CatalogTool): string;
+/**
+ * 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 declare function analyzeToolCatalog(tools: readonly CatalogTool[], options?: AnalyzeToolCatalogOptions): Promise<ToolCatalogReport>;
+/**
+ * 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 declare function differentiationHint(a: CatalogTool, b: CatalogTool): string;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/types/lib/tool-lint/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../../../src/lib/tool-lint/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,KAAK,EACV,yBAAyB,EACzB,WAAW,EAGX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB;;oEAEoE;AACpE,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD,+CAA+C;AAC/C,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB;;;EAGpC,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,WAAW,EAAE,CAM/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAO3D;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,iBAAiB,CAAC,CAyF5B;AA4CD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,MAAM,CA6B1E"}

package/dist/types/lib/tool-lint/cli.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 type { CatalogTool } from './types.js';
+export interface ToolLintCliIO {
+    readonly stdout: (line: string) => void;
+    readonly stderr: (line: string) => void;
+}
+/**
+ * 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 declare function coerceCatalog(json: unknown): readonly CatalogTool[];
+/**
+ * Run the lint CLI. Returns the exit code (never calls `process.exit` —
+ * the bin wrapper assigns it to `process.exitCode`).
+ */
+export declare function runToolLintCli(argv: readonly string[], io?: ToolLintCliIO): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/types/lib/tool-lint/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../../src/lib/tool-lint/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAqBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,WAAW,EAAE,CAuCnE;AAmDD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,aAKH,GACA,OAAO,CAAC,MAAM,CAAC,CAkDjB"}

package/dist/types/lib/tool-lint/format.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+import type { ToolCatalogReport } from './types.js';
+export interface FormatReportOptions {
+    /** How many ranked pairs to show in the relative-ordering section.
+     *  Default 10. 0 hides the section. */
+    readonly topPairs?: number;
+    /** How many WATCH pairs to print before eliding the rest (the report
+     *  object always carries all of them). Default 10. */
+    readonly maxWatch?: number;
+}
+export declare function formatToolCatalogReport(report: ToolCatalogReport, options?: FormatReportOptions): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/types/lib/tool-lint/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../../src/lib/tool-lint/format.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC;2CACuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;0DACsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA6DR"}

package/dist/types/lib/tool-lint/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 type { AnalyzeToolCatalogOptions, CatalogTool, ConfusablePairFinding, LintRule, LintSeverity, PairVerdict, SimilarityReport, StructuralFinding, ToolCatalogReport, } from './types.js';
+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, type DescriptionRuleOptions, type OptionalParamRuleOptions, type SaysWhatNotWhenRuleOptions, } from './rules.js';
+export { formatToolCatalogReport, type FormatReportOptions } from './format.js';
+export { coerceCatalog, runToolLintCli, type ToolLintCliIO } from './cli.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/tool-lint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/tool-lint/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,YAAY,EACV,yBAAyB,EACzB,WAAW,EACX,qBAAqB,EACrB,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,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,EACjB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,GAChC,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/types/lib/tool-lint/rules.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Structural lint rules (RFC-002 block C2) — the PLUGGABLE RULE PACK.
+ *
+ * Pattern: Strategy list — each rule is a plain `{ id, check }` object;
+ *          `defaultStructuralRules` is OUR pack, and consumers add /
+ *          remove / replace freely via `AnalyzeToolCatalogOptions.rules`.
+ *          Parameterizable rules ship as FACTORIES (`descriptionRule`,
+ *          `saysWhatNotWhenRule`, …) returning a configured `LintRule`.
+ * Role:    `src/lib/tool-lint/` leaf. Pure functions over `CatalogTool`;
+ *          no embedder, no I/O.
+ *
+ * Every rule encodes a FIELD FINDING from real catalogs (the Neo SAN
+ * triage agent's 29-tool catalog was the seed corpus):
+ *
+ *   1. description-missing-or-short — the model can only guess from a name.
+ *   2. says-what-not-when — describes WHAT the tool returns but gives the
+ *      model no cue for WHEN to pick it over a sibling (the #1 cause of
+ *      twin-tool confusion: 'get_fcns_database' vs 'influx_get_fcns_database').
+ *   3. enum-in-prose — string params whose legal values are listed in prose
+ *      ("avg_iops | peak_iops | mbps") instead of a JSON-Schema `enum` the
+ *      model (and validators, see #9 tool-args validation) can act on.
+ *   4. optional-param-undocumented — optional params whose omission has
+ *      meaning (fabric-wide sweep vs one switch) but whose schema never
+ *      says so; the model can't reason about leaving them out.
+ *
+ * Honest claim: these are token/regex HEURISTICS. They flag review
+ * prompts, not certainties — expect (rare) false positives and tune via
+ * the factory options instead of deleting the rule.
+ */
+import type { LintRule } from './types.js';
+export interface DescriptionRuleOptions {
+    /** Descriptions shorter than this (in chars) get a `warn`. Default 40. */
+    readonly minChars?: number;
+}
+/**
+ * Missing description → `error` (the model can only guess from the
+ * name). Present but shorter than `minChars` → `warn` (too short to
+ * differentiate from siblings).
+ */
+export declare function descriptionRule(options?: DescriptionRuleOptions): LintRule;
+/** RFC-002 C2 heuristic cue list — temporal/conditional words whose
+ *  presence suggests the description says WHEN to use the tool. */
+export declare const DEFAULT_WHEN_CUES: readonly string[];
+export interface SaysWhatNotWhenRuleOptions {
+    /** Cue tokens (whole-word, case-insensitive). Default `DEFAULT_WHEN_CUES`. */
+    readonly cueTokens?: readonly string[];
+}
+/**
+ * A description with NO temporal/conditional cue token usually describes
+ * WHAT the tool returns but never WHEN to pick it — the #1 cause of
+ * twin-tool confusion. Heuristic by design: tune `cueTokens` rather than
+ * dropping the rule. Skips tools with no description (rule 1's finding).
+ */
+export declare function saysWhatNotWhenRule(options?: SaysWhatNotWhenRuleOptions): LintRule;
+/**
+ * A string param whose description enumerates its legal values in prose
+ * (pipe-separated literals, or comma lists behind "one of"/"allowed
+ * values") should declare a JSON-Schema `enum` instead — the model picks
+ * reliably from enums, and arg validators (#9) can enforce them. The
+ * field case: Neo's `influx_get_port_ranking.metric` =
+ * `"avg_iops | peak_iops | mbps"`.
+ */
+export declare function enumInProseRule(): LintRule;
+/** Words that signal the description DOES say what omission means. */
+export declare const DEFAULT_OMISSION_CUES: readonly string[];
+export interface OptionalParamRuleOptions {
+    /** Cue tokens that satisfy the rule. Default `DEFAULT_OMISSION_CUES`. */
+    readonly omissionCues?: readonly string[];
+}
+/**
+ * An optional param's omission usually MEANS something (Neo:
+ * `influx_get_interface_counters` without `switch_name` = fabric-wide
+ * sweep) — but the model can only reason about leaving a param out if
+ * the description says so. No description at all, or one with no
+ * omission cue, gets a `warn`.
+ */
+export declare function optionalParamRule(options?: OptionalParamRuleOptions): LintRule;
+/**
+ * OUR rule pack, built with default options. Compose your own:
+ *
+ *   rules: [...defaultStructuralRules, myRule]                 // add
+ *   rules: defaultStructuralRules.filter(r => r.id !== '…')    // remove
+ *   rules: [descriptionRule({ minChars: 80 }), …]              // re-tune
+ */
+export declare const defaultStructuralRules: readonly LintRule[];
+//# sourceMappingURL=rules.d.ts.map

package/dist/types/lib/tool-lint/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../../src/lib/tool-lint/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAe,QAAQ,EAAqB,MAAM,YAAY,CAAC;AA2C3E,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,QAAQ,CA6B9E;AAID;mEACmE;AACnE,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAO9C,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,QAAQ,CAqBtF;AAcD;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,QAAQ,CA4B1C;AAgBD,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAalD,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,QAAQ,CA+BlF;AAID;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,QAAQ,EAKrD,CAAC"}

package/dist/types/lib/tool-lint/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * tool-lint types — the tool-catalog confusability lint contract
+ * (RFC-002 tier 1, blocks C1–C3).
+ *
+ * Pattern: Strategy seam (the plug-and-play meta-pattern) — the frame
+ *          and rule engine are the library's; the embedder, thresholds,
+ *          and structural rule pack are all consumer-injected, with our
+ *          defaults. Exactly like NarrativeFormatter / reliability /
+ *          permission / commentary strategies.
+ * Role:    `src/lib/` leaf module. ZERO stack buy-in: input is a plain
+ *          `{ name, description?, inputSchema? }[]` — any OpenAI /
+ *          Anthropic / LangChain / MCP tool list normalizes to it
+ *          (see `coerceCatalog`). The library's own `Tool[]` adapts via
+ *          `catalogFromTools`.
+ *
+ * ## Honest claim (RFC-002 §2)
+ *
+ * Confusability here is embedding geometry over what the model READS
+ * (tool name + description) — a deterministic heuristic for "could the
+ * model mix these up", never a measurement of any model's actual
+ * selection function. Tier 3 (choice-entropy sampling) validates the
+ * proxy; until then treat verdicts as review prompts, not ground truth.
+ */
+import type { Embedder, SimilarityPair } from '../influence-core/index.js';
+/**
+ * One tool as the lint sees it — the minimal, framework-agnostic shape.
+ * `inputSchema` is a JSON Schema object (the same one the LLM sees);
+ * structural rules read `properties` / `required` / `enum` from it.
+ */
+export interface CatalogTool {
+    readonly name: string;
+    readonly description?: string;
+    /** JSON Schema for the tool's arguments (`type: 'object'` shape). */
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+}
+/** Verdict for one description pair from the similarity analysis. */
+export type PairVerdict = 'confusable' | 'watch';
+/** One flagged pair: two tools the model could plausibly mix up. */
+export interface ConfusablePairFinding {
+    readonly kind: PairVerdict;
+    /** Tool names (input order: `a` has the lower catalog index). */
+    readonly a: string;
+    readonly b: string;
+    /** cosine(embed(a), embed(b)) over `confusabilityText` of each tool. */
+    readonly similarity: number;
+    /**
+     * Heuristic suggestion for the DIFFERENTIATING AXIS — what to make
+     * explicit in the descriptions so the model can tell them apart
+     * (e.g. "names differ only by 'influx' — say WHEN to use each").
+     */
+    readonly hint: string;
+}
+/** Severity of a structural finding. `error` fails the gate by default. */
+export type LintSeverity = 'error' | 'warn';
+/** One structural finding from a `LintRule`. */
+export interface StructuralFinding {
+    /** Id of the rule that produced this finding. */
+    readonly rule: string;
+    /** Name of the offending tool. */
+    readonly tool: string;
+    readonly severity: LintSeverity;
+    readonly message: string;
+    /** Offending parameter name, when the finding is param-scoped. */
+    readonly param?: string;
+    /** Concrete fix suggestion (e.g. the JSON-Schema `enum` to add). */
+    readonly suggestion?: string;
+}
+/**
+ * One pluggable structural rule. Rules are plain objects — add your own
+ * to `rules` in `analyzeToolCatalog` options, or filter the exported
+ * `defaultStructuralRules` to remove ours.
+ */
+export interface LintRule {
+    /** Stable id, kebab-case (shows on findings + CLI output). */
+    readonly id: string;
+    /** Inspect ONE tool (with the whole catalog for context) and return
+     *  zero or more findings. Must not throw on weird-but-valid input. */
+    check(tool: CatalogTool, catalog: readonly CatalogTool[]): readonly StructuralFinding[];
+}
+export interface AnalyzeToolCatalogOptions {
+    /**
+     * Injected embedder for the confusability analysis. OMITTED → the
+     * similarity analysis is skipped (structural rules still run) and
+     * `report.similarity.analyzed` is false.
+     *
+     * Wrap in an `EmbeddingCache` (from `agentfootprint/observe`) so
+     * catalog descriptions embed once across lint runs — keyed by content
+     * hash, so unchanged descriptions cost nothing on re-lint.
+     */
+    readonly embedder?: Embedder;
+    /**
+     * Pairs with similarity ≥ this are `confusable`. Default 0.85 — a
+     * STARTING point calibrated for real sentence embedders (where
+     * unrelated tool descriptions typically land 0.3–0.7).
+     *
+     * ⚠ Per-embedder calibration is REQUIRED (RFC-002 §3): absolute
+     * cosine ranges differ by embedder. The test/demo `mockEmbedder`
+     * (character-frequency) compresses unrelated prose into ~0.85–0.97,
+     * so with the mock use `MOCK_EMBEDDER_CALIBRATION` and trust only
+     * RELATIVE ordering of pairs, never absolute verdicts.
+     */
+    readonly confusabilityThreshold?: number;
+    /**
+     * Pairs within this band BELOW the threshold are `watch` (advisory —
+     * never fail the gate). Default 0.05.
+     */
+    readonly watchBand?: number;
+    /**
+     * The structural rule pack. Default `defaultStructuralRules`.
+     * Add/remove freely — rules are plain `{ id, check }` objects.
+     */
+    readonly rules?: readonly LintRule[];
+    /**
+     * Which structural severity fails the gate (`report.ok`).
+     * Default 'error' — warnings are advisory. 'warn' = strict mode.
+     */
+    readonly failOn?: LintSeverity;
+    /** Abort signal threaded to the embedder (network backends). */
+    readonly signal?: AbortSignal;
+}
+/** The similarity section of a report. */
+export interface SimilarityReport {
+    /** False when no embedder was supplied — similarity was skipped. */
+    readonly analyzed: boolean;
+    readonly confusable: readonly ConfusablePairFinding[];
+    readonly watch: readonly ConfusablePairFinding[];
+    /**
+     * EVERY pair ranked by similarity, descending — the relative-ordering
+     * view that stays meaningful under ANY embedder (including the mock).
+     * Empty when `analyzed` is false.
+     */
+    readonly ranked: readonly SimilarityPair[];
+    readonly thresholds: {
+        readonly confusabilityThreshold: number;
+        readonly watchBand: number;
+    };
+}
+/** The lint report — `ok` is the CI-gateable verdict. */
+export interface ToolCatalogReport {
+    /**
+     * True when there are no confusable pairs AND no structural findings
+     * at/above `failOn` severity. The CI gate: exit non-zero on `!ok`.
+     */
+    readonly ok: boolean;
+    readonly toolCount: number;
+    readonly similarity: SimilarityReport;
+    readonly structural: readonly StructuralFinding[];
+    readonly summary: {
+        readonly confusable: number;
+        readonly watch: number;
+        readonly errors: number;
+        readonly warnings: number;
+    };
+}
+export type { Embedder, SimilarityPair };
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/tool-lint/types.d.ts.map

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

package/dist/types/observe.d.ts

@@ -52,4 +52,6 @@ export { agentThinkingTrace, type AgentThinkingTraceHandle, type AgentThinkingTr
 export { typedEmit } from './recorders/core/typedEmit.js';
 export { adaptWeights, averageRelevancy, compositeScore, contentHash, DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, EmbeddingCache, embeddingCache, finalAnswerSimilarity, pairwiseSimilarity, persistence, scoreInfluence, scoreMargin, structuralProximity, type CandidateScore, type Embedder, type EmbeddingCacheOptions, type EmbeddingCacheStats, type EvidenceInput, type InfluenceScore, type InfluenceWeights, type MarginCandidate, type MarginResult, type PairwiseSimilarityArgs, type PairwiseSimilarityResult, type ScoreInfluenceArgs, type ScoreMarginArgs, type SignalScores, type SimilarityItem, type SimilarityPair, } from './lib/influence-core/index.js';
 export { callTraceTool, TOOLPACK_HARD_CAPS, traceToolpack, type TraceToolpackArtifacts, type TraceToolpackOptions, } from './lib/trace-toolpack/index.js';
+export { analyzeToolCatalog, catalogFromTools, coerceCatalog, confusabilityText, DEFAULT_CONFUSABILITY_THRESHOLD, DEFAULT_OMISSION_CUES, DEFAULT_WATCH_BAND, DEFAULT_WHEN_CUES, defaultStructuralRules, descriptionRule, differentiationHint, enumInProseRule, formatToolCatalogReport, MOCK_EMBEDDER_CALIBRATION, optionalParamRule, runToolLintCli, saysWhatNotWhenRule, type AnalyzeToolCatalogOptions, type CatalogTool, type ConfusablePairFinding, type DescriptionRuleOptions, type FormatReportOptions, type LintRule, type LintSeverity, type OptionalParamRuleOptions, type PairVerdict, type SaysWhatNotWhenRuleOptions, type SimilarityReport, type StructuralFinding, type ToolCatalogReport, type ToolLintCliIO, } from './lib/tool-lint/index.js';
+export { buildChoiceContext, toolChoiceRecorder, type OfferedTool, type ToolChoiceCall, type ToolChoiceRecorderHandle, type ToolChoiceRecorderOptions, type ToolChoiceSkipReason, type ToolChoiceSummary, } from './recorders/observability/ToolChoiceRecorder.js';
 //# sourceMappingURL=observe.d.ts.map

package/dist/types/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"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"}

package/dist/types/recorders/observability/ToolChoiceRecorder.d.ts

@@ -0,0 +1,165 @@
+/**
+ * toolChoiceRecorder — runtime tool-choice margins (RFC-002 tier 2,
+ * blocks C4–C6).
+ *
+ * Per LLM call that OFFERED tools, this recorder captures the menu the
+ * model saw (`stream.llm_start.tools`), what it actually invoked
+ * (`stream.tool_start`), and the choice context — then, LAZILY on first
+ * read, ranks the offered candidates against that context via
+ * influence-core's `scoreMargin` (C4):
+ *
+ *   margin = score(best chosen) − score(best non-chosen)
+ *
+ * Small margin (`narrow`, < `marginThreshold`, default 0.05) = the
+ * choice was a close call under the proxy. Top-scored candidate not
+ * among the chosen (`proxyDisagreement`) is ALWAYS flagged — either a
+ * proxy miss or a genuinely surprising model choice; both are exactly
+ * what a debugger wants surfaced.
+ *
+ * ## The choice context (C4 — what is embedded, precisely)
+ *
+ * `buildChoiceContext` assembles the SAME two slots the model's
+ * tool-selection reasoning ran on:
+ *
+ *   INCLUDED
+ *   1. the user message of the current turn (`agent.turn_start.userPrompt`)
+ *      — the task the model is choosing a tool FOR (first
+ *      `maxSlotChars` chars: the head states the task);
+ *   2. the latest assistant reasoning text — the most recent
+ *      `stream.llm_end.content` of this turn, when present (last
+ *      `maxSlotChars` chars: the tail is where "what next" lives).
+ *      Iteration 1 has no assistant text; the slot is omitted.
+ *
+ *   EXCLUDED (deliberately)
+ *   - the system prompt: constant across every call of the run — zero
+ *     per-call discrimination, it only dilutes the embedding;
+ *   - older history turns: recency dominates tool choice, and the full
+ *     transcript grows the embedding cost linearly with run length;
+ *   - raw tool results: the model reads them, but their distilled
+ *     effect on the NEXT choice is the assistant's own reasoning text,
+ *     which IS included; raw payloads skew the embedding toward data
+ *     vocabulary (the honest-proxy discipline: mirror the
+ *     decision-relevant text, not every visible byte);
+ *   - tool schemas: those are the CANDIDATES being ranked, not context.
+ *
+ * Candidate text per offered tool = `confusabilityText` (tokenized name
+ * + description) — the SAME construction the catalog lint (C1) embeds,
+ * so build-time confusability and runtime margins measure one geometry.
+ *
+ * ## Laziness (C5)
+ *
+ * Event hooks only RECORD (string copies into a KeyedStore). The
+ * embedder runs on the first `getCalls()` / `getFlagged()` /
+ * `getSummary()` — embedding I/O NEVER rides the hot path, even when
+ * the recorder is attached inline. Scores memoize per entry. Attach
+ * with `{ delivery: 'deferred' }` (footprintjs RFC-001) to move the
+ * bookkeeping off the hot path too — it is a normal CombinedRecorder.
+ *
+ * Pattern: CombinedRecorder (Convention 1 — single purpose: tool-choice
+ *          margin evidence). Owns a `KeyedStore<ToolChoiceEntry>` keyed
+ *          by the LLM call's `runtimeStageId`. Convention 4: resets on a
+ *          new `runId` via `FlowRecorder.onRunStart`.
+ * Role:    Tier-3 /observe recorder. Attach via `Agent.create(...)
+ *          .recorder(handle)` or `executor.attachCombinedRecorder`.
+ *
+ * Honest claim (RFC-002 §2): margins are embedding geometry between the
+ * context and tool descriptions — a deterministic PROXY for the model's
+ * selection function, never "the model chose because". Tier 3
+ * (choice-entropy sampling) validates the proxy.
+ */
+import type { EmitEvent } from 'footprintjs';
+import { type Embedder, type MarginResult } from '../../lib/influence-core/index.js';
+/** Minimal structural slice of footprintjs's FlowRunEvent (runId is all
+ *  we read — Convention 4). */
+interface RunBoundaryEvent {
+    readonly traversalContext?: {
+        readonly runId?: string;
+    };
+}
+/** One offered tool, as the model saw it on `llm_start`. */
+export interface OfferedTool {
+    readonly name: string;
+    readonly description?: string;
+}
+/** Why an entry has no margin. */
+export type ToolChoiceSkipReason = 
+/** The model answered without invoking any tool — no choice to score. */
+'nothing-chosen'
+/** A chosen tool name was not in the offered catalog (wiring anomaly —
+ *  surfaced, not silently massaged). */
+ | 'chosen-not-offered';
+/** One LLM call that offered tools — the recorder's public row shape. */
+export interface ToolChoiceCall {
+    /** runtimeStageId of the LLM-call stage (the KeyedStore key). */
+    readonly runtimeStageId: string;
+    readonly iteration: number;
+    /** The catalog the model saw, in request order. */
+    readonly offered: readonly OfferedTool[];
+    /** Unique tool names actually invoked, in first-call order. */
+    readonly chosen: readonly string[];
+    /** Every invocation (parallel calls + repeat calls of one tool visible). */
+    readonly toolCallIds: readonly string[];
+    /** The choice context that was (or will be) embedded. */
+    readonly contextText: string;
+    /** Ranked scores + margin + flags. Undefined until scored, or when
+     *  `skipped` says why it never will be. */
+    readonly margin?: MarginResult;
+    readonly skipped?: ToolChoiceSkipReason;
+}
+/** Run-summary counts (C6). */
+export interface ToolChoiceSummary {
+    /** LLM calls that offered tools (= recorded entries). */
+    readonly llmCallsWithTools: number;
+    /** Entries where the model invoked at least one tool. */
+    readonly choices: number;
+    /** Entries with a computed `margin`. */
+    readonly scored: number;
+    /** narrow OR proxy-disagreement. */
+    readonly flagged: number;
+    readonly narrow: number;
+    readonly proxyDisagreement: number;
+    /** Entries that will never score (`skipped` set). */
+    readonly skipped: number;
+}
+export interface ToolChoiceRecorderOptions {
+    /**
+     * Injected embedder — runs ONLY on first read (lazy). Wrap in
+     * `embeddingCache(...)` (agentfootprint/observe) so repeated tool
+     * descriptions embed once across calls and runs.
+     */
+    readonly embedder: Embedder;
+    /** Margins below this flag `narrow`. Default 0.05 (RFC-002 §4). */
+    readonly marginThreshold?: number;
+    /** Per-slot cap for the choice context. Default 2000 chars. */
+    readonly maxSlotChars?: number;
+    /** Recorder id (default 'tool-choice'). */
+    readonly id?: string;
+}
+export interface ToolChoiceRecorderHandle {
+    readonly id: string;
+    /** All recorded LLM calls (scored on demand — first call runs the
+     *  embedder; results memoize). Entries still open mid-run stay
+     *  unscored until they close. */
+    getCalls(): Promise<readonly ToolChoiceCall[]>;
+    /** Calls whose choice was fragile: `narrow` margin OR
+     *  `proxyDisagreement` (always flagged) — C6. */
+    getFlagged(): Promise<readonly ToolChoiceCall[]>;
+    /** Run-summary counts (C6). Scores pending entries first. */
+    getSummary(): Promise<ToolChoiceSummary>;
+    clear(): void;
+    onEmit(event: EmitEvent): void;
+    onRunStart(event: RunBoundaryEvent): void;
+    onRunEnd(event: RunBoundaryEvent): void;
+    onRunFailed(event: RunBoundaryEvent): void;
+}
+/** C4: the precise choice-context construction (see module JSDoc for the
+ *  include/exclude rationale). Exported so consumers can reproduce it. */
+export declare function buildChoiceContext(args: {
+    readonly userPrompt: string;
+    readonly latestAssistantText?: string;
+    readonly maxSlotChars?: number;
+}): string;
+/** Build the tool-choice margin recorder (C5). */
+export declare function toolChoiceRecorder(options: ToolChoiceRecorderOptions): ToolChoiceRecorderHandle;
+export {};
+//# sourceMappingURL=ToolChoiceRecorder.d.ts.map

package/dist/types/recorders/observability/ToolChoiceRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolChoiceRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/ToolChoiceRecorder.ts"],"names":[],"mappings":"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"}