agentfootprint 6.24.0 → 6.26.0

package/dist/lib/tool-lint/rules.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultStructuralRules = exports.optionalParamRule = exports.DEFAULT_OMISSION_CUES = exports.enumInProseRule = exports.saysWhatNotWhenRule = exports.DEFAULT_WHEN_CUES = exports.descriptionRule = void 0;
+/** Read `properties` / `required` out of a JSON-Schema-ish inputSchema,
+ *  tolerating absent or malformed shapes (rules must never throw). */
+function readObjectSchema(tool) {
+    const schema = tool.inputSchema;
+    const props = schema?.properties;
+    const properties = props !== null && typeof props === 'object'
+        ? Object.entries(props).filter((entry) => entry[1] !== null && typeof entry[1] === 'object')
+        : [];
+    const required = new Set(Array.isArray(schema?.required) ? schema.required.filter((r) => typeof r === 'string') : []);
+    return { properties, required };
+}
+function hasWholeWord(text, word) {
+    return new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(word.toLowerCase())}(?:[^a-z0-9]|$)`).test(text.toLowerCase());
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Missing description → `error` (the model can only guess from the
+ * name). Present but shorter than `minChars` → `warn` (too short to
+ * differentiate from siblings).
+ */
+function descriptionRule(options = {}) {
+    const minChars = options.minChars ?? 40;
+    return {
+        id: 'description-missing-or-short',
+        check(tool) {
+            const description = tool.description?.trim() ?? '';
+            if (description.length === 0) {
+                return [
+                    {
+                        rule: 'description-missing-or-short',
+                        tool: tool.name,
+                        severity: 'error',
+                        message: 'tool has no description — the model can only guess from the name',
+                    },
+                ];
+            }
+            if (description.length < minChars) {
+                return [
+                    {
+                        rule: 'description-missing-or-short',
+                        tool: tool.name,
+                        severity: 'warn',
+                        message: `description is ${description.length} chars (< ${minChars}) — too short to differentiate this tool from its siblings`,
+                    },
+                ];
+            }
+            return [];
+        },
+    };
+}
+exports.descriptionRule = descriptionRule;
+// ── Rule 2 — says WHAT, not WHEN ─────────────────────────────────────
+/** RFC-002 C2 heuristic cue list — temporal/conditional words whose
+ *  presence suggests the description says WHEN to use the tool. */
+exports.DEFAULT_WHEN_CUES = [
+    'for',
+    'when',
+    'after',
+    'first',
+    'fallback',
+    'only',
+];
+/**
+ * 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).
+ */
+function saysWhatNotWhenRule(options = {}) {
+    const cues = options.cueTokens ?? exports.DEFAULT_WHEN_CUES;
+    return {
+        id: 'says-what-not-when',
+        check(tool) {
+            const description = tool.description?.trim() ?? '';
+            if (description.length === 0)
+                return [];
+            if (cues.some((cue) => hasWholeWord(description, cue)))
+                return [];
+            return [
+                {
+                    rule: 'says-what-not-when',
+                    tool: tool.name,
+                    severity: 'warn',
+                    message: 'description says WHAT the tool returns but gives no cue for WHEN to use it ' +
+                        `(no ${cues.map((c) => `'${c}'`).join('/')}) — add the choice condition, ` +
+                        'e.g. "Use when …" / "Call FIRST" / "FALLBACK if …"',
+                },
+            ];
+        },
+    };
+}
+exports.saysWhatNotWhenRule = saysWhatNotWhenRule;
+// ── Rule 3 — enum described in prose ─────────────────────────────────
+const IDENT = '[A-Za-z][A-Za-z0-9_.-]*';
+/** `avg_iops | peak_iops | mbps` — two or more pipe-separated literals. */
+const PIPE_LIST = new RegExp(`(${IDENT})(?:\\s*\\|\\s*(?:${IDENT}))+`);
+/** `one of: red, green, blue` — comma lists only behind an explicit
+ *  values marker, so free-form examples ("e.g. 1h, 24h") don't flag. */
+const COMMA_LIST = new RegExp(`(?:one of|allowed values?|valid values?|options|values)\\s*:?\\s*(${IDENT}(?:\\s*,\\s*${IDENT})+)`, 'i');
+/**
+ * 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"`.
+ */
+function enumInProseRule() {
+    return {
+        id: 'enum-in-prose',
+        check(tool) {
+            const findings = [];
+            const { properties } = readObjectSchema(tool);
+            for (const [param, prop] of properties) {
+                if (prop.enum !== undefined)
+                    continue;
+                if (prop.type !== undefined && prop.type !== 'string')
+                    continue;
+                const description = typeof prop.description === 'string' ? prop.description : '';
+                if (description.length === 0)
+                    continue;
+                const literals = extractProseLiterals(description);
+                if (literals === undefined)
+                    continue;
+                findings.push({
+                    rule: 'enum-in-prose',
+                    tool: tool.name,
+                    severity: 'warn',
+                    param,
+                    message: `param '${param}' lists its legal values in prose ("${description.slice(0, 80)}") — declare them as a JSON-Schema enum so the model picks reliably`,
+                    suggestion: `"enum": ${JSON.stringify(literals)}`,
+                });
+            }
+            return findings;
+        },
+    };
+}
+exports.enumInProseRule = enumInProseRule;
+function extractProseLiterals(description) {
+    const pipe = PIPE_LIST.exec(description);
+    if (pipe) {
+        return pipe[0].split('|').map((v) => v.trim());
+    }
+    const comma = COMMA_LIST.exec(description);
+    if (comma) {
+        return comma[1].split(',').map((v) => v.trim());
+    }
+    return undefined;
+}
+// ── Rule 4 — optional param whose omission is undocumented ───────────
+/** Words that signal the description DOES say what omission means. */
+exports.DEFAULT_OMISSION_CUES = [
+    'optional',
+    'default',
+    'defaults',
+    'omit',
+    'omitted',
+    'if not',
+    'when not',
+    'absent',
+    'all',
+    'entire',
+    'every',
+    'fallback',
+];
+/**
+ * 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`.
+ */
+function optionalParamRule(options = {}) {
+    const cues = options.omissionCues ?? exports.DEFAULT_OMISSION_CUES;
+    return {
+        id: 'optional-param-undocumented',
+        check(tool) {
+            const findings = [];
+            const { properties, required } = readObjectSchema(tool);
+            for (const [param, prop] of properties) {
+                if (required.has(param))
+                    continue;
+                const description = typeof prop.description === 'string' ? prop.description.trim() : '';
+                if (description.length === 0) {
+                    findings.push({
+                        rule: 'optional-param-undocumented',
+                        tool: tool.name,
+                        severity: 'warn',
+                        param,
+                        message: `optional param '${param}' has no description — say what happens when it is omitted (a default? a broader scope?)`,
+                    });
+                }
+                else if (!cues.some((cue) => hasWholeWord(description, cue))) {
+                    findings.push({
+                        rule: 'optional-param-undocumented',
+                        tool: tool.name,
+                        severity: 'warn',
+                        param,
+                        message: `optional param '${param}' is described but never says what omission means — add e.g. "optional — defaults to …" / "omit for all …"`,
+                    });
+                }
+            }
+            return findings;
+        },
+    };
+}
+exports.optionalParamRule = optionalParamRule;
+// ── The default pack ─────────────────────────────────────────────────
+/**
+ * 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
+ */
+exports.defaultStructuralRules = [
+    descriptionRule(),
+    saysWhatNotWhenRule(),
+    enumInProseRule(),
+    optionalParamRule(),
+];
+//# sourceMappingURL=rules.js.map

