agentfootprint 7.4.0 → 7.6.0

package/dist/esm/lib/influence-core/lexical.d.ts

@@ -0,0 +1,60 @@
+/**
+ * scoreLexicalInfluence — the DETERMINISTIC, zero-dependency influence
+ * scorer: the same four-signal FDL frame as `scoreInfluence`
+ * (fa / avg / persist / depth, adaptive weights, composite, stable desc
+ * sort), with ONE substitution — cosine-over-embeddings becomes set-cosine
+ * over word tokens. Nothing here embeds; nothing here calls the network.
+ *
+ * ## Honest claim (same discipline as `scoreInfluence`, one rung blinder)
+ *
+ * Every returned `InfluenceScore.signals` / `weights` / `adapted` is
+ * GENUINELY computed — nothing is fabricated. But the FA signal here means
+ * "shares words with the final answer", NOT "semantically close" and NOT
+ * "caused". It is cheaper and BLINDER than `'semantic-alignment'`: a
+ * paraphrase (different words, same meaning) is a miss. The claim-ladder
+ * guarantee is unchanged — a scorer only reorders suspects; ablation alone
+ * convicts. So the worst a lexical ranking does is confirm slower, never
+ * wrong.
+ *
+ * English / ASCII by construction (the tokenizer splits on non-alphanumerics
+ * and folds a single trailing plural `s`) — use `'semantic-alignment'` for
+ * other languages.
+ */
+import type { Embedder, EvidenceInput, InfluenceScore, InfluenceWeights } from './types.js';
+/**
+ * Args for `scoreLexicalInfluence` — a SUPERTYPE of `ScoreInfluenceArgs`:
+ * everything the embedding scorer takes, with `embedder` optional and NEVER
+ * called. That supertype relationship is what makes `scoreLexicalInfluence`
+ * assignable to `InfluenceScorer` (parameter contravariance) while remaining
+ * honestly callable with no embedder at all.
+ */
+export interface ScoreLexicalInfluenceArgs {
+    /** Evidence items (tool results / context sources) with ancestors. */
+    readonly evidence: readonly EvidenceInput[];
+    /** The final answer text the evidence is scored against. */
+    readonly finalAnswerText: string;
+    /** Accepted only for `InfluenceScorer` compatibility. IGNORED — this scorer never embeds. */
+    readonly embedder?: Embedder;
+    /** Composite weights (same frame as `scoreInfluence`). Default 0.40/0.30/0.20/0.10. */
+    readonly weights?: InfluenceWeights;
+    /** PERSIST threshold on the LEXICAL overlap scale (set-cosine, 0..1). Default 0.30. */
+    readonly persistenceThreshold?: number;
+    /** Accepted for compatibility; unused (nothing async to abort — resolves immediately). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Score every evidence item on the four FDL signals — the LEXICAL kernel
+ * (set-cosine over word tokens instead of embedding cosine) — and rank by
+ * composite, descending. Ties keep input order (stable sort).
+ *
+ * Deterministic: same inputs → byte-identical output, every run, every
+ * machine. Zero dependencies, zero network, sync-fast (async only to satisfy
+ * the `InfluenceScorer` seam). Never touches `args.embedder` or `args.signal`.
+ *
+ * Honest claim: ranked WORD-OVERLAP proxies — cheaper and blinder than the
+ * embedding scorer (paraphrase = miss). NOT causal attribution — see module
+ * docs.
+ *
+ * @throws on duplicate evidence ids or invalid weights.
+ */
+export declare function scoreLexicalInfluence(args: ScoreLexicalInfluenceArgs): Promise<InfluenceScore[]>;

package/dist/esm/lib/influence-core/lexical.js

@@ -0,0 +1,142 @@
+import { DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_PERSISTENCE_THRESHOLD } from './types.js';
+import { adaptWeights, assertUniqueIds, assertValidWeights, compositeScore, structuralProximity, } from './signals.js';
+/** Small, conservative stop list — fillers that would only add noise to
+ *  the overlap. Copied verbatim from the injection-engine's `EntryScorer`
+ *  (influence-core is a leaf — it restates rather than imports). */
+const STOP_WORDS = new Set([
+    'a',
+    'an',
+    'the',
+    'and',
+    'or',
+    'but',
+    'if',
+    'to',
+    'of',
+    'for',
+    'in',
+    'on',
+    'at',
+    'by',
+    'with',
+    'is',
+    'are',
+    'was',
+    'were',
+    'be',
+    'been',
+    'it',
+    'this',
+    'that',
+    'these',
+    'those',
+    'i',
+    'you',
+    'we',
+    'my',
+    'our',
+    'me',
+    'please',
+    'can',
+    'could',
+    'would',
+    'should',
+    'do',
+    'does',
+    'how',
+    'what',
+    'need',
+    'want',
+]);
+/**
+ * Lowercase → split on non-alphanumerics → drop 1-char tokens + stop words →
+ * light plural fold → set. The plural fold (drop a single trailing `s` on
+ * tokens length ≥ 4, but never `-ss`) lets `refund` match `refunds` while
+ * `address` stays `address`. ASCII-only by construction (the regex splits
+ * away non-Latin/accented text — use `'semantic-alignment'` for other
+ * languages).
+ */
+function tokenize(text) {
+    const out = new Set();
+    for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 2 || STOP_WORDS.has(raw))
+            continue;
+        const fold = raw.length >= 4 && raw.endsWith('s') && !raw.endsWith('ss');
+        out.add(fold ? raw.slice(0, -1) : raw);
+    }
+    return out;
+}
+/** |A ∩ B| / sqrt(|A| · |B|) — set cosine, range [0, 1]. Empty either side → 0.
+ *  Iterates the smaller set (same kernel as EntryScorer's `setCosine`). */
+function overlap(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+    let shared = 0;
+    for (const t of small)
+        if (large.has(t))
+            shared += 1;
+    return shared / Math.sqrt(a.size * b.size);
+}
+/**
+ * Score every evidence item on the four FDL signals — the LEXICAL kernel
+ * (set-cosine over word tokens instead of embedding cosine) — and rank by
+ * composite, descending. Ties keep input order (stable sort).
+ *
+ * Deterministic: same inputs → byte-identical output, every run, every
+ * machine. Zero dependencies, zero network, sync-fast (async only to satisfy
+ * the `InfluenceScorer` seam). Never touches `args.embedder` or `args.signal`.
+ *
+ * Honest claim: ranked WORD-OVERLAP proxies — cheaper and blinder than the
+ * embedding scorer (paraphrase = miss). NOT causal attribution — see module
+ * docs.
+ *
+ * @throws on duplicate evidence ids or invalid weights.
+ */
+export async function scoreLexicalInfluence(args) {
+    const weights = args.weights ?? DEFAULT_INFLUENCE_WEIGHTS;
+    assertValidWeights(weights, 'scoreLexicalInfluence');
+    const threshold = args.persistenceThreshold ?? DEFAULT_PERSISTENCE_THRESHOLD;
+    assertUniqueIds(args.evidence, 'scoreLexicalInfluence');
+    // One deduplicated tokenization pass over every distinct text.
+    const tokensByText = new Map();
+    const tokensOf = (text) => {
+        let set = tokensByText.get(text);
+        if (set === undefined) {
+            set = tokenize(text);
+            tokensByText.set(text, set);
+        }
+        return set;
+    };
+    const answerTokens = tokensOf(args.finalAnswerText);
+    const scored = args.evidence.map((item) => {
+        const evidenceTokens = tokensOf(item.text);
+        const ancestorTokens = item.ancestorTexts.map((t) => tokensOf(t));
+        const n = ancestorTokens.length;
+        let avgSum = 0;
+        let above = 0;
+        for (const ancestor of ancestorTokens) {
+            const sim = overlap(evidenceTokens, ancestor);
+            avgSum += sim;
+            if (sim > threshold)
+                above += 1;
+        }
+        const signals = {
+            fa: overlap(evidenceTokens, answerTokens),
+            avg: n === 0 ? 0 : avgSum / n,
+            persist: n === 0 ? 0 : above / n,
+            depth: structuralProximity(n),
+        };
+        const effective = adaptWeights(weights, n);
+        return {
+            id: item.id,
+            signals,
+            weights: effective.weights,
+            adapted: effective.adapted,
+            score: compositeScore(signals, effective.weights),
+        };
+    });
+    // Stable sort — equal scores keep evidence input order.
+    return scored.sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=lexical.js.map

package/dist/esm/lib/influence-core/lexical.js.map

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

package/dist/esm/lib/influence-core/signals.d.ts

@@ -126,3 +126,8 @@ export declare function embedAll(embedder: Embedder, texts: readonly string[], s
  * attributes the error to the actual caller.
  */
 export declare function assertValidWeights(weights: InfluenceWeights, fnName?: string): void;
+/**
+ * Validate that every evidence id is unique. Shared by `scoreInfluence` and
+ * `scoreLexicalInfluence` — `fnName` attributes the error to the actual caller.
+ */
+export declare function assertUniqueIds(evidence: readonly EvidenceInput[], fnName?: string): void;

package/dist/esm/lib/influence-core/signals.js

@@ -225,11 +225,15 @@ export function assertValidWeights(weights, fnName = 'scoreInfluence') {
         throw new Error(`${fnName}: all weights are zero — the composite would always be 0`);
     }
 }
-function assertUniqueIds(evidence) {
+/**
+ * Validate that every evidence id is unique. Shared by `scoreInfluence` and
+ * `scoreLexicalInfluence` — `fnName` attributes the error to the actual caller.
+ */
+export function assertUniqueIds(evidence, fnName = 'scoreInfluence') {
     const seen = new Set();
     for (const item of evidence) {
         if (seen.has(item.id)) {
-            throw new Error(`scoreInfluence: duplicate evidence id '${item.id}' — ids must be unique`);
+            throw new Error(`${fnName}: duplicate evidence id '${item.id}' — ids must be unique`);
         }
         seen.add(item.id);
     }

package/dist/esm/lib/influence-core/signals.js.map

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

package/dist/esm/lib/influence-core/strategies.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Named influence strategies — a plain-named descriptor AROUND the already-
+ * public `InfluenceScorer` function seam, exactly the shape a host UI's
+ * strategy selector needs (mirrors the `EntryScorer` / `ConfidenceStrategy`
+ * "name shown in any strategy picker" precedent).
+ *
+ * A strategy is `{ name, description, requirements, scorer }`. Two ship:
+ *   • `semanticAlignmentStrategy` — the FDL four-signal embedding composite
+ *     (`scoreInfluence`). The default; needs an embedder.
+ *   • `lexicalOverlapStrategy`    — deterministic word overlap
+ *     (`scoreLexicalInfluence`). Free, zero deps; requires nothing.
+ *
+ * `listInfluenceStrategies()` enumerates them so a selector can render the
+ * two options and grey out what the host can't run (`requirements`).
+ *
+ * Sugar, not a replacement: `localizeContextBug({ scorer })` still accepts a
+ * bare `InfluenceScorer` function; it now ALSO accepts one of these.
+ */
+import type { InfluenceScorer } from './signals.js';
+/**
+ * What a strategy needs the host to supply before it can run. A selector UI
+ * greys out strategies whose requirements the host can't meet. `'embedder'`
+ * is the only well-known value today; the type stays open for consumer
+ * strategies (`'llm'`, `'reference-run'`, …).
+ */
+export type InfluenceStrategyRequirement = 'embedder' | (string & Record<never, never>);
+/**
+ * A NAMED influence-scoring strategy — an `InfluenceScorer` plus the metadata
+ * a strategy picker needs. Sugar AROUND the function seam, not a replacement:
+ * `localizeContextBug({ scorer })` accepts either a bare `InfluenceScorer` or
+ * one of these.
+ */
+export interface InfluenceStrategy {
+    /** Stable kebab-case id — shown in a selector, echoed on `ContextBugReport.rankedBy`. */
+    readonly name: string;
+    /** One-or-two-sentence plain description for the picker, honesty caveat included. */
+    readonly description: string;
+    /** What the host must supply to run this strategy (empty = runs anywhere, $0). */
+    readonly requirements: readonly InfluenceStrategyRequirement[];
+    /** The scorer itself — plugs into `localizeContextBug({ scorer })` directly. */
+    readonly scorer: InfluenceScorer;
+}
+/** The DEFAULT: the FDL four-signal embedding composite (`scoreInfluence`). */
+export declare const semanticAlignmentStrategy: InfluenceStrategy;
+/** The cheap option: deterministic word overlap (`scoreLexicalInfluence`), zero deps. */
+export declare const lexicalOverlapStrategy: InfluenceStrategy;
+/**
+ * The built-in strategies, default first. Frozen — a host UI renders its
+ * selector straight off this (concat your own custom strategies after).
+ */
+export declare function listInfluenceStrategies(): readonly InfluenceStrategy[];

package/dist/esm/lib/influence-core/strategies.js

@@ -0,0 +1,29 @@
+import { scoreInfluence } from './signals.js';
+import { scoreLexicalInfluence } from './lexical.js';
+/** The DEFAULT: the FDL four-signal embedding composite (`scoreInfluence`). */
+export const semanticAlignmentStrategy = Object.freeze({
+    name: 'semantic-alignment',
+    description: 'Ranks sources by how semantically close their content is to the final answer, using ' +
+        'embeddings (the four-signal composite). The default. Needs an embedder; scores are a ' +
+        'proxy for alignment, never proof of cause.',
+    requirements: Object.freeze(['embedder']),
+    scorer: scoreInfluence,
+});
+/** The cheap option: deterministic word overlap (`scoreLexicalInfluence`), zero deps. */
+export const lexicalOverlapStrategy = Object.freeze({
+    name: 'lexical-overlap',
+    description: 'Ranks sources by plain word overlap with the final answer. Deterministic, free, no ' +
+        'dependencies — the simpler, cheaper option. Misses paraphrases; same proxy caveat: ' +
+        'overlap is not cause.',
+    requirements: Object.freeze([]),
+    scorer: scoreLexicalInfluence,
+});
+const BUILT_IN = Object.freeze([semanticAlignmentStrategy, lexicalOverlapStrategy]);
+/**
+ * The built-in strategies, default first. Frozen — a host UI renders its
+ * selector straight off this (concat your own custom strategies after).
+ */
+export function listInfluenceStrategies() {
+    return BUILT_IN;
+}
+//# sourceMappingURL=strategies.js.map

package/dist/esm/lib/influence-core/strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/strategies.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AA2BrD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,yBAAyB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACxE,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EACT,sFAAsF;QACtF,uFAAuF;QACvF,4CAA4C;IAC9C,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU,CAAU,CAAC;IAClD,MAAM,EAAE,cAAc;CACvB,CAAC,CAAC;AAEH,yFAAyF;AACzF,MAAM,CAAC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACrE,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,qFAAqF;QACrF,qFAAqF;QACrF,uBAAuB;IACzB,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,EAAW,CAAC;IACxC,MAAM,EAAE,qBAAqB;CAC9B,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,yBAAyB,EAAE,sBAAsB,CAAC,CAAC,CAAC;AAEpF;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,QAAQ,CAAC;AAClB,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