agentfootprint 7.5.0 → 7.6.0

package/README.md

@@ -299,6 +299,26 @@ again.answer;              // 'HOLD …'
 again.whatChanged.summary; // 'Removing sources [social-sentiment] changed the answer in 3/3 seeded re-runs …'
 ```
 
+### Chat sessions that can explain themselves
+
+`recordedChat` wraps your agent factory into a recorded conversation. Every `send()`
+freezes that turn's evidence. `reason(k)` shows what influenced reply K. `rerunTurn(k,
+{ ignore })` re-runs that exact turn — same recorded history, byte for byte — without a
+source, and returns the same honest result `rerunWithoutSources` gives you. `fork(k,
+{ fromRerun })` continues the conversation from the what-if as a new recorded session.
+Branch, never rewrite.
+
+```ts
+import { recordedChat } from 'agentfootprint/debug';
+
+const chat = recordedChat({ makeAgent });          // your factory, specs applied at construction
+await chat.send('Should we BUY or HOLD?');         // recorded turn (frozen evidence)
+const rerun = await chat.rerunTurn(1, {            // that turn, minus one source
+  ignore: ['social-sentiment'], embedder, checkBaseline: true,
+});
+const fork = chat.fork(1, { fromRerun: rerun });   // continue from the what-if
+```
+
 ---
 
 ## Pick your door

package/dist/debug.js

@@ -20,7 +20,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifySuspect = exports.DEFAULT_RECENCY_DECAY = exports.buildWriterFrameIndex = exports.walkTrajectory = exports.walkToRoot = exports.shortlistEarlyCulprits = exports.bucketByAnchors = exports.bisectCulprits = exports.assignCostVerdicts = exports.assembleTrajectory = exports.applyAblations = exports.ablationForSuspect = exports.traceDebugAgent = exports.SelfExplainBinding = exports.buildSelfExplainToolProvider = exports.buildSelfExplainSkill = exports.traceToolpack = exports.TOOLPACK_HARD_CAPS = exports.NO_COMPLETED_RUN_MESSAGE = exports.lazyTraceToolpack = exports.callTraceTool = exports.structuralProximity = exports.snippetUnits = exports.semanticAlignmentStrategy = exports.scoreMargin = exports.scoreLexicalInfluence = exports.scoreInfluence = exports.scoreContrastiveInfluence = exports.ratioStrategy = exports.rankingConfidence = exports.persistence = exports.pairwiseSimilarity = exports.marginStrategy = exports.listInfluenceStrategies = exports.lexicalOverlapStrategy = exports.explainChoice = exports.attributeChoice = exports.finalAnswerSimilarity = exports.embeddingCache = exports.EmbeddingCache = exports.DEFAULT_SHORTLIST_BAND = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = exports.DEFAULT_CLEAR_WINNER_RATIO = exports.DEFAULT_CLEAR_WINNER_MARGIN = exports.contentHash = exports.compositeScore = exports.averageRelevancy = exports.adaptWeights = void 0;
-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.toBacktrackTrace = exports.sliceToBacktrackTrace = exports.verdictFor = exports.suspectLabel = exports.stepOutputText = exports.runRestorationProbe = exports.runAblationProbe = exports.rerunWithoutSources = exports.removableSources = exports.probeFlipped = exports.localizeContextBug = exports.llmEdgeWeigher = exports.llmCallIdsFromEvents = exports.formatContextBugReport = exports.findDroppedContext = exports.defaultSuspectClassifier = exports.defaultOutcomeComparator = exports.CONTEXT_BISECT_DEFAULTS = exports.findLoopHeads = void 0;
+exports.recordedChat = 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.toBacktrackTrace = exports.sliceToBacktrackTrace = exports.verdictFor = exports.suspectLabel = exports.stepOutputText = exports.runRestorationProbe = exports.runAblationProbe = exports.rerunWithoutSources = exports.removableSources = exports.probeFlipped = exports.localizeContextBug = exports.llmEdgeWeigher = exports.llmCallIdsFromEvents = exports.formatContextBugReport = exports.findDroppedContext = exports.defaultSuspectClassifier = exports.defaultOutcomeComparator = exports.CONTEXT_BISECT_DEFAULTS = exports.findLoopHeads = void 0;
 // influence-core — the ONE embedding-based scoring engine (RFC-002/003
 // block D6). Not a recorder: pure, embedder-injected scoring functions
 // + the shared bounded embedding cache. Honest claim: every score is an
@@ -141,4 +141,13 @@ Object.defineProperty(exports, "MOCK_EMBEDDER_CALIBRATION", { enumerable: true,
 Object.defineProperty(exports, "optionalParamRule", { enumerable: true, get: function () { return index_js_6.optionalParamRule; } });
 Object.defineProperty(exports, "runToolLintCli", { enumerable: true, get: function () { return index_js_6.runToolLintCli; } });
 Object.defineProperty(exports, "saysWhatNotWhenRule", { enumerable: true, get: function () { return index_js_6.saysWhatNotWhenRule; } });
+// recorded-chat — the session-scoped turn recorder. Wraps a consumer agent
+// factory into a recorded conversation: send() freezes each turn's evidence,
+// reason(k)/rerunTurn(k)/fork(k) are the per-turn transparency loop. Absorbs
+// the three glue traps (per-turn artifact freezing, byte-exact history
+// threading, same-factory runner derivation) while COMPOSING with the loop
+// above (localizeContextBug + rerunWithoutSources returned UNMODIFIED), never
+// duplicating it. Branch, never rewrite.
+var index_js_7 = require("./lib/recorded-chat/index.js");
+Object.defineProperty(exports, "recordedChat", { enumerable: true, get: function () { return index_js_7.recordedChat; } });
 //# sourceMappingURL=debug.js.map

package/dist/debug.js.map

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

package/dist/esm/debug.d.ts

@@ -23,3 +23,4 @@ export { buildSelfExplainSkill, buildSelfExplainToolProvider, SelfExplainBinding
 export { ablationForSuspect, applyAblations, assembleTrajectory, assignCostVerdicts, bisectCulprits, bucketByAnchors, shortlistEarlyCulprits, walkToRoot, walkTrajectory, buildWriterFrameIndex, DEFAULT_RECENCY_DECAY, classifySuspect, findLoopHeads, CONTEXT_BISECT_DEFAULTS, defaultOutcomeComparator, defaultSuspectClassifier, findDroppedContext, formatContextBugReport, llmCallIdsFromEvents, llmEdgeWeigher, localizeContextBug, probeFlipped, removableSources, rerunWithoutSources, runAblationProbe, runRestorationProbe, stepOutputText, suspectLabel, verdictFor, type AblationRerun, type AblationRunner, type AblationRunStats, type AblationSpec, type AblationTargets, type AblationVerdict, type AblationVerdictKind, type AnchorBucket, type AssembleTrajectoryOptions, type LoopCandidate, type LoopRecallShortlist, type ShortlistEarlyCulpritsOptions, type RootCauseHop, type RootCauseNote, type RootCausePath, type WalkToRootOptions, type BisectCulpritsOptions, type BisectionProbe, type BisectionResult, type CapturedEventLike, type ClassifyContext, type ContextBugArtifacts, type ContextBugReport, type ContextSource, type ContextUnit, type CostRange, type CostStats, type CostVerdict, type DroppedUnit, type EdgePathStep, type LoopFrame, type HonestyFlag, type HonestyFlagKind, type IgnoredSource, type LlmEdgeWeigherHandle, type LlmEdgeWeigherOptions, type LocalizeContextBugOptions, type MissingContextResult, type OutcomeComparator, type QualityTriggerLookup, type RankedParentEdge, type RemovableSource, type RerunWithoutSourcesOptions, type RerunWithoutSourcesResult, type RestorationProbeConfig, type RestorationRerun, type RestorationRunner, type RestoredCandidate, type RunCost, type SimilarityStats, type SliceStats, type Suspect, type SuspectClass, type SuspectClassifier, type SuspectDetail, type SuspectKind, type SuspectSeed, type SyntheticQuestionNode, type Trajectory, type WhatChanged, } from './lib/context-bisect/index.js';
 export { sliceToBacktrackTrace, toBacktrackTrace, type BacktrackCustodyHop, type BacktrackHop, type BacktrackSuspectCard, type BacktrackTrace, type BacktrackTrail, type SliceToBacktrackTraceOptions, type ToBacktrackTraceOptions, } from './lib/context-bisect/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 { recordedChat, type ChatFormat, type ChatMessage, type ChatTurn, type ForkOptions, type ForkOrigin, type MakeChatAgent, type ReasonOptions, type RecordedChat, type RecordedChatOptions, type RerunTurnOptions, type SendOptions, } from './lib/recorded-chat/index.js';

package/dist/esm/debug.js

@@ -51,4 +51,12 @@ export { sliceToBacktrackTrace, toBacktrackTrace, } from './lib/context-bisect/i
 // injected with our defaults. Bin: `agentfootprint-lint-tools`.
 // Front door: docs/guides/tool-catalog-lint.md.
 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, } from './lib/tool-lint/index.js';
+// recorded-chat — the session-scoped turn recorder. Wraps a consumer agent
+// factory into a recorded conversation: send() freezes each turn's evidence,
+// reason(k)/rerunTurn(k)/fork(k) are the per-turn transparency loop. Absorbs
+// the three glue traps (per-turn artifact freezing, byte-exact history
+// threading, same-factory runner derivation) while COMPOSING with the loop
+// above (localizeContextBug + rerunWithoutSources returned UNMODIFIED), never
+// duplicating it. Branch, never rewrite.
+export { recordedChat, } from './lib/recorded-chat/index.js';
 //# sourceMappingURL=debug.js.map

package/dist/esm/debug.js.map

@@ -1 +1 @@
-{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,wEAAwE;AACxE,4BAA4B;AAC5B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,yBAAyB,EACzB,YAAY,EACZ,mBAAmB,GAiCpB,MAAM,+BAA+B,CAAC;AACvC,uEAAuE;AACvE,2EAA2E;AAC3E,mEAAmE;AACnE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,GAGd,MAAM,+BAA+B,CAAC;AACvC,uEAAuE;AACvE,yEAAyE;AACzE,0EAA0E;AAC1E,kEAAkE;AAClE,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,kBAAkB,EAClB,eAAe,GAGhB,MAAM,+BAA+B,CAAC;AACvC,qEAAqE;AACrE,sEAAsE;AACtE,sEAAsE;AACtE,+DAA+D;AAC/D,oEAAoE;AACpE,mEAAmE;AACnE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,UAAU,GA6DX,MAAM,+BAA+B,CAAC;AACvC,sEAAsE;AACtE,uEAAuE;AACvE,mEAAmE;AACnE,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GAQjB,MAAM,+BAA+B,CAAC;AACvC,wEAAwE;AACxE,8EAA8E;AAC9E,qEAAqE;AACrE,wEAAwE;AACxE,uEAAuE;AACvE,gEAAgE;AAChE,gDAAgD;AAChD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,+BAA+B,EAC/B,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,uBAAuB,EACvB,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GAepB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,wEAAwE;AACxE,4BAA4B;AAC5B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,yBAAyB,EACzB,YAAY,EACZ,mBAAmB,GAiCpB,MAAM,+BAA+B,CAAC;AACvC,uEAAuE;AACvE,2EAA2E;AAC3E,mEAAmE;AACnE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,GAGd,MAAM,+BAA+B,CAAC;AACvC,uEAAuE;AACvE,yEAAyE;AACzE,0EAA0E;AAC1E,kEAAkE;AAClE,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,kBAAkB,EAClB,eAAe,GAGhB,MAAM,+BAA+B,CAAC;AACvC,qEAAqE;AACrE,sEAAsE;AACtE,sEAAsE;AACtE,+DAA+D;AAC/D,oEAAoE;AACpE,mEAAmE;AACnE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,UAAU,GA6DX,MAAM,+BAA+B,CAAC;AACvC,sEAAsE;AACtE,uEAAuE;AACvE,mEAAmE;AACnE,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GAQjB,MAAM,+BAA+B,CAAC;AACvC,wEAAwE;AACxE,8EAA8E;AAC9E,qEAAqE;AACrE,wEAAwE;AACxE,uEAAuE;AACvE,gEAAgE;AAChE,gDAAgD;AAChD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,+BAA+B,EAC/B,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,uBAAuB,EACvB,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GAepB,MAAM,0BAA0B,CAAC;AAClC,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,uEAAuE;AACvE,2EAA2E;AAC3E,8EAA8E;AAC9E,yCAAyC;AACzC,OAAO,EACL,YAAY,GAYb,MAAM,8BAA8B,CAAC"}

package/dist/esm/lib/recorded-chat/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * recorded-chat — the session-scoped turn recorder over the context-bisect
+ * product loop. Absorbs the three correctness traps every chat host re-writes
+ * (per-turn artifact freezing, byte-exact history threading, same-factory
+ * runner derivation) while COMPOSING with the 7.5 surface, not duplicating it.
+ *
+ * Exported from `agentfootprint/debug` (every symbol it composes with lives
+ * there). Named exports — `export *` is not the house style.
+ */
+export { recordedChat } from './recordedChat.js';
+export type { ChatFormat, ChatMessage, ChatTurn, ForkOptions, ForkOrigin, MakeChatAgent, ReasonOptions, RecordedChat, RecordedChatOptions, RerunTurnOptions, SendOptions, } from './types.js';

package/dist/esm/lib/recorded-chat/index.js

@@ -0,0 +1,11 @@
+/**
+ * recorded-chat — the session-scoped turn recorder over the context-bisect
+ * product loop. Absorbs the three correctness traps every chat host re-writes
+ * (per-turn artifact freezing, byte-exact history threading, same-factory
+ * runner derivation) while COMPOSING with the 7.5 surface, not duplicating it.
+ *
+ * Exported from `agentfootprint/debug` (every symbol it composes with lives
+ * there). Named exports — `export *` is not the house style.
+ */
+export { recordedChat } from './recordedChat.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/recorded-chat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/recorded-chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/lib/recorded-chat/recordedChat.d.ts

@@ -0,0 +1,20 @@
+/**
+ * recordedChat — the session-scoped turn recorder.
+ *
+ * `recordedChat({ makeAgent })` returns a `RecordedChat`: `send()` runs one
+ * recorded turn through the consumer's agent factory and freezes that turn's
+ * evidence immediately; `reason(k)` / `rerunTurn(k)` / `fork(k)` are the
+ * per-turn transparency loop, composing with the existing context-bisect
+ * surface (`localizeContextBug`, `rerunWithoutSources`) rather than
+ * duplicating it. See `./types.ts` for the three traps this owns.
+ *
+ * Compose-don't-inherit house style: a module-private session class,
+ * factory-returned; no base classes.
+ */
+import type { RecordedChat, RecordedChatOptions } from './types.js';
+/**
+ * Record a chat turn-by-turn so any reply can be explained, counterfactually
+ * re-run, and forked — without re-writing the correctness-critical glue every
+ * chat host gets subtly wrong. See the [recordedChat guide](doc:recorded-chat).
+ */
+export declare function recordedChat(options: RecordedChatOptions): RecordedChat;

package/dist/esm/lib/recorded-chat/recordedChat.js

@@ -0,0 +1,240 @@
+/**
+ * recordedChat — the session-scoped turn recorder.
+ *
+ * `recordedChat({ makeAgent })` returns a `RecordedChat`: `send()` runs one
+ * recorded turn through the consumer's agent factory and freezes that turn's
+ * evidence immediately; `reason(k)` / `rerunTurn(k)` / `fork(k)` are the
+ * per-turn transparency loop, composing with the existing context-bisect
+ * surface (`localizeContextBug`, `rerunWithoutSources`) rather than
+ * duplicating it. See `./types.ts` for the three traps this owns.
+ *
+ * Compose-don't-inherit house style: a module-private session class,
+ * factory-returned; no base classes.
+ */
+import { llmCallIdsFromEvents, localizeContextBug, rerunWithoutSources, } from '../context-bisect/index.js';
+const DEFAULT_HEADER = 'Recent conversation:';
+const DEFAULT_USER_LABEL = 'User';
+const DEFAULT_ASSISTANT_LABEL = 'Assistant';
+/** Deterministic key for spec dedup — recursively sorts object keys. */
+function canonicalKey(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            const sorted = {};
+            for (const k of Object.keys(val).sort()) {
+                sorted[k] = val[k];
+            }
+            return sorted;
+        }
+        return val;
+    });
+}
+/** Union of ablation specs, deduped by canonical JSON (order-preserving, first wins). */
+function dedupeSpecs(specs) {
+    const seen = new Set();
+    const out = [];
+    for (const spec of specs) {
+        const key = canonicalKey(spec);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(spec);
+    }
+    return out;
+}
+class RecordedChatSession {
+    makeAgentFn;
+    formatOpt;
+    header;
+    userLabel;
+    assistantLabel;
+    /** seed + one (user, assistant) pair per recorded turn. */
+    entries;
+    seedMessages;
+    removedSpecs;
+    turnsInternal = [];
+    reports = new Map();
+    /** result -> turnIndex, the in-process fork-provenance guard. */
+    rerunOwner = new WeakMap();
+    sending = false;
+    forkedFromValue = undefined;
+    constructor(options) {
+        this.makeAgentFn = options.makeAgent;
+        this.formatOpt = options.format;
+        this.header = options.format?.header ?? DEFAULT_HEADER;
+        this.userLabel = options.format?.userLabel ?? DEFAULT_USER_LABEL;
+        this.assistantLabel = options.format?.assistantLabel ?? DEFAULT_ASSISTANT_LABEL;
+        this.seedMessages = Object.freeze((options.seed ?? []).map((m) => ({ ...m })));
+        this.entries = [...this.seedMessages];
+        this.removedSpecs = Object.freeze([...(options.removed ?? [])]);
+    }
+    get turns() {
+        return this.turnsInternal;
+    }
+    get seed() {
+        return this.seedMessages;
+    }
+    get removed() {
+        return this.removedSpecs;
+    }
+    get forkedFrom() {
+        return this.forkedFromValue;
+    }
+    renderLine(message) {
+        const label = message.role === 'user' ? this.userLabel : this.assistantLabel;
+        return `${label}: ${message.text}`;
+    }
+    composeMessage(lines, userMessage) {
+        if (lines.length === 0)
+            return `${this.userLabel}: ${userMessage}`;
+        return `${this.header}\n${lines.join('\n')}\n\n${this.userLabel}: ${userMessage}`;
+    }
+    async send(userMessage, options) {
+        if (this.sending) {
+            throw new Error('recordedChat.send: a turn is already in flight — one turn at a time; await the previous send');
+        }
+        this.sending = true;
+        try {
+            // Compose the message ONCE, at record time, from the frozen transcript
+            // (trap 2 — byte-exact history is threaded HERE and replayed verbatim).
+            const transcriptBefore = Object.freeze(this.entries.map((m) => this.renderLine(m)));
+            const message = this.composeMessage(transcriptBefore, userMessage);
+            const agent = await this.makeAgentFn({ specs: this.removedSpecs, seed: 0 });
+            const events = [];
+            // Attach the tap BEFORE run() — listener-presence gating drops events
+            // otherwise (agentfootprint invariant). Unsubscribe in finally.
+            const off = agent.on('*', (event) => {
+                events.push(event);
+            });
+            let out;
+            try {
+                const raw = await agent.run({
+                    message,
+                    ...(options?.identity !== undefined ? { identity: options.identity } : {}),
+                });
+                if (typeof raw !== 'string') {
+                    throw new Error("recordedChat.send: the run paused (askHuman/checkIn) — recorded chat turns don't " +
+                        'support pauses; drive pausing agents with agent.run() directly');
+                }
+                out = raw;
+            }
+            finally {
+                off();
+            }
+            // Capture IMMEDIATELY (trap 1) — getLastSnapshot() is last-run-only, but
+            // the per-turn agent is discarded here, so clobbering is impossible.
+            const snapshot = agent.getLastSnapshot();
+            if (snapshot === undefined) {
+                throw new Error('recordedChat.send: the run produced no snapshot — cannot record the turn');
+            }
+            const lastLlmCallId = llmCallIdsFromEvents(events).at(-1);
+            const index = this.turnsInternal.length;
+            this.entries.push({ role: 'user', text: userMessage }, { role: 'assistant', text: out });
+            const turn = Object.freeze({
+                index,
+                userMessage,
+                reply: out,
+                message,
+                transcriptBefore,
+                artifacts: Object.freeze({ snapshot, events: Object.freeze(events) }),
+                lastLlmCallId,
+                identity: options?.identity,
+            });
+            this.turnsInternal.push(turn);
+            return turn;
+        }
+        finally {
+            this.sending = false;
+        }
+    }
+    turn(k) {
+        const n = this.turnsInternal.length;
+        if (!Number.isInteger(k) || k < 0 || k >= n) {
+            const range = n === 0 ? '(no turns recorded yet)' : `0..${n - 1}`;
+            throw new RangeError(`recordedChat.turn: no turn ${k} — valid range is ${range}`);
+        }
+        return this.turnsInternal[k];
+    }
+    async reason(k, options) {
+        const turn = this.turn(k);
+        const { fresh, atStep, ...rest } = options;
+        const memo = this.reports.get(k);
+        if (memo !== undefined && fresh !== true)
+            return memo;
+        const resolvedAtStep = atStep ?? turn.lastLlmCallId;
+        const report = await localizeContextBug({
+            ...rest,
+            artifacts: turn.artifacts,
+            ...(resolvedAtStep !== undefined ? { atStep: resolvedAtStep } : {}),
+        });
+        this.reports.set(k, report);
+        return report;
+    }
+    async rerunTurn(k, options) {
+        const turn = this.turn(k);
+        const { report: reportOption, ...rerunRest } = options;
+        let report = reportOption ?? this.reports.get(k);
+        if (report === undefined) {
+            report = await this.reason(k, { embedder: options.embedder });
+        }
+        // Derive the runner from the SAME factory (traps 2 + 3): the frozen
+        // message bytes are replayed verbatim, and the session's persistent
+        // removals ALWAYS apply on top of the probe's specs (empty specs = the
+        // baseline probe, which replays the identical turn).
+        const runner = async (specs, run) => {
+            const agent = await this.makeAgentFn({
+                specs: [...this.removedSpecs, ...specs],
+                seed: run.seed,
+            });
+            const out = await agent.run({
+                message: turn.message,
+                ...(turn.identity !== undefined ? { identity: turn.identity } : {}),
+            });
+            if (typeof out !== 'string') {
+                throw new Error('recordedChat.rerunTurn: a probe run paused (askHuman/checkIn) — recorded chat re-runs ' +
+                    "don't support pauses");
+            }
+            return out;
+        };
+        const result = await rerunWithoutSources({
+            ...rerunRest,
+            report,
+            runner,
+            originalAnswer: turn.reply,
+        });
+        this.rerunOwner.set(result, k);
+        return result;
+    }
+    fork(k, options) {
+        const turn = this.turn(k);
+        const fromRerun = options?.fromRerun;
+        if (fromRerun !== undefined && this.rerunOwner.get(fromRerun) !== k) {
+            throw new Error(`recordedChat.fork: that result was not produced by this session's rerunTurn for turn ${k} — ` +
+                're-run this turn first, then fork');
+        }
+        const reply = fromRerun?.answer ?? turn.reply;
+        const cut = this.seedMessages.length + 2 * k;
+        const seed = [
+            ...this.entries.slice(0, cut).map((m) => ({ ...m })),
+            { role: 'user', text: turn.userMessage },
+            { role: 'assistant', text: reply },
+        ];
+        const removed = dedupeSpecs([...this.removedSpecs, ...(fromRerun?.removed ?? [])]);
+        const child = new RecordedChatSession({
+            makeAgent: this.makeAgentFn,
+            ...(this.formatOpt !== undefined ? { format: this.formatOpt } : {}),
+            seed,
+            removed,
+        });
+        child.forkedFromValue = { parent: this, turnIndex: k, viaRerun: fromRerun !== undefined };
+        return child;
+    }
+}
+/**
+ * Record a chat turn-by-turn so any reply can be explained, counterfactually
+ * re-run, and forked — without re-writing the correctness-critical glue every
+ * chat host gets subtly wrong. See the [recordedChat guide](doc:recorded-chat).
+ */
+export function recordedChat(options) {
+    return new RecordedChatSession(options);
+}
+//# sourceMappingURL=recordedChat.js.map