package/dist/lib/tool-lint/rules.js.map

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

package/dist/lib/tool-lint/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/lib/tool-lint/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/tool-lint/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/observe.js

@@ -32,7 +32,8 @@
  * directly; Tier 3 dashboards are opt-in.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.traceToolpack = exports.TOOLPACK_HARD_CAPS = exports.callTraceTool = exports.structuralProximity = exports.scoreMargin = exports.scoreInfluence = exports.persistence = exports.pairwiseSimilarity = exports.finalAnswerSimilarity = exports.embeddingCache = exports.EmbeddingCache = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = exports.contentHash = exports.compositeScore = exports.averageRelevancy = exports.adaptWeights = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.skillRecorder = exports.permissionRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
+exports.bisectCulprits = exports.applyAblations = exports.ablationForSuspect = exports.traceToolpack = exports.TOOLPACK_HARD_CAPS = exports.callTraceTool = exports.structuralProximity = exports.scoreMargin = exports.scoreInfluence = exports.persistence = exports.pairwiseSimilarity = exports.finalAnswerSimilarity = exports.embeddingCache = exports.EmbeddingCache = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = exports.contentHash = exports.compositeScore = exports.averageRelevancy = exports.adaptWeights = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.skillRecorder = exports.permissionRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
+exports.toolChoiceRecorder = exports.buildChoiceContext = exports.saysWhatNotWhenRule = exports.runToolLintCli = exports.optionalParamRule = exports.MOCK_EMBEDDER_CALIBRATION = exports.formatToolCatalogReport = exports.enumInProseRule = exports.differentiationHint = exports.descriptionRule = exports.defaultStructuralRules = exports.DEFAULT_WHEN_CUES = exports.DEFAULT_WATCH_BAND = exports.DEFAULT_OMISSION_CUES = exports.DEFAULT_CONFUSABILITY_THRESHOLD = exports.confusabilityText = exports.coerceCatalog = exports.catalogFromTools = exports.analyzeToolCatalog = exports.verdictFor = exports.suspectLabel = exports.stepOutputText = exports.runAblationProbe = exports.probeFlipped = exports.localizeContextBug = exports.llmEdgeWeigher = exports.llmCallIdsFromEvents = exports.formatContextBugReport = exports.defaultSuspectClassifier = exports.defaultOutcomeComparator = exports.CONTEXT_BISECT_DEFAULTS = void 0;
 // Tier 1 — context + stream
 var ContextRecorder_js_1 = require("./recorders/core/ContextRecorder.js");
 Object.defineProperty(exports, "ContextRecorder", { enumerable: true, get: function () { return ContextRecorder_js_1.ContextRecorder; } });
