sidekick-shared 0.13.2

package/dist/aggregation/FrequencyTracker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generic frequency counter with LRU eviction.
+ *
+ * Tracks word/key frequencies with count, firstSeen, lastSeen metadata.
+ * Used for tool name frequency, event type frequency, and summary word frequency.
+ *
+ * @module aggregation/FrequencyTracker
+ */
+export interface FrequencyEntry {
+    key: string;
+    count: number;
+    firstSeen: string;
+    lastSeen: string;
+}
+export interface SerializedFrequencyState {
+    entries: Array<[string, {
+        count: number;
+        firstSeen: string;
+        lastSeen: string;
+    }]>;
+}
+export declare class FrequencyTracker {
+    private entries;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    /** Increment frequency for a key. */
+    increment(key: string, timestamp?: string): void;
+    /** Get the top N entries by count. */
+    getTopN(n: number): FrequencyEntry[];
+    /** Get all entries sorted by count descending. */
+    getAll(): FrequencyEntry[];
+    /** Get count for a specific key. */
+    getCount(key: string): number;
+    /** Get total number of tracked keys. */
+    get size(): number;
+    /** Reset all tracked frequencies. */
+    reset(): void;
+    /** Serialize for snapshot persistence. */
+    serialize(): SerializedFrequencyState;
+    /** Restore from serialized state. */
+    restore(state: SerializedFrequencyState): void;
+}

package/dist/aggregation/FrequencyTracker.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Generic frequency counter with LRU eviction.
+ *
+ * Tracks word/key frequencies with count, firstSeen, lastSeen metadata.
+ * Used for tool name frequency, event type frequency, and summary word frequency.
+ *
+ * @module aggregation/FrequencyTracker
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrequencyTracker = void 0;
+const DEFAULT_MAX_ENTRIES = 10_000;
+class FrequencyTracker {
+    entries = new Map();
+    maxEntries;
+    constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+        this.maxEntries = maxEntries;
+    }
+    /** Increment frequency for a key. */
+    increment(key, timestamp) {
+        const ts = timestamp ?? new Date().toISOString();
+        const existing = this.entries.get(key);
+        if (existing) {
+            existing.count++;
+            existing.lastSeen = ts;
+            // Move to end for LRU ordering (Map preserves insertion order)
+            this.entries.delete(key);
+            this.entries.set(key, existing);
+        }
+        else {
+            // Evict oldest if at capacity
+            if (this.entries.size >= this.maxEntries) {
+                const oldest = this.entries.keys().next().value;
+                if (oldest !== undefined) {
+                    this.entries.delete(oldest);
+                }
+            }
+            this.entries.set(key, { count: 1, firstSeen: ts, lastSeen: ts });
+        }
+    }
+    /** Get the top N entries by count. */
+    getTopN(n) {
+        const sorted = Array.from(this.entries.entries())
+            .map(([key, data]) => ({ key, ...data }))
+            .sort((a, b) => b.count - a.count);
+        return sorted.slice(0, n);
+    }
+    /** Get all entries sorted by count descending. */
+    getAll() {
+        return this.getTopN(this.entries.size);
+    }
+    /** Get count for a specific key. */
+    getCount(key) {
+        return this.entries.get(key)?.count ?? 0;
+    }
+    /** Get total number of tracked keys. */
+    get size() {
+        return this.entries.size;
+    }
+    /** Reset all tracked frequencies. */
+    reset() {
+        this.entries.clear();
+    }
+    /** Serialize for snapshot persistence. */
+    serialize() {
+        return { entries: Array.from(this.entries.entries()) };
+    }
+    /** Restore from serialized state. */
+    restore(state) {
+        this.entries = new Map(state.entries);
+    }
+}
+exports.FrequencyTracker = FrequencyTracker;