package/dist/esm/lib/recorded-chat/recordedChat.js.map

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

package/dist/esm/lib/recorded-chat/types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * recorded-chat types — the session-scoped turn recorder over the existing
+ * context-bisect product loop (localizeContextBug + rerunWithoutSources +
+ * removableSources).
+ *
+ * WHY THIS EXISTS: multi-turn chat on agentfootprint is a HOST convention —
+ * `AgentInput` has no history field, so hosts thread the transcript into the
+ * `message` string themselves. Every chat host that wanted per-turn
+ * transparency then re-wrote the same correctness-critical glue and got three
+ * things subtly wrong:
+ *
+ *   1. `agent.getLastSnapshot()` is last-run-only — a second `run()` clobbers
+ *      it, so reasoning about turn K after turn K+1 ran silently attributes
+ *      the wrong run.
+ *   2. History is a convention — the transcript preamble must be BYTE-identical
+ *      between the recorded turn and its counterfactual re-run, or the re-run
+ *      ablates a subtly different scenario without failing anything.
+ *   3. The `AblationRunner` duplicates turn construction — the re-run is only
+ *      valid if the rebuilt turn matches the recorded one (same system, facts,
+ *      preamble).
+ *
+ * `recordedChat({ makeAgent })` owns exactly those three: per-turn artifact
+ * freezing (1), byte-exact history threading (2), and deriving the turn-K
+ * runner from the SAME `makeAgent` that ran the turn (3). It COMPOSES with the
+ * 7.5 surface — `reason()` calls `localizeContextBug`, `rerunTurn()` delegates
+ * to `rerunWithoutSources` and returns its result UNMODIFIED (the honesty
+ * tiers are not hidden). Session registries, UI joins, comparators and
+ * persistence stay host-side by design (see the guide's "What stays yours").
+ */
+import type { RuntimeSnapshot } from 'footprintjs';
+import type { Agent } from '../../core/Agent.js';
+import type { MemoryIdentity } from '../../memory/identity/types.js';
+import type { AblationSpec, CapturedEventLike, ContextBugReport, LocalizeContextBugOptions, RerunWithoutSourcesOptions, RerunWithoutSourcesResult } from '../context-bisect/index.js';
+/**
+ * The ONE agent factory — live turns, rerun probes, baseline probes, and
+ * fork turns all go through it (the single source of truth the
+ * `AblationRunner` contract already demands).
+ *
+ * Contract (the `AblationRunner` contract, now enforced-by-shape for live
+ * turns too):
+ * - Return a FRESH agent with a FRESH provider on every call — scripted
+ *   mock providers are stateful (replies consume in order).
+ * - Apply `specs` at CONSTRUCTION (the documented seam): filter facts /
+ *   tools / memory entries with `applyAblations(specs, { ... })` before
+ *   building. `specs` is ALWAYS the union of the session's persistent
+ *   removals (forks carry these) and the probe's ablation specs; it is
+ *   empty for a plain live turn in an unforked session.
+ * - `seed` varies 0..N-1 across a probe's samples (always 0 for live
+ *   turns). Thread it into any stochastic knob; ignore it when the agent
+ *   is deterministic.
+ */
+export type MakeChatAgent = (build: {
+    readonly specs: readonly AblationSpec[];
+    readonly seed: number;
+}) => Agent | Promise<Agent>;
+/** How transcript lines and the per-turn message string are rendered. */
+export interface ChatFormat {
+    /** Preamble header line. Default `'Recent conversation:'`. */
+    readonly header?: string;
+    /** Label for user lines (`'<userLabel>: ...'`). Default `'User'`. */
+    readonly userLabel?: string;
+    /** Label for reply lines. Default `'Assistant'`. */
+    readonly assistantLabel?: string;
+}
+/** One transcript entry — the structured form of a rendered line. */
+export interface ChatMessage {
+    readonly role: 'user' | 'assistant';
+    readonly text: string;
+}
+export interface RecordedChatOptions {
+    readonly makeAgent: MakeChatAgent;
+    readonly format?: ChatFormat;
+    /**
+     * Transcript the session OPENS with (frozen; rendered as the seed
+     * preamble of every turn). `fork()` fills this; hosts may also pass a
+     * persisted transcript to rehydrate a session — authenticity of a
+     * hand-supplied seed is then the host's responsibility.
+     */
+    readonly seed?: readonly ChatMessage[];
+    /**
+     * Session-persistent removals: every turn (and every probe) in this
+     * session runs with these specs applied. `fork()` fills this so the
+     * what-if world STAYS the what-if world.
+     */
+    readonly removed?: readonly AblationSpec[];
+}
+/** One recorded turn — everything frozen at record time. */
+export interface ChatTurn {
+    /** 0-based position in `turns`. */
+    readonly index: number;
+    readonly userMessage: string;
+    /** The agent's reply (agentfootprint `AgentOutput` string). */
+    readonly reply: string;
+    /**
+     * The EXACT message string `agent.run()` received — composed once at
+     * record time. Re-runs of this turn replay these bytes verbatim; the
+     * byte-exact-history guarantee lives here.
+     */
+    readonly message: string;
+    /** Rendered transcript lines the turn opened with (frozen copy). */
+    readonly transcriptBefore: readonly string[];
+    /**
+     * Localize-ready evidence: pass straight to
+     * `localizeContextBug({ artifacts: turn.artifacts, ... })`.
+     */
+    readonly artifacts: {
+        readonly snapshot: RuntimeSnapshot;
+        readonly events: readonly CapturedEventLike[];
+    };
+    /** runtimeStageId of the turn's LAST LLM call — the default `atStep`. */
+    readonly lastLlmCallId: string | undefined;
+    /** The identity `send()` was given, threaded into re-runs unchanged. */
+    readonly identity: MemoryIdentity | undefined;
+}
+export interface SendOptions {
+    /** Multi-tenant memory scope, passed through to `agent.run()`. */
+    readonly identity?: MemoryIdentity;
+}
+/** `reason(k)` options — localize passthrough minus what the turn provides. */
+export interface ReasonOptions extends Omit<LocalizeContextBugOptions, 'artifacts' | 'rerun'> {
+    /** Recompute even if a memoized report exists (e.g. a new scorer). */
+    readonly fresh?: boolean;
+}
+/** `rerunTurn(k)` options — `rerunWithoutSources` minus what the turn provides. */
+export interface RerunTurnOptions extends Omit<RerunWithoutSourcesOptions, 'report' | 'runner' | 'originalAnswer'> {
+    /**
+     * The report to resolve `ignore` against. Default: the turn's memoized
+     * `reason(k)` report (computed with this call's `embedder` + the default
+     * scorer if none exists yet).
+     */
+    readonly report?: ContextBugReport;
+}
+export interface ForkOptions {
+    /**
+     * Seed the fork's last reply with this counterfactual answer. MUST be a
+     * result produced by THIS session's `rerunTurn(k, ...)` for the SAME k
+     * (identity-checked) — a fabricated fork would be a lie. Omitted: the
+     * fork continues from the ORIGINAL reply (a plain branch, no ablation).
+     */
+    readonly fromRerun?: RerunWithoutSourcesResult;
+}
+export interface ForkOrigin {
+    readonly parent: RecordedChat;
+    readonly turnIndex: number;
+    /** True when the fork was seeded from a re-run's counterfactual answer. */
+    readonly viaRerun: boolean;
+}
+export interface RecordedChat {
+    /** Runs one recorded turn. One send at a time — concurrent sends throw. */
+    send(userMessage: string, options?: SendOptions): Promise<ChatTurn>;
+    /** Turn K's frozen record. Out-of-range throws (names the valid range). */
+    turn(k: number): ChatTurn;
+    readonly turns: readonly ChatTurn[];
+    /** The transcript the session opened with (forks / rehydration; else `[]`). */
+    readonly seed: readonly ChatMessage[];
+    /** The session's persistent removals (forks carry these; else `[]`). */
+    readonly removed: readonly AblationSpec[];
+    /** Set on sessions created by `fork()`; `undefined` otherwise. */
+    readonly forkedFrom: ForkOrigin | undefined;
+    /**
+     * Turn K's `ContextBugReport` (agentfootprint's, unmodified) via
+     * `localizeContextBug` over the frozen artifacts, `atStep` defaulted to
+     * the turn's last LLM call. Memoized per turn; `fresh: true` recomputes.
+     */
+    reason(k: number, options: ReasonOptions): Promise<ContextBugReport>;
+    /**
+     * Re-run turn K without the named sources — same recorded history bytes,
+     * same user message, minus the sources — delegating to
+     * `rerunWithoutSources` with a runner derived from `makeAgent`. Returns
+     * agentfootprint's `RerunWithoutSourcesResult` UNMODIFIED (a `verdict`
+     * only when `checkBaseline: true` — the honesty tiers are not hidden).
+     */
+    rerunTurn(k: number, options: RerunTurnOptions): Promise<RerunWithoutSourcesResult>;
+    /**
+     * Branch, never rewrite: a NEW `RecordedChat` (same `makeAgent`, same
+     * format) whose seed is the conversation through turn K with the reply
+     * swapped for the re-run's counterfactual answer (or kept, without
+     * `fromRerun`), and whose `removed` is this session's removals plus the
+     * re-run's `removed` specs. The original session is never touched.
+     */
+    fork(k: number, options?: ForkOptions): RecordedChat;
+}

package/dist/esm/lib/recorded-chat/types.js

@@ -0,0 +1,31 @@
+/**
+ * recorded-chat types — the session-scoped turn recorder over the existing
+ * context-bisect product loop (localizeContextBug + rerunWithoutSources +
+ * removableSources).
+ *
+ * WHY THIS EXISTS: multi-turn chat on agentfootprint is a HOST convention —
+ * `AgentInput` has no history field, so hosts thread the transcript into the
+ * `message` string themselves. Every chat host that wanted per-turn
+ * transparency then re-wrote the same correctness-critical glue and got three
+ * things subtly wrong:
+ *
+ *   1. `agent.getLastSnapshot()` is last-run-only — a second `run()` clobbers
+ *      it, so reasoning about turn K after turn K+1 ran silently attributes
+ *      the wrong run.
+ *   2. History is a convention — the transcript preamble must be BYTE-identical
+ *      between the recorded turn and its counterfactual re-run, or the re-run
+ *      ablates a subtly different scenario without failing anything.
+ *   3. The `AblationRunner` duplicates turn construction — the re-run is only
+ *      valid if the rebuilt turn matches the recorded one (same system, facts,
+ *      preamble).
+ *
+ * `recordedChat({ makeAgent })` owns exactly those three: per-turn artifact
+ * freezing (1), byte-exact history threading (2), and deriving the turn-K
+ * runner from the SAME `makeAgent` that ran the turn (3). It COMPOSES with the
+ * 7.5 surface — `reason()` calls `localizeContextBug`, `rerunTurn()` delegates
+ * to `rerunWithoutSources` and returns its result UNMODIFIED (the honesty
+ * tiers are not hidden). Session registries, UI joins, comparators and
+ * persistence stay host-side by design (see the guide's "What stays yours").
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/lib/recorded-chat/types.js.map

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

package/dist/lib/recorded-chat/index.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * recorded-chat — the session-scoped turn recorder over the context-bisect
+ * product loop. Absorbs the three correctness traps every chat host re-writes
+ * (per-turn artifact freezing, byte-exact history threading, same-factory
+ * runner derivation) while COMPOSING with the 7.5 surface, not duplicating it.
+ *
+ * Exported from `agentfootprint/debug` (every symbol it composes with lives
+ * there). Named exports — `export *` is not the house style.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordedChat = void 0;
+var recordedChat_js_1 = require("./recordedChat.js");
+Object.defineProperty(exports, "recordedChat", { enumerable: true, get: function () { return recordedChat_js_1.recordedChat; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/recorded-chat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/recorded-chat/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,qDAAiD;AAAxC,+GAAA,YAAY,OAAA"}

package/dist/lib/recorded-chat/recordedChat.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * recordedChat — the session-scoped turn recorder.
+ *
+ * `recordedChat({ makeAgent })` returns a `RecordedChat`: `send()` runs one
+ * recorded turn through the consumer's agent factory and freezes that turn's
+ * evidence immediately; `reason(k)` / `rerunTurn(k)` / `fork(k)` are the
+ * per-turn transparency loop, composing with the existing context-bisect
+ * surface (`localizeContextBug`, `rerunWithoutSources`) rather than
+ * duplicating it. See `./types.ts` for the three traps this owns.
+ *
+ * Compose-don't-inherit house style: a module-private session class,
+ * factory-returned; no base classes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordedChat = void 0;
+const index_js_1 = require("../context-bisect/index.js");
+const DEFAULT_HEADER = 'Recent conversation:';
+const DEFAULT_USER_LABEL = 'User';
+const DEFAULT_ASSISTANT_LABEL = 'Assistant';
+/** Deterministic key for spec dedup — recursively sorts object keys. */
+function canonicalKey(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            const sorted = {};
+            for (const k of Object.keys(val).sort()) {
+                sorted[k] = val[k];
+            }
+            return sorted;
+        }
+        return val;
+    });
+}
+/** Union of ablation specs, deduped by canonical JSON (order-preserving, first wins). */
+function dedupeSpecs(specs) {
+    const seen = new Set();
+    const out = [];
+    for (const spec of specs) {
+        const key = canonicalKey(spec);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(spec);
+    }
+    return out;
+}
+class RecordedChatSession {
+    makeAgentFn;
+    formatOpt;
+    header;
+    userLabel;
+    assistantLabel;
+    /** seed + one (user, assistant) pair per recorded turn. */
+    entries;
+    seedMessages;
+    removedSpecs;
+    turnsInternal = [];
+    reports = new Map();
+    /** result -> turnIndex, the in-process fork-provenance guard. */
+    rerunOwner = new WeakMap();
+    sending = false;
+    forkedFromValue = undefined;
+    constructor(options) {
+        this.makeAgentFn = options.makeAgent;
+        this.formatOpt = options.format;
+        this.header = options.format?.header ?? DEFAULT_HEADER;
+        this.userLabel = options.format?.userLabel ?? DEFAULT_USER_LABEL;
+        this.assistantLabel = options.format?.assistantLabel ?? DEFAULT_ASSISTANT_LABEL;
+        this.seedMessages = Object.freeze((options.seed ?? []).map((m) => ({ ...m })));
+        this.entries = [...this.seedMessages];
+        this.removedSpecs = Object.freeze([...(options.removed ?? [])]);
+    }
+    get turns() {
+        return this.turnsInternal;
+    }
+    get seed() {
+        return this.seedMessages;
+    }
+    get removed() {
+        return this.removedSpecs;
+    }
+    get forkedFrom() {
+        return this.forkedFromValue;
+    }
+    renderLine(message) {
+        const label = message.role === 'user' ? this.userLabel : this.assistantLabel;
+        return `${label}: ${message.text}`;
+    }
+    composeMessage(lines, userMessage) {
+        if (lines.length === 0)
+            return `${this.userLabel}: ${userMessage}`;
+        return `${this.header}\n${lines.join('\n')}\n\n${this.userLabel}: ${userMessage}`;
+    }
+    async send(userMessage, options) {
+        if (this.sending) {
+            throw new Error('recordedChat.send: a turn is already in flight — one turn at a time; await the previous send');
+        }
+        this.sending = true;
+        try {
+            // Compose the message ONCE, at record time, from the frozen transcript
+            // (trap 2 — byte-exact history is threaded HERE and replayed verbatim).
+            const transcriptBefore = Object.freeze(this.entries.map((m) => this.renderLine(m)));
+            const message = this.composeMessage(transcriptBefore, userMessage);
+            const agent = await this.makeAgentFn({ specs: this.removedSpecs, seed: 0 });
+            const events = [];
+            // Attach the tap BEFORE run() — listener-presence gating drops events
+            // otherwise (agentfootprint invariant). Unsubscribe in finally.
+            const off = agent.on('*', (event) => {
+                events.push(event);
+            });
+            let out;
+            try {
+                const raw = await agent.run({
+                    message,
+                    ...(options?.identity !== undefined ? { identity: options.identity } : {}),
+                });
+                if (typeof raw !== 'string') {
+                    throw new Error("recordedChat.send: the run paused (askHuman/checkIn) — recorded chat turns don't " +
+                        'support pauses; drive pausing agents with agent.run() directly');
+                }
+                out = raw;
+            }
+            finally {
+                off();
+            }
+            // Capture IMMEDIATELY (trap 1) — getLastSnapshot() is last-run-only, but
+            // the per-turn agent is discarded here, so clobbering is impossible.
+            const snapshot = agent.getLastSnapshot();
+            if (snapshot === undefined) {
+                throw new Error('recordedChat.send: the run produced no snapshot — cannot record the turn');
+            }
+            const lastLlmCallId = (0, index_js_1.llmCallIdsFromEvents)(events).at(-1);
+            const index = this.turnsInternal.length;
+            this.entries.push({ role: 'user', text: userMessage }, { role: 'assistant', text: out });
+            const turn = Object.freeze({
+                index,
+                userMessage,
+                reply: out,
+                message,
+                transcriptBefore,
+                artifacts: Object.freeze({ snapshot, events: Object.freeze(events) }),
+                lastLlmCallId,
+                identity: options?.identity,
+            });
+            this.turnsInternal.push(turn);
+            return turn;
+        }
+        finally {
+            this.sending = false;
+        }
+    }
+    turn(k) {
+        const n = this.turnsInternal.length;
+        if (!Number.isInteger(k) || k < 0 || k >= n) {
+            const range = n === 0 ? '(no turns recorded yet)' : `0..${n - 1}`;
+            throw new RangeError(`recordedChat.turn: no turn ${k} — valid range is ${range}`);
+        }
+        return this.turnsInternal[k];
+    }
+    async reason(k, options) {
+        const turn = this.turn(k);
+        const { fresh, atStep, ...rest } = options;
+        const memo = this.reports.get(k);
+        if (memo !== undefined && fresh !== true)
+            return memo;
+        const resolvedAtStep = atStep ?? turn.lastLlmCallId;
+        const report = await (0, index_js_1.localizeContextBug)({
+            ...rest,
+            artifacts: turn.artifacts,
+            ...(resolvedAtStep !== undefined ? { atStep: resolvedAtStep } : {}),
+        });
+        this.reports.set(k, report);
+        return report;
+    }
+    async rerunTurn(k, options) {
+        const turn = this.turn(k);
+        const { report: reportOption, ...rerunRest } = options;
+        let report = reportOption ?? this.reports.get(k);
+        if (report === undefined) {
+            report = await this.reason(k, { embedder: options.embedder });
+        }
+        // Derive the runner from the SAME factory (traps 2 + 3): the frozen
+        // message bytes are replayed verbatim, and the session's persistent
+        // removals ALWAYS apply on top of the probe's specs (empty specs = the
+        // baseline probe, which replays the identical turn).
+        const runner = async (specs, run) => {
+            const agent = await this.makeAgentFn({
+                specs: [...this.removedSpecs, ...specs],
+                seed: run.seed,
+            });
+            const out = await agent.run({
+                message: turn.message,
+                ...(turn.identity !== undefined ? { identity: turn.identity } : {}),
+            });
+            if (typeof out !== 'string') {
+                throw new Error('recordedChat.rerunTurn: a probe run paused (askHuman/checkIn) — recorded chat re-runs ' +
+                    "don't support pauses");
+            }
+            return out;
+        };
+        const result = await (0, index_js_1.rerunWithoutSources)({
+            ...rerunRest,
+            report,
+            runner,
+            originalAnswer: turn.reply,
+        });
+        this.rerunOwner.set(result, k);
+        return result;
+    }
+    fork(k, options) {
+        const turn = this.turn(k);
+        const fromRerun = options?.fromRerun;
+        if (fromRerun !== undefined && this.rerunOwner.get(fromRerun) !== k) {
+            throw new Error(`recordedChat.fork: that result was not produced by this session's rerunTurn for turn ${k} — ` +
+                're-run this turn first, then fork');
+        }
+        const reply = fromRerun?.answer ?? turn.reply;
+        const cut = this.seedMessages.length + 2 * k;
+        const seed = [
+            ...this.entries.slice(0, cut).map((m) => ({ ...m })),
+            { role: 'user', text: turn.userMessage },
+            { role: 'assistant', text: reply },
+        ];
+        const removed = dedupeSpecs([...this.removedSpecs, ...(fromRerun?.removed ?? [])]);
+        const child = new RecordedChatSession({
+            makeAgent: this.makeAgentFn,
+            ...(this.formatOpt !== undefined ? { format: this.formatOpt } : {}),
+            seed,
+            removed,
+        });
+        child.forkedFromValue = { parent: this, turnIndex: k, viaRerun: fromRerun !== undefined };
+        return child;
+    }
+}
+/**
+ * Record a chat turn-by-turn so any reply can be explained, counterfactually
+ * re-run, and forked — without re-writing the correctness-critical glue every
+ * chat host gets subtly wrong. See the [recordedChat guide](doc:recorded-chat).
+ */
+function recordedChat(options) {
+    return new RecordedChatSession(options);
+}
+exports.recordedChat = recordedChat;
+//# sourceMappingURL=recordedChat.js.map

