agentfootprint 6.23.0 → 6.25.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/lib/trace-toolpack/bounded.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Bounded serialization helpers for the trace toolpack.
+ *
+ * Pattern: pure functions — no state, no events.
+ * Role:    The token-economics layer. EVERY value the toolpack serves goes
+ *          through these: previews are capped, truncation is EXPLICIT
+ *          (never silent), and nested-path keys round-trip between the
+ *          engine's DELIM encoding and LLM-friendly dot notation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampParam = exports.renderPreview = exports.boundedPreview = exports.safeStringify = exports.displayText = exports.normalizeKey = exports.displayKey = exports.FP_PATH_DELIM = void 0;
+/**
+ * footprintjs's canonical nested-path delimiter (ASCII unit separator,
+ * `src/lib/memory/utils.ts`). Internal to the engine — the toolpack
+ * translates it to/from dot notation so the LLM never sees a control char.
+ */
+exports.FP_PATH_DELIM = '\u001F';
+/** Engine path → LLM-friendly dotted display form. */
+function displayKey(path) {
+    return path.includes(exports.FP_PATH_DELIM) ? path.split(exports.FP_PATH_DELIM).join('.') : path;
+}
+exports.displayKey = displayKey;
+/**
+ * LLM-supplied key → engine path. Exact keys pass through; a dotted key
+ * that doesn't exist verbatim but matches a known DELIM-joined path is
+ * translated back. `knownPaths` is the set of every path seen in the
+ * commit log's trace entries.
+ */
+function normalizeKey(key, knownPaths) {
+    if (knownPaths.has(key))
+        return key;
+    if (key.includes('.')) {
+        const delimForm = key.split('.').join(exports.FP_PATH_DELIM);
+        if (knownPaths.has(delimForm))
+            return delimForm;
+    }
+    return key;
+}
+exports.normalizeKey = normalizeKey;
+/** Replace every DELIM in an already-formatted text block with '.' for display. */
+function displayText(text) {
+    return text.split(exports.FP_PATH_DELIM).join('.');
+}
+exports.displayText = displayText;
+/**
+ * Serialize a value to compact JSON, total-function style: cycles, BigInt
+ * and other non-JSON values degrade to a tagged placeholder instead of
+ * throwing — a debugger tool must never crash on the evidence it serves.
+ */
+function safeStringify(value) {
+    if (value === undefined)
+        return 'undefined';
+    try {
+        const json = JSON.stringify(value);
+        return json === undefined ? String(value) : json;
+    }
+    catch {
+        return '[unserializable value]';
+    }
+}
+exports.safeStringify = safeStringify;
+/** Serialize + cap at `maxChars`. Truncation is reported, never silent. */
+function boundedPreview(value, maxChars) {
+    const full = safeStringify(value);
+    if (full.length <= maxChars) {
+        return { text: full, totalChars: full.length, truncated: false };
+    }
+    return { text: `${full.slice(0, maxChars)}…`, totalChars: full.length, truncated: true };
+}
+exports.boundedPreview = boundedPreview;
+/** Render a preview with its honesty suffix when truncated. */
+function renderPreview(preview, fetchHint) {
+    if (!preview.truncated)
+        return preview.text;
+    const hint = fetchHint ? ` — ${fetchHint}` : '';
+    return `${preview.text} (${preview.totalChars} chars total${hint})`;
+}
+exports.renderPreview = renderPreview;
+/** Clamp an LLM-supplied numeric param into [min, hardCap], with a default. */
+function clampParam(requested, fallback, min, hardCap) {
+    const value = typeof requested === 'number' && Number.isFinite(requested) ? requested : fallback;
+    return Math.max(min, Math.min(Math.floor(value), hardCap));
+}
+exports.clampParam = clampParam;
+//# sourceMappingURL=bounded.js.map

package/dist/lib/trace-toolpack/bounded.js.map

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

package/dist/lib/trace-toolpack/index.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * trace-toolpack — RFC-003 Part C: the introspection toolpack.
+ *
+ * footprintjs trace evidence exposed as TOOLS an LLM calls: a debugging
+ * model navigates a COMPLETED run's evidence by runtimeStageIds instead of
+ * reading dumps. Bounded, honest (⚠ markers), redaction-respecting.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLPACK_HARD_CAPS = exports.traceToolpack = exports.callTraceTool = void 0;
+var traceToolpack_js_1 = require("./traceToolpack.js");
+Object.defineProperty(exports, "callTraceTool", { enumerable: true, get: function () { return traceToolpack_js_1.callTraceTool; } });
+Object.defineProperty(exports, "traceToolpack", { enumerable: true, get: function () { return traceToolpack_js_1.traceToolpack; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "TOOLPACK_HARD_CAPS", { enumerable: true, get: function () { return types_js_1.TOOLPACK_HARD_CAPS; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/trace-toolpack/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/trace-toolpack/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,uDAAkE;AAAzD,iHAAA,aAAa,OAAA;AAAE,iHAAA,aAAa,OAAA;AACrC,uCAIoB;AAHlB,8GAAA,kBAAkB,OAAA"}