package/dist/aggregation/HeatmapTracker.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Rolling heatmap tracker using a circular buffer of minute-buckets.
+ *
+ * Records event timestamps into minute-resolution buckets for activity
+ * visualization. Older buckets age out as time advances.
+ *
+ * @module aggregation/HeatmapTracker
+ */
+export interface HeatmapBucket {
+    /** ISO timestamp of the minute this bucket represents. */
+    timestamp: string;
+    /** Number of events in this minute. */
+    count: number;
+}
+export interface SerializedHeatmapState {
+    buckets: Array<{
+        minuteKey: number;
+        count: number;
+    }>;
+    oldestMinuteKey: number;
+}
+export declare class HeatmapTracker {
+    private buckets;
+    private readonly bucketCount;
+    constructor(bucketCount?: number);
+    /** Record an event at the given timestamp. */
+    record(timestamp: string): void;
+    /** Get the rolling window of buckets, filled with zeros for empty minutes. */
+    getBuckets(): HeatmapBucket[];
+    /** Get the maximum count in any bucket (for intensity scaling). */
+    getMaxCount(): number;
+    /** Reset all tracked data. */
+    reset(): void;
+    /** Serialize for snapshot persistence. */
+    serialize(): SerializedHeatmapState;
+    /** Restore from serialized state. */
+    restore(state: SerializedHeatmapState): void;
+    /** Prune buckets outside the rolling window. */
+    private prune;
+}

package/dist/aggregation/HeatmapTracker.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Rolling heatmap tracker using a circular buffer of minute-buckets.
+ *
+ * Records event timestamps into minute-resolution buckets for activity
+ * visualization. Older buckets age out as time advances.
+ *
+ * @module aggregation/HeatmapTracker
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeatmapTracker = void 0;
+const DEFAULT_BUCKET_COUNT = 60;
+/** Truncate a Date to minute resolution and return the minute-key (epoch minutes). */
+function toMinuteKey(date) {
+    return Math.floor(date.getTime() / 60_000);
+}
+class HeatmapTracker {
+    buckets = new Map(); // minuteKey -> count
+    bucketCount;
+    constructor(bucketCount = DEFAULT_BUCKET_COUNT) {
+        this.bucketCount = bucketCount;
+    }
+    /** Record an event at the given timestamp. */
+    record(timestamp) {
+        const date = new Date(timestamp);
+        if (isNaN(date.getTime()))
+            return;
+        const minuteKey = toMinuteKey(date);
+        this.buckets.set(minuteKey, (this.buckets.get(minuteKey) ?? 0) + 1);
+        this.prune(minuteKey);
+    }
+    /** Get the rolling window of buckets, filled with zeros for empty minutes. */
+    getBuckets() {
+        if (this.buckets.size === 0)
+            return [];
+        // Find the latest minute key
+        let latestKey = 0;
+        for (const key of this.buckets.keys()) {
+            if (key > latestKey)
+                latestKey = key;
+        }
+        const result = [];
+        const startKey = latestKey - this.bucketCount + 1;
+        for (let key = startKey; key <= latestKey; key++) {
+            result.push({
+                timestamp: new Date(key * 60_000).toISOString(),
+                count: this.buckets.get(key) ?? 0,
+            });
+        }
+        return result;
+    }
+    /** Get the maximum count in any bucket (for intensity scaling). */
+    getMaxCount() {
+        let max = 0;
+        for (const count of this.buckets.values()) {
+            if (count > max)
+                max = count;
+        }
+        return max;
+    }
+    /** Reset all tracked data. */
+    reset() {
+        this.buckets.clear();
+    }
+    /** Serialize for snapshot persistence. */
+    serialize() {
+        let oldest = Infinity;
+        const entries = [];
+        for (const [key, count] of this.buckets) {
+            entries.push({ minuteKey: key, count });
+            if (key < oldest)
+                oldest = key;
+        }
+        return { buckets: entries, oldestMinuteKey: oldest === Infinity ? 0 : oldest };
+    }
+    /** Restore from serialized state. */
+    restore(state) {
+        this.buckets.clear();
+        for (const { minuteKey, count } of state.buckets) {
+            this.buckets.set(minuteKey, count);
+        }
+    }
+    /** Prune buckets outside the rolling window. */
+    prune(latestKey) {
+        const cutoff = latestKey - this.bucketCount;
+        for (const key of this.buckets.keys()) {
+            if (key <= cutoff) {
+                this.buckets.delete(key);
+            }
+        }
+    }
+}
+exports.HeatmapTracker = HeatmapTracker;

