agentfootprint 1.22.0 → 1.23.0

package/dist/esm/recorders/AgentTimelineRecorder.js

@@ -34,9 +34,14 @@
  *
  * await agent.run('Investigate port errors on switch-3');
  *
- * t.getTimeline();         // AgentTimeline { turns, messages, tools, ... }
- * t.getEntryRanges();      // O(1) per-step range index for sliders
- * t.aggregate(...);        // reduce all entries
+ * // 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
@@ -44,25 +49,70 @@
  * its own `executor.getSnapshot().recorders[id]` slot. Multi-agent
  * shells aggregate them by id.
  */
-import { SequenceRecorder } from 'footprintjs/trace';
+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 ─────────────────────────────────────────────────────
     /**
-     * Single entry point: every emit event the executor dispatches passes
-     * through here. Translates the event into a TimelineEntry and stores
-     * it via `SequenceRecorder.emit()`. Unknown events are silently
-     * ignored — the executor delivers events from many subsystems and we
-     * only care about agent-shaped ones.
+     * 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);
@@ -73,23 +123,142 @@ export class AgentTimelineRecorder extends SequenceRecorder {
         if (entry.type === 'llm_end' || entry.type === 'turn_end') {
             this.llmPhaseActive = false;
         }
-        // SequenceRecorder.emit is protected — fine, we're a subclass.
         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();
     }
-    /** Reset state. Called automatically by the executor before each
-     *  `run()` (recorder-pattern lifecycle hook). */
     clear() {
         super.clear();
         this.llmPhaseActive = false;
+        this.topology.clear();
+        this.bumpVersion();
     }
-    // ── Derived view ────────────────────────────────────────────────────
-    /**
-     * Fold the recorder's flat entry sequence into the agent-shaped
-     * AgentTimeline. Pure derivation — same input always produces same
-     * output. Cheap because entry count is bounded by run length.
-     */
-    getTimeline() {
-        return foldEntries(this.getEntries(), { id: this.id, name: this.name });
+    // ── 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;
     }
 }
 /**
@@ -256,7 +425,7 @@ function maybeUsage(u) {
         out.outputTokens = x.outputTokens;
     return out;
 }
-function foldCore(entries, agent, deriveSubs) {
+function foldCore(entries) {
     const turns = [];
     const messages = [];
     const toolByCallId = new Map();
@@ -284,8 +453,23 @@ function foldCore(entries, agent, deriveSubs) {
                 break;
             }
             case 'llm_start': {
-                if (!currentTurn)
-                    continue;
+                // 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: '',
@@ -431,78 +615,493 @@ function foldCore(entries, agent, deriveSubs) {
         };
     });
     return {
-        agent,
         turns: frozenTurns,
         messages: [...messages],
         tools: allTools,
         finalDecision: {},
-        // `subAgents` is the multi-agent dimension. When the caller is
-        // `foldEntries` (the public path), we derive it. When the caller
-        // is `deriveSubAgents` (already inside a sub-agent fold), we don't
-        // recurse — passing `deriveSubs: false` short-circuits the recursion.
-        subAgents: deriveSubs ? deriveSubAgents(entries) : [],
     };
 }
-function foldEntries(entries, agent) {
-    return foldCore(entries, agent, true);
-}
+// ── Slice helpers — used by selectors ─────────────────────────────────
 /**
- * Group timeline entries by their `subflowPath[0]` (the top-level
- * sub-agent name) and fold each group into its own SubAgentTimeline.
- *
- * Single-agent runs have `subflowPath = []` on every event → produces
- * empty array (UIs render single container).
+ * 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.
  *
- * Multi-agent runs (Pipeline / Swarm) — events from each sub-agent
- * fire with `subflowPath = ["classify"]`, `["analyze"]`, etc. — one
- * SubAgentTimeline per distinct first segment.
+ * 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.
  *
- * Each sub-agent slice is its own self-contained timeline (re-folded
- * from the subset of entries belonging to it). The OUTER timeline
- * still contains everything; sub-agents are an additional view, not
- * a replacement.
+ * 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).
  */
-function deriveSubAgents(entries) {
-    // Group by subflowPath[0]. Skip entries with empty subflowPath
-    // (those belong to the root parent agent, not a sub-agent).
+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 entry of entries) {
-        const subAgentId = entry.subflowPath[0];
-        if (!subAgentId)
+    for (const e of events) {
+        const id = e.subflowPath[0];
+        if (!id || !subAgentIds.has(id))
             continue;
-        const arr = bySubAgent.get(subAgentId) ?? [];
-        arr.push(entry);
-        bySubAgent.set(subAgentId, arr);
+        const arr = bySubAgent.get(id) ?? [];
+        arr.push(e);
+        bySubAgent.set(id, arr);
     }
-    if (bySubAgent.size === 0)
-        return [];
-    // Find the parent's user message — sub-agent slices don't get their
-    // own turn_start (the parent owns the conversation), but the fold
-    // requires one to initialize `currentTurn`. Synthesize one prepended
-    // to each sub-agent's entries so the fold has a turn anchor.
-    const parentTurnStart = entries.find((e) => e.type === 'turn_start');
+    // 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 : '';
-    // Fold each group with `deriveSubs=false` to short-circuit recursion.
-    // Sub-agents inherit the subflow id as their name — upstream wiring
-    // (Agent.create({ name }) on sub-agents) can carry the real human
-    // name through future enhancements.
-    const out = [];
-    for (const [id, subEntries] of bySubAgent) {
+    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:${id}`,
-            timestamp: subEntries[0]?.timestamp ?? Date.now(),
-            subflowPath: [id],
+            runtimeStageId: `synth:turn_start:${node.id}`,
+            timestamp: subEvents[0]?.timestamp ?? Date.now(),
+            subflowPath: [node.id],
             userMessage: parentUserMessage,
         };
-        const subTimeline = foldCore([synthTurnStart, ...subEntries], { id, name: id }, false);
+        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({
-            id,
-            name: id,
-            turns: subTimeline.turns,
-            tools: subTimeline.tools,
+            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