sidekick-shared 0.22.0 → 0.23.0

package/dist/aggregation/EventAggregator.js

@@ -20,6 +20,7 @@ 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;
@@ -27,7 +28,7 @@ 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;
+const 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 +80,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 +93,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 +110,8 @@ class EventAggregator {
     pendingSubagents = new Map(); // toolUseId -> index
     // Plan state
     planExtractor;
+    planState = null;
+    planEnteredAt;
     // Context attribution
     contextAttribution = {
         systemPrompt: 0,
@@ -160,6 +173,7 @@ class EventAggregator {
         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 +185,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 +202,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 +240,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 +257,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;
@@ -297,6 +320,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 +330,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,12 +339,7 @@ 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);
@@ -354,6 +373,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 +407,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 +451,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 +483,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 +496,8 @@ class EventAggregator {
         this.subagents = [];
         this.pendingSubagents.clear();
         this.planExtractor.reset();
+        this.planState = null;
+        this.planEnteredAt = undefined;
         this.currentPermissionMode = null;
         this.permissionModeHistory = [];
         this.contextTimeline = [];
@@ -523,6 +557,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,
@@ -563,6 +601,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;
@@ -653,13 +695,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;
@@ -697,6 +743,7 @@ class EventAggregator {
         this.modelUsage.set(perModelKey, acc);
         // Burn rate sampling
         this.updateBurnRate(timestamp);
+        return cost;
     }
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Burn Rate
@@ -788,6 +835,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 +845,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 +941,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 +952,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 +1018,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 +1087,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 +1131,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 +1229,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 +1565,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.js

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

package/dist/aggregation/types.d.ts

@@ -2,8 +2,29 @@
  * 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). */
@@ -105,6 +126,7 @@ export interface AggregatedMetrics {
     truncationCount: number;
     truncationEvents: TruncationEvent[];
     toolStats: ToolAnalytics[];
+    errorRollup: ErrorRollup;
     burnRate: BurnRateInfo;
     taskState: TaskState;
     subagents: SubagentLifecycle[];

package/dist/analytics/codeImpact.d.ts

@@ -0,0 +1,20 @@
+export interface ModelCostInput {
+    model: string;
+    cost: number;
+    priced?: boolean;
+}
+export interface CodeImpact {
+    changedLines: number;
+    additions: number;
+    deletions: number;
+    totalCost: number;
+    costPerChangedLine: number | null;
+    byModel: Array<{
+        model: string;
+        cost: number;
+        priced: boolean;
+        changedLines: number;
+        costPerChangedLine: number | null;
+    }>;
+}
+export declare function calculateCodeImpact(totalCost: number, additions: number, deletions: number, models?: ModelCostInput[]): CodeImpact;

package/dist/analytics/codeImpact.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateCodeImpact = calculateCodeImpact;
+function calculateCodeImpact(totalCost, additions, deletions, models = []) {
+    const safeAdditions = Math.max(0, additions);
+    const safeDeletions = Math.max(0, deletions);
+    const changedLines = safeAdditions + safeDeletions;
+    return {
+        changedLines,
+        additions: safeAdditions,
+        deletions: safeDeletions,
+        totalCost,
+        costPerChangedLine: changedLines > 0 ? totalCost / changedLines : null,
+        byModel: models.map((model) => ({
+            ...model,
+            priced: model.priced !== false,
+            changedLines,
+            costPerChangedLine: changedLines > 0 && model.priced !== false ? model.cost / changedLines : null,
+        })),
+    };
+}

package/dist/analytics/compactionLedger.d.ts

@@ -0,0 +1,11 @@
+import type { CompactionEvent } from '../types/sessionEvent';
+export interface CompactionLedger {
+    count: number;
+    tokensEvicted: number;
+    reestablishmentCostUsd: number | null;
+    source: 'reported' | 'heuristic' | 'mixed';
+    reportedCount: number;
+    heuristicCount: number;
+}
+export declare function calculateCompactionLedger(events: CompactionEvent[], model?: string | null): CompactionLedger;
+export declare function formatCompactionLedger(ledger: CompactionLedger): string;

package/dist/analytics/compactionLedger.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateCompactionLedger = calculateCompactionLedger;
+exports.formatCompactionLedger = formatCompactionLedger;
+const modelInfo_1 = require("../modelInfo");
+function calculateCompactionLedger(events, model) {
+    const tokensEvicted = events.reduce((sum, event) => sum + Math.max(0, event.tokensReclaimed), 0);
+    const reportedCount = events.filter((event) => event.source === 'reported').length;
+    const heuristicCount = events.length - reportedCount;
+    const pricing = model ? (0, modelInfo_1.getModelPricing)(model) : null;
+    return {
+        count: events.length,
+        tokensEvicted,
+        reestablishmentCostUsd: pricing
+            ? (0, modelInfo_1.calculateCostWithPricing)({ inputTokens: tokensEvicted, outputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0 }, pricing)
+            : null,
+        source: reportedCount > 0 && heuristicCount > 0
+            ? 'mixed'
+            : reportedCount > 0
+                ? 'reported'
+                : 'heuristic',
+        reportedCount,
+        heuristicCount,
+    };
+}
+function formatCompactionLedger(ledger) {
+    const cost = ledger.reestablishmentCostUsd == null
+        ? 'cost unavailable'
+        : `~$${ledger.reestablishmentCostUsd.toFixed(2)} re-establishing context`;
+    return `${ledger.count} compaction${ledger.count === 1 ? '' : 's'} · ${ledger.tokensEvicted.toLocaleString()} tokens evicted · ${cost} · ${ledger.source}`;
+}

package/dist/analytics/qualityScore.d.ts

@@ -0,0 +1,26 @@
+import type { AggregatedMetrics } from '../aggregation/types';
+import type { SessionHistoryRecord } from '../types/historicalData';
+export type QualityFactorId = 'latency' | 'reliability' | 'context' | 'permission_safety' | 'outcomes';
+export interface QualityFactorContribution {
+    id: QualityFactorId;
+    label: string;
+    contribution: number;
+    maximum: number;
+    detail: string;
+}
+export interface SessionQualityScore {
+    /** Composite score. Beta until weights are calibrated against durable history. */
+    score: number;
+    beta: true;
+    factors: QualityFactorContribution[];
+}
+export interface QualityTrend {
+    currentWeekAverage: number | null;
+    previousWeekAverage: number | null;
+    delta: number | null;
+    direction: 'improving' | 'declining' | 'flat' | 'insufficient';
+    currentWeekSessions: number;
+    previousWeekSessions: number;
+}
+export declare function scoreSessionQuality(metrics: AggregatedMetrics): SessionQualityScore;
+export declare function calculateQualityTrend(records: SessionHistoryRecord[], now?: Date): QualityTrend;