package/dist/aggregation/PatternExtractor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Simplified Drain algorithm for session event clustering.
+ *
+ * Tokenizes event summaries, groups by token count, clusters by shared prefix
+ * tokens, and replaces variable tokens with `<*>` to produce templates.
+ * Surfaces repetitive patterns like "Read src/<*>.ts" (count: 5).
+ *
+ * @module aggregation/PatternExtractor
+ */
+export interface PatternCluster {
+    /** Template string with <*> wildcards for variable tokens. */
+    template: string;
+    /** Number of events matching this pattern. */
+    count: number;
+    /** Up to 3 example summaries. */
+    examples: string[];
+}
+export interface SerializedPatternState {
+    clusters: Array<{
+        tokens: string[];
+        mask: boolean[];
+        count: number;
+        examples: string[];
+    }>;
+}
+export declare class PatternExtractor {
+    private readonly maxClusters;
+    private readonly maxDepth;
+    private readonly similarityThreshold;
+    private groups;
+    constructor(options?: {
+        maxClusters?: number;
+        maxDepth?: number;
+        similarityThreshold?: number;
+    });
+    /** Add a summary string for clustering. */
+    add(summary: string): void;
+    /** Get all patterns sorted by frequency. */
+    getPatterns(): PatternCluster[];
+    /** Reset all tracked patterns. */
+    reset(): void;
+    /** Serialize for snapshot persistence. */
+    serialize(): SerializedPatternState;
+    /** Restore from serialized state. */
+    restore(state: SerializedPatternState): void;
+    private tokenize;
+    private similarity;
+    private buildTemplate;
+    private totalClusters;
+    private evictSmallest;
+}

package/dist/aggregation/PatternExtractor.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Simplified Drain algorithm for session event clustering.
+ *
+ * Tokenizes event summaries, groups by token count, clusters by shared prefix
+ * tokens, and replaces variable tokens with `<*>` to produce templates.
+ * Surfaces repetitive patterns like "Read src/<*>.ts" (count: 5).
+ *
+ * @module aggregation/PatternExtractor
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PatternExtractor = void 0;
+const DEFAULT_MAX_CLUSTERS = 100;
+const DEFAULT_MAX_DEPTH = 4;
+const DEFAULT_SIMILARITY_THRESHOLD = 0.5;
+class PatternExtractor {
+    maxClusters;
+    maxDepth;
+    similarityThreshold;
+    // Group clusters by token count for efficient lookup
+    groups = new Map();
+    constructor(options) {
+        this.maxClusters = options?.maxClusters ?? DEFAULT_MAX_CLUSTERS;
+        this.maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+        this.similarityThreshold = options?.similarityThreshold ?? DEFAULT_SIMILARITY_THRESHOLD;
+    }
+    /** Add a summary string for clustering. */
+    add(summary) {
+        const tokens = this.tokenize(summary);
+        if (tokens.length === 0)
+            return;
+        const key = tokens.length;
+        let group = this.groups.get(key);
+        if (!group) {
+            group = [];
+            this.groups.set(key, group);
+        }
+        // Find best matching cluster
+        let bestCluster = null;
+        let bestSim = 0;
+        for (const cluster of group) {
+            const sim = this.similarity(tokens, cluster);
+            if (sim > bestSim) {
+                bestSim = sim;
+                bestCluster = cluster;
+            }
+        }
+        if (bestCluster && bestSim >= this.similarityThreshold) {
+            // Merge into existing cluster
+            bestCluster.count++;
+            if (bestCluster.examples.length < 3) {
+                bestCluster.examples.push(summary);
+            }
+            // Update mask: mark differing positions as wildcards
+            for (let i = 0; i < tokens.length; i++) {
+                if (!bestCluster.mask[i] && tokens[i] !== bestCluster.tokens[i]) {
+                    bestCluster.mask[i] = true;
+                }
+            }
+        }
+        else {
+            // Create new cluster (evict least-used if at capacity)
+            if (this.totalClusters() >= this.maxClusters) {
+                this.evictSmallest();
+            }
+            group.push({
+                tokens: [...tokens],
+                mask: new Array(tokens.length).fill(false),
+                count: 1,
+                examples: [summary],
+            });
+        }
+    }
+    /** Get all patterns sorted by frequency. */
+    getPatterns() {
+        const result = [];
+        for (const group of this.groups.values()) {
+            for (const cluster of group) {
+                if (cluster.count < 2)
+                    continue; // Only show patterns with 2+ matches
+                result.push({
+                    template: this.buildTemplate(cluster),
+                    count: cluster.count,
+                    examples: [...cluster.examples],
+                });
+            }
+        }
+        return result.sort((a, b) => b.count - a.count);
+    }
+    /** Reset all tracked patterns. */
+    reset() {
+        this.groups.clear();
+    }
+    /** Serialize for snapshot persistence. */
+    serialize() {
+        const clusters = [];
+        for (const group of this.groups.values()) {
+            for (const cluster of group) {
+                clusters.push({
+                    tokens: [...cluster.tokens],
+                    mask: [...cluster.mask],
+                    count: cluster.count,
+                    examples: [...cluster.examples],
+                });
+            }
+        }
+        return { clusters };
+    }
+    /** Restore from serialized state. */
+    restore(state) {
+        this.groups.clear();
+        for (const c of state.clusters) {
+            const key = c.tokens.length;
+            let group = this.groups.get(key);
+            if (!group) {
+                group = [];
+                this.groups.set(key, group);
+            }
+            group.push({
+                tokens: [...c.tokens],
+                mask: [...c.mask],
+                count: c.count,
+                examples: [...c.examples],
+            });
+        }
+    }
+    // ── Private ──
+    tokenize(text) {
+        return text.split(/\s+/).filter(t => t.length > 0).slice(0, this.maxDepth * 4);
+    }
+    similarity(tokens, cluster) {
+        const len = Math.min(tokens.length, this.maxDepth);
+        let matches = 0;
+        for (let i = 0; i < len; i++) {
+            if (cluster.mask[i] || tokens[i] === cluster.tokens[i]) {
+                matches++;
+            }
+        }
+        return matches / len;
+    }
+    buildTemplate(cluster) {
+        return cluster.tokens
+            .map((tok, i) => (cluster.mask[i] ? '<*>' : tok))
+            .join(' ');
+    }
+    totalClusters() {
+        let total = 0;
+        for (const group of this.groups.values()) {
+            total += group.length;
+        }
+        return total;
+    }
+    evictSmallest() {
+        let minCount = Infinity;
+        let minGroup = null;
+        let minIndex = -1;
+        for (const group of this.groups.values()) {
+            for (let i = 0; i < group.length; i++) {
+                if (group[i].count < minCount) {
+                    minCount = group[i].count;
+                    minGroup = group;
+                    minIndex = i;
+                }
+            }
+        }
+        if (minGroup && minIndex >= 0) {
+            minGroup.splice(minIndex, 1);
+        }
+    }
+}
+exports.PatternExtractor = PatternExtractor;