package/dist/lib/recorded-chat/recordedChat.js.map

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

package/dist/lib/recorded-chat/types.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * recorded-chat types — the session-scoped turn recorder over the existing
+ * context-bisect product loop (localizeContextBug + rerunWithoutSources +
+ * removableSources).
+ *
+ * WHY THIS EXISTS: multi-turn chat on agentfootprint is a HOST convention —
+ * `AgentInput` has no history field, so hosts thread the transcript into the
+ * `message` string themselves. Every chat host that wanted per-turn
+ * transparency then re-wrote the same correctness-critical glue and got three
+ * things subtly wrong:
+ *
+ *   1. `agent.getLastSnapshot()` is last-run-only — a second `run()` clobbers
+ *      it, so reasoning about turn K after turn K+1 ran silently attributes
+ *      the wrong run.
+ *   2. History is a convention — the transcript preamble must be BYTE-identical
+ *      between the recorded turn and its counterfactual re-run, or the re-run
+ *      ablates a subtly different scenario without failing anything.
+ *   3. The `AblationRunner` duplicates turn construction — the re-run is only
+ *      valid if the rebuilt turn matches the recorded one (same system, facts,
+ *      preamble).
+ *
+ * `recordedChat({ makeAgent })` owns exactly those three: per-turn artifact
+ * freezing (1), byte-exact history threading (2), and deriving the turn-K
+ * runner from the SAME `makeAgent` that ran the turn (3). It COMPOSES with the
+ * 7.5 surface — `reason()` calls `localizeContextBug`, `rerunTurn()` delegates
+ * to `rerunWithoutSources` and returns its result UNMODIFIED (the honesty
+ * tiers are not hidden). Session registries, UI joins, comparators and
+ * persistence stay host-side by design (see the guide's "What stays yours").
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/lib/recorded-chat/types.js.map

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

package/dist/types/debug.d.ts

@@ -23,4 +23,5 @@ export { buildSelfExplainSkill, buildSelfExplainToolProvider, SelfExplainBinding
 export { ablationForSuspect, applyAblations, assembleTrajectory, assignCostVerdicts, bisectCulprits, bucketByAnchors, shortlistEarlyCulprits, walkToRoot, walkTrajectory, buildWriterFrameIndex, DEFAULT_RECENCY_DECAY, classifySuspect, findLoopHeads, CONTEXT_BISECT_DEFAULTS, defaultOutcomeComparator, defaultSuspectClassifier, findDroppedContext, formatContextBugReport, llmCallIdsFromEvents, llmEdgeWeigher, localizeContextBug, probeFlipped, removableSources, rerunWithoutSources, runAblationProbe, runRestorationProbe, stepOutputText, suspectLabel, verdictFor, type AblationRerun, type AblationRunner, type AblationRunStats, type AblationSpec, type AblationTargets, type AblationVerdict, type AblationVerdictKind, type AnchorBucket, type AssembleTrajectoryOptions, type LoopCandidate, type LoopRecallShortlist, type ShortlistEarlyCulpritsOptions, type RootCauseHop, type RootCauseNote, type RootCausePath, type WalkToRootOptions, type BisectCulpritsOptions, type BisectionProbe, type BisectionResult, type CapturedEventLike, type ClassifyContext, type ContextBugArtifacts, type ContextBugReport, type ContextSource, type ContextUnit, type CostRange, type CostStats, type CostVerdict, type DroppedUnit, type EdgePathStep, type LoopFrame, type HonestyFlag, type HonestyFlagKind, type IgnoredSource, type LlmEdgeWeigherHandle, type LlmEdgeWeigherOptions, type LocalizeContextBugOptions, type MissingContextResult, type OutcomeComparator, type QualityTriggerLookup, type RankedParentEdge, type RemovableSource, type RerunWithoutSourcesOptions, type RerunWithoutSourcesResult, type RestorationProbeConfig, type RestorationRerun, type RestorationRunner, type RestoredCandidate, type RunCost, type SimilarityStats, type SliceStats, type Suspect, type SuspectClass, type SuspectClassifier, type SuspectDetail, type SuspectKind, type SuspectSeed, type SyntheticQuestionNode, type Trajectory, type WhatChanged, } from './lib/context-bisect/index.js';
 export { sliceToBacktrackTrace, toBacktrackTrace, type BacktrackCustodyHop, type BacktrackHop, type BacktrackSuspectCard, type BacktrackTrace, type BacktrackTrail, type SliceToBacktrackTraceOptions, type ToBacktrackTraceOptions, } from './lib/context-bisect/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 { recordedChat, type ChatFormat, type ChatMessage, type ChatTurn, type ForkOptions, type ForkOrigin, type MakeChatAgent, type ReasonOptions, type RecordedChat, type RecordedChatOptions, type RerunTurnOptions, type SendOptions, } from './lib/recorded-chat/index.js';
 //# sourceMappingURL=debug.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,yBAAyB,EACzB,YAAY,EACZ,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EACjC,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,EACb,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,kBAAkB,EAClB,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,GAC5B,MAAM,+BAA+B,CAAC;AAOvC,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,UAAU,EACV,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EAClC,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,GAC7B,MAAM,+BAA+B,CAAC;AAQvC,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,+BAA+B,EAC/B,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,uBAAuB,EACvB,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,KAAK,yBAAyB,EAC9B,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EAChB,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAC;AAQlC,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,8BAA8B,CAAC"}

package/dist/types/lib/recorded-chat/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * recorded-chat — the session-scoped turn recorder over the context-bisect
+ * product loop. Absorbs the three correctness traps every chat host re-writes
+ * (per-turn artifact freezing, byte-exact history threading, same-factory
+ * runner derivation) while COMPOSING with the 7.5 surface, not duplicating it.
+ *
+ * Exported from `agentfootprint/debug` (every symbol it composes with lives
+ * there). Named exports — `export *` is not the house style.
+ */
+export { recordedChat } from './recordedChat.js';
+export type { ChatFormat, ChatMessage, ChatTurn, ForkOptions, ForkOrigin, MakeChatAgent, ReasonOptions, RecordedChat, RecordedChatOptions, RerunTurnOptions, SendOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/recorded-chat/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/recorded-chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/types/lib/recorded-chat/recordedChat.d.ts

@@ -0,0 +1,21 @@
+/**
+ * recordedChat — the session-scoped turn recorder.
+ *
+ * `recordedChat({ makeAgent })` returns a `RecordedChat`: `send()` runs one
+ * recorded turn through the consumer's agent factory and freezes that turn's
+ * evidence immediately; `reason(k)` / `rerunTurn(k)` / `fork(k)` are the
+ * per-turn transparency loop, composing with the existing context-bisect
+ * surface (`localizeContextBug`, `rerunWithoutSources`) rather than
+ * duplicating it. See `./types.ts` for the three traps this owns.
+ *
+ * Compose-don't-inherit house style: a module-private session class,
+ * factory-returned; no base classes.
+ */
+import type { RecordedChat, RecordedChatOptions } from './types.js';
+/**
+ * Record a chat turn-by-turn so any reply can be explained, counterfactually
+ * re-run, and forked — without re-writing the correctness-critical glue every
+ * chat host gets subtly wrong. See the [recordedChat guide](doc:recorded-chat).
+ */
+export declare function recordedChat(options: RecordedChatOptions): RecordedChat;
+//# sourceMappingURL=recordedChat.d.ts.map

package/dist/types/lib/recorded-chat/recordedChat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordedChat.d.ts","sourceRoot":"","sources":["../../../../src/lib/recorded-chat/recordedChat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAaH,OAAO,KAAK,EAQV,YAAY,EACZ,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAwPpB;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAEvE"}

package/dist/types/lib/recorded-chat/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * recorded-chat types — the session-scoped turn recorder over the existing
+ * context-bisect product loop (localizeContextBug + rerunWithoutSources +
+ * removableSources).
+ *
+ * WHY THIS EXISTS: multi-turn chat on agentfootprint is a HOST convention —
+ * `AgentInput` has no history field, so hosts thread the transcript into the
+ * `message` string themselves. Every chat host that wanted per-turn
+ * transparency then re-wrote the same correctness-critical glue and got three
+ * things subtly wrong:
+ *
+ *   1. `agent.getLastSnapshot()` is last-run-only — a second `run()` clobbers
+ *      it, so reasoning about turn K after turn K+1 ran silently attributes
+ *      the wrong run.
+ *   2. History is a convention — the transcript preamble must be BYTE-identical
+ *      between the recorded turn and its counterfactual re-run, or the re-run
+ *      ablates a subtly different scenario without failing anything.
+ *   3. The `AblationRunner` duplicates turn construction — the re-run is only
+ *      valid if the rebuilt turn matches the recorded one (same system, facts,
+ *      preamble).
+ *
+ * `recordedChat({ makeAgent })` owns exactly those three: per-turn artifact
+ * freezing (1), byte-exact history threading (2), and deriving the turn-K
+ * runner from the SAME `makeAgent` that ran the turn (3). It COMPOSES with the
+ * 7.5 surface — `reason()` calls `localizeContextBug`, `rerunTurn()` delegates
+ * to `rerunWithoutSources` and returns its result UNMODIFIED (the honesty
+ * tiers are not hidden). Session registries, UI joins, comparators and
+ * persistence stay host-side by design (see the guide's "What stays yours").
+ */
+import type { RuntimeSnapshot } from 'footprintjs';
+import type { Agent } from '../../core/Agent.js';
+import type { MemoryIdentity } from '../../memory/identity/types.js';
+import type { AblationSpec, CapturedEventLike, ContextBugReport, LocalizeContextBugOptions, RerunWithoutSourcesOptions, RerunWithoutSourcesResult } from '../context-bisect/index.js';
+/**
+ * The ONE agent factory — live turns, rerun probes, baseline probes, and
+ * fork turns all go through it (the single source of truth the
+ * `AblationRunner` contract already demands).
+ *
+ * Contract (the `AblationRunner` contract, now enforced-by-shape for live
+ * turns too):
+ * - Return a FRESH agent with a FRESH provider on every call — scripted
+ *   mock providers are stateful (replies consume in order).
+ * - Apply `specs` at CONSTRUCTION (the documented seam): filter facts /
+ *   tools / memory entries with `applyAblations(specs, { ... })` before
+ *   building. `specs` is ALWAYS the union of the session's persistent
+ *   removals (forks carry these) and the probe's ablation specs; it is
+ *   empty for a plain live turn in an unforked session.
+ * - `seed` varies 0..N-1 across a probe's samples (always 0 for live
+ *   turns). Thread it into any stochastic knob; ignore it when the agent
+ *   is deterministic.
+ */
+export type MakeChatAgent = (build: {
+    readonly specs: readonly AblationSpec[];
+    readonly seed: number;
+}) => Agent | Promise<Agent>;
+/** How transcript lines and the per-turn message string are rendered. */
+export interface ChatFormat {
+    /** Preamble header line. Default `'Recent conversation:'`. */
+    readonly header?: string;
+    /** Label for user lines (`'<userLabel>: ...'`). Default `'User'`. */
+    readonly userLabel?: string;
+    /** Label for reply lines. Default `'Assistant'`. */
+    readonly assistantLabel?: string;
+}
+/** One transcript entry — the structured form of a rendered line. */
+export interface ChatMessage {
+    readonly role: 'user' | 'assistant';
+    readonly text: string;
+}
+export interface RecordedChatOptions {
+    readonly makeAgent: MakeChatAgent;
+    readonly format?: ChatFormat;
+    /**
+     * Transcript the session OPENS with (frozen; rendered as the seed
+     * preamble of every turn). `fork()` fills this; hosts may also pass a
+     * persisted transcript to rehydrate a session — authenticity of a
+     * hand-supplied seed is then the host's responsibility.
+     */
+    readonly seed?: readonly ChatMessage[];
+    /**
+     * Session-persistent removals: every turn (and every probe) in this
+     * session runs with these specs applied. `fork()` fills this so the
+     * what-if world STAYS the what-if world.
+     */
+    readonly removed?: readonly AblationSpec[];
+}
+/** One recorded turn — everything frozen at record time. */
+export interface ChatTurn {
+    /** 0-based position in `turns`. */
+    readonly index: number;
+    readonly userMessage: string;
+    /** The agent's reply (agentfootprint `AgentOutput` string). */
+    readonly reply: string;
+    /**
+     * The EXACT message string `agent.run()` received — composed once at
+     * record time. Re-runs of this turn replay these bytes verbatim; the
+     * byte-exact-history guarantee lives here.
+     */
+    readonly message: string;
+    /** Rendered transcript lines the turn opened with (frozen copy). */
+    readonly transcriptBefore: readonly string[];
+    /**
+     * Localize-ready evidence: pass straight to
+     * `localizeContextBug({ artifacts: turn.artifacts, ... })`.
+     */
+    readonly artifacts: {
+        readonly snapshot: RuntimeSnapshot;
+        readonly events: readonly CapturedEventLike[];
+    };
+    /** runtimeStageId of the turn's LAST LLM call — the default `atStep`. */
+    readonly lastLlmCallId: string | undefined;
+    /** The identity `send()` was given, threaded into re-runs unchanged. */
+    readonly identity: MemoryIdentity | undefined;
+}
+export interface SendOptions {
+    /** Multi-tenant memory scope, passed through to `agent.run()`. */
+    readonly identity?: MemoryIdentity;
+}
+/** `reason(k)` options — localize passthrough minus what the turn provides. */
+export interface ReasonOptions extends Omit<LocalizeContextBugOptions, 'artifacts' | 'rerun'> {
+    /** Recompute even if a memoized report exists (e.g. a new scorer). */
+    readonly fresh?: boolean;
+}
+/** `rerunTurn(k)` options — `rerunWithoutSources` minus what the turn provides. */
+export interface RerunTurnOptions extends Omit<RerunWithoutSourcesOptions, 'report' | 'runner' | 'originalAnswer'> {
+    /**
+     * The report to resolve `ignore` against. Default: the turn's memoized
+     * `reason(k)` report (computed with this call's `embedder` + the default
+     * scorer if none exists yet).
+     */
+    readonly report?: ContextBugReport;
+}
+export interface ForkOptions {
+    /**
+     * Seed the fork's last reply with this counterfactual answer. MUST be a
+     * result produced by THIS session's `rerunTurn(k, ...)` for the SAME k
+     * (identity-checked) — a fabricated fork would be a lie. Omitted: the
+     * fork continues from the ORIGINAL reply (a plain branch, no ablation).
+     */
+    readonly fromRerun?: RerunWithoutSourcesResult;
+}
+export interface ForkOrigin {
+    readonly parent: RecordedChat;
+    readonly turnIndex: number;
+    /** True when the fork was seeded from a re-run's counterfactual answer. */
+    readonly viaRerun: boolean;
+}
+export interface RecordedChat {
+    /** Runs one recorded turn. One send at a time — concurrent sends throw. */
+    send(userMessage: string, options?: SendOptions): Promise<ChatTurn>;
+    /** Turn K's frozen record. Out-of-range throws (names the valid range). */
+    turn(k: number): ChatTurn;
+    readonly turns: readonly ChatTurn[];
+    /** The transcript the session opened with (forks / rehydration; else `[]`). */
+    readonly seed: readonly ChatMessage[];
+    /** The session's persistent removals (forks carry these; else `[]`). */
+    readonly removed: readonly AblationSpec[];
+    /** Set on sessions created by `fork()`; `undefined` otherwise. */
+    readonly forkedFrom: ForkOrigin | undefined;
+    /**
+     * Turn K's `ContextBugReport` (agentfootprint's, unmodified) via
+     * `localizeContextBug` over the frozen artifacts, `atStep` defaulted to
+     * the turn's last LLM call. Memoized per turn; `fresh: true` recomputes.
+     */
+    reason(k: number, options: ReasonOptions): Promise<ContextBugReport>;
+    /**
+     * Re-run turn K without the named sources — same recorded history bytes,
+     * same user message, minus the sources — delegating to
+     * `rerunWithoutSources` with a runner derived from `makeAgent`. Returns
+     * agentfootprint's `RerunWithoutSourcesResult` UNMODIFIED (a `verdict`
+     * only when `checkBaseline: true` — the honesty tiers are not hidden).
+     */
+    rerunTurn(k: number, options: RerunTurnOptions): Promise<RerunWithoutSourcesResult>;
+    /**
+     * Branch, never rewrite: a NEW `RecordedChat` (same `makeAgent`, same
+     * format) whose seed is the conversation through turn K with the reply
+     * swapped for the re-run's counterfactual answer (or kept, without
+     * `fromRerun`), and whose `removed` is this session's removals plus the
+     * re-run's `removed` specs. The original session is never touched.
+     */
+    fork(k: number, options?: ForkOptions): RecordedChat;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/recorded-chat/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "7.5.0",
+  "version": "7.6.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",