agentfootprint 7.5.0 → 7.6.1

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/esm/recorders/core/types.d.ts

@@ -81,13 +81,20 @@ export interface EvictionRecord {
 }
 /**
  * Budget-pressure warning — emitted before evictions fire.
+ *
+ * `capTokens` / `projectedTokens` are historical names: slot budgets are
+ * measured in CHARS. Renaming them would be breaking, so they stay.
+ *
+ * `planAction: 'none'` means no mitigation was performed — nothing was
+ * evicted or truncated and the full content still went to the LLM. It is
+ * the honest reading of a slot that composed over its `budgetCap`.
  */
 export interface BudgetPressureRecord {
     readonly slot: ContextSlot;
     readonly capTokens: number;
     readonly projectedTokens: number;
     readonly overflowBy: number;
-    readonly planAction: 'evict' | 'summarize' | 'abort';
+    readonly planAction: 'evict' | 'summarize' | 'abort' | 'none';
 }
 export declare const COMPOSITION_KEYS: {
     readonly SLOT_COMPOSED: "slotCompositions";

package/dist/esm/recorders/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/recorders/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6FH,uEAAuE;AACvE,0EAA0E;AAC1E,4BAA4B;AAC5B,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,aAAa,EAAE,kBAAkB;IACjC,OAAO,EAAE,eAAe;IACxB,eAAe,EAAE,qBAAqB;CAC9B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/recorders/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoGH,uEAAuE;AACvE,0EAA0E;AAC1E,4BAA4B;AAC5B,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,aAAa,EAAE,kBAAkB;IACjC,OAAO,EAAE,eAAe;IACxB,eAAe,EAAE,qBAAqB;CAC9B,CAAC"}

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"}