package/dist/aggregation/snapshot.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Session snapshot sidecar — persists aggregator state + reader position
+ * so that re-attaching to a session skips full replay.
+ *
+ * Snapshots are stored in ~/.config/sidekick/snapshots/{sessionId}.json.
+ * They are invalidated when the source file changes beyond the snapshot position.
+ *
+ * @module aggregation/snapshot
+ */
+import type { SerializedAggregatorState } from './EventAggregator';
+/** Snapshot sidecar file content. */
+export interface SessionSnapshot {
+    /** Schema version for forward-compatibility checks. */
+    version: number;
+    /** Session identifier (from provider.getSessionId). */
+    sessionId: string;
+    /** Provider identifier (claude-code, opencode, codex). */
+    providerId: string;
+    /** Reader position at snapshot time (byte offset or timestamp). */
+    readerPosition: number;
+    /** Source file size at snapshot time (for staleness check; 0 for DB-backed). */
+    sourceSize: number;
+    /** ISO timestamp when snapshot was written. */
+    createdAt: string;
+    /** Serialized EventAggregator state. */
+    aggregator: SerializedAggregatorState;
+    /** Serialized consumer-specific state (SessionMonitor fields, DashboardState fields, etc.). */
+    consumer: Record<string, unknown>;
+}
+/** Returns the path to a snapshot file for a given session. */
+export declare function getSnapshotPath(sessionId: string): string;
+/**
+ * Saves a session snapshot to disk.
+ *
+ * Creates the snapshots directory if it doesn't exist.
+ * Writes atomically via rename to avoid partial reads.
+ */
+export declare function saveSnapshot(snapshot: SessionSnapshot): void;
+/**
+ * Loads a session snapshot from disk if it exists and is valid.
+ *
+ * Returns null if:
+ * - No snapshot file exists
+ * - Schema version doesn't match
+ * - JSON parse fails
+ *
+ * The caller is responsible for staleness checks (comparing sourceSize
+ * and readerPosition against the actual file).
+ */
+export declare function loadSnapshot(sessionId: string): SessionSnapshot | null;
+/**
+ * Deletes a session snapshot file.
+ */
+export declare function deleteSnapshot(sessionId: string): void;
+/**
+ * Validates whether a snapshot is still usable for a given source file.
+ *
+ * For JSONL providers: checks that the file hasn't been truncated
+ * (current size >= snapshot position) and that the size matches or has grown.
+ *
+ * For DB-backed providers: sourceSize is 0, so we always consider valid
+ * (the DB reader's timestamp-based cursor handles staleness naturally).
+ */
+export declare function isSnapshotValid(snapshot: SessionSnapshot, currentSourceSize: number): boolean;

