sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/aggregation/FrequencyTracker.js

@@ -0,0 +1,69 @@
+/**
+ * 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
+ */
+const DEFAULT_MAX_ENTRIES = 10_000;
+export 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);
+    }
+}

package/dist/esm/aggregation/HeatmapTracker.js

@@ -0,0 +1,89 @@
+/**
+ * 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
+ */
+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);
+}
+export 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);
+            }
+        }
+    }
+}

package/dist/esm/aggregation/PatternExtractor.js

@@ -0,0 +1,168 @@
+/**
+ * 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
+ */
+const DEFAULT_MAX_CLUSTERS = 100;
+const DEFAULT_MAX_DEPTH = 4;
+const DEFAULT_SIMILARITY_THRESHOLD = 0.5;
+export 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);
+        }
+    }
+}

package/dist/esm/aggregation/costProvenance.js

@@ -0,0 +1,31 @@
+const PROVENANCE_LABELS = {
+    reported: 'provider-reported',
+    estimated: 'estimated from catalog pricing',
+    mixed: 'partly provider-reported, partly estimated',
+    unpriced: 'unpriced',
+    none: '',
+};
+/**
+ * Human-readable qualifier for an aggregate cost, for report footers and
+ * table cells. Empty when there is nothing to qualify.
+ */
+export function describeCostProvenance(tokens) {
+    const base = PROVENANCE_LABELS[tokens.costProvenance] ?? '';
+    const unpriced = tokens.unpricedCalls > 0
+        ? `${tokens.unpricedCalls} unpriced call${tokens.unpricedCalls === 1 ? '' : 's'}`
+        : '';
+    if (base && unpriced)
+        return `${base} · ${unpriced}`;
+    return base || unpriced;
+}
+/** Classify a cost breakdown by how many events fell into each bucket. */
+export function classifyCostProvenance(counts) {
+    const { reportedCalls, estimatedCalls, unpricedCalls } = counts;
+    if (reportedCalls > 0 && estimatedCalls > 0)
+        return 'mixed';
+    if (reportedCalls > 0)
+        return 'reported';
+    if (estimatedCalls > 0)
+        return 'estimated';
+    return unpricedCalls > 0 ? 'unpriced' : 'none';
+}

package/dist/esm/aggregation/snapshot.js

@@ -0,0 +1,161 @@
+/**
+ * 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 * as fs from 'fs';
+import * as path from 'path';
+import { getConfigDir } from '../paths';
+import { atomicWriteJsonSync } from '../writers/atomic';
+import { SNAPSHOT_SCHEMA_VERSION } from './EventAggregator';
+/** Current schema version — bump when format changes. */
+const SNAPSHOT_VERSION = SNAPSHOT_SCHEMA_VERSION;
+/** Newest snapshots kept on disk; older ones are pruned opportunistically. */
+export const MAX_SNAPSHOT_FILES = 200;
+/** Prune runs once per this many saves, so steady-state writes stay one file each. */
+const PRUNE_EVERY_N_SAVES = 25;
+let savesSincePrune = 0;
+/** Returns the directory for snapshot files. */
+function getSnapshotsDir() {
+    return path.join(getConfigDir(), 'snapshots');
+}
+/** Returns the path to a snapshot file for a given session. */
+export 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. Uses the shared
+ * fsynced atomic writer with a per-process temp name, so the CLI dashboard and
+ * the extension host snapshotting the same session cannot collide on a shared
+ * `.tmp` file. Every {@link PRUNE_EVERY_N_SAVES} saves the directory is
+ * trimmed to the newest {@link MAX_SNAPSHOT_FILES}; snapshots are caches, so
+ * dropping an old one only costs a replay.
+ */
+export function saveSnapshot(snapshot) {
+    try {
+        const dir = getSnapshotsDir();
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        atomicWriteJsonSync(getSnapshotPath(snapshot.sessionId), snapshot);
+        savesSincePrune += 1;
+        if (savesSincePrune >= PRUNE_EVERY_N_SAVES) {
+            savesSincePrune = 0;
+            pruneSnapshots(MAX_SNAPSHOT_FILES);
+        }
+    }
+    catch {
+        // Non-critical — snapshot failure should never break session monitoring
+    }
+}
+/**
+ * Deletes all but the newest `keep` snapshot files (by modification time).
+ * Returns how many files were removed. Best-effort; never throws.
+ */
+export function pruneSnapshots(keep = MAX_SNAPSHOT_FILES) {
+    try {
+        const dir = getSnapshotsDir();
+        const entries = fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith('.json'))
+            .map((name) => {
+            const filePath = path.join(dir, name);
+            try {
+                return { filePath, mtimeMs: fs.statSync(filePath).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null)
+            .sort((a, b) => b.mtimeMs - a.mtimeMs);
+        let removed = 0;
+        for (const entry of entries.slice(Math.max(0, keep))) {
+            try {
+                fs.unlinkSync(entry.filePath);
+                removed += 1;
+            }
+            catch {
+                // Already gone or locked; skip.
+            }
+        }
+        return removed;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * 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 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.
+ */
+export 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).
+ */
+export 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;
+}

package/dist/esm/aggregation/types.js

@@ -0,0 +1,5 @@
+/**
+ * Aggregated metrics output types for EventAggregator.
+ * Re-exports canonical types from sessionEvent and defines aggregation-specific shapes.
+ */
+export {};

package/dist/esm/analytics/codeImpact.js

@@ -0,0 +1,18 @@
+export 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/esm/analytics/compactionLedger.js

@@ -0,0 +1,37 @@
+import { calculateNormalizedUsageCost, normalizeProviderUsage } from '../usageNormalization';
+export 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;
+    // Re-establishing evicted context means sending it again as uncached input.
+    // Price it through the same normalized path every other cost figure uses so
+    // the ledger can never disagree with the session total on the same tokens.
+    const reestablishment = model
+        ? calculateNormalizedUsageCost({
+            usage: normalizeProviderUsage({
+                semantics: 'sidekick',
+                inputTokens: tokensEvicted,
+                reasoningIncludedInOutput: true,
+            }),
+            modelId: model,
+        })
+        : null;
+    return {
+        count: events.length,
+        tokensEvicted,
+        reestablishmentCostUsd: reestablishment?.costUsd ?? null,
+        source: reportedCount > 0 && heuristicCount > 0
+            ? 'mixed'
+            : reportedCount > 0
+                ? 'reported'
+                : 'heuristic',
+        reportedCount,
+        heuristicCount,
+    };
+}
+export 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}`;
+}