sidekick-shared 0.22.0 → 0.23.1

package/dist/aggregation/EventAggregator.js

@@ -9,7 +9,7 @@
  * @module aggregation/EventAggregator
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventAggregator = void 0;
+exports.EventAggregator = exports.SNAPSHOT_SCHEMA_VERSION = void 0;
 exports.parseTodoDependencies = parseTodoDependencies;
 const jsonl_1 = require("../parsers/jsonl");
 const planExtractor_1 = require("../parsers/planExtractor");
@@ -20,14 +20,16 @@ const FrequencyTracker_1 = require("./FrequencyTracker");
 const HeatmapTracker_1 = require("./HeatmapTracker");
 const PatternExtractor_1 = require("./PatternExtractor");
 const modelInfo_1 = require("../modelInfo");
+const errorTaxonomy_1 = require("../extractors/errorTaxonomy");
 // ── Defaults ──
 const DEFAULT_TIMELINE_CAP = 200;
 const DEFAULT_LATENCY_CAP = 100;
+const DEFAULT_CONTEXT_TIMELINE_CAP = 2_000;
 const DEFAULT_BURN_WINDOW_MS = 5 * 60_000;
 const DEFAULT_BURN_SAMPLE_MS = 10_000;
 const COMPACTION_DROP_THRESHOLD = 0.8; // >20% drop
 /** Schema version for serialized snapshots. */
-const SNAPSHOT_SCHEMA_VERSION = 1;
+exports.SNAPSHOT_SCHEMA_VERSION = 3;
 // ── Goal gate detection regex ──
 const GOAL_GATE_REGEX = /\b(CRITICAL|MUST|blocker|required|must.?complete|goal.?gate|essential|do.?not.?skip|blocking)\b/i;
 // ── Todo dependency parsing ──