package/dist/aggregation/snapshot.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Session snapshot sidecar — persists aggregator state + reader position
+ * so that re-attaching to a session skips full replay.
+ *
+ * Snapshots are stored in ~/.config/sidekick/snapshots/{sessionId}.json.
+ * They are invalidated when the source file changes beyond the snapshot position.
+ *
+ * @module aggregation/snapshot
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSnapshotPath = getSnapshotPath;
+exports.saveSnapshot = saveSnapshot;
+exports.loadSnapshot = loadSnapshot;
+exports.deleteSnapshot = deleteSnapshot;
+exports.isSnapshotValid = isSnapshotValid;
+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;
+/** Returns the directory for snapshot files. */
+function getSnapshotsDir() {
+    return path.join((0, paths_1.getConfigDir)(), 'snapshots');
+}
+/** Returns the path to a snapshot file for a given session. */
+function getSnapshotPath(sessionId) {
+    // Sanitize sessionId for filesystem safety (remove path separators)
+    const safe = sessionId.replace(/[/\\:]/g, '_');
+    return path.join(getSnapshotsDir(), `${safe}.json`);
+}
+/**
+ * Saves a session snapshot to disk.
+ *
+ * Creates the snapshots directory if it doesn't exist.
+ * Writes atomically via rename to avoid partial reads.
+ */
+function saveSnapshot(snapshot) {
+    try {
+        const dir = getSnapshotsDir();
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        const filePath = getSnapshotPath(snapshot.sessionId);
+        const tmpPath = filePath + '.tmp';
+        fs.writeFileSync(tmpPath, JSON.stringify(snapshot), 'utf-8');
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch {
+        // Non-critical — snapshot failure should never break session monitoring
+    }
+}
+/**
+ * Loads a session snapshot from disk if it exists and is valid.
+ *
+ * Returns null if:
+ * - No snapshot file exists
+ * - Schema version doesn't match
+ * - JSON parse fails
+ *
+ * The caller is responsible for staleness checks (comparing sourceSize
+ * and readerPosition against the actual file).
+ */
+function loadSnapshot(sessionId) {
+    try {
+        const filePath = getSnapshotPath(sessionId);
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const snapshot = JSON.parse(raw);
+        // Version check
+        if (snapshot.version !== SNAPSHOT_VERSION) {
+            deleteSnapshot(sessionId);
+            return null;
+        }
+        return snapshot;
+    }
+    catch {
+        // Corrupt or unreadable — delete and move on
+        deleteSnapshot(sessionId);
+        return null;
+    }
+}
+/**
+ * Deletes a session snapshot file.
+ */
+function deleteSnapshot(sessionId) {
+    try {
+        const filePath = getSnapshotPath(sessionId);
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+    }
+    catch {
+        // Best-effort cleanup
+    }
+}
+/**
+ * Validates whether a snapshot is still usable for a given source file.
+ *
+ * For JSONL providers: checks that the file hasn't been truncated
+ * (current size >= snapshot position) and that the size matches or has grown.
+ *
+ * For DB-backed providers: sourceSize is 0, so we always consider valid
+ * (the DB reader's timestamp-based cursor handles staleness naturally).
+ */
+function isSnapshotValid(snapshot, currentSourceSize) {
+    // DB-backed providers store sourceSize=0 — always valid (cursor is a timestamp)
+    if (snapshot.sourceSize === 0) {
+        return true;
+    }
+    // File was truncated or rewritten (smaller than when we snapshotted)
+    if (currentSourceSize < snapshot.readerPosition) {
+        return false;
+    }
+    return true;
+}