sidekick-shared 0.13.2

package/README.md

@@ -0,0 +1,92 @@
+# sidekick-shared
+
+Shared data access library for [Sidekick Agent Hub](https://github.com/cesarandreslopez/sidekick-agent-hub).
+
+[![npm version](https://img.shields.io/npm/v/sidekick-shared.svg)](https://www.npmjs.com/package/sidekick-shared)
+[![license](https://img.shields.io/npm/l/sidekick-shared.svg)](https://github.com/cesarandreslopez/sidekick-agent-hub/blob/main/LICENSE)
+
+Types, parsers, providers, readers, formatters, aggregation, search, reporting, credentials, and quota for AI agent session monitoring. Used by both the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=CesarAndresLopez.sidekick-for-max) and the [CLI dashboard](https://www.npmjs.com/package/sidekick-agent-hub).
+
+## Installation
+
+```bash
+npm install sidekick-shared
+```
+
+## API Overview
+
+| Module | Description |
+|--------|-------------|
+| **Types** | Session events, OpenCode/Codex format types, persistence schemas (tasks, decisions, notes, plans, historical data) |
+| **Paths** | Config directory resolution, project data paths, workspace encoding |
+| **Readers** | Read tasks, decisions, notes, history, handoff, and plans from `~/.config/sidekick/` |
+| **Providers** | Session provider abstraction with Claude Code, OpenCode, and Codex implementations; auto-detection via filesystem |
+| **Parsers** | JSONL event parsing, OpenCode/Codex format normalization, subagent scanning, session path resolution, debug log parsing |
+| **Watchers** | Live session file watching with event bridging |
+| **Formatters** | Tool summary, noise classification, session dump (text/markdown/JSON), event highlighting |
+| **Search** | Cross-session full-text search, advanced filtering (substring, fuzzy, regex, date) |
+| **Aggregation** | Event aggregation, frequency tracking, activity heatmaps, pattern extraction |
+| **Report** | Self-contained HTML session report generation |
+| **Credentials** | Claude Max OAuth credential reading from `~/.claude/.credentials.json` |
+| **Quota** | Claude Max subscription quota fetching (5-hour and 7-day windows) |
+
+## Usage Examples
+
+### Detect the active session provider
+
+```typescript
+import { detectProvider } from 'sidekick-shared';
+
+const provider = await detectProvider('/path/to/project');
+if (provider) {
+  console.log(`Active provider: ${provider.id}`);
+  const sessions = await provider.listSessions();
+}
+```
+
+### Read persisted tasks
+
+```typescript
+import { readTasks, getProjectSlug } from 'sidekick-shared';
+
+const slug = getProjectSlug('/path/to/project');
+const tasks = readTasks({ projectSlug: slug });
+console.log(`Found ${tasks.length} tasks`);
+```
+
+### Fetch subscription quota
+
+```typescript
+import { fetchQuota, readClaudeMaxCredentials } from 'sidekick-shared';
+
+const creds = readClaudeMaxCredentials();
+if (creds) {
+  const quota = await fetchQuota(creds.accessToken);
+  console.log(`5-hour utilization: ${quota.fiveHour.percentUsed}%`);
+}
+```
+
+## Building
+
+```bash
+npm run build
+```
+
+Compiles TypeScript to `dist/` via `tsc`.
+
+## Testing
+
+```bash
+npm test
+```
+
+Uses Vitest. Run `npm run test:watch` for watch mode.
+
+## See Also
+
+- [Sidekick for Max](https://marketplace.visualstudio.com/items?itemName=CesarAndresLopez.sidekick-for-max) — VS Code extension
+- [Sidekick CLI](https://www.npmjs.com/package/sidekick-agent-hub) — Terminal dashboard (`npm install -g sidekick-agent-hub`)
+
+## License
+
+MIT

package/dist/aggregation/EventAggregator.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Shared event aggregation engine.
+ *
+ * Pure computation class (no I/O, no framework dependencies) that processes
+ * SessionEvent and FollowEvent objects to accumulate session metrics.
+ * Both the VS Code SessionMonitor and CLI DashboardState delegate to this.
+ *
+ * @module aggregation/EventAggregator
+ */
+import type { SessionEvent, ToolAnalytics, TimelineEvent, TrackedTask, TaskState, PlanState, CompactionEvent, TruncationEvent, ContextAttribution, ContextSizePoint, ResponseLatency, LatencyStats, PermissionMode, PermissionModeChange } from '../types/sessionEvent';
+import type { FollowEvent } from '../watchers/types';
+import type { EventAggregatorOptions, AggregatedTokens, ModelUsageStats, BurnRateInfo, SubagentLifecycle, AggregatedMetrics } from './types';
+import type { SerializedFrequencyState } from './FrequencyTracker';
+import type { SerializedHeatmapState } from './HeatmapTracker';
+import type { SerializedPatternState } from './PatternExtractor';
+/**
+ * JSON-serializable snapshot of EventAggregator state.
+ * Used by session snapshot sidecar files for fast resume.
+ */
+export interface SerializedAggregatorState {
+    version: number;
+    tokens: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+        cacheRead: number;
+        reportedCost: number;
+    };
+    modelUsage: Array<[string, {
+        calls: number;
+        tokens: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheWriteTokens: number;
+        cacheReadTokens: number;
+        cost: number;
+    }]>;
+    contextSize: number;
+    previousContextSize: number;
+    compactionEvents: CompactionEvent[];
+    truncationEvents: TruncationEvent[];
+    toolAnalytics: Array<[string, ToolAnalytics]>;
+    contextAttribution: ContextAttribution;
+    burnSamples: BurnSample[];
+    lastBurnSampleTime: number;
+    tokensSinceLastSample: number;
+    latencyRecords: ResponseLatency[];
+    tasks: Array<[string, TrackedTask]>;
+    activeTaskId: string | null;
+    subagents: SubagentLifecycle[];
+    permissionMode?: PermissionMode | null;
+    permissionModeHistory?: PermissionModeChange[];
+    contextTimeline?: ContextSizePoint[];
+    contextTurnIndex?: number;
+    timeline: TimelineEvent[];
+    messageCount: number;
+    eventCount: number;
+    sessionStartTime: string | null;
+    lastEventTime: string | null;
+    currentModel: string | null;
+    toolFrequency?: SerializedFrequencyState;
+    wordFrequency?: SerializedFrequencyState;
+    patternState?: SerializedPatternState;
+    heatmapState?: SerializedHeatmapState;
+}
+interface BurnSample {
+    time: number;
+    tokens: number;
+}
+export declare class EventAggregator {
+    private readonly timelineCap;
+    private readonly latencyCap;
+    private readonly burnWindowMs;
+    private readonly burnSampleMs;
+    private readonly computeContextSize;
+    private readonly providerId;
+    private inputTokens;
+    private outputTokens;
+    private cacheWriteTokens;
+    private cacheReadTokens;
+    private reportedCost;
+    private modelUsage;
+    private currentContextSize;
+    private previousContextSize;
+    private compactionEvents;
+    private truncationEvents;
+    private toolAnalytics;
+    private pendingToolCalls;
+    private burnSamples;
+    private lastBurnSampleTime;
+    private tokensSinceLastSample;
+    private tasks;
+    private pendingTaskCreates;
+    private activeTaskId;
+    private subagents;
+    private pendingSubagents;
+    private planExtractor;
+    private contextAttribution;
+    private currentPermissionMode;
+    private permissionModeHistory;
+    private contextTimeline;
+    private contextTurnIndex;
+    private timeline;
+    private pendingUserRequest;
+    private latencyRecords;
+    private messageCount;
+    private eventCount;
+    private sessionStartTime;
+    private lastEventTime;
+    private currentModel;
+    private _providerId;
+    private toolFrequency;
+    private wordFrequency;
+    private patternExtractor;
+    private heatmapTracker;
+    constructor(options?: EventAggregatorOptions);
+    processEvent(event: SessionEvent): void;
+    processFollowEvent(event: FollowEvent): void;
+    getAggregatedTokens(): AggregatedTokens;
+    getModelStats(): ModelUsageStats[];
+    getToolStats(): ToolAnalytics[];
+    getCompactionEvents(): CompactionEvent[];
+    getTruncationEvents(): TruncationEvent[];
+    getBurnRate(): BurnRateInfo;
+    getTaskState(): TaskState;
+    getSubagents(): SubagentLifecycle[];
+    getPlan(): PlanState | null;
+    getContextAttribution(): ContextAttribution;
+    getTimeline(): TimelineEvent[];
+    getLatencyStats(): LatencyStats | null;
+    getMetrics(): AggregatedMetrics;
+    reset(): void;
+    /** Seeds the current context size (e.g., from a provider usage snapshot on attach). */
+    seedContextSize(size: number): void;
+    /** Seeds context attribution (e.g., from a provider's DB-backed attribution). */
+    seedContextAttribution(attribution: ContextAttribution): void;
+    /** Serializes all mutable state to a JSON-safe object for snapshot persistence. */
+    serialize(): SerializedAggregatorState;
+    /** Restores mutable state from a serialized snapshot. Clears transient state (pending calls). */
+    restore(state: SerializedAggregatorState): void;
+    private accumulateUsage;
+    private updateBurnRate;
+    private processLatency;
+    private extractToolsFromContent;
+    private detectTruncationInContent;
+    private recordFollowToolUse;
+    private recordFollowToolResult;
+    private detectTruncationFromFollowEvent;
+    private extractTaskStateFromEvent;
+    private extractTaskStateFromFollowEvent;
+    private applyTaskUpdate;
+    private resolveTaskCreate;
+    private extractSubagentFromEvent;
+    private extractSubagentFromFollowEvent;
+    private completeSubagent;
+    private extractPlanFromSessionEvent;
+    private convertExtractedPlanToPlanState;
+    private attributeContextFromEvent;
+    private attributeContextFromFollowEvent;
+    private trackPermissionMode;
+    private addTimelineFromSessionEvent;
+    private addTimelineFromFollowEvent;
+    private estimateTokens;
+    private hasTextContent;
+    private extractTextContent;
+    private extractTaskIdFromResult;
+    private isSystemPromptContent;
+    private extractToolNameFromEvent;
+    /** Feed event data into frequency trackers, pattern extractor, and heatmap. */
+    private feedAnalytics;
+}
+export {};