agentfootprint 7.0.0 → 7.2.0

package/dist/lib/context-ledger/contextLedger.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * contextLedger — the post-run bookkeeper (see types.ts for the WHY).
+ *
+ * DESIGN: a pure POST-RUN analyzer over the run's own commit log — no live
+ * recorder lifecycle, no event-order coupling. Everything it counts is
+ * already durably recorded by the engine (dogfooding: offers come from
+ * `commitValueAt` folds, answer attribution from `sliceForKey` — the same
+ * canonical queries every triage surface uses):
+ *
+ *   offers  — the context IN EFFECT at each LLM call. Call marker: a
+ *             commit that wrote `totalInputTokens` (monotonic — never
+ *             net-change-dropped) and did NOT write `userMessage` (which
+ *             only the seed writes). At each call index, fold
+ *             `activeInjections` + `dynamicToolSchemas`, and add the
+ *             STATIC tool registry (duck-read from the runner's public
+ *             `getUIGroup().extra.toolNames` — static registries live in a
+ *             closure, never in scope state). NOTE offers are deliberately
+ *             NOT "per context-key commit": the net-change filter drops
+ *             identical re-commits, so stable context appears once in the
+ *             log while still being offered (and paying tokens) per call.
+ *             Static-registry tools count offers with approxTokens 0 in L1
+ *             (their schema JSON isn't in the log) — earnRate, the gate
+ *             signal, is unaffected; dynamicToolSchemas carries real sizes.
+ *   uses    — tool: assistant messages' toolCalls in the final history;
+ *             skill: `activatedInjectionIds`;
+ *             injection: its SLOT's write sits on the final answer's
+ *             backward slice (slot-granular, labeled).
+ *   outcome — consumer label per run, credited to every offered piece.
+ *
+ * The slot→slice join needs NO id conventions: for each slot key
+ * (INJECTION_KEYS.*), `findLastWriter` names the commit that fed the final
+ * LLM call; membership of that writer in the answer slice IS the signal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextLedger = void 0;
+const trace_1 = require("footprintjs/trace");
+const trace_2 = require("footprintjs/trace");
+const conventions_js_1 = require("../../conventions.js");
+/** chars ÷ 4 — a serialized-length ESTIMATE, deliberately rough and cheap. */
+function approxTokens(value) {
+    try {
+        return Math.ceil(JSON.stringify(value).length / 4);
+    }
+    catch {
+        return 0;
+    }
+}
+/** sf-llm-call mount keys in loop order — grouped-mode iterations live in
+ *  their own retained inner logs (the same projection context-bisect's
+ *  assembleGroupedTrajectory uses). */
+function llmCallMountKeys(subflowResults) {
+    if (!subflowResults)
+        return [];
+    return Object.keys(subflowResults)
+        .filter((k) => k.includes('#') && (0, trace_2.splitStageId)(k.split('#')[0]).localStageId === conventions_js_1.SUBFLOW_IDS.LLM_CALL)
+        .sort((a, b) => (0, trace_2.parseRuntimeStageId)(a).executionIndex - (0, trace_2.parseRuntimeStageId)(b).executionIndex);
+}
+function snapshotOf(source) {
+    const maybeRunner = source;
+    if (typeof maybeRunner?.getLastSnapshot === 'function') {
+        return maybeRunner.getLastSnapshot();
+    }
+    return source;
+}
+/** Static tool registry names, duck-read from the runner's public UI-group
+ *  metadata (Agent fills `extra.toolNames`). Empty for non-runner sources. */
+function staticToolNamesOf(source) {
+    const maybeRunner = source;
+    if (typeof maybeRunner?.getUIGroup !== 'function')
+        return [];
+    try {
+        const names = maybeRunner.getUIGroup()?.extra?.toolNames;
+        return Array.isArray(names) ? names.filter((n) => typeof n === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+function contextLedger() {
+    const table = new Map(); // key: `${kind}:${id}`
+    const runOffers = new Map(); // runRef → offered keys
+    let runsRecorded = 0;
+    let lastRunRef;
+    function rowOf(kind, id) {
+        const key = `${kind}:${id}`;
+        let row = table.get(key);
+        if (!row) {
+            row = { id, kind, offered: 0, approxTokensSpent: 0, used: 0, usedVia: {}, runsSeen: 0, outcomes: {} };
+            table.set(key, row);
+        }
+        return row;
+    }
+    function markUsed(kind, id, via) {
+        const row = rowOf(kind, id);
+        row.used += 1;
+        row.usedVia[via] = (row.usedVia[via] ?? 0) + 1;
+    }
+    function recordRun(source) {
+        const snapshot = snapshotOf(source);
+        const log = snapshot?.commitLog;
+        if (!log?.length)
+            return undefined;
+        runsRecorded += 1;
+        const runRef = `run-${runsRecorded}`;
+        const offeredKeys = new Set();
+        const offer = (kind, id, tokens) => {
+            const row = rowOf(kind, id);
+            row.offered += 1;
+            row.approxTokensSpent += tokens;
+            offeredKeys.add(`${kind}:${id}`);
+        };
+        // ── OFFERS: the context IN EFFECT at each LLM call ───────────────────
+        // Call marker: wrote totalInputTokens (monotonic — survives the
+        // net-change filter) and NOT userMessage (the seed's unique write).
+        // A SINGLE forward pass per log tracks the latest context values as
+        // writes appear (one commitValueAt per actual write — O(N), review
+        // finding #3), so each marker reads the context in effect exactly even
+        // though identical re-commits are dropped from the log.
+        //
+        // GROUPED reactMode (review finding #1): call-llm + the slots live
+        // INSIDE per-iteration `sf-llm-call#k` subflow logs (their context keys
+        // never bubble to the root), so offers fold over each retained inner
+        // log — the same projection context-bisect's grouped trajectory uses.
+        const staticTools = staticToolNamesOf(source);
+        let callMarkers = 0;
+        const foldOffersFrom = (bundles) => {
+            let injections = [];
+            let schemas = [];
+            for (let i = 0; i < bundles.length; i++) {
+                const paths = new Set(bundles[i].trace.map((t) => t.path));
+                if (paths.has('activeInjections')) {
+                    const v = (0, trace_1.commitValueAt)(bundles, i, 'activeInjections');
+                    if (Array.isArray(v))
+                        injections = v;
+                }
+                if (paths.has('dynamicToolSchemas')) {
+                    const v = (0, trace_1.commitValueAt)(bundles, i, 'dynamicToolSchemas');
+                    if (Array.isArray(v))
+                        schemas = v;
+                }
+                if (!paths.has('totalInputTokens') || paths.has('userMessage'))
+                    continue;
+                callMarkers += 1;
+                for (const inj of injections) {
+                    if (!inj?.id)
+                        continue;
+                    const kind = inj.flavor === 'skill' ? 'skill' : 'injection';
+                    offer(kind, inj.id, approxTokens(inj));
+                }
+                // Tools: dynamic schemas (real sizes) + the static registry (offer
+                // counted, size unknowable from the log in L1 — earnRate unaffected).
+                const offeredToolsThisCall = new Set();
+                for (const schema of schemas) {
+                    if (!schema?.name || offeredToolsThisCall.has(schema.name))
+                        continue;
+                    offeredToolsThisCall.add(schema.name);
+                    offer('tool', schema.name, approxTokens(schema));
+                }
+                for (const name of staticTools) {
+                    if (offeredToolsThisCall.has(name))
+                        continue;
+                    offeredToolsThisCall.add(name);
+                    offer('tool', name, 0);
+                }
+            }
+        };
+        const mountKeys = llmCallMountKeys(snapshot?.subflowResults);
+        if (mountKeys.length > 0) {
+            for (const key of mountKeys) {
+                const inner = snapshot?.subflowResults?.[key]?.treeContext?.history;
+                if (Array.isArray(inner))
+                    foldOffersFrom(inner);
+            }
+        }
+        else {
+            foldOffersFrom(log);
+        }
+        // A run with NO call markers anywhere is a shape this ledger cannot
+        // meter (e.g. the LLMCall runner, which never writes totalInputTokens)
+        // — report honestly instead of confidently recording zero offers.
+        if (callMarkers === 0) {
+            runsRecorded -= 1;
+            return undefined;
+        }
+        // ── USES: tool calls (assistant messages in the final history) ───────
+        const lastIdx = log.length - 1;
+        const history = (0, trace_1.commitValueAt)(log, lastIdx, 'history');
+        if (Array.isArray(history)) {
+            for (const msg of history) {
+                if (msg?.role !== 'assistant' || !Array.isArray(msg.toolCalls))
+                    continue;
+                for (const call of msg.toolCalls) {
+                    if (call?.name)
+                        markUsed('tool', call.name, 'tool-called');
+                }
+            }
+        }
+        // ── USES: skill activations ──────────────────────────────────────────
+        const activated = (0, trace_1.commitValueAt)(log, lastIdx, 'activatedInjectionIds');
+        if (Array.isArray(activated)) {
+            for (const id of activated) {
+                if (typeof id === 'string' && id.length > 0)
+                    markUsed('skill', id, 'skill-activated');
+            }
+        }
+        // ── USES: answer-slice membership per slot (slot-granular, honest) ───
+        // Slice the final answer; a slot counts as "on the answer's dependency
+        // chain" when its key's LAST WRITER is a slice member. Every injection
+        // in the FINAL context of that slot gets the (shared) credit.
+        let sliceAvailable = false;
+        const tree = snapshot?.executionTree;
+        if (tree) {
+            const reads = (0, trace_1.keysReadFromExecutionTree)(tree);
+            const slice = (0, trace_1.sliceForKey)(log, 'finalContent', reads);
+            if (slice.root) {
+                sliceAvailable = true;
+                const memberIds = new Set((0, trace_1.flattenCausalDAG)(slice.root).map((n) => n.runtimeStageId));
+                const finalInjections = (0, trace_1.commitValueAt)(log, lastIdx, 'activeInjections');
+                const finalBySlotKey = new Map();
+                // Which slot carried each injection is projected per-slot into the
+                // INJECTION_KEYS records — fold each slot key's final value.
+                for (const slotKey of Object.values(conventions_js_1.INJECTION_KEYS)) {
+                    const writer = (0, trace_1.findLastWriter)(log, slotKey);
+                    if (!writer || !memberIds.has(writer.runtimeStageId))
+                        continue;
+                    const slotRecords = (0, trace_1.commitValueAt)(log, lastIdx, slotKey);
+                    if (Array.isArray(slotRecords))
+                        finalBySlotKey.set(slotKey, slotRecords);
+                }
+                // Credit: injections present in a slice-member slot's final records.
+                const activeById = new Map();
+                if (Array.isArray(finalInjections)) {
+                    for (const inj of finalInjections) {
+                        if (inj?.id)
+                            activeById.set(inj.id, inj);
+                    }
+                }
+                for (const records of finalBySlotKey.values()) {
+                    for (const rec of records) {
+                        const id = rec?.id;
+                        if (!id)
+                            continue;
+                        const flavor = activeById.get(id)?.flavor ?? rec.source;
+                        const kind = flavor === 'skill' ? 'skill' : 'injection';
+                        markUsed(kind, id, 'answer-slice(slot)');
+                    }
+                }
+            }
+        }
+        // runsSeen: once per run per offered piece.
+        for (const key of offeredKeys) {
+            const row = table.get(key);
+            if (row)
+                row.runsSeen += 1;
+        }
+        runOffers.set(runRef, offeredKeys);
+        lastRunRef = runRef;
+        return { runRef, offeredPieces: [...offeredKeys], sliceAvailable };
+    }
+    function recordOutcome(label, runRef) {
+        const ref = runRef ?? lastRunRef;
+        if (!ref)
+            return false;
+        const offered = runOffers.get(ref);
+        if (!offered)
+            return false;
+        for (const key of offered) {
+            const row = table.get(key);
+            if (row)
+                row.outcomes[label] = (row.outcomes[label] ?? 0) + 1;
+        }
+        return true;
+    }
+    function freeze(row) {
+        return {
+            ...row,
+            usedVia: { ...row.usedVia },
+            outcomes: { ...row.outcomes },
+            earnRate: row.offered > 0 ? row.used / row.offered : 0,
+        };
+    }
+    return {
+        recordRun,
+        recordOutcome,
+        rows: () => [...table.values()].map(freeze).sort((a, b) => a.earnRate - b.earnRate),
+        row: (kind, id) => {
+            const row = table.get(`${kind}:${id}`);
+            return row ? freeze(row) : undefined;
+        },
+        exportJSON: () => ({ version: 1, rows: [...table.values()].map(freeze), runsRecorded }),
+        importJSON: (json) => {
+            if (json?.version !== 1)
+                return;
+            for (const r of json.rows) {
+                const row = rowOf(r.kind, r.id);
+                row.offered += r.offered;
+                row.approxTokensSpent += r.approxTokensSpent;
+                row.used += r.used;
+                row.runsSeen += r.runsSeen;
+                for (const [via, n] of Object.entries(r.usedVia)) {
+                    row.usedVia[via] = (row.usedVia[via] ?? 0) + (n ?? 0);
+                }
+                for (const [label, n] of Object.entries(r.outcomes)) {
+                    row.outcomes[label] = (row.outcomes[label] ?? 0) + n;
+                }
+            }
+            runsRecorded += json.runsRecorded;
+        },
+    };
+}
+exports.contextLedger = contextLedger;
+//# sourceMappingURL=contextLedger.js.map

package/dist/lib/context-ledger/contextLedger.js.map

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

package/dist/lib/context-ledger/gates.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * context-ledger/gates.ts — L2: the ledger's rows feed what gets included.
+ *
+ * Three gates, one policy, each hooking an EXISTING seam (no new framework
+ * surface): `gatedTools(inner, predicate)` for tools, `skillGraph().entryBy`
+ * for skills, and a rule-trigger wrapper for injections.
+ *
+ * THE POLICY PRINCIPLE — demote, never starve: a piece the ledger judges
+ * poorly is demoted, but every `refreshEvery`-th decision lets it through
+ * anyway ("parole"), so it keeps generating fresh ledger data. Without
+ * parole a piece demoted once could never earn again — a self-fulfilling
+ * verdict. And the ledger never judges a piece it barely knows: below
+ * `minOffers` everything passes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ledgerGated = exports.ledgerEntryScorer = exports.ledgerToolGate = void 0;
+const entryScorer_js_1 = require("../injection-engine/entryScorer.js");
+const DEFAULTS = { minOffers: 5, earnRateFloor: 0.05, refreshEvery: 10 };
+/**
+ * The shared verdict: should this piece be included right now?
+ * Stateful per gate instance (the parole counter), pure otherwise.
+ */
+function makeVerdict(ledger, policy) {
+    const p = { ...DEFAULTS, ...policy };
+    const demotions = new Map();
+    return (kind, id) => {
+        const row = ledger.row(kind, id);
+        if (!row)
+            return true; // unknown to the ledger → always include
+        if (row.offered < p.minOffers)
+            return true; // not enough data to judge
+        if (row.earnRate >= p.earnRateFloor)
+            return true; // earning its tokens
+        // Demoted — but parole every Nth decision keeps the data flowing.
+        const key = `${kind}:${id}`;
+        const count = (demotions.get(key) ?? 0) + 1;
+        demotions.set(key, count);
+        return p.refreshEvery !== Infinity && count % p.refreshEvery === 0;
+    };
+}
+/**
+ * TOOL GATE — plug into the existing provider combinator:
+ *
+ * ```ts
+ * import { gatedTools, staticTools } from 'agentfootprint/tool-providers';
+ * builder.toolProvider(gatedTools(staticTools(tools), ledgerToolGate(ledger)));
+ * ```
+ *
+ * Unused tool schemas are usually the biggest silent token cost — this is
+ * the gate to start with.
+ */
+function ledgerToolGate(ledger, policy) {
+    const verdict = makeVerdict(ledger, policy);
+    return (toolName) => verdict('tool', toolName);
+}
+exports.ledgerToolGate = ledgerToolGate;
+/**
+ * SKILL GATE — an `EntryScorer` for `skillGraph().entryBy(...)` that wraps
+ * another scorer (keyword, embedding, …) and demotes candidates the ledger
+ * says never earn. Demotion multiplies the inner score toward the floor —
+ * ranking pressure, not exclusion — and parole restores full weight
+ * periodically, so a demoted skill can still win when nothing else fits.
+ */
+function ledgerEntryScorer(ledger, inner, policy) {
+    const verdict = makeVerdict(ledger, policy);
+    const DEMOTION_WEIGHT = 0.25;
+    return {
+        name: `ledger(${inner.name})`,
+        async score(input, signal) {
+            const base = await inner.score(input, signal);
+            // Re-rank through rankEntries so `chosen`, `score` AND `relevance` are
+            // recomputed TOGETHER from the demoted scores — preserving the
+            // entryScorer contract (argmax-score == argmax-relevance; the "Why
+            // this skill?" panel and the pick can never disagree).
+            const candidates = base.ranked.map((r) => ({
+                id: r.id,
+                description: input.candidates.find((c) => c.id === r.id)?.description ?? '',
+            }));
+            const demotedScores = base.ranked.map((r) => verdict('skill', r.id) ? r.score : r.score * DEMOTION_WEIGHT);
+            return (0, entryScorer_js_1.rankEntries)(`ledger(${base.scorer})`, candidates, demotedScores);
+        },
+    };
+}
+exports.ledgerEntryScorer = ledgerEntryScorer;
+/**
+ * INJECTION GATE — wrap ONE injection so the ledger's verdict joins its
+ * trigger. `always` becomes a ledger-backed rule; an existing `rule` is
+ * AND-ed with the verdict. `on-tool-return` / `llm-activated` are returned
+ * UNCHANGED (they are already demand-driven — the ledger has nothing to
+ * add). `always` pieces are exempt unless you explicitly wrap them — the
+ * safety-first default from the design.
+ */
+function ledgerGated(injection, ledger, policy) {
+    const verdict = makeVerdict(ledger, policy);
+    const kind = injection.flavor === 'skill' ? 'skill' : 'injection';
+    const trigger = injection.trigger;
+    if (trigger.kind === 'always') {
+        return { ...injection, trigger: { kind: 'rule', activeWhen: () => verdict(kind, injection.id) } };
+    }
+    if (trigger.kind === 'rule') {
+        const original = trigger.activeWhen;
+        return {
+            ...injection,
+            trigger: { kind: 'rule', activeWhen: (ctx) => original(ctx) && verdict(kind, injection.id) },
+        };
+    }
+    return injection; // demand-driven triggers pass through untouched
+}
+exports.ledgerGated = ledgerGated;
+//# sourceMappingURL=gates.js.map

package/dist/lib/context-ledger/gates.js.map

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

package/dist/lib/context-ledger/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * context-ledger — which context pieces EARNED their tokens?
+ *
+ * Post-run bookkeeping over the run's own commit log (offers, structural
+ * uses, consumer outcomes) whose rows feed the gating seams so future turns
+ * include less. See README.md for the honesty model and the L2 gates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ledgerGated = exports.ledgerEntryScorer = exports.ledgerToolGate = exports.contextLedger = void 0;
+var contextLedger_js_1 = require("./contextLedger.js");
+Object.defineProperty(exports, "contextLedger", { enumerable: true, get: function () { return contextLedger_js_1.contextLedger; } });
+var gates_js_1 = require("./gates.js");
+Object.defineProperty(exports, "ledgerToolGate", { enumerable: true, get: function () { return gates_js_1.ledgerToolGate; } });
+Object.defineProperty(exports, "ledgerEntryScorer", { enumerable: true, get: function () { return gates_js_1.ledgerEntryScorer; } });
+Object.defineProperty(exports, "ledgerGated", { enumerable: true, get: function () { return gates_js_1.ledgerGated; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/context-ledger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/context-ledger/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AAStB,uCAA+F;AAAtF,0GAAA,cAAc,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,uGAAA,WAAW,OAAA"}

package/dist/lib/context-ledger/types.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * context-ledger/types.ts — the bookkeeper's vocabulary.
+ *
+ * WHY THIS LIBRARY EXISTS: context engineering fails in one predictable
+ * direction — "include everything to be safe". Every injection, skill and
+ * tool schema costs tokens EVERY turn, whether or not it ever mattered. The
+ * ledger keeps score across runs: which pieces EARNED their tokens (were
+ * called, activated, or sat on the answer's dependency slice) and which
+ * never did. Its rows feed the L2 gates (gatedTools predicate, skill-graph
+ * EntryScorer, injection demotion) so future turns include less — the
+ * mechanism that makes lesser models viable.
+ *
+ * HONESTY (the discipline everything here inherits):
+ * - Every counter is a STRUCTURAL fact from the run's own commit log —
+ *   offers are recorded commits, uses are recorded calls/activations/slice
+ *   membership. Nothing is inferred from model internals.
+ * - Each kind's `used` definition is explicit ({@link UsedSignal}) and rides
+ *   every count — a consumer can always see WHY a piece counted as used.
+ * - Slice membership is slot-granular (all injections sharing a slot share
+ *   its write) — the signal name says so: `'answer-slice(slot)'`.
+ * - `approxTokens*` is a serialized-length estimate (JSON chars ÷ 4), named
+ *   so nobody mistakes it for a tokenizer count.
+ * - The ledger never claims causation. `earnRate` is bookkeeping;
+ *   ablation (context-bisect) can upgrade individual claims when you pay
+ *   for it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/lib/context-ledger/types.js.map

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

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

@@ -37,6 +37,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.callTraceTool = exports.traceToolpack = void 0;
 const trace_1 = require("footprintjs/trace");
+const trace_2 = require("footprintjs/trace");
 const toolArgsValidation_js_1 = require("../../core/agent/toolArgsValidation.js");
 const tools_js_1 = require("../../core/tools.js");
 const types_js_1 = require("../../identity/types.js");
@@ -214,6 +215,7 @@ function truncateText(text, cap) {
  * | `run_overview`   | What happened, broadly? (the entry point)                 |
  * | `trace_node`     | What did step X read/write, and where did its inputs come from? |
  * | `trace_slice`    | Which chain of steps produced the data at X? (causal slice) |
+ * | `backtrack`      | Why is VARIABLE K what it is? (+ `element`: who made K[i]?) — variable-first |
  * | `who_wrote`      | Which step last wrote key K?                              |
  * | `get_value`      | The full value of K as of step X (capped, truncation-marked) |
  * | `read_narrative` | The human-readable story, paginated (only when narrative provided) |
@@ -235,6 +237,7 @@ function traceToolpack(artifacts, options) {
         buildRunOverview(artifacts, index),
         buildTraceNode(artifacts, index, opts),
         buildTraceSlice(artifacts, index, opts),
+        buildBacktrack(artifacts, index, opts),
         buildWhoWrote(index, opts),
         buildGetValue(index, opts),
     ];
@@ -551,6 +554,114 @@ function buildTraceSlice(artifacts, index, opts) {
     });
 }
 // ── who_wrote ──────────────────────────────────────────────────────────────
+// ── backtrack — variable-first triage (the follow-up question shape) ──────
+/**
+ * `trace_slice` is STEP-addressed ("what fed step X?"). Follow-up questions
+ * arrive VARIABLE-addressed ("why did you say the quote is 11.88?" → "why is
+ * `quote` what it is?") — and for agent history, ELEMENT-addressed ("where
+ * did message 7 come from?"). This tool is that address translation, built
+ * on footprintjs' slice layer (`sliceForKey` / `elementProvenance`): anchor
+ * at the variable's last writer, walk backwards; or name one array element's
+ * birth step. Same honesty contracts as the rest of the pack — a missing
+ * slice states WHY (initial state / frozen args / a closure), element
+ * attribution carries its basis (append-verb exact vs prefix-inference),
+ * and reads-coverage warns when read tracking was off.
+ */
+function buildBacktrack(artifacts, index, opts) {
+    return (0, tools_js_1.defineTool)({
+        name: 'backtrack',
+        description: "Why is a state VARIABLE what it is? Anchors at the variable's last writer and walks the " +
+            'backward dependency chain (variable-first — you do not need a step id). For array ' +
+            "variables (e.g. 'history'), pass 'element' to ask which step produced element N instead. " +
+            "Optional 'before' (commit index) time-travels: the value as it stood before that point. " +
+            `Bounded by maxDepth (default ${opts.sliceMaxDepth}, max ${types_js_2.TOOLPACK_HARD_CAPS.sliceMaxDepth}) ` +
+            `and maxNodes (default ${opts.sliceMaxNodes}, max ${types_js_2.TOOLPACK_HARD_CAPS.sliceMaxNodes}).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                variable: keyProperty(index, "The state key to explain, e.g. 'quote' or 'history'."),
+                element: {
+                    type: 'integer',
+                    description: 'Optional array index: ask which step PRODUCED this element (birth attribution) ' +
+                        'instead of slicing the whole variable.',
+                },
+                before: {
+                    type: 'integer',
+                    description: 'Optional exclusive commit index — explain the value as it stood BEFORE this point ' +
+                        "(chain from an element birth with: element_birth's commitIdx + 1).",
+                },
+                maxDepth: {
+                    type: 'integer',
+                    description: `Optional slice depth (default ${opts.sliceMaxDepth}, hard cap ${types_js_2.TOOLPACK_HARD_CAPS.sliceMaxDepth}).`,
+                },
+                maxNodes: {
+                    type: 'integer',
+                    description: `Optional node budget (default ${opts.sliceMaxNodes}, hard cap ${types_js_2.TOOLPACK_HARD_CAPS.sliceMaxNodes}).`,
+                },
+            },
+            required: ['variable'],
+            additionalProperties: false,
+        },
+        execute: ({ variable, element, before, maxDepth, maxNodes }) => {
+            const key = (0, bounded_js_1.normalizeKey)(variable, index.knownPaths);
+            // ── element mode: birth attribution ─────────────────────────────────
+            if (element !== undefined) {
+                const birth = (0, trace_2.elementProvenance)(index.commitLog, key, element, {
+                    ...(before !== undefined && { atIdx: before - 1 }),
+                });
+                if (!birth) {
+                    const prov = (0, trace_2.arrayProvenance)(index.commitLog, key, {
+                        ...(before !== undefined && { atIdx: before - 1 }),
+                    });
+                    if (prov.missing === 'never-written') {
+                        return (`'${(0, bounded_js_1.displayKey)(key)}' was never written in range — it may come from run input ` +
+                            '(args), env, pre-run state, or a closure; the commit log cannot see those.');
+                    }
+                    if (prov.missing === 'not-an-array') {
+                        return (`'${(0, bounded_js_1.displayKey)(key)}' is not an array at that point (scalar, deleted, or degraded) — ` +
+                            `element attribution does not apply. Call backtrack without 'element' to slice it.`);
+                    }
+                    if (prov.missing === 'empty-log')
+                        return 'the commit log is empty — nothing executed.';
+                    return (`element ${element} is out of range for '${(0, bounded_js_1.displayKey)(key)}' ` +
+                        `(length ${prov.length}). Valid indices: 0..${(prov.length ?? 1) - 1}.`);
+                }
+                return (`'${(0, bounded_js_1.displayKey)(key)}'[${birth.index}] = ${(0, bounded_js_1.renderPreview)((0, bounded_js_1.boundedPreview)(birth.value, opts.previewChars))} — ` +
+                    `born at ${birth.runtimeStageId} ("${birth.stageName}", verb: ${birth.verb}, ` +
+                    `attribution: ${birth.basis}${birth.basis === 'append-verb' ? ' — engine-recorded, exact' : ''}). ` +
+                    `Drill the producer with trace_node('${birth.runtimeStageId}'), or ask why it wrote this ` +
+                    `with backtrack({variable: '${(0, bounded_js_1.displayKey)(key)}', before: ${birth.commitIdx + 1}}).`);
+            }
+            // ── slice mode: variable-first backward slice ────────────────────────
+            const depth = (0, bounded_js_1.clampParam)(maxDepth, opts.sliceMaxDepth, 1, types_js_2.TOOLPACK_HARD_CAPS.sliceMaxDepth);
+            const nodeBudget = (0, bounded_js_1.clampParam)(maxNodes, opts.sliceMaxNodes, 2, types_js_2.TOOLPACK_HARD_CAPS.sliceMaxNodes);
+            const keysReadOf = (id) => {
+                const node = index.nodes.get(id);
+                return node?.stageReads ? Object.keys(node.stageReads) : [];
+            };
+            const slice = (0, trace_2.sliceForKey)(index.commitLog, key, keysReadOf, {
+                maxDepth: depth,
+                maxNodes: nodeBudget,
+                ...(before !== undefined && { before }),
+                ...(artifacts.controlDeps ? { controlDeps: artifacts.controlDeps } : {}),
+            });
+            const lines = [
+                (0, bounded_js_1.displayText)((0, trace_2.formatSlice)(slice)),
+                '',
+                'drill any (stepId) with trace_node; fetch values with get_value; array variables take ' +
+                    "'element' for per-element attribution.",
+            ];
+            if (slice.root !== undefined && !artifacts.controlDeps) {
+                lines.push('⚠ control edges unavailable — artifacts carry no controlDeps lookup; decisions that ' +
+                    'routed execution are not shown.');
+            }
+            if (slice.root !== undefined && !index.hasReadTracking) {
+                lines.push('⚠ artifacts carry no per-step read tracking — the slice may show only the writer step.');
+            }
+            return lines.join('\n');
+        },
+    });
+}
 function buildWhoWrote(index, opts) {
     return (0, tools_js_1.defineTool)({
         name: 'who_wrote',