@@ -120,4 +121,58 @@ var index_js_2 = require("./lib/trace-toolpack/index.js");
 Object.defineProperty(exports, "callTraceTool", { enumerable: true, get: function () { return index_js_2.callTraceTool; } });
 Object.defineProperty(exports, "TOOLPACK_HARD_CAPS", { enumerable: true, get: function () { return index_js_2.TOOLPACK_HARD_CAPS; } });
 Object.defineProperty(exports, "traceToolpack", { enumerable: true, get: function () { return index_js_2.traceToolpack; } });
+// Contextual-bug localizer (RFC-003 Part B, D7–D9) — "git bisect for
+// context". Assembly: footprintjs causal DAG (control edges + honesty
+// markers + EdgeWeigher) × influence-core scoring (D6) × consumer-run
+// counterfactual ablation. §B2 claim tiers: scores/weights are
+// embedding-geometry PROXIES; ablation verdicts are the ONLY causal
+// claims; slice completeness is bounded by tracking — and says so.
+var index_js_3 = require("./lib/context-bisect/index.js");
+Object.defineProperty(exports, "ablationForSuspect", { enumerable: true, get: function () { return index_js_3.ablationForSuspect; } });
+Object.defineProperty(exports, "applyAblations", { enumerable: true, get: function () { return index_js_3.applyAblations; } });
+Object.defineProperty(exports, "bisectCulprits", { enumerable: true, get: function () { return index_js_3.bisectCulprits; } });
+Object.defineProperty(exports, "CONTEXT_BISECT_DEFAULTS", { enumerable: true, get: function () { return index_js_3.CONTEXT_BISECT_DEFAULTS; } });
+Object.defineProperty(exports, "defaultOutcomeComparator", { enumerable: true, get: function () { return index_js_3.defaultOutcomeComparator; } });
+Object.defineProperty(exports, "defaultSuspectClassifier", { enumerable: true, get: function () { return index_js_3.defaultSuspectClassifier; } });
+Object.defineProperty(exports, "formatContextBugReport", { enumerable: true, get: function () { return index_js_3.formatContextBugReport; } });
+Object.defineProperty(exports, "llmCallIdsFromEvents", { enumerable: true, get: function () { return index_js_3.llmCallIdsFromEvents; } });
+Object.defineProperty(exports, "llmEdgeWeigher", { enumerable: true, get: function () { return index_js_3.llmEdgeWeigher; } });
+Object.defineProperty(exports, "localizeContextBug", { enumerable: true, get: function () { return index_js_3.localizeContextBug; } });
+Object.defineProperty(exports, "probeFlipped", { enumerable: true, get: function () { return index_js_3.probeFlipped; } });
+Object.defineProperty(exports, "runAblationProbe", { enumerable: true, get: function () { return index_js_3.runAblationProbe; } });
+Object.defineProperty(exports, "stepOutputText", { enumerable: true, get: function () { return index_js_3.stepOutputText; } });
+Object.defineProperty(exports, "suspectLabel", { enumerable: true, get: function () { return index_js_3.suspectLabel; } });
+Object.defineProperty(exports, "verdictFor", { enumerable: true, get: function () { return index_js_3.verdictFor; } });
+// Tool-catalog confusability lint (RFC-002 tier 1, C1–C3) — build-time,
+// CI-gateable, framework-agnostic: plain { name, description?, inputSchema? }
+// tools in (OpenAI/Anthropic/MCP lists coerce via coerceCatalog; the
+// library's Tool[] via catalogFromTools), a report with a gateable `ok`
+// out. Pluggable structural rule pack; thresholds + embedder consumer-
+// injected with our defaults. Bin: `agentfootprint-lint-tools`.
+// Front door: docs/guides/tool-catalog-lint.md.
+var index_js_4 = require("./lib/tool-lint/index.js");
+Object.defineProperty(exports, "analyzeToolCatalog", { enumerable: true, get: function () { return index_js_4.analyzeToolCatalog; } });
+Object.defineProperty(exports, "catalogFromTools", { enumerable: true, get: function () { return index_js_4.catalogFromTools; } });
+Object.defineProperty(exports, "coerceCatalog", { enumerable: true, get: function () { return index_js_4.coerceCatalog; } });
+Object.defineProperty(exports, "confusabilityText", { enumerable: true, get: function () { return index_js_4.confusabilityText; } });
+Object.defineProperty(exports, "DEFAULT_CONFUSABILITY_THRESHOLD", { enumerable: true, get: function () { return index_js_4.DEFAULT_CONFUSABILITY_THRESHOLD; } });
+Object.defineProperty(exports, "DEFAULT_OMISSION_CUES", { enumerable: true, get: function () { return index_js_4.DEFAULT_OMISSION_CUES; } });
+Object.defineProperty(exports, "DEFAULT_WATCH_BAND", { enumerable: true, get: function () { return index_js_4.DEFAULT_WATCH_BAND; } });
+Object.defineProperty(exports, "DEFAULT_WHEN_CUES", { enumerable: true, get: function () { return index_js_4.DEFAULT_WHEN_CUES; } });
+Object.defineProperty(exports, "defaultStructuralRules", { enumerable: true, get: function () { return index_js_4.defaultStructuralRules; } });
+Object.defineProperty(exports, "descriptionRule", { enumerable: true, get: function () { return index_js_4.descriptionRule; } });
+Object.defineProperty(exports, "differentiationHint", { enumerable: true, get: function () { return index_js_4.differentiationHint; } });
+Object.defineProperty(exports, "enumInProseRule", { enumerable: true, get: function () { return index_js_4.enumInProseRule; } });
+Object.defineProperty(exports, "formatToolCatalogReport", { enumerable: true, get: function () { return index_js_4.formatToolCatalogReport; } });
+Object.defineProperty(exports, "MOCK_EMBEDDER_CALIBRATION", { enumerable: true, get: function () { return index_js_4.MOCK_EMBEDDER_CALIBRATION; } });
+Object.defineProperty(exports, "optionalParamRule", { enumerable: true, get: function () { return index_js_4.optionalParamRule; } });
+Object.defineProperty(exports, "runToolLintCli", { enumerable: true, get: function () { return index_js_4.runToolLintCli; } });
+Object.defineProperty(exports, "saysWhatNotWhenRule", { enumerable: true, get: function () { return index_js_4.saysWhatNotWhenRule; } });
+// Tool-choice margin recorder (RFC-002 tier 2, C4–C6) — per LLM call,
+// ranks the OFFERED catalog against the choice context (user message +
+// latest assistant reasoning) via influence-core scoreMargin; embeds
+// LAZILY on first read; flags narrow margins + proxy disagreements.
+var ToolChoiceRecorder_js_1 = require("./recorders/observability/ToolChoiceRecorder.js");
+Object.defineProperty(exports, "buildChoiceContext", { enumerable: true, get: function () { return ToolChoiceRecorder_js_1.buildChoiceContext; } });
+Object.defineProperty(exports, "toolChoiceRecorder", { enumerable: true, get: function () { return ToolChoiceRecorder_js_1.toolChoiceRecorder; } });
 //# sourceMappingURL=observe.js.map