@@ -79,6 +81,12 @@ class EventAggregator {
     // Context size tracking
     currentContextSize = 0;
     previousContextSize = 0;
+    /**
+     * Index of a heuristic compaction event still awaiting its real
+     * post-compaction size from the next usage event. Prevents the usage-drop
+     * detector from double-counting an explicit compaction marker.
+     */
+    pendingHeuristicCompactionIndex = null;
     // Compaction
     compactionEvents = [];
     // Truncation
@@ -86,6 +94,10 @@ class EventAggregator {
     // Tool analytics
     toolAnalytics = new Map();
     pendingToolCalls = new Map();
+    errorByToolCategory = new Map();
+    errorBuckets = new Map();
+    retryAttempts = 0;
+    finishReasons = new Map();
     // Burn rate
     burnSamples = [];
     lastBurnSampleTime = 0;
@@ -99,6 +111,8 @@ class EventAggregator {
     pendingSubagents = new Map(); // toolUseId -> index
     // Plan state
     planExtractor;
+    planState = null;
+    planEnteredAt;
     // Context attribution
     contextAttribution = {
         systemPrompt: 0,
@@ -114,6 +128,7 @@ class EventAggregator {
     permissionModeHistory = [];
     // Context timeline
     contextTimeline = [];
+    contextTimelineCap;
     contextTurnIndex = 0;
     // Timeline
     timeline = [];
@@ -137,6 +152,7 @@ class EventAggregator {
         this.latencyCap = options?.latencyCap ?? DEFAULT_LATENCY_CAP;
         this.burnWindowMs = options?.burnWindowMs ?? DEFAULT_BURN_WINDOW_MS;
         this.burnSampleMs = options?.burnSampleMs ?? DEFAULT_BURN_SAMPLE_MS;
+        this.contextTimelineCap = options?.contextTimelineCap ?? DEFAULT_CONTEXT_TIMELINE_CAP;
         this.computeContextSize = options?.computeContextSize ?? null;
         this.providerId = options?.providerId ?? null;
         this._providerId = this.providerId;
@@ -154,12 +170,17 @@ class EventAggregator {
         this.lastEventTime = event.timestamp;
         // Guard: some event types (e.g. 'summary') have no message field in the raw JSONL
         if (!event.message) {
+            if (event.type === 'summary') {
+                this.recordExplicitCompaction(event.timestamp, event.compaction);
+                this.addTimelineFromSessionEvent(event);
+            }
             return;
         }
         // 2. Track model
         if (event.message.model) {
             this.currentModel = event.message.model;
         }
+        this.recordProviderMetadata(event);
         // 3. Skip system/audit events and synthetic token-count events for messageCount
         const msgId = event.message.id ?? '';
         if (event.type !== 'system' && !msgId.startsWith('token-count-')) {
@@ -171,7 +192,8 @@ class EventAggregator {
         }
         // 5. Token accumulation
         if (event.message.usage) {
-            this.accumulateUsage(event.message.usage, event.timestamp, event.message.model);
+            const usageCost = this.accumulateUsage(event.message.usage, event.timestamp, event.message.model);
+            this.attributePlanUsage(event.message.usage.input_tokens + event.message.usage.output_tokens, usageCost);
         }
         if (event.type !== 'system') {
             // 6. Tool extraction from content blocks
@@ -187,6 +209,9 @@ class EventAggregator {
         this.attributeContextFromEvent(event);
         // 11. Permission mode tracking
         this.trackPermissionMode(event);
+        if (event.type === 'summary') {
+            this.recordExplicitCompaction(event.timestamp, event.compaction);
+        }
         // 12. Timeline
         this.addTimelineFromSessionEvent(event);
         // 13. Gonzo/Lazyjournal analytics
@@ -222,6 +247,7 @@ class EventAggregator {
             this.outputTokens += outputTok;
             this.cacheReadTokens += cacheRead;
             this.cacheWriteTokens += cacheWrite;
+            this.attributePlanUsage(inputTok + outputTok, event.cost ?? 0);
             // Tokens since last burn sample
             this.tokensSinceLastSample += inputTok + outputTok;
             // Context size
@@ -238,13 +264,17 @@ class EventAggregator {
                 contextSize = inputTok + cacheWrite + cacheRead;
             }
             // Compaction detection
-            if (this.previousContextSize > 0 &&
+            if (this.resolvePendingHeuristicCompaction(contextSize)) {
+                // The drop belongs to the explicit compaction marker just recorded.
+            }
+            else if (this.previousContextSize > 0 &&
                 contextSize < this.previousContextSize * COMPACTION_DROP_THRESHOLD) {
                 this.compactionEvents.push({
                     timestamp: new Date(event.timestamp),
                     contextBefore: this.previousContextSize,
                     contextAfter: contextSize,
                     tokensReclaimed: this.previousContextSize - contextSize,
+                    source: 'heuristic',
                 });
             }
             this.previousContextSize = contextSize;
@@ -277,7 +307,7 @@ class EventAggregator {
                     priced: true,
                 };
                 acc.calls++;
-                acc.tokens += inputTok + outputTok;
+                acc.tokens += inputTok + outputTok + cacheWrite + cacheRead;
                 acc.inputTokens += inputTok;
                 acc.outputTokens += outputTok;
                 acc.cacheWriteTokens += cacheWrite;
@@ -297,6 +327,7 @@ class EventAggregator {
         // 4. Tool tracking from FollowEvent
         if (event.type === 'tool_use' && event.toolName) {
             this.recordFollowToolUse(event);
+            this.attributePlanToolCall(event.toolName);
         }
         else if (event.type === 'tool_result') {
             this.recordFollowToolResult(event);
@@ -306,7 +337,7 @@ class EventAggregator {
         // 6. Subagent tracking
         this.extractSubagentFromFollowEvent(event);
         // 7. Plan extraction
-        this.planExtractor.processEvent(event);
+        this.processPlanFollowEvent(event);
         // 8. Context attribution
         this.attributeContextFromFollowEvent(event);
         // 9. Truncation detection from tool results
@@ -315,19 +346,14 @@ class EventAggregator {
         }
         // 10. Explicit compaction event (summary type)
         if (event.type === 'summary') {
-            this.compactionEvents.push({
-                timestamp: new Date(event.timestamp),
-                contextBefore: this.previousContextSize,
-                contextAfter: 0,
-                tokensReclaimed: this.previousContextSize,
-            });
+            this.recordExplicitCompaction(event.timestamp, event.compaction);
         }
         // 11. Timeline
         this.addTimelineFromFollowEvent(event);
         // 12. Gonzo/Lazyjournal analytics
         this.feedAnalytics(event.timestamp, event.summary, event.toolName);
         // Message count (skip system events)
-        if (event.type !== 'system') {
+        if (event.type === 'user' || event.type === 'assistant') {
             this.messageCount++;
         }
     }
@@ -354,6 +380,15 @@ class EventAggregator {
             b.pendingCount -
             (a.successCount + a.failureCount + a.pendingCount));
     }
+    getErrorRollup() {
+        return {
+            totalFailures: Array.from(this.errorByToolCategory.values()).reduce((sum, entry) => sum + entry.count, 0),
+            byToolCategory: Array.from(this.errorByToolCategory.values()).sort((a, b) => b.count - a.count),
+            byHourModel: Array.from(this.errorBuckets.values()).sort((a, b) => a.hour.localeCompare(b.hour)),
+            retryAttempts: this.retryAttempts,
+            finishReasons: Array.from(this.finishReasons, ([reason, count]) => ({ reason, count })).sort((a, b) => b.count - a.count),
+        };
+    }
     getCompactionEvents() {
         return [...this.compactionEvents];
     }
@@ -379,10 +414,9 @@ class EventAggregator {
         return [...this.subagents];
     }
     getPlan() {
-        const extracted = this.planExtractor.plan;
-        if (!extracted)
-            return null;
-        return this.convertExtractedPlanToPlanState(extracted);
+        return this.planState
+            ? { ...this.planState, steps: this.planState.steps.map((step) => ({ ...step })) }
+            : null;
     }
     getContextAttribution() {
         return { ...this.contextAttribution };
@@ -424,6 +458,7 @@ class EventAggregator {
             truncationCount: this.truncationEvents.length,
             truncationEvents: this.getTruncationEvents(),
             toolStats: this.getToolStats(),
+            errorRollup: this.getErrorRollup(),
             burnRate: this.getBurnRate(),
             taskState: this.getTaskState(),
             subagents: this.getSubagents(),
@@ -455,6 +490,10 @@ class EventAggregator {
         this.truncationEvents = [];
         this.toolAnalytics.clear();
         this.pendingToolCalls.clear();
+        this.errorByToolCategory.clear();
+        this.errorBuckets.clear();
+        this.retryAttempts = 0;
+        this.finishReasons.clear();
         this.burnSamples = [];
         this.lastBurnSampleTime = 0;
         this.tokensSinceLastSample = 0;
@@ -464,6 +503,8 @@ class EventAggregator {
         this.subagents = [];
         this.pendingSubagents.clear();
         this.planExtractor.reset();
+        this.planState = null;
+        this.planEnteredAt = undefined;
         this.currentPermissionMode = null;
         this.permissionModeHistory = [];
         this.contextTimeline = [];
@@ -509,7 +550,7 @@ class EventAggregator {
     /** Serializes all mutable state to a JSON-safe object for snapshot persistence. */
     serialize() {
         return {
-            version: SNAPSHOT_SCHEMA_VERSION,
+            version: exports.SNAPSHOT_SCHEMA_VERSION,
             tokens: {
                 input: this.inputTokens,
                 output: this.outputTokens,
@@ -523,6 +564,10 @@ class EventAggregator {
             compactionEvents: this.compactionEvents,
             truncationEvents: this.truncationEvents,
             toolAnalytics: Array.from(this.toolAnalytics.entries()),
+            errorByToolCategory: Array.from(this.errorByToolCategory.entries()),
+            errorBuckets: Array.from(this.errorBuckets.entries()),
+            retryAttempts: this.retryAttempts,
+            finishReasons: Array.from(this.finishReasons.entries()),
             contextAttribution: { ...this.contextAttribution },
             burnSamples: [...this.burnSamples],
             lastBurnSampleTime: this.lastBurnSampleTime,
@@ -549,8 +594,8 @@ class EventAggregator {
     }
     /** Restores mutable state from a serialized snapshot. Clears transient state (pending calls). */
     restore(state) {
-        if (state.version !== SNAPSHOT_SCHEMA_VERSION) {
-            return; // Incompatible snapshot — caller should fall back to full replay
+        if (state.version !== exports.SNAPSHOT_SCHEMA_VERSION) {
+            return false;
         }
         this.inputTokens = state.tokens.input;
         this.outputTokens = state.tokens.output;
@@ -563,6 +608,10 @@ class EventAggregator {
         this.compactionEvents = [...state.compactionEvents];
         this.truncationEvents = [...state.truncationEvents];
         this.toolAnalytics = new Map(state.toolAnalytics);
+        this.errorByToolCategory = new Map(state.errorByToolCategory);
+        this.errorBuckets = new Map(state.errorBuckets);
+        this.retryAttempts = state.retryAttempts;
+        this.finishReasons = new Map(state.finishReasons);
         this.contextAttribution = { ...state.contextAttribution };
         this.burnSamples = [...state.burnSamples];
         this.lastBurnSampleTime = state.lastBurnSampleTime;
@@ -575,7 +624,9 @@ class EventAggregator {
         this.permissionModeHistory = state.permissionModeHistory
             ? [...state.permissionModeHistory]
             : [];
-        this.contextTimeline = state.contextTimeline ? [...state.contextTimeline] : [];
+        this.contextTimeline = state.contextTimeline
+            ? state.contextTimeline.slice(-this.contextTimelineCap)
+            : [];
         this.contextTurnIndex = state.contextTurnIndex ?? 0;
         this.timeline = [...state.timeline];
         this.messageCount = state.messageCount;
@@ -598,6 +649,7 @@ class EventAggregator {
         this.pendingSubagents.clear();
         this.pendingUserRequest = null;
         this.planExtractor.reset();
+        return true;
     }
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Token & Context
@@ -653,13 +705,17 @@ class EventAggregator {
             contextSize = inputTok + cacheWrite + cacheRead;
         }
         // Compaction detection
-        if (this.previousContextSize > 0 &&
+        if (this.resolvePendingHeuristicCompaction(contextSize)) {
+            // The drop belongs to the explicit compaction marker just recorded.
+        }
+        else if (this.previousContextSize > 0 &&
             contextSize < this.previousContextSize * COMPACTION_DROP_THRESHOLD) {
             this.compactionEvents.push({
                 timestamp: new Date(timestamp),
                 contextBefore: this.previousContextSize,
                 contextAfter: contextSize,
                 tokensReclaimed: this.previousContextSize - contextSize,
+                source: 'heuristic',
             });
         }
         this.previousContextSize = contextSize;
@@ -670,6 +726,9 @@ class EventAggregator {
             inputTokens: contextSize,
             turnIndex: this.contextTurnIndex++,
         });
+        if (this.contextTimeline.length > this.contextTimelineCap) {
+            this.contextTimeline.splice(0, this.contextTimeline.length - this.contextTimelineCap);
+        }
         // Per-model usage. Accumulate reasoning tokens and an inverted-sticky
         // `priced` flag so one unpriced event taints the aggregate (UI renders "—").
         const perModelKey = model ?? this.currentModel ?? 'unknown';
@@ -685,7 +744,7 @@ class EventAggregator {
             priced: true,
         };
         acc.calls++;
-        acc.tokens += inputTok + outputTok;
+        acc.tokens += inputTok + outputTok + cacheWrite + cacheRead;
         acc.inputTokens += inputTok;
         acc.outputTokens += outputTok;
         acc.cacheWriteTokens += cacheWrite;
@@ -697,6 +756,7 @@ class EventAggregator {
         this.modelUsage.set(perModelKey, acc);
         // Burn rate sampling
         this.updateBurnRate(timestamp);
+        return cost;
     }
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Burn Rate
@@ -788,6 +848,7 @@ class EventAggregator {
                     name,
                     startTime: new Date(event.timestamp),
                 });
+                this.attributePlanToolCall(name);
             }
             else if (block.type === 'tool_result') {
                 // User content: tool_result block
@@ -797,6 +858,9 @@ class EventAggregator {
                     continue;
                 const pending = this.pendingToolCalls.get(toolUseId);
                 if (pending) {
+                    if (isError) {
+                        this.recordError(pending.name, (0, errorTaxonomy_1.categorizeError)(block.content), event.timestamp, this.currentModel ?? 'unknown');
+                    }
                     this.pendingToolCalls.delete(toolUseId);
                     const analytics = this.toolAnalytics.get(pending.name);
                     if (analytics) {
@@ -890,6 +954,7 @@ class EventAggregator {
             const isError = raw.is_error === true;
             if (isError) {
                 analytics.failureCount++;
+                this.recordError(pending.name, (0, errorTaxonomy_1.categorizeError)(raw.content ?? event.summary), event.timestamp, event.model ?? this.currentModel ?? 'unknown');
             }
             else {
                 analytics.successCount++;
@@ -900,6 +965,36 @@ class EventAggregator {
             }
         }
     }
+    recordProviderMetadata(event) {
+        const metadata = event.providerMetadata;
+        if (!metadata)
+            return;
+        this.retryAttempts += metadata.retryAttempts?.length ?? 0;
+        for (const reason of metadata.finishReasons ?? []) {
+            this.finishReasons.set(reason, (this.finishReasons.get(reason) ?? 0) + 1);
+        }
+        if (metadata.providerError) {
+            this.recordError('ProviderAPI', (0, errorTaxonomy_1.categorizeError)(metadata.providerError, metadata.providerError.type), event.timestamp, event.message.model ?? this.currentModel ?? 'unknown');
+        }
+    }
+    recordError(tool, category, timestamp, model) {
+        const categoryKey = `${tool}\u0000${category}`;
+        const current = this.errorByToolCategory.get(categoryKey);
+        if (current)
+            current.count++;
+        else
+            this.errorByToolCategory.set(categoryKey, { tool, category, count: 1 });
+        const parsed = new Date(timestamp);
+        const hour = Number.isNaN(parsed.getTime())
+            ? timestamp.slice(0, 13)
+            : parsed.toISOString().slice(0, 13);
+        const bucketKey = `${hour}\u0000${model}\u0000${tool}\u0000${category}`;
+        const bucket = this.errorBuckets.get(bucketKey);
+        if (bucket)
+            bucket.count++;
+        else
+            this.errorBuckets.set(bucketKey, { hour, model, tool, category, count: 1 });
+    }
     detectTruncationFromFollowEvent(event) {
         const raw = event.raw;
         if (!raw)
@@ -936,6 +1031,49 @@ class EventAggregator {
             }
         }
     }
+    recordExplicitCompaction(timestamp, reported) {
+        const hasReported = reported !== undefined &&
+            Number.isFinite(reported.tokensBefore) &&
+            Number.isFinite(reported.tokensAfter) &&
+            reported.tokensBefore >= reported.tokensAfter &&
+            reported.tokensAfter >= 0;
+        // Without reported counts, assume the full context was reclaimed until
+        // the next usage event supplies the real post-compaction size.
+        const contextBefore = hasReported ? reported.tokensBefore : this.previousContextSize;
+        const contextAfter = hasReported ? reported.tokensAfter : 0;
+        this.compactionEvents.push({
+            timestamp: new Date(timestamp),
+            contextBefore,
+            contextAfter,
+            tokensReclaimed: Math.max(0, contextBefore - contextAfter),
+            source: hasReported ? 'reported' : 'heuristic',
+        });
+        if (hasReported) {
+            this.previousContextSize = contextAfter;
+            this.currentContextSize = contextAfter;
+        }
+        else {
+            this.pendingHeuristicCompactionIndex = this.compactionEvents.length - 1;
+        }
+    }
+    /**
+     * Fills a pending heuristic compaction with the first observed
+     * post-compaction context size. Returns true when the observed drop was
+     * consumed by that pending event, so the caller must not record it again.
+     */
+    resolvePendingHeuristicCompaction(contextSize) {
+        if (this.pendingHeuristicCompactionIndex === null)
+            return false;
+        const compaction = this.compactionEvents[this.pendingHeuristicCompactionIndex];
+        this.pendingHeuristicCompactionIndex = null;
+        if (!compaction)
+            return false;
+        if (contextSize < compaction.contextBefore) {
+            compaction.contextAfter = contextSize;
+            compaction.tokensReclaimed = compaction.contextBefore - contextSize;
+        }
+        return true;
+    }
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Task State from SessionEvent
     // ═══════════════════════════════════════════════════════════════════════
@@ -962,6 +1100,7 @@ class EventAggregator {
                 }
                 else if (name === 'TaskUpdate') {
                     this.applyTaskUpdate(input);
+                    this.syncPlanStepFromTaskUpdate(input, new Date(event.timestamp));
                 }
                 else if (name === 'TodoWrite') {
                     this.handleTodoWrite(input, new Date(event.timestamp));
@@ -1005,6 +1144,7 @@ class EventAggregator {
             }
             else if (event.toolName === 'TaskUpdate') {
                 this.applyTaskUpdate(input);
+                this.syncPlanStepFromTaskUpdate(input, new Date(event.timestamp));
             }
             else if (event.toolName === 'TodoWrite') {
                 this.handleTodoWrite(input, new Date(event.timestamp));
@@ -1102,6 +1242,36 @@ class EventAggregator {
             }
         }
     }
+    syncPlanStepFromTaskUpdate(input, now) {
+        if (!this.planState || !input.status)
+            return;
+        const taskId = String(input.taskId ?? input.task_id ?? '');
+        const stepId = taskId.startsWith('plan-') ? `step-${taskId.slice(5)}` : taskId;
+        const step = this.planState.steps.find((candidate) => candidate.id === stepId);
+        if (!step)
+            return;
+        const rawStatus = String(input.status).toLowerCase();
+        const status = rawStatus === 'completed'
+            ? 'completed'
+            : rawStatus === 'in_progress' || rawStatus === 'in-progress'
+                ? 'in_progress'
+                : rawStatus === 'deleted'
+                    ? 'skipped'
+                    : 'pending';
+        if (status === 'in_progress' && step.status !== 'in_progress') {
+            step.startedAt = now.toISOString();
+        }
+        if (status === 'completed' && step.status !== status) {
+            step.startedAt ??= now.toISOString();
+            step.completedAt = now.toISOString();
+            step.durationMs = Math.max(0, now.getTime() - new Date(step.startedAt).getTime());
+        }
+        step.status = status;
+        const completed = this.planState.steps.filter((candidate) => candidate.status === 'completed');
+        this.planState.completionRate =
+            this.planState.steps.length > 0 ? completed.length / this.planState.steps.length : 0;
+        this.planState.active = this.planState.steps.some((candidate) => candidate.status === 'pending' || candidate.status === 'in_progress');
+    }
     resolveTaskCreate(toolUseId, content, timestamp, isError) {
         const pending = this.pendingTaskCreates.get(toolUseId);
         if (!pending)
@@ -1408,27 +1578,83 @@ class EventAggregator {
         const providerId = this._providerId ?? 'claude-code';
         const followEvents = (0, eventBridge_1.toFollowEvents)(event, providerId);
         for (const fe of followEvents) {
-            this.planExtractor.processEvent(fe);
+            this.processPlanFollowEvent(fe);
         }
     }
-    convertExtractedPlanToPlanState(extracted) {
+    processPlanFollowEvent(event) {
+        const now = new Date(event.timestamp);
+        if (event.type === 'tool_use' && event.toolName === 'EnterPlanMode') {
+            this.planEnteredAt = now;
+            this.planState = {
+                active: true,
+                steps: [],
+                enteredAt: now,
+                source: event.providerId,
+            };
+        }
+        const updated = this.planExtractor.processEvent(event);
+        if (updated && this.planExtractor.plan) {
+            this.planState = this.convertExtractedPlanToPlanState(this.planExtractor.plan, now);
+        }
+        if (event.type === 'tool_use' && event.toolName === 'ExitPlanMode' && this.planState) {
+            this.planState.exitedAt = now;
+            if (this.planState.enteredAt) {
+                this.planState.totalDurationMs = now.getTime() - this.planState.enteredAt.getTime();
+            }
+        }
+    }
+    convertExtractedPlanToPlanState(extracted, now) {
+        const previous = this.planState;
+        const previousSteps = new Map((previous?.steps ?? []).map((step) => [`${step.id}\u0000${step.description}`, step]));
         const completed = extracted.steps.filter((s) => s.status === 'completed').length;
         const total = extracted.steps.length;
+        const steps = extracted.steps.map((step) => {
+            const old = previousSteps.get(`${step.id}\u0000${step.description}`);
+            const merged = { ...step, ...old, status: step.status };
+            if (step.status === 'in_progress' && old?.status !== 'in_progress' && !merged.startedAt) {
+                merged.startedAt = now.toISOString();
+            }
+            if ((step.status === 'completed' || step.status === 'failed') &&
+                old?.status !== step.status &&
+                !merged.completedAt) {
+                merged.startedAt ??= previous?.enteredAt?.toISOString() ?? now.toISOString();
+                merged.completedAt = now.toISOString();
+                merged.durationMs = Math.max(0, now.getTime() - new Date(merged.startedAt).getTime());
+            }
+            return merged;
+        });
         return {
-            active: true,
-            steps: extracted.steps.map((s) => ({
-                id: s.id,
-                description: s.description,
-                status: s.status,
-                phase: s.phase,
-                complexity: s.complexity,
-            })),
+            active: steps.some((step) => step.status === 'pending' || step.status === 'in_progress'),
+            steps,
             title: extracted.title,
             source: extracted.source,
             completionRate: total > 0 ? completed / total : 0,
             rawMarkdown: extracted.rawMarkdown,
+            enteredAt: previous?.enteredAt ?? this.planEnteredAt ?? now,
+            exitedAt: previous?.exitedAt,
+            totalDurationMs: previous?.totalDurationMs,
+            prompt: previous?.prompt,
+            revision: previous?.revision,
         };
     }
+    getActivePlanStep() {
+        return this.planState?.steps.find((step) => step.status === 'in_progress');
+    }
+    attributePlanUsage(tokens, costUsd) {
+        const step = this.getActivePlanStep();
+        if (!step)
+            return;
+        step.tokensUsed = (step.tokensUsed ?? 0) + tokens;
+        if (costUsd > 0)
+            step.costUsd = (step.costUsd ?? 0) + costUsd;
+    }
+    attributePlanToolCall(toolName) {
+        if (['EnterPlanMode', 'ExitPlanMode', 'UpdatePlan', 'TaskUpdate'].includes(toolName))
+            return;
+        const step = this.getActivePlanStep();
+        if (step)
+            step.toolCalls = (step.toolCalls ?? 0) + 1;
+    }
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Context Attribution from SessionEvent
     // ═══════════════════════════════════════════════════════════════════════

package/dist/aggregation/snapshot.d.ts

@@ -7,7 +7,7 @@
  *
  * @module aggregation/snapshot
  */
-import type { SerializedAggregatorState } from './EventAggregator';
+import { type SerializedAggregatorState } from './EventAggregator';
 /** Snapshot sidecar file content. */
 export interface SessionSnapshot {
     /** Schema version for forward-compatibility checks. */

package/dist/aggregation/snapshot.js

@@ -50,8 +50,9 @@ exports.isSnapshotValid = isSnapshotValid;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const paths_1 = require("../paths");
+const EventAggregator_1 = require("./EventAggregator");
 /** Current schema version — bump when format changes. */
-const SNAPSHOT_VERSION = 1;
+const SNAPSHOT_VERSION = EventAggregator_1.SNAPSHOT_SCHEMA_VERSION;
 /** Returns the directory for snapshot files. */
 function getSnapshotsDir() {
     return path.join((0, paths_1.getConfigDir)(), 'snapshots');

package/dist/aggregation/types.d.ts

@@ -2,14 +2,37 @@
  * Aggregated metrics output types for EventAggregator.
  * Re-exports canonical types from sessionEvent and defines aggregation-specific shapes.
  */
-export type { SessionEvent, ClaudeSessionEvent, MessageUsage, TokenUsage, ToolCall, ToolAnalytics, TimelineEvent, PendingToolCall, TrackedTask, TaskState, TaskStatus, SubagentStats, PlanState, PlanStep, CompactionEvent, TruncationEvent, ContextAttribution, TurnAttribution, ContextSizePoint, PendingUserRequest, ResponseLatency, LatencyStats, SessionStats, PermissionMode, PermissionModeChange, } from '../types/sessionEvent';
+export type { SessionEvent, MessageUsage, TokenUsage, ToolCall, ToolAnalytics, TimelineEvent, PendingToolCall, TrackedTask, TaskState, TaskStatus, SubagentStats, PlanState, PlanStep, CompactionEvent, TruncationEvent, ContextAttribution, TurnAttribution, ContextSizePoint, PendingUserRequest, ResponseLatency, LatencyStats, SessionStats, PermissionMode, PermissionModeChange, } from '../types/sessionEvent';
 import type { ContextAttribution, ContextSizePoint, CompactionEvent, TruncationEvent, ToolAnalytics, TimelineEvent, TaskState, PlanState, LatencyStats, PermissionMode, PermissionModeChange } from '../types/sessionEvent';
+import type { ErrorCategory } from '../extractors/errorTaxonomy';
+export interface ErrorRollupEntry {
+    tool: string;
+    category: ErrorCategory;
+    count: number;
+}
+export interface ErrorBucketMetric extends ErrorRollupEntry {
+    /** ISO hour bucket, e.g. 2026-07-18T14. */
+    hour: string;
+    model: string;
+}
+export interface ErrorRollup {
+    totalFailures: number;
+    byToolCategory: ErrorRollupEntry[];
+    byHourModel: ErrorBucketMetric[];
+    retryAttempts: number;
+    finishReasons: Array<{
+        reason: string;
+        count: number;
+    }>;
+}
 /** Configuration options for EventAggregator. */
 export interface EventAggregatorOptions {
     /** Maximum timeline events to retain (default 200). */
     timelineCap?: number;
     /** Maximum latency records to retain (default 100). */
     latencyCap?: number;
+    /** Maximum context-size points to retain (default 2000). */
+    contextTimelineCap?: number;
     /** Burn rate sliding window in ms (default 5 * 60_000). */
     burnWindowMs?: number;
     /** Burn rate sample interval in ms (default 10_000). */
@@ -105,6 +128,7 @@ export interface AggregatedMetrics {
     truncationCount: number;
     truncationEvents: TruncationEvent[];
     toolStats: ToolAnalytics[];
+    errorRollup: ErrorRollup;
     burnRate: BurnRateInfo;
     taskState: TaskState;
     subagents: SubagentLifecycle[];