agentfootprint 1.23.0 → 2.0.1

package/dist/esm/recorders/AgentTimelineRecorder.js

@@ -1,1107 +0,0 @@
-/**
- * AgentTimelineRecorder — the canonical agent-shaped narrative.
- *
- * THE ABSTRACTION (mirrors footprintjs CombinedNarrativeRecorder):
- *
- *   footprintjs                            agentfootprint
- *   ───────────                            ──────────────
- *   CombinedNarrativeRecorder              AgentTimelineRecorder
- *      ↓ produces NarrativeEntry[]            ↓ produces AgentTimeline
- *      ↓ for ANY UI                           ↓ for ANY UI
- *   ExplainableShell, custom shells       Lens, Grafana panels,
- *                                         CLI debuggers, replay tools
- *
- * The library emits `agentfootprint.stream.*` + `agentfootprint.context.*`
- * events at every interesting moment in a run. This recorder is the ONE
- * PLACE every UI / observability consumer translates that emit stream
- * into the agent-shaped narrative they render against (turns →
- * iterations → tool calls + per-iteration context injections + ledger).
- * One recorder, one shape, every consumer.
- *
- * Storage primitive: footprintjs `SequenceRecorder<TimelineEntry>` —
- * inherits insertion-ordered storage, O(1) per-step lookup via
- * runtimeStageId map, range index for time-travel sliders, and
- * progressive `accumulate()` reduction. We don't reinvent these.
- *
- * @example
- * ```ts
- * import { Agent, agentTimeline, anthropic } from 'agentfootprint';
- *
- * const t = agentTimeline();
- * const agent = Agent.create({ provider: anthropic('claude-sonnet-4') })
- *   .recorder(t)
- *   .build();
- *
- * await agent.run('Investigate port errors on switch-3');
- *
- * // v2 API — call selectors, not a pre-shaped bundle
- * t.selectTurns();         // AgentTurn[] — iterations with tool calls + context
- * t.selectActivities();    // Activity[] — humanized breadcrumb list (ThinkKit)
- * t.selectStatus();        // StatusLine — typing-bubble one-liner
- * t.selectCommentary();    // CommentaryLine[] — human narrative per event
- * t.selectTopology();      // Topology — composition graph for flowchart view
- * t.selectRunSummary();    // RunSummary — tokens, tools, duration totals
- * t.setHumanizer({ describeToolStart: ... });  // swap domain phrasings
- * ```
- *
- * Multi-agent: each sub-agent in a Pipeline/Swarm gets its own named
- * instance — `agentTimeline({ id: 'classify' })` — and each lands in
- * its own `executor.getSnapshot().recorders[id]` slot. Multi-agent
- * shells aggregate them by id.
- */
-import { SequenceRecorder, TopologyRecorder } from 'footprintjs/trace';
-/**
- * AgentTimelineRecorder v2 — event stream + selectors + humanizer.
- *
- * THE ARCHITECTURE (one shape, many renderers):
- *
- *   EVENT STREAM              (structured, canonical — single source of truth)
- *       ↓
- *   SELECTORS                 (typed, memoized, lazy, composable — THE API)
- *       ↓
- *   VIEWS                     (React / Vue / Angular / CLI / Grafana / replay)
- *
- * Consumers never reshape data themselves — they call selectors. New
- * renderer view? Add a selector. Never add pre-computed fields to some
- * timeline blob (that's the anti-pattern this design replaces).
- *
- * OBSERVER CHANNELS (from footprintjs):
- *
- *   1. EmitRecorder       — `agentfootprint.stream.*` / `.context.*`
- *                           events translate into the `AgentEvent` stream.
- *   2. FlowRecorder       — subflow / fork / decision / loop events
- *                           forwarded to a composed `TopologyRecorder`.
- *   3. SequenceRecorder<AgentEvent> base — storage + O(1) per-step lookup.
- *
- * Footprintjs's `attachCombinedRecorder` detects which methods this
- * recorder implements and routes events accordingly. Consumers attach
- * once; all three channels wire up automatically.
- *
- * HUMANIZATION: swap `setHumanizer(custom)` to override generic phrasings
- * ("Running toolName") with domain-specific strings ("Checking port status
- * on switch-3"). The library NEVER bakes rendered strings into events —
- * they appear only at selector time, through the humanizer, so translation,
- * localization, and UX tone changes don't require data-model changes.
- */
-export class AgentTimelineRecorder extends SequenceRecorder {
-    id;
-    name;
-    /** True between an iter's llm_start and llm_end. Drives context-event
-     *  routing (THIS iter vs NEXT iter). */
-    llmPhaseActive = false;
-    /** Composed topology accumulator — selectors use this for subflow/
-     *  fork/decision queries. Private; consumers query via `selectTopology()`. */
-    topology;
-    /** Active humanizer. Starts as the default; consumer swaps via
-     *  `setHumanizer`. */
-    humanizer = {};
-    /**
-     * Memoization version — incremented on every `emit()` and `clear()`.
-     * Selector results are keyed by `(selectorName, version, cursor)`. A
-     * long run renders many frames without recomputing unchanged views.
-     */
-    version = 0;
-    cache = new Map();
-    constructor(options) {
-        super();
-        this.id = options?.id ?? 'agentfootprint-agent-timeline';
-        this.name = options?.name ?? 'Agent';
-        this.topology = new TopologyRecorder({ id: `${this.id}-topology` });
-    }
-    // ── EmitRecorder ─────────────────────────────────────────────────────
-    /**
-     * Translate the incoming emit event into an `AgentEvent` and append to
-     * the stream. Events not in the agent shape are silently dropped —
-     * executors deliver events from many subsystems.
-     */
-    onEmit(event) {
-        const entry = translate(event, this.llmPhaseActive);
-        if (!entry)
-            return;
-        if (entry.type === 'llm_start')
-            this.llmPhaseActive = true;
-        if (entry.type === 'llm_end' || entry.type === 'turn_end') {
-            this.llmPhaseActive = false;
-        }
-        this.emit(entry);
-        this.bumpVersion();
-    }
-    // ── FlowRecorder hooks (forward to composed TopologyRecorder) ────────
-    onSubflowEntry(event) {
-        this.topology.onSubflowEntry(event);
-        this.bumpVersion();
-    }
-    onSubflowExit(event) {
-        this.topology.onSubflowExit(event);
-        this.bumpVersion();
-    }
-    onFork(event) {
-        this.topology.onFork(event);
-        this.bumpVersion();
-    }
-    onDecision(event) {
-        this.topology.onDecision(event);
-        this.bumpVersion();
-    }
-    onLoop(event) {
-        this.topology.onLoop(event);
-        this.bumpVersion();
-    }
-    clear() {
-        super.clear();
-        this.llmPhaseActive = false;
-        this.topology.clear();
-        this.bumpVersion();
-    }
-    // ── Raw event-stream access ──────────────────────────────────────────
-    /** The canonical event stream. Most consumers call selectors instead;
-     *  this is for low-level tools (custom renderers, debug bundles). */
-    getEvents() {
-        return this.getEntries();
-    }
-    /** Direct access to the composed topology recorder for consumers that
-     *  need the full composition graph (fork-branches, decision-branches,
-     *  edges). Equivalent for rendering: use `selectTopology()`. */
-    getTopology() {
-        return this.topology;
-    }
-    // ── Humanizer ────────────────────────────────────────────────────────
-    /** Override or replace the active humanizer. Invalidates memoized
-     *  selector results so the next read re-phrases. */
-    setHumanizer(humanizer) {
-        this.humanizer = humanizer;
-        this.bumpVersion();
-    }
-    /** Returns the currently-active humanizer (consumer-supplied). */
-    getHumanizer() {
-        return this.humanizer;
-    }
-    // ── Selectors (memoized, lazy, the API) ──────────────────────────────
-    /** Agent identity — { id, name } from constructor options. */
-    selectAgent() {
-        return { id: this.id, name: this.name };
-    }
-    /** All turns with their iterations, tool calls, context injections. */
-    selectTurns() {
-        return this.memo('turns', () => foldTurns(this.getEvents()));
-    }
-    /** Message list mirroring `sharedState.messages` (reconstructed from
-     *  `turn_start.userMessage` + `llm_end.content` + assistant tool calls
-     *  + `tool_end.result`). */
-    selectMessages() {
-        return this.memo('messages', () => foldMessages(this.getEvents()));
-    }
-    /** All tool invocations across all turns, in chronological order. */
-    selectTools() {
-        return this.memo('tools', () => foldTools(this.getEvents()));
-    }
-    /** Sub-agent slices for multi-agent runs. Identity from the composed
-     *  topology's subflow nodes; per-sub-agent content (turns, tools) folded
-     *  from emit events tagged with matching `subflowPath[0]`. Empty for
-     *  single-agent runs. */
-    selectSubAgents() {
-        return this.memo('subAgents', () => deriveSubAgentSlices(this.getEvents(), this.topology));
-    }
-    /** Final decision object captured from `agentfootprint.agent.turn_complete`. */
-    selectFinalDecision() {
-        return this.memo('finalDecision', () => foldFinalDecision(this.getEvents()));
-    }
-    /** Composition graph snapshot. Renderers use `nodes`/`edges` for layout. */
-    selectTopology() {
-        // Topology has its own internal state; snapshot once per query.
-        return this.topology.getTopology();
-    }
-    /** Event-reduced activity list for status/progress renderers (ThinkKit).
-     *  Humanized labels. Optional cursor: only include events up to that
-     *  index (progressive reveal / time-travel scrubbing). */
-    selectActivities(cursor) {
-        const key = cursor === undefined ? 'activities:all' : `activities:${cursor}`;
-        return this.memo(key, () => reduceActivities(this.getEvents(), this.humanizer, cursor));
-    }
-    /** Single-line current status — for typing bubbles / "now running…" pills.
-     *  Cursor defaults to the latest event. */
-    selectStatus(cursor) {
-        const key = cursor === undefined ? 'status:latest' : `status:${cursor}`;
-        return this.memo(key, () => deriveStatus(this.getEvents(), this.humanizer, cursor));
-    }
-    /** Human-readable narrative — one line per significant event. For
-     *  analyst-style commentary panels. Humanized. */
-    selectCommentary(cursor) {
-        const key = cursor === undefined ? 'commentary:all' : `commentary:${cursor}`;
-        return this.memo(key, () => buildCommentary(this.getEvents(), this.humanizer, cursor));
-    }
-    /** Numeric totals — turn count, token usage, duration, tool usage. */
-    selectRunSummary() {
-        return this.memo('runSummary', () => computeRunSummary(this.getEvents()));
-    }
-    /** Context-engineering injection summary — per slot, grouped by source
-     *  (rag / skill / memory / instructions / custom). Powers slot-row badges
-     *  on the flowchart AND the analyst Commentary panel. Cursor-aware:
-     *  pass an event index to see injections up to that point. */
-    selectContextBySource(cursor) {
-        const key = cursor === undefined ? 'contextBySource:all' : `contextBySource:${cursor}`;
-        return this.memo(key, () => computeContextBySource(this.getEvents(), cursor));
-    }
-    /** Iteration ↔ event-stream index map for scrubbers / time-travel. */
-    selectIterationRanges() {
-        return this.memo('iterationRanges', () => computeIterationRanges(this.getEvents()));
-    }
-    // ── Internals ────────────────────────────────────────────────────────
-    bumpVersion() {
-        this.version++;
-        this.cache.clear();
-    }
-    memo(key, compute) {
-        const cacheKey = `${key}@${this.version}`;
-        const cached = this.cache.get(cacheKey);
-        if (cached !== undefined)
-            return cached;
-        const value = compute();
-        this.cache.set(cacheKey, value);
-        return value;
-    }
-}
-/**
- * Public factory. Use this in app code rather than `new AgentTimelineRecorder()`
- * — matches the convention of `agentObservability()`, `contextEngineering()`,
- * and footprintjs's `narrative()` / `metrics()` / `debug()`.
- */
-export function agentTimeline(options) {
-    return new AgentTimelineRecorder(options);
-}
-// ── Translation ───────────────────────────────────────────────────────
-function translate(event, llmPhaseActive) {
-    const ts = event.timestamp;
-    const id = event.runtimeStageId;
-    const payload = (event.payload ?? {});
-    const name = event.name;
-    // Preserve subflowPath verbatim — the folder uses it to derive the
-    // multi-agent `subAgents` slices. Empty array for root flowchart.
-    const subflowPath = event.subflowPath ?? [];
-    if (name === 'agentfootprint.stream.llm_start') {
-        return {
-            type: 'llm_start',
-            runtimeStageId: id,
-            timestamp: ts,
-            subflowPath,
-            iteration: numberOr(payload.iteration, 1),
-        };
-    }
-    if (name === 'agentfootprint.stream.llm_end') {
-        return {
-            type: 'llm_end',
-            runtimeStageId: id,
-            timestamp: ts,
-            subflowPath,
-            iteration: numberOr(payload.iteration, 1),
-            content: stringOr(payload.content, ''),
-            ...(typeof payload.model === 'string' && { model: payload.model }),
-            ...maybeUsage(payload.usage),
-            ...(typeof payload.stopReason === 'string' && { stopReason: payload.stopReason }),
-            ...(typeof payload.durationMs === 'number' && { durationMs: payload.durationMs }),
-            toolCallCount: numberOr(payload.toolCallCount, 0),
-        };
-    }
-    if (name === 'agentfootprint.stream.tool_start') {
-        return {
-            type: 'tool_start',
-            runtimeStageId: id,
-            timestamp: ts,
-            subflowPath,
-            toolName: stringOr(payload.toolName, 'unknown'),
-            toolCallId: stringOr(payload.toolCallId, `tool-${ts}`),
-            args: payload.args ?? {},
-        };
-    }
-    if (name === 'agentfootprint.stream.tool_end') {
-        const r = payload.result;
-        const result = typeof r === 'string'
-            ? r
-            : r && typeof r === 'object'
-                ? stringOr(r.content, '')
-                : '';
-        const error = r && typeof r === 'object' && r.error === true;
-        return {
-            type: 'tool_end',
-            runtimeStageId: id,
-            timestamp: ts,
-            subflowPath,
-            toolCallId: stringOr(payload.toolCallId, ''),
-            result,
-            ...(error ? { error: true } : {}),
-            ...(typeof payload.durationMs === 'number' ? { durationMs: payload.durationMs } : {}),
-        };
-    }
-    if (name === 'agentfootprint.agent.turn_start') {
-        return {
-            type: 'turn_start',
-            runtimeStageId: id,
-            timestamp: ts,
-            subflowPath,
-            userMessage: stringOr(payload.userMessage, ''),
-        };
-    }
-    if (name === 'agentfootprint.agent.turn_complete') {
-        return {
-            type: 'turn_end',
-            runtimeStageId: id,
-            timestamp: ts,
-            subflowPath,
-            ...(typeof payload.content === 'string' && { finalContent: payload.content }),
-        };
-    }
-    if (name.startsWith('agentfootprint.context.')) {
-        const suffix = name.slice('agentfootprint.context.'.length);
-        const tagged = buildContextInjection(suffix, payload);
-        return {
-            type: 'context_injection',
-            runtimeStageId: id,
-            timestamp: ts,
-            subflowPath,
-            ...tagged,
-            attachedToCurrentIter: llmPhaseActive,
-        };
-    }
-    return null;
-}
-function buildContextInjection(suffix, data) {
-    const role = typeof data.role === 'string' ? data.role : undefined;
-    const targetIndex = typeof data.targetIndex === 'number' ? data.targetIndex : undefined;
-    const deltaCount = data.deltaCount && typeof data.deltaCount === 'object'
-        ? data.deltaCount
-        : undefined;
-    const enriched = {
-        ...(role !== undefined && { role }),
-        ...(targetIndex !== undefined && { targetIndex }),
-        ...(deltaCount !== undefined && { deltaCount }),
-        payload: data,
-    };
-    switch (suffix) {
-        case 'rag.chunks': {
-            const chunkCount = numberOr(data.chunkCount, 0);
-            const topScore = typeof data.topScore === 'number' ? data.topScore : undefined;
-            const label = chunkCount > 0
-                ? `${chunkCount} chunk${chunkCount === 1 ? '' : 's'}${topScore !== undefined ? ` · top ${topScore.toFixed(2)}` : ''}`
-                : '0 chunks';
-            return { source: 'rag', slot: 'messages', label, ...enriched };
-        }
-        case 'skill.activated': {
-            const skillId = stringOr(data.skillId, 'skill');
-            return { source: 'skill', slot: 'system-prompt', label: skillId, ...enriched };
-        }
-        case 'memory.injected': {
-            const count = numberOr(data.count, 0);
-            const label = count > 0 ? `memory · ${count} msg${count === 1 ? '' : 's'}` : 'memory';
-            return { source: 'memory', slot: 'messages', label, ...enriched };
-        }
-        case 'instructions.fired': {
-            const count = numberOr(data.count, Array.isArray(data.ids) ? data.ids.length : 1);
-            const label = `${count} instruction${count === 1 ? '' : 's'}`;
-            return { source: 'instructions', slot: 'system-prompt', label, ...enriched };
-        }
-        default:
-            return {
-                source: suffix.split('.')[0] || 'context',
-                slot: 'messages',
-                label: suffix,
-                ...enriched,
-            };
-    }
-}
-function stringOr(v, fallback) {
-    return typeof v === 'string' ? v : fallback;
-}
-function numberOr(v, fallback) {
-    return typeof v === 'number' ? v : fallback;
-}
-function maybeUsage(u) {
-    if (!u || typeof u !== 'object')
-        return {};
-    const x = u;
-    const out = {};
-    if (typeof x.inputTokens === 'number')
-        out.inputTokens = x.inputTokens;
-    if (typeof x.outputTokens === 'number')
-        out.outputTokens = x.outputTokens;
-    return out;
-}
-function foldCore(entries) {
-    const turns = [];
-    const messages = [];
-    const toolByCallId = new Map();
-    let pendingPreIterInjections = [];
-    let currentTurn = null;
-    let currentIter = null;
-    for (const entry of entries) {
-        switch (entry.type) {
-            case 'turn_start': {
-                currentTurn = {
-                    index: turns.length,
-                    userPrompt: entry.userMessage,
-                    iterations: [],
-                    finalContent: '',
-                    totalInputTokens: 0,
-                    totalOutputTokens: 0,
-                    totalDurationMs: 0,
-                };
-                turns.push(currentTurn);
-                if (entry.userMessage) {
-                    messages.push({ role: 'user', content: entry.userMessage });
-                }
-                pendingPreIterInjections = [];
-                currentIter = null;
-                break;
-            }
-            case 'llm_start': {
-                // Synthesize a turn anchor if none exists. Real executors call
-                // recorder.clear() at run-start, wiping any turn_start that
-                // arrived via observe() BEFORE run. Rather than forcing every
-                // caller to emit turn_start on the emit channel, we recover
-                // here: first llm_start without a turn creates a synthetic one.
-                if (!currentTurn) {
-                    currentTurn = {
-                        index: turns.length,
-                        userPrompt: '',
-                        iterations: [],
-                        finalContent: '',
-                        totalInputTokens: 0,
-                        totalOutputTokens: 0,
-                        totalDurationMs: 0,
-                    };
-                    turns.push(currentTurn);
-                }
-                currentIter = {
-                    index: entry.iteration,
-                    assistantContent: '',
-                    toolCalls: [],
-                    decisionAtStart: {},
-                    visibleTools: [],
-                    messagesSentCount: messages.length,
-                    contextInjections: pendingPreIterInjections,
-                };
-                pendingPreIterInjections = [];
-                currentTurn.iterations.push(currentIter);
-                break;
-            }
-            case 'llm_end': {
-                if (!currentIter || !currentTurn)
-                    continue;
-                currentIter.assistantContent = entry.content;
-                if (entry.model !== undefined)
-                    currentIter.model = entry.model;
-                if (entry.inputTokens !== undefined) {
-                    currentIter.inputTokens = entry.inputTokens;
-                    currentTurn.totalInputTokens += entry.inputTokens;
-                }
-                if (entry.outputTokens !== undefined) {
-                    currentIter.outputTokens = entry.outputTokens;
-                    currentTurn.totalOutputTokens += entry.outputTokens;
-                }
-                if (entry.stopReason !== undefined)
-                    currentIter.stopReason = entry.stopReason;
-                if (entry.durationMs !== undefined) {
-                    currentIter.durationMs = entry.durationMs;
-                    currentTurn.totalDurationMs += entry.durationMs;
-                }
-                if (entry.content) {
-                    messages.push({ role: 'assistant', content: entry.content });
-                }
-                if (entry.toolCallCount === 0) {
-                    currentTurn.finalContent = entry.content;
-                }
-                // currentIter STAYS bound — tool_start fires AFTER llm_end and
-                // belongs to this iteration. The phase flag in the recorder
-                // tracks llm-active separately for context routing.
-                break;
-            }
-            case 'tool_start': {
-                if (!currentIter || !currentTurn)
-                    continue;
-                const tool = {
-                    id: entry.toolCallId || `tool-${currentIter.toolCalls.length}`,
-                    name: entry.toolName,
-                    arguments: entry.args,
-                    result: '',
-                    iterationIndex: currentIter.index,
-                    turnIndex: currentTurn.index,
-                };
-                currentIter.toolCalls.push(tool);
-                toolByCallId.set(tool.id, tool);
-                break;
-            }
-            case 'tool_end': {
-                const tool = toolByCallId.get(entry.toolCallId);
-                if (!tool)
-                    continue;
-                tool.result = entry.result;
-                if (entry.error === true)
-                    tool.error = true;
-                if (entry.durationMs !== undefined)
-                    tool.durationMs = entry.durationMs;
-                messages.push({ role: 'tool', content: entry.result, toolCallId: tool.id });
-                break;
-            }
-            case 'context_injection': {
-                if (!currentTurn)
-                    continue;
-                const injection = {
-                    source: entry.source,
-                    slot: entry.slot,
-                    label: entry.label,
-                    ...(entry.role !== undefined && { role: entry.role }),
-                    ...(entry.targetIndex !== undefined && { targetIndex: entry.targetIndex }),
-                    ...(entry.deltaCount !== undefined && { deltaCount: entry.deltaCount }),
-                    payload: entry.payload,
-                };
-                if (entry.attachedToCurrentIter && currentIter) {
-                    currentIter.contextInjections.push(injection);
-                }
-                else {
-                    pendingPreIterInjections.push(injection);
-                }
-                break;
-            }
-            case 'turn_end': {
-                if (!currentTurn)
-                    continue;
-                if (entry.finalContent && !currentTurn.finalContent) {
-                    currentTurn.finalContent = entry.finalContent;
-                }
-                currentTurn = null;
-                currentIter = null;
-                break;
-            }
-        }
-    }
-    // Freeze + derive turn-level fields
-    const allTools = [];
-    const frozenTurns = turns.map((t) => {
-        const turnInjections = [];
-        const turnLedger = {};
-        const iterations = t.iterations.map((i) => {
-            const tcs = i.toolCalls.map((tc) => ({ ...tc }));
-            allTools.push(...tcs);
-            const contextInjections = [...i.contextInjections];
-            const contextLedger = {};
-            for (const ci of contextInjections) {
-                if (!ci.deltaCount)
-                    continue;
-                for (const [key, val] of Object.entries(ci.deltaCount)) {
-                    if (typeof val === 'number') {
-                        const prev = typeof contextLedger[key] === 'number' ? contextLedger[key] : 0;
-                        contextLedger[key] = prev + val;
-                        const prevTurn = typeof turnLedger[key] === 'number' ? turnLedger[key] : 0;
-                        turnLedger[key] = prevTurn + val;
-                    }
-                    else if (typeof val === 'boolean') {
-                        contextLedger[key] = contextLedger[key] === true || val;
-                        turnLedger[key] = turnLedger[key] === true || val;
-                    }
-                }
-            }
-            turnInjections.push(...contextInjections);
-            return {
-                ...i,
-                toolCalls: tcs,
-                contextInjections,
-                contextLedger,
-            };
-        });
-        return {
-            ...t,
-            iterations,
-            contextInjections: turnInjections,
-            contextLedger: turnLedger,
-        };
-    });
-    return {
-        turns: frozenTurns,
-        messages: [...messages],
-        tools: allTools,
-        finalDecision: {},
-    };
-}
-// ── Slice helpers — used by selectors ─────────────────────────────────
-/**
- * Multi-agent slices: the topology supplies sub-agent identity (id, name);
- * per-sub-agent content (turns, tools) is folded from emit events whose
- * `subflowPath[0]` matches the node's id. Both sources come from the same
- * executor traversal — topology via FlowRecorder events, subflowPath via
- * emit-event metadata — but it's the recorder's job to stitch them.
- *
- * For sub-agents that have no matching emit events (e.g. a plain-stage
- * fork child), turns/tools are empty arrays.
- */
-/**
- * An Agent's signature — the set of API-slot subflows every Agent
- * mounts via `buildAgentLoop`. A topology subflow that CONTAINS any of
- * these as a child is an Agent wrapper (and therefore a sub-agent when
- * nested inside a composition runner). Subflows that ARE one of these
- * slots themselves, or other leaf subflows not containing a slot, are
- * internal structure — not sub-agents.
- *
- * This heuristic replaces a hardcoded deny-list. Robust against new
- * internal-agent subflows added later (they'll auto-classify as
- * "internal" because they don't wrap slots).
- */
-const AGENT_SLOT_SUBFLOW_IDS = new Set([
-    'sf-system-prompt',
-    'sf-messages',
-    'sf-tools',
-]);
-/** TopologyRecorder disambiguates re-entered subflows with a `#n`
- *  suffix. Strip that suffix so a re-entered slot still matches the
- *  signature set. */
-function baseSubflowId(id) {
-    const hashIdx = id.indexOf('#');
-    return hashIdx === -1 ? id : id.slice(0, hashIdx);
-}
-function isAgentWrapper(nodeId, topology) {
-    // A sub-agent is a subflow whose descendants in the topology tree
-    // include at least one of the API-slot signature subflows.
-    const stack = [...topology.getChildren(nodeId)];
-    while (stack.length > 0) {
-        const child = stack.pop();
-        if (AGENT_SLOT_SUBFLOW_IDS.has(baseSubflowId(child.id)))
-            return true;
-        stack.push(...topology.getChildren(child.id));
-    }
-    return false;
-}
-function deriveSubAgentSlices(events, topology) {
-    const allNodes = topology.getSubflowNodes();
-    // Keep only subflows that WRAP an Agent (have API-slot descendants).
-    // In single-agent runs, the slots are top-level — nothing wraps them
-    // → empty array → Lens renders the single-agent flowchart.
-    // In multi-agent (Pipeline/Parallel/Swarm/Conditional), each sub-agent
-    // root wraps its own slots → returned as a sub-agent.
-    const nodes = allNodes.filter((n) => isAgentWrapper(n.id, topology));
-    if (nodes.length === 0)
-        return [];
-    // Group events by first subflowPath segment. Keep only events whose
-    // top-of-path IS one of the classified sub-agents (filter out events
-    // belonging to internal-agent subflows of the root agent, which are
-    // technically at subflowPath[0] in single-agent runs but aren't
-    // sub-agents).
-    const subAgentIds = new Set(nodes.map((n) => n.id));
-    const bySubAgent = new Map();
-    for (const e of events) {
-        const id = e.subflowPath[0];
-        if (!id || !subAgentIds.has(id))
-            continue;
-        const arr = bySubAgent.get(id) ?? [];
-        arr.push(e);
-        bySubAgent.set(id, arr);
-    }
-    // Synthesize a turn_start so the fold has a turn anchor (sub-agents
-    // inherit the parent's conversation; they don't emit their own
-    // turn_start events).
-    const parentTurnStart = events.find((e) => e.type === 'turn_start');
-    const parentUserMessage = parentTurnStart?.type === 'turn_start' ? parentTurnStart.userMessage : '';
-    return nodes.map((node) => {
-        const subEvents = bySubAgent.get(node.id);
-        if (!subEvents || subEvents.length === 0) {
-            return { id: node.id, name: node.name, turns: [], tools: [] };
-        }
-        const synthTurnStart = {
-            type: 'turn_start',
-            runtimeStageId: `synth:turn_start:${node.id}`,
-            timestamp: subEvents[0]?.timestamp ?? Date.now(),
-            subflowPath: [node.id],
-            userMessage: parentUserMessage,
-        };
-        const bundle = foldCore([synthTurnStart, ...subEvents]);
-        return { id: node.id, name: node.name, turns: bundle.turns, tools: bundle.tools };
-    });
-}
-function foldTurns(events) {
-    return foldCore(events).turns;
-}
-function foldMessages(events) {
-    return foldCore(events).messages;
-}
-function foldTools(events) {
-    return foldCore(events).tools;
-}
-function foldFinalDecision(events) {
-    return foldCore(events).finalDecision;
-}
-// ── Default humanizer — generic phrasings for every event kind ────────
-//
-// Consumer-supplied `Humanizer` overrides win. Each describeXxx returns
-// a short phrase ready for Activity.label / StatusLine.text.
-function defaultTurnStart() {
-    return 'Getting started';
-}
-function defaultTurnEnd() {
-    return 'Done';
-}
-function defaultLLMStart() {
-    return 'Thinking';
-}
-function defaultLLMEnd(e) {
-    return e.toolCallCount > 0
-        ? `Running ${e.toolCallCount} step${e.toolCallCount === 1 ? '' : 's'}`
-        : 'Writing response';
-}
-function defaultToolStart(e) {
-    return `Running ${e.toolName}`;
-}
-function defaultToolEnd(e) {
-    return e.error ? 'Tool errored' : 'Got result';
-}
-function defaultContextInjection(e) {
-    return `${e.source} → ${e.slot}`;
-}
-/** Pick the humanizer's phrasing or fall through to the default. */
-function humanize(custom, fallback, e) {
-    if (custom) {
-        const r = custom(e);
-        if (typeof r === 'string')
-            return r;
-    }
-    return fallback(e);
-}
-// ── Activity reduction state machine ──────────────────────────────────
-//
-// `selectActivities()` uses this to turn the event stream into an
-// ordered breadcrumb list {id, label, done, meta, kind}. The humanizer
-// shapes every user-visible string.
-function reduceActivities(events, h, cursor) {
-    const end = cursor === undefined ? events.length : Math.min(cursor + 1, events.length);
-    const out = [];
-    const toolIdxByCallId = new Map();
-    let llmIdx = null;
-    for (let i = 0; i < end; i++) {
-        const e = events[i];
-        switch (e.type) {
-            case 'llm_start': {
-                out.push({
-                    id: `llm-${e.iteration}-${i}`,
-                    label: humanize(h.describeLLMStart, defaultLLMStart, e),
-                    done: false,
-                    kind: 'llm',
-                    runtimeStageId: e.runtimeStageId,
-                    iterationIndex: e.iteration,
-                });
-                llmIdx = out.length - 1;
-                break;
-            }
-            case 'llm_end': {
-                if (llmIdx !== null) {
-                    out[llmIdx] = {
-                        ...out[llmIdx],
-                        done: true,
-                        meta: humanize(h.describeLLMEnd, defaultLLMEnd, e),
-                    };
-                    llmIdx = null;
-                }
-                break;
-            }
-            case 'tool_start': {
-                out.push({
-                    id: e.toolCallId || `tool-${i}`,
-                    label: humanize(h.describeToolStart, defaultToolStart, e),
-                    done: false,
-                    kind: 'tool',
-                    runtimeStageId: e.runtimeStageId,
-                });
-                toolIdxByCallId.set(e.toolCallId || `tool-${i}`, out.length - 1);
-                break;
-            }
-            case 'tool_end': {
-                const idx = toolIdxByCallId.get(e.toolCallId);
-                if (idx !== undefined) {
-                    const prev = out[idx];
-                    // Look up the tool name from the matching start event for the humanizer.
-                    const toolName = findToolNameForCallId(events, e.toolCallId) ?? '';
-                    out[idx] = {
-                        ...prev,
-                        done: true,
-                        meta: humanize(h.describeToolEnd, defaultToolEnd, {
-                            toolName,
-                            result: e.result,
-                            ...(e.error !== undefined ? { error: e.error } : {}),
-                        }),
-                    };
-                    toolIdxByCallId.delete(e.toolCallId);
-                }
-                break;
-            }
-            case 'turn_start':
-            case 'turn_end':
-            case 'context_injection':
-            default:
-                break;
-        }
-    }
-    return out;
-}
-function findToolNameForCallId(events, toolCallId) {
-    for (const e of events) {
-        if (e.type === 'tool_start' && e.toolCallId === toolCallId)
-            return e.toolName;
-    }
-    return undefined;
-}
-// ── Status one-liner ──────────────────────────────────────────────────
-function deriveStatus(events, h, cursor) {
-    const end = cursor === undefined ? events.length - 1 : Math.min(cursor, events.length - 1);
-    if (end < 0) {
-        return {
-            text: humanize(h.describeTurnStart, defaultTurnStart, { userMessage: '' }),
-            kind: 'idle',
-            eventIndex: -1,
-        };
-    }
-    const e = events[end];
-    switch (e.type) {
-        case 'turn_start':
-            return {
-                text: humanize(h.describeTurnStart, defaultTurnStart, e),
-                kind: 'turn',
-                eventIndex: end,
-            };
-        case 'turn_end':
-            return {
-                text: humanize(h.describeTurnEnd, defaultTurnEnd, e),
-                kind: 'turn',
-                eventIndex: end,
-            };
-        case 'llm_start':
-            return {
-                text: humanize(h.describeLLMStart, defaultLLMStart, e),
-                kind: 'llm',
-                eventIndex: end,
-            };
-        case 'llm_end':
-            return { text: humanize(h.describeLLMEnd, defaultLLMEnd, e), kind: 'llm', eventIndex: end };
-        case 'tool_start':
-            return {
-                text: humanize(h.describeToolStart, defaultToolStart, e),
-                kind: 'tool',
-                eventIndex: end,
-            };
-        case 'tool_end': {
-            const toolName = findToolNameForCallId(events, e.toolCallId) ?? '';
-            return {
-                text: humanize(h.describeToolEnd, defaultToolEnd, {
-                    toolName,
-                    result: e.result,
-                    ...(e.error !== undefined ? { error: e.error } : {}),
-                }),
-                kind: 'tool',
-                eventIndex: end,
-            };
-        }
-        default:
-            return { text: '', kind: 'idle', eventIndex: end };
-    }
-}
-// ── Commentary builder — one narrative line per event ─────────────────
-function buildCommentary(events, h, cursor) {
-    const end = cursor === undefined ? events.length : Math.min(cursor + 1, events.length);
-    const out = [];
-    for (let i = 0; i < end; i++) {
-        const e = events[i];
-        let text = '';
-        let kind = 'llm';
-        switch (e.type) {
-            case 'turn_start':
-                text = humanize(h.describeTurnStart, defaultTurnStart, e);
-                kind = 'turn';
-                break;
-            case 'turn_end':
-                text = humanize(h.describeTurnEnd, defaultTurnEnd, e);
-                kind = 'turn';
-                break;
-            case 'llm_start':
-                text = humanize(h.describeLLMStart, defaultLLMStart, e);
-                kind = 'llm';
-                break;
-            case 'llm_end':
-                text = humanize(h.describeLLMEnd, defaultLLMEnd, e);
-                kind = 'llm';
-                break;
-            case 'tool_start':
-                text = humanize(h.describeToolStart, defaultToolStart, e);
-                kind = 'tool';
-                break;
-            case 'tool_end': {
-                const toolName = findToolNameForCallId(events, e.toolCallId) ?? '';
-                text = humanize(h.describeToolEnd, defaultToolEnd, {
-                    toolName,
-                    result: e.result,
-                    ...(e.error !== undefined ? { error: e.error } : {}),
-                });
-                kind = 'tool';
-                break;
-            }
-            case 'context_injection':
-                text = humanize(h.describeContextInjection, defaultContextInjection, e);
-                kind = 'context';
-                break;
-        }
-        if (text === '')
-            continue;
-        out.push({
-            text,
-            kind,
-            ...(e.runtimeStageId !== undefined ? { runtimeStageId: e.runtimeStageId } : {}),
-            timestamp: e.timestamp,
-        });
-    }
-    return out;
-}
-// ── Run summary totals ────────────────────────────────────────────────
-function computeRunSummary(events) {
-    let turnCount = 0;
-    let iterationCount = 0;
-    let toolCallCount = 0;
-    let inputTokens = 0;
-    let outputTokens = 0;
-    let totalDurationMs = 0;
-    const toolUsage = new Map();
-    const skillsActivated = new Set();
-    const toolStarts = new Map(); // toolCallId → toolName
-    for (const e of events) {
-        switch (e.type) {
-            case 'turn_start':
-                turnCount++;
-                break;
-            case 'llm_start':
-                iterationCount++;
-                break;
-            case 'llm_end':
-                if (e.inputTokens !== undefined)
-                    inputTokens += e.inputTokens;
-                if (e.outputTokens !== undefined)
-                    outputTokens += e.outputTokens;
-                if (e.durationMs !== undefined)
-                    totalDurationMs += e.durationMs;
-                break;
-            case 'tool_start':
-                toolCallCount++;
-                toolStarts.set(e.toolCallId, e.toolName);
-                if (e.toolName === 'read_skill' && typeof e.args.id === 'string') {
-                    skillsActivated.add(e.args.id);
-                }
-                break;
-            case 'tool_end': {
-                const name = toolStarts.get(e.toolCallId);
-                if (!name)
-                    break;
-                const prev = toolUsage.get(name) ?? { count: 0, totalDurationMs: 0 };
-                toolUsage.set(name, {
-                    count: prev.count + 1,
-                    totalDurationMs: prev.totalDurationMs + (e.durationMs ?? 0),
-                });
-                break;
-            }
-        }
-    }
-    return {
-        turnCount,
-        iterationCount,
-        toolCallCount,
-        inputTokens,
-        outputTokens,
-        totalDurationMs,
-        toolUsage: Object.fromEntries(toolUsage),
-        skillsActivated: [...skillsActivated],
-    };
-}
-// ── Context-engineering summary ───────────────────────────────────────
-function computeContextBySource(events, cursor) {
-    const end = cursor === undefined ? events.length : Math.min(cursor + 1, events.length);
-    const slotOrder = ['system-prompt', 'messages', 'tools'];
-    const slotBuckets = new Map();
-    const aggregatedLedger = {};
-    for (const slot of slotOrder)
-        slotBuckets.set(slot, new Map());
-    for (let i = 0; i < end; i++) {
-        const e = events[i];
-        if (e.type !== 'context_injection')
-            continue;
-        const slot = e.slot;
-        const bucket = slotBuckets.get(slot);
-        if (!bucket)
-            continue;
-        const group = bucket.get(e.source) ?? { count: 0, deltaCount: {}, labels: [] };
-        group.count += 1;
-        group.labels.push(e.label);
-        if (e.deltaCount) {
-            for (const [k, v] of Object.entries(e.deltaCount)) {
-                if (typeof v === 'number') {
-                    group.deltaCount[k] = (group.deltaCount[k] ?? 0) + v;
-                    aggregatedLedger[k] = (aggregatedLedger[k] ?? 0) + v;
-                }
-                else if (typeof v === 'boolean') {
-                    // Boolean flags: true wins (indicates feature was active at least once).
-                    group.deltaCount[k] = group.deltaCount[k] || v;
-                    aggregatedLedger[k] = aggregatedLedger[k] || v;
-                }
-            }
-        }
-        bucket.set(e.source, group);
-    }
-    const slots = slotOrder.map((slot) => {
-        const bucket = slotBuckets.get(slot);
-        const sources = [];
-        let totalInjections = 0;
-        for (const [source, group] of bucket) {
-            sources.push({
-                source,
-                count: group.count,
-                deltaCount: group.deltaCount,
-                labels: group.labels,
-            });
-            totalInjections += group.count;
-        }
-        return { slot, sources, totalInjections };
-    });
-    return { slots, aggregatedLedger };
-}
-// ── Iteration ↔ event-stream range index ──────────────────────────────
-function computeIterationRanges(events) {
-    const iterations = [];
-    const byEventIndex = [];
-    let turnIndex = -1;
-    let currentIterStart = -1;
-    let currentIter = null;
-    const flushCurrent = (endIdx) => {
-        if (currentIter === null || currentIterStart < 0)
-            return;
-        iterations.push({
-            turnIndex,
-            iterationIndex: currentIter,
-            firstEventIndex: currentIterStart,
-            lastEventIndex: endIdx,
-            ...(events[currentIterStart]?.runtimeStageId !== undefined
-                ? { runtimeStageId: events[currentIterStart].runtimeStageId }
-                : {}),
-        });
-        for (let i = currentIterStart; i <= endIdx; i++)
-            byEventIndex[i] = iterations.length - 1;
-    };
-    for (let i = 0; i < events.length; i++) {
-        const e = events[i];
-        if (e.type === 'turn_start') {
-            flushCurrent(i - 1);
-            currentIter = null;
-            currentIterStart = -1;
-            turnIndex++;
-            byEventIndex[i] = iterations.length; // belongs to the next iteration slot
-            continue;
-        }
-        if (e.type === 'llm_start') {
-            flushCurrent(i - 1);
-            currentIter = e.iteration;
-            currentIterStart = i;
-        }
-        byEventIndex[i] = iterations.length; // pending iteration
-    }
-    flushCurrent(events.length - 1);
-    return { iterations, byEventIndex };
-}
-//# sourceMappingURL=AgentTimelineRecorder.js.map