agentfootprint 10.2.0 → 10.3.1

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

@@ -1,247 +0,0 @@
-"use strict";
-/**
- * innerRunRecords — the record a tool keeps of its OWN run.
- *
- * Pattern: bounded LRU store + a structural join key (a registry symbol).
- * Role:    the one place the outer trace and an inner trace are allowed to
- *          know about each other. Nothing here executes, renders, or
- *          formats — it holds records and hands them back by id.
- *
- * THE GAP
- * ───────
- * `inspect_tool_call` resolves a tool call end to end and then stops at a
- * wall: *"⚠ boundary: what happened INSIDE the tool is not traced."* That
- * marker is honest for a tool that calls someone else's system. It is
- * needlessly honest for a tool that IS a footprintjs flowchart — that tool
- * recorded every stage it ran, and then threw the recording away, because
- * nobody was holding it.
- *
- * So: hold it. `flowchartAsTool({ keepRecord: true })` keeps each
- * invocation's inner record here, keyed by the `toolCallId` the outer run
- * already uses to name that call. One id, two levels — which is what makes
- * the descent a lookup rather than a correlation puzzle.
- *
- * WHY BOUNDED, AND WHY LRU
- * ────────────────────────
- * A retained snapshot is retained memory. An agent that runs a chart tool
- * on every turn for a week would pin every one of those runs, and the
- * failure would look like a leak rather than like a feature. So the store
- * has a cap (default {@link DEFAULT_INNER_RUN_LIMIT}), drops the
- * least-recently-USED record when it overflows, and COUNTS the drops —
- * because "we kept the last 20 of 340" is an answer a debugging session can
- * act on, and a silently missing row is not.
- *
- * Reading refreshes recency on purpose: a record under active investigation
- * (three drills into one inner run) must not be the next one evicted by a
- * turn happening beside it.
- *
- * THE JOIN KEY
- * ────────────
- * The store rides the `Tool` object under a registry symbol rather than a
- * named property: a `Tool` is a consumer-authored shape, and a plain name
- * like `innerRuns` would be a name a consumer's own tool could collide
- * with. `Symbol.for` (registry, not unique-per-module) because this package
- * ships CJS *and* ESM — two module instances of this file must agree on the
- * key or a tool built in one half would be invisible to the other.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.innerRunsOfConversation = exports.mergeInnerRuns = exports.innerRunStore = exports.innerRunsOf = exports.INNER_RUN_RECORDS = exports.DEFAULT_INNER_RUN_LIMIT = void 0;
-/**
- * How many invocations one tool keeps by default.
- *
- * Twenty is a debugging window, not an archive: enough that "the call three
- * turns ago" is still there, small enough that a long-lived server holding
- * one store per chart tool has a ceiling it can multiply out. Raise it with
- * `keepRecordLimit` when the sessions are long and the charts are small.
- */
-exports.DEFAULT_INNER_RUN_LIMIT = 20;
-/**
- * The key an inner-record store rides on a `Tool`.
- *
- * Registry symbol, not a unique one: this package ships CJS and ESM, and a
- * tool built through one entry point must be readable through the other.
- */
-exports.INNER_RUN_RECORDS = Symbol.for('agentfootprint.trace.innerRunRecords');
-/**
- * Read the inner-run store off a candidate, or undefined when it carries
- * none. Structural and total — a plain tool, a string, `null` all answer
- * "no records" rather than throwing.
- */
-function innerRunsOf(candidate) {
-    if (candidate === null || typeof candidate !== 'object')
-        return undefined;
-    const held = candidate[exports.INNER_RUN_RECORDS];
-    if (held === null || typeof held !== 'object')
-        return undefined;
-    return typeof held.get === 'function' ? held : undefined;
-}
-exports.innerRunsOf = innerRunsOf;
-/**
- * A bounded LRU store of inner runs.
- *
- * @param limit maximum retained records (clamped to at least 1 — a store
- *              that keeps nothing is `keepRecord: false`, and saying so with
- *              a zero would be config that lies).
- */
-function innerRunStore(limit = exports.DEFAULT_INNER_RUN_LIMIT) {
-    const cap = Math.max(1, Math.floor(limit));
-    // Insertion order IS recency order: delete-then-set moves a key to the
-    // end, so the first key is always the least-recently-used one. Keyed by
-    // run AND call id — see `InnerRunRecord.runId`.
-    const records = new Map();
-    let dropped = 0;
-    // Drops per outer run ('' = no run), bounded like the records they count.
-    const dropsByRun = new Map();
-    const keyOf = (record) => `${record.runId ?? ''}\u001f${record.toolCallId}`;
-    const touch = (key, record) => {
-        records.delete(key);
-        records.set(key, record);
-    };
-    const newestWhere = (toolCallId, accept) => {
-        const all = [...records.entries()];
-        for (let i = all.length - 1; i >= 0; i--) {
-            const entry = all[i];
-            if (entry[1].toolCallId === toolCallId && accept(entry[1]))
-                return entry;
-        }
-        return undefined;
-    };
-    // Reading refreshes recency (a record under investigation stays).
-    const getWhere = (toolCallId, accept) => {
-        const found = newestWhere(toolCallId, accept);
-        if (found === undefined)
-            return undefined;
-        touch(found[0], found[1]);
-        return found[1];
-    };
-    return {
-        keep(record) {
-            touch(keyOf(record), record);
-            while (records.size > cap) {
-                const oldest = records.entries().next().value;
-                if (oldest === undefined)
-                    break;
-                records.delete(oldest[0]);
-                dropped++;
-                const run = oldest[1].runId ?? '';
-                dropsByRun.delete(run);
-                dropsByRun.set(run, (dropsByRun.get(run) ?? 0) + 1);
-                while (dropsByRun.size > cap * 4) {
-                    const first = dropsByRun.keys().next();
-                    if (first.done === true)
-                        break;
-                    dropsByRun.delete(first.value);
-                }
-            }
-        },
-        get: (toolCallId) => getWhere(toolCallId, () => true),
-        getWhere,
-        list() {
-            return [...records.values()].map((record) => ({
-                toolCallId: record.toolCallId,
-                toolName: record.toolName,
-                outcome: record.outcome,
-                steps: record.steps,
-                ...(record.runId !== undefined && { runId: record.runId }),
-            }));
-        },
-        get dropped() {
-            return dropped;
-        },
-        droppedWhere(accept) {
-            let total = 0;
-            for (const [run, count] of dropsByRun)
-                if (accept(run === '' ? undefined : run))
-                    total += count;
-            return total;
-        },
-        get limit() {
-            return cap;
-        },
-    };
-}
-exports.innerRunStore = innerRunStore;
-/**
- * One lookup over several stores — an agent may mount more than one chart
- * tool, and the model asking "descend into call c3" should not have to know
- * which tool produced c3.
- *
- * Returns undefined for an empty list so callers can spread the field
- * conditionally rather than passing an empty lookup that answers "nothing
- * was kept" when the truth is "nothing keeps anything".
- */
-function mergeInnerRuns(lookups) {
-    if (lookups.length === 0)
-        return undefined;
-    if (lookups.length === 1)
-        return lookups[0];
-    return {
-        get: (toolCallId) => {
-            for (const lookup of lookups) {
-                const found = lookup.get(toolCallId);
-                if (found !== undefined)
-                    return found;
-            }
-            return undefined;
-        },
-        getWhere: (toolCallId, accept) => {
-            for (const lookup of lookups) {
-                const found = viewGet(lookup, toolCallId, accept);
-                if (found !== undefined)
-                    return found;
-            }
-            return undefined;
-        },
-        list: () => lookups.flatMap((lookup) => lookup.list()),
-        get dropped() {
-            return lookups.reduce((total, lookup) => total + lookup.dropped, 0);
-        },
-        droppedWhere: (accept) => lookups.reduce((total, lookup) => total + (lookup.droppedWhere?.(accept) ?? 0), 0),
-        get limit() {
-            return Math.min(...lookups.map((lookup) => lookup.limit));
-        },
-    };
-}
-exports.mergeInnerRuns = mergeInnerRuns;
-/**
- * The records ONE conversation's runs filed — the view a self-explaining agent
- * serves (`selfExplain.ts · SelfExplainBinding`), so a why-question asked in
- * one conversation can neither descend into, list, nor count a call another
- * conversation's run made.
- *
- * `belongs(runId)` answers for a record's outer run (`InnerRunRecord.runId`);
- * a record that names no run is asked with `undefined`. A record the view does
- * not admit answers exactly like a record never kept — the same not-found, so
- * the view says nothing about whether anyone else called the tool — and its
- * drops are not in `dropped`. `limit` is the store's.
- *
- * @example
- * ```ts
- * const mine = innerRunsOfConversation(lookup, (runId) => myRuns.has(runId ?? ''));
- * mine.get('call-from-another-run'); // undefined — not found, not forbidden
- * ```
- */
-function innerRunsOfConversation(lookup, belongs) {
-    const admits = (record) => belongs(record.runId);
-    return {
-        get: (toolCallId) => viewGet(lookup, toolCallId, admits),
-        getWhere: (toolCallId, accept) => viewGet(lookup, toolCallId, (record) => admits(record) && accept(record)),
-        list: () => lookup.list().filter((summary) => belongs(summary.runId)),
-        get dropped() {
-            return lookup.droppedWhere?.(belongs) ?? 0;
-        },
-        droppedWhere: (accept) => lookup.droppedWhere?.((runId) => belongs(runId) && accept(runId)) ?? 0,
-        get limit() {
-            return lookup.limit;
-        },
-    };
-}
-exports.innerRunsOfConversation = innerRunsOfConversation;
-/** `getWhere` when the lookup has it; else `get`, admitted or not found. */
-function viewGet(lookup, toolCallId, accept) {
-    if (lookup.getWhere !== undefined)
-        return lookup.getWhere(toolCallId, accept);
-    const found = lookup.get(toolCallId);
-    return found !== undefined && accept(found) ? found : undefined;
-}
-//# sourceMappingURL=innerRunRecords.js.map

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

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

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

@@ -1,104 +0,0 @@
-"use strict";
-/**
- * lazyTraceToolpack — the toolpack with LATE-BOUND artifacts.
- *
- * `traceToolpack(artifacts)` is a factory over FROZEN artifacts: it
- * precomputes an index and even bakes step-id enums into tool schemas.
- * That is right for the dedicated debugger (the run is already complete
- * when you build it) — and wrong for `.selfExplain()`, where the tools
- * are defined at Agent BUILD time but must read the agent's own *previous
- * completed run*, which changes every turn.
- *
- * This wrapper splits the two lifetimes:
- *
- *   - SCHEMAS are built once from an empty template (artifact-independent —
- *     no id enums, generic descriptions; the same shape `traceToolpack`
- *     itself produces past the enum cap), so the tools can be mounted on
- *     a skill before any run exists.
- *   - EXECUTION resolves `resolve()` per call, builds the REAL toolpack
- *     over the resolved artifacts (memoized by snapshot identity — one
- *     index per completed run, not per call), and delegates through
- *     `callTraceTool` so arg validation matches the eager path.
- *
- * When `resolve()` returns undefined (no completed run yet), every tool
- * answers with an honest, model-visible message instead of throwing —
- * the same #9 philosophy as the toolpack's unknown-id corrections.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.lazyTraceToolpack = exports.missingArtifactMessage = exports.NO_COMPLETED_RUN_MESSAGE = void 0;
-const traceToolpack_js_1 = require("./traceToolpack.js");
-const traceToolNames_js_1 = require("./traceToolNames.js");
-Object.defineProperty(exports, "NO_COMPLETED_RUN_MESSAGE", { enumerable: true, get: function () { return traceToolNames_js_1.NO_COMPLETED_RUN_MESSAGE; } });
-/**
- * Model-visible answer when a tool MOUNTED on the catalog has no evidence
- * to serve for this particular run.
- *
- * The lazy pack's shape is fixed at Agent BUILD time — the tool catalog and
- * the builder's name reservation both need to know the list before any run
- * exists — while an artifact bag's OPTIONAL parts (the narrative, the event
- * tail) are decided per run. So a tool can be on the catalog with nothing
- * behind it, and the honest move is to say which switch turns it back on
- * rather than to answer emptily.
- */
-function missingArtifactMessage(toolName) {
-    const part = toolName === 'read_narrative' ? 'narrative' : 'events';
-    return (`${toolName} has nothing to read for this run — the captured evidence carries no ` +
-        `${part}. This agent was built with selfExplain({ include: { ${part}: false } }), or the ` +
-        `artifacts were assembled without it. The other trace tools are unaffected.`);
-}
-exports.missingArtifactMessage = missingArtifactMessage;
-/**
- * Minimal empty snapshot for building artifact-independent template
- * schemas. The cast is safe because the toolpack's CONSTRUCTION reads
- * only `commitLog` (`?? []`) and `executionTree` (visit() guards
- * undefined) — `sharedState`/`commitValues` are read only inside
- * execute paths, and the wrapper below shadows every template execute.
- */
-const EMPTY_SNAPSHOT = {
-    commitLog: [],
-    executionTree: undefined,
-    sharedState: {},
-    commitValues: 'full',
-};
-/**
- * Build the toolpack with late-bound artifacts.
- *
- * The template is built over an artifact bag that declares EVERY optional
- * part (an empty narrative, an empty event tail), so the lazy pack mounts
- * the same tool list every time. That fixed list is what the Agent
- * builder's name reservation and the tool catalog are both keyed on — a
- * pack whose shape depended on a run that has not happened yet could not
- * be reserved at build time. When a resolved run turns out not to carry
- * one of those parts, the tool answers with
- * {@link missingArtifactMessage} instead of quietly disappearing.
- */
-function lazyTraceToolpack(resolve, options) {
-    const template = (0, traceToolpack_js_1.traceToolpack)({ snapshot: EMPTY_SNAPSHOT, narrative: [], events: [] }, options);
-    // One real toolpack per completed run: memoized by snapshot identity.
-    // Retention note: the memo pins at most ONE prior snapshot (whatever a
-    // trace tool last executed against) until the next call rebinds it.
-    let memoSnapshot;
-    let memoTools;
-    const realTools = (artifacts) => {
-        if (memoTools === undefined || memoSnapshot !== artifacts.snapshot) {
-            memoSnapshot = artifacts.snapshot;
-            memoTools = (0, traceToolpack_js_1.traceToolpack)(artifacts, options);
-        }
-        return memoTools;
-    };
-    return template.map((tool) => ({
-        ...tool,
-        execute: async (args) => {
-            const artifacts = resolve();
-            if (!artifacts)
-                return traceToolNames_js_1.NO_COMPLETED_RUN_MESSAGE;
-            const real = realTools(artifacts);
-            if (!real.some((candidate) => candidate.schema.name === tool.schema.name)) {
-                return missingArtifactMessage(tool.schema.name);
-            }
-            return (0, traceToolpack_js_1.callTraceTool)(real, tool.schema.name, args);
-        },
-    }));
-}
-exports.lazyTraceToolpack = lazyTraceToolpack;
-//# sourceMappingURL=lazyToolpack.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"lazyToolpack.js","sourceRoot":"","sources":["../../../src/lib/trace-toolpack/lazyToolpack.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAKH,yDAAkE;AAClE,2DAA+D;AAMtD,yGANA,4CAAwB,OAMA;AAEjC;;;;;;;;;;GAUG;AACH,SAAgB,sBAAsB,CAAC,QAAgB;IACrD,MAAM,IAAI,GAAG,QAAQ,KAAK,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;IACpE,OAAO,CACL,GAAG,QAAQ,uEAAuE;QAClF,GAAG,IAAI,wDAAwD,IAAI,uBAAuB;QAC1F,4EAA4E,CAC7E,CAAC;AACJ,CAAC;AAPD,wDAOC;AAED;;;;;;GAMG;AACH,MAAM,cAAc,GAAG;IACrB,SAAS,EAAE,EAAE;IACb,aAAa,EAAE,SAAS;IACxB,WAAW,EAAE,EAAE;IACf,YAAY,EAAE,MAAM;CACS,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,SAAgB,iBAAiB,CAC/B,OAAiD,EACjD,OAA8B;IAE9B,MAAM,QAAQ,GAAG,IAAA,gCAAa,EAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IAEjG,sEAAsE;IACtE,uEAAuE;IACvE,oEAAoE;IACpE,IAAI,YAAyC,CAAC;IAC9C,IAAI,SAA6B,CAAC;IAClC,MAAM,SAAS,GAAG,CAAC,SAAiC,EAAU,EAAE;QAC9D,IAAI,SAAS,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,CAAC,QAAQ,EAAE,CAAC;YACnE,YAAY,GAAG,SAAS,CAAC,QAAQ,CAAC;YAClC,SAAS,GAAG,IAAA,gCAAa,EAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7B,GAAG,IAAI;QACP,OAAO,EAAE,KAAK,EAAE,IAA6B,EAAE,EAAE;YAC/C,MAAM,SAAS,GAAG,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,SAAS;gBAAE,OAAO,4CAAwB,CAAC;YAChD,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1E,OAAO,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,IAAA,gCAAa,EAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrD,CAAC;KACF,CAAC,CAAC,CAAC;AACN,CAAC;AA/BD,8CA+BC"}

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

@@ -1,128 +0,0 @@
-"use strict";
-/**
- * openRecording — a saved run, reopened as evidence a model can navigate.
- *
- * Pattern: pure adapter. One shape in (`Recording`), one shape out
- *          (`TraceToolpackArtifacts`). No engine, no agent, no I/O.
- * Role:    the door between the two halves of this library that already
- *          knew about each other's data and had no way to say so.
- *
- * `recordRun(agent)` freezes a run into `{ snapshot, events, structure }` —
- * the shape a viewer reads. The trace toolpack reads a different shape.
- * Until now, a team with a recording on disk from last Tuesday and a
- * question about it had to reassemble the bag by hand, which meant
- * reassembling it differently in every integration and losing the
- * narrative and the events on the way.
- *
- *   const recording = JSON.parse(fs.readFileSync('run.json', 'utf8'));
- *   const tools = traceToolpack(openRecording(recording));
- *   await callTraceTool(tools, 'run_overview');
- *
- * WHAT SURVIVES THE ROUND TRIP, AND WHAT DOES NOT
- * ───────────────────────────────────────────────
- * A recording is JSON. Everything the toolpack needs from the snapshot
- * survives that (the commit log, the execution tree, shared state, the
- * mode discriminants) and so do the events. Two things do not:
- *
- *   - `controlDeps` is a LOOKUP FUNCTION built by a recorder that watched
- *     the run happen. A function does not serialize, and nothing in a
- *     finished recording can rebuild one. So slices opened over a
- *     recording carry the toolpack's existing "⚠ control edges
- *     unavailable" marker — the honest answer, already written.
- *   - The narrative survives only if it was ATTACHED. `recordRun`
- *     deliberately attaches no narrative recorder (see its header), so a
- *     recording made without `narrative()` has none, and `read_narrative`
- *     is simply not mounted. This function lifts it from the snapshot's
- *     recorder rows when it IS there.
- *
- * `structure` — the build-time chart — has no reader in the toolpack: the
- * toolpack navigates what a run DID, and the chart says what it COULD do.
- * It is left on the recording for the viewers that draw it.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.openRecording = exports.narrativeFrom = void 0;
-const recordingPack_js_1 = require("../../recorders/observability/recordingPack.js");
-/**
- * The narrative recorder's row: `data` is an array of `{ text, depth }`.
- *
- * @internal Exported for the bug-report bundler, which writes the same lines to
- * `narrative.txt`. One shape-detector, one answer to "is there a narrative in
- * this snapshot?" — two copies would disagree the first time the row changes.
- */
-function narrativeFrom(snapshot) {
-    const rows = snapshot.recorders;
-    if (!Array.isArray(rows))
-        return undefined;
-    for (const row of rows) {
-        const data = row?.data;
-        if (!Array.isArray(data) || data.length === 0)
-            continue;
-        // Identify by SHAPE, not by id. A consumer may attach `narrative({ id })`
-        // under any id they like, and a row whose entries carry `text` + `depth`
-        // is a narrative whatever it calls itself.
-        const first = data[0];
-        if (typeof first?.text !== 'string' || typeof first?.depth !== 'number')
-            continue;
-        return data.map((entry) => typeof entry?.text === 'string' ? entry.text : '');
-    }
-    return undefined;
-}
-exports.narrativeFrom = narrativeFrom;
-/**
- * Reopen a saved recording as toolpack artifacts.
- *
- * @param recording the `{ snapshot, events, structure }` bundle from
- *                  `recordRun(...).toRecording()` — live, or parsed back
- *                  from JSON — or the same recording packed
- *                  (`packRecording`), which is expanded first.
- *
- * A packed recording is expanded only when its plain form is within
- * `unpackRecording`'s default bound (`DEFAULT_UNPACK_MAX_BYTES`, 512 MiB): the
- * toolpack previews a value by serializing it, so it walks what it reads as a
- * tree, and a few KB packed can stand for far more than any plain recording
- * could hold. A larger recording you trust is opened by expanding it first,
- * with the bound you choose:
- * `openRecording(unpackRecording(packed, { maxBytes }))`.
- *
- * @throws PackedRecordingTooLargeError for a packed recording over that bound.
- * @throws when the recording carries no usable snapshot. A toolpack over
- *         an empty bag would answer every question with "nothing
- *         happened", which is the one answer a debugging session must
- *         never be given by mistake.
- */
-function openRecording(input) {
-    const recording = (0, recordingPack_js_1.unpackRecording)(input);
-    const snapshot = recording?.snapshot;
-    if (snapshot === null || typeof snapshot !== 'object') {
-        throw new Error('openRecording: this recording has no snapshot. A recording is ' +
-            '{ snapshot, events, structure } and the snapshot is the part the trace tools read — ' +
-            'without it there is no commit log, no execution tree, and nothing to explain. ' +
-            'Produce one with `recordRun(agent)` BEFORE the run and `toRecording()` after it; a ' +
-            'bundle assembled by hand after the fact cannot contain one.');
-    }
-    if (!Array.isArray(snapshot.commitLog) || snapshot.executionTree === undefined) {
-        const missing = [
-            Array.isArray(snapshot.commitLog) ? undefined : 'commitLog',
-            snapshot.executionTree === undefined ? 'executionTree' : undefined,
-        ]
-            .filter(Boolean)
-            .join(' and ');
-        throw new Error(`openRecording: the snapshot in this recording is missing ${missing} — the trace tools ` +
-            'navigate a run by what each step wrote (commitLog) and what each step was ' +
-            '(executionTree), so neither is optional. This usually means the object handed in is ' +
-            'not a footprintjs run snapshot (a partial log, a UI view model, an older format). ' +
-            'The producer is `recordRun(agent).toRecording()`, whose `snapshot` is ' +
-            '`agent.getLastSnapshot()` verbatim.');
-    }
-    const narrative = narrativeFrom(snapshot);
-    const events = recording?.events;
-    return {
-        snapshot,
-        // controlDeps is deliberately absent — see the header. The toolpack
-        // already says "⚠ control edges unavailable" rather than pretending.
-        ...(narrative !== undefined && { narrative }),
-        ...(Array.isArray(events) && { events: events }),
-    };
-}
-exports.openRecording = openRecording;
-//# sourceMappingURL=openRecording.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"openRecording.js","sourceRoot":"","sources":["../../../src/lib/trace-toolpack/openRecording.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;;;AAMH,qFAGwD;AAqBxD;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,QAE7B;IACC,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,GAAG,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACxD,0EAA0E;QAC1E,yEAAyE;QACzE,2CAA2C;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAoD,CAAC;QACzE,IAAI,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,EAAE,KAAK,KAAK,QAAQ;YAAE,SAAS;QAClF,OAAQ,IAA6B,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAClD,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAClD,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAlBD,sCAkBC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,aAAa,CAAC,KAA0C;IACtE,MAAM,SAAS,GAAG,IAAA,kCAAe,EAAC,KAAK,CAAkC,CAAC;IAC1E,MAAM,QAAQ,GAAG,SAAS,EAAE,QAEf,CAAC;IAEd,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CACb,gEAAgE;YAC9D,sFAAsF;YACtF,gFAAgF;YAChF,qFAAqF;YACrF,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QAC/E,MAAM,OAAO,GAAG;YACd,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;YAC3D,QAAQ,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;SACnE;aACE,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,OAAO,CAAC,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,4DAA4D,OAAO,qBAAqB;YACtF,4EAA4E;YAC5E,sFAAsF;YACtF,oFAAoF;YACpF,wEAAwE;YACxE,qCAAqC,CACxC,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC;IACjC,OAAO;QACL,QAAQ;QACR,oEAAoE;QACpE,qEAAqE;QACrE,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAwC,EAAE,CAAC;KACnF,CAAC;AACJ,CAAC;AAzCD,sCAyCC"}