package/dist/observe.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AAEH,4BAA4B;AAC5B,0EAAmG;AAA1F,qHAAA,eAAe,OAAA;AACxB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AAEvB,+BAA+B;AAC/B,kFAGiD;AAF/C,6HAAA,mBAAmB,OAAA;AAGrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qFAkBuD;AAjBrD,uHAAA,gBAAgB,OAAA;AAChB,uHAAA,gBAAgB,OAAA;AAiBlB,mFAWsD;AAVpD,mHAAA,aAAa,OAAA;AACb,qHAAA,eAAe,OAAA;AACf,qHAAA,eAAe,OAAA;AASjB,uFAUwD;AATtD,uHAAA,eAAe,OAAA;AACf,sHAAA,cAAc,OAAA;AAShB,uFAUwD;AATtD,yHAAA,iBAAiB,OAAA;AACjB,yHAAA,iBAAiB,OAAA;AACjB,sHAAA,cAAc,OAAA;AACd,uHAAA,eAAe,OAAA;AACf,4HAAA,oBAAoB,OAAA;AAOtB,6BAA6B;AAC7B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,4FAGsD;AAFpD,uIAAA,wBAAwB,OAAA;AAG1B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,mFAMsD;AALpD,mHAAA,aAAa,OAAA;AACb,oHAAA,cAAc,OAAA;AAKhB,iFAIqD;AAHnD,iHAAA,YAAY,OAAA;AAId,4EAA4E;AAC5E,gFAAgF;AAChF,2FAO0D;AANxD,6HAAA,mBAAmB,OAAA;AAOrB,gFAAgF;AAChF,gFAAgF;AAChF,yGASiE;AAR/D,mIAAA,kBAAkB,OAAA;AAUpB,uDAAuD;AACvD,8DAA0D;AAAjD,yGAAA,SAAS,OAAA;AAElB,uEAAuE;AACvE,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,oEAAoE;AACpE,kEAAkE;AAClE,eAAe;AACf,0DAgCuC;AA/BrC,wGAAA,YAAY,OAAA;AACZ,4GAAA,gBAAgB,OAAA;AAChB,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,qHAAA,yBAAyB,OAAA;AACzB,oHAAA,wBAAwB,OAAA;AACxB,yHAAA,6BAA6B,OAAA;AAC7B,0GAAA,cAAc,OAAA;AACd,0GAAA,cAAc,OAAA;AACd,iHAAA,qBAAqB,OAAA;AACrB,8GAAA,kBAAkB,OAAA;AAClB,uGAAA,WAAW,OAAA;AACX,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,+GAAA,mBAAmB,OAAA;AAkBrB,uEAAuE;AACvE,2EAA2E;AAC3E,mEAAmE;AACnE,0DAMuC;AALrC,yGAAA,aAAa,OAAA;AACb,8GAAA,kBAAkB,OAAA;AAClB,yGAAA,aAAa,OAAA"}
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"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"}

package/dist/recorders/observability/ToolChoiceRecorder.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolChoiceRecorder = exports.buildChoiceContext = void 0;
+const trace_1 = require("footprintjs/trace");
+const index_js_1 = require("../../lib/influence-core/index.js");
+const analyze_js_1 = require("../../lib/tool-lint/analyze.js");
+/** C4: the precise choice-context construction (see module JSDoc for the
+ *  include/exclude rationale). Exported so consumers can reproduce it. */
+function buildChoiceContext(args) {
+    const max = args.maxSlotChars ?? 2000;
+    const user = `user: ${args.userPrompt.slice(0, max)}`;
+    const assistant = args.latestAssistantText?.trim();
+    if (assistant === undefined || assistant.length === 0)
+        return user;
+    return `${user}\n\nassistant: ${assistant.slice(-max)}`;
+}
+exports.buildChoiceContext = buildChoiceContext;
+/** Build the tool-choice margin recorder (C5). */
+function toolChoiceRecorder(options) {
+    const marginThreshold = options.marginThreshold ?? index_js_1.DEFAULT_MARGIN_THRESHOLD;
+    const maxSlotChars = options.maxSlotChars ?? 2000;
+    const store = new trace_1.KeyedStore();
+    let lastRunId;
+    let userPrompt = '';
+    let lastAssistantText;
+    let openKey;
+    const closeOpen = () => {
+        if (openKey === undefined)
+            return;
+        const open = store.get(openKey);
+        if (open)
+            open.closed = true;
+        openKey = undefined;
+    };
+    const reset = () => {
+        store.clear();
+        userPrompt = '';
+        lastAssistantText = undefined;
+        openKey = undefined;
+    };
+    /** Lazy scoring pass — the ONLY place the embedder runs. */
+    const ensureScored = async () => {
+        for (const entry of store.getMap().values()) {
+            if (!entry.closed || entry.margin !== undefined || entry.skipped !== undefined)
+                continue;
+            if (entry.chosen.length === 0) {
+                entry.skipped = 'nothing-chosen';
+                continue;
+            }
+            const offeredNames = new Set(entry.offered.map((tool) => tool.name));
+            if (!entry.chosen.every((name) => offeredNames.has(name))) {
+                entry.skipped = 'chosen-not-offered';
+                continue;
+            }
+            entry.margin = await (0, index_js_1.scoreMargin)({
+                candidates: entry.offered.map((tool) => ({
+                    name: tool.name,
+                    text: (0, analyze_js_1.confusabilityText)(tool),
+                })),
+                contextText: entry.contextText,
+                chosen: entry.chosen,
+                embedder: options.embedder,
+                marginThreshold,
+            });
+        }
+    };
+    const toCall = (entry) => ({
+        runtimeStageId: entry.runtimeStageId,
+        iteration: entry.iteration,
+        offered: entry.offered,
+        chosen: [...entry.chosen],
+        toolCallIds: [...entry.toolCallIds],
+        contextText: entry.contextText,
+        ...(entry.margin !== undefined ? { margin: entry.margin } : {}),
+        ...(entry.skipped !== undefined ? { skipped: entry.skipped } : {}),
+    });
+    return {
+        id: options.id ?? 'tool-choice',
+        onEmit(event) {
+            const payload = event.payload;
+            if (payload === null || typeof payload !== 'object')
+                return; // redacted or foreign
+            const p = payload;
+            switch (event.name) {
+                case 'agentfootprint.agent.turn_start': {
+                    // New turn on the same run: fresh context slots.
+                    closeOpen();
+                    userPrompt = typeof p.userPrompt === 'string' ? p.userPrompt : '';
+                    lastAssistantText = undefined;
+                    break;
+                }
+                case 'agentfootprint.stream.llm_start': {
+                    closeOpen();
+                    const tools = Array.isArray(p.tools) ? p.tools : [];
+                    if (tools.length === 0)
+                        break; // no menu — nothing to confuse
+                    store.set(event.runtimeStageId, {
+                        runtimeStageId: event.runtimeStageId,
+                        iteration: Number(p.iteration ?? 0),
+                        offered: tools.map((tool) => ({
+                            name: tool.name,
+                            ...(tool.description !== undefined ? { description: tool.description } : {}),
+                        })),
+                        contextText: buildChoiceContext({
+                            userPrompt,
+                            ...(lastAssistantText !== undefined
+                                ? { latestAssistantText: lastAssistantText }
+                                : {}),
+                            maxSlotChars,
+                        }),
+                        chosen: [],
+                        toolCallIds: [],
+                        closed: false,
+                    });
+                    openKey = event.runtimeStageId;
+                    break;
+                }
+                case 'agentfootprint.stream.llm_end': {
+                    if (typeof p.content === 'string' && p.content.length > 0) {
+                        lastAssistantText = p.content;
+                    }
+                    break;
+                }
+                case 'agentfootprint.stream.tool_start': {
+                    if (openKey === undefined)
+                        break;
+                    const entry = store.get(openKey);
+                    if (entry === undefined)
+                        break;
+                    const name = String(p.toolName ?? 'unknown');
+                    if (!entry.chosen.includes(name))
+                        entry.chosen.push(name);
+                    entry.toolCallIds.push(String(p.toolCallId ?? ''));
+                    break;
+                }
+                case 'agentfootprint.agent.turn_end': {
+                    closeOpen();
+                    break;
+                }
+                default:
+                    break;
+            }
+        },
+        /** Convention 4 — a new runId means a new run: reset accumulation so
+         *  runtimeStageId keys (which restart per run) cannot collide. The
+         *  executor also calls `clear()` before each `run()` — this hook is
+         *  the detection that works regardless of attach surface. Same-
+         *  executor `resume()` fires `onResume` (not `onRunStart`) and skips
+         *  `clear()`, so pre-pause entries SURVIVE a resume by design. */
+        onRunStart(event) {
+            const runId = event.traversalContext?.runId;
+            if (runId !== undefined && runId !== lastRunId) {
+                reset();
+                lastRunId = runId;
+            }
+        },
+        onRunEnd() {
+            closeOpen();
+        },
+        onRunFailed() {
+            closeOpen();
+        },
+        async getCalls() {
+            await ensureScored();
+            return [...store.getMap().values()].map(toCall);
+        },
+        async getFlagged() {
+            await ensureScored();
+            return [...store.getMap().values()]
+                .filter((entry) => entry.margin !== undefined &&
+                (entry.margin.flags.narrow || entry.margin.flags.proxyDisagreement))
+                .map(toCall);
+        },
+        async getSummary() {
+            await ensureScored();
+            const entries = [...store.getMap().values()];
+            const scored = entries.filter((entry) => entry.margin !== undefined);
+            const narrow = scored.filter((entry) => entry.margin?.flags.narrow).length;
+            const proxyDisagreement = scored.filter((entry) => entry.margin?.flags.proxyDisagreement).length;
+            const flagged = scored.filter((entry) => entry.margin?.flags.narrow || entry.margin?.flags.proxyDisagreement).length;
+            return {
+                llmCallsWithTools: entries.length,
+                choices: entries.filter((entry) => entry.chosen.length > 0).length,
+                scored: scored.length,
+                flagged,
+                narrow,
+                proxyDisagreement,
+                skipped: entries.filter((entry) => entry.skipped !== undefined).length,
+            };
+        },
+        clear() {
+            reset();
+        },
+    };
+}
+exports.toolChoiceRecorder = toolChoiceRecorder;
+//# sourceMappingURL=ToolChoiceRecorder.js.map