sidekick-shared 0.24.5 → 0.26.0

package/dist/usage/importSessionHistory.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Import finished sessions from every provider into the history store.
+ *
+ * The VS Code extension used to import Claude Code only, by hand-parsing
+ * JSONL files; the CLI could not import at all. This walks the sessions
+ * every provider knows about, reads each once through the unified stats
+ * path, and hands a `SessionSummary` to the caller, which applies it to the
+ * store it owns (the extension's debounced persistence service or the CLI's
+ * locked atomic writer). Dedupe is the caller's `isImported` answer
+ * (imported file paths plus persisted session ids); the capped per-session
+ * list is deliberately not used as the dedupe key.
+ *
+ * Node-only: reads session files.
+ *
+ * @module usage/importSessionHistory
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVE_SESSION_MTIME_THRESHOLD_MS = void 0;
+exports.importSessionHistory = importSessionHistory;
+const historicalStore_1 = require("../historicalStore");
+const sessionPreviews_1 = require("../sessionPreviews");
+const sessionStats_1 = require("../sessionStats");
+/** Files modified more recently than this are skipped: they may still be live. */
+exports.ACTIVE_SESSION_MTIME_THRESHOLD_MS = 60_000;
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+async function importSessionHistory(options) {
+    const now = options.now ?? new Date();
+    const threshold = options.activeFileThresholdMs ?? exports.ACTIVE_SESSION_MTIME_THRESHOLD_MS;
+    const listed = await (0, sessionPreviews_1.listSessionPreviewsAsync)(options.providers, {
+        since: options.since,
+        workspacePath: options.workspacePath,
+        limit: Number.MAX_SAFE_INTEGER,
+    });
+    const providerById = new Map(options.providers.map((provider) => [provider.id, provider]));
+    const result = {
+        filesFound: listed.previews.length,
+        filesProcessed: 0,
+        filesSkipped: 0,
+        filesUnavailable: 0,
+        sessionsImported: 0,
+        messagesImported: 0,
+        diagnostics: [...listed.diagnostics],
+    };
+    const total = listed.previews.length;
+    let loaded = 0;
+    for (const preview of listed.previews) {
+        loaded += 1;
+        const provider = providerById.get(preview.provider);
+        const modifiedMs = Date.parse(preview.modifiedAt);
+        const recentlyModified = Number.isFinite(modifiedMs) && now.getTime() - modifiedMs < threshold;
+        if (!provider || recentlyModified || options.isImported(preview.sessionId, preview.filePath)) {
+            result.filesSkipped += 1;
+            options.onProgress?.(loaded, total);
+            continue;
+        }
+        const stats = (0, sessionStats_1.readSessionFileStats)(provider, preview.filePath);
+        result.filesProcessed += 1;
+        if (stats.availability === 'unavailable') {
+            result.filesUnavailable += 1;
+            result.diagnostics.push({
+                providerId: preview.provider,
+                kind: 'read_failed',
+                severity: 'warning',
+                phase: 'read',
+                message: `${preview.provider} session ${preview.sessionId}: ${stats.unavailableReason ?? 'unavailable'}`,
+            });
+        }
+        else if (Object.keys(stats.modelUsage).length === 0) {
+            // No usage record at all (for example a prompt that never got an
+            // answer): nothing to credit, but mark the file so it is not re-read
+            // on every run.
+            result.filesUnavailable += 1;
+            options.markImported(preview.filePath);
+        }
+        else {
+            options.applySummary((0, historicalStore_1.sessionSummaryFromStats)(stats, { project: preview.workspacePath }), preview.filePath);
+            options.markImported(preview.filePath);
+            result.sessionsImported += 1;
+            result.messagesImported += stats.messageCount;
+        }
+        options.onProgress?.(loaded, total);
+        await yieldToEventLoop();
+    }
+    return result;
+}

package/dist/usage/usageEvents.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Usage events collected from session logs, cached per session.
+ *
+ * Feeds the billing-block view and the log-derived daily/weekly/monthly
+ * reports, so CLI-only users get numbers without the extension's history
+ * store. Each session is read once through its provider reader; the
+ * extracted usage is cached under `<configDir>/usage-cache/` keyed by the
+ * session's size and mtime, so a repeat run only re-reads sessions that
+ * changed. Token counts are cached raw and priced at load time, so a pricing
+ * catalog refresh never leaves stale costs behind. Cache files are touched on
+ * every hit and pruned least-recently-used, once per collection.
+ *
+ * Node-only: reads session files and the cache directory.
+ *
+ * @module usage/usageEvents
+ */
+import type { ProviderId, SessionProviderBase, SessionProviderDiagnostic } from '../providers/types';
+import type { TokenTotals } from '../types/historicalData';
+import type { PricingProvenance } from '../usageNormalization';
+/** Bump when the cached record shape changes; older files are re-read. */
+export declare const USAGE_CACHE_VERSION = 1;
+/**
+ * Most-recently-used cache files kept on disk. Sized for a busy month of
+ * sessions (files are a few KB each); a collection larger than this still
+ * completes, it just re-reads what was evicted. Pruning runs once after a
+ * collection, never during one, so a working set is never evicted mid-run.
+ */
+export declare const MAX_USAGE_CACHE_FILES = 5000;
+/** One priced usage event from a session log. */
+export interface UsageEventRecord {
+    /** Event time in ms since epoch. */
+    timestamp: number;
+    provider: ProviderId;
+    sessionId: string;
+    /** Workspace path recorded in the session, when known. */
+    project: string | null;
+    model: string;
+    /** Four buckets plus the provider-semantics-aware total. */
+    tokens: TokenTotals & {
+        totalTokens: number;
+    };
+    costUsd: number | null;
+    costProvenance: PricingProvenance;
+}
+/** One session that contributed events. */
+export interface UsageSessionRecord {
+    provider: ProviderId;
+    sessionId: string;
+    filePath: string;
+    project: string | null;
+    fingerprint: string;
+    firstTimestamp: number | null;
+    lastTimestamp: number | null;
+    eventCount: number;
+    fromCache: boolean;
+}
+export interface CollectUsageEventsOptions {
+    providers: SessionProviderBase[];
+    /** Only sessions modified after this instant, and only events at or after it. */
+    since?: Date | string;
+    /** Only events at or before this instant. */
+    until?: Date | string;
+    /** Restrict to one workspace's sessions. */
+    workspacePath?: string;
+    /** Preview-read concurrency (see `listSessionPreviewsAsync`). */
+    concurrency?: number;
+    /** Cache directory (default `<configDir>/usage-cache`). */
+    cacheDir?: string;
+    /** Skip the on-disk cache entirely. */
+    noCache?: boolean;
+    onDiagnostic?: (diagnostic: SessionProviderDiagnostic) => void;
+}
+export interface CollectUsageEventsResult {
+    /** Events within the window, oldest first. */
+    events: UsageEventRecord[];
+    sessions: UsageSessionRecord[];
+    diagnostics: SessionProviderDiagnostic[];
+    cacheHits: number;
+    cacheMisses: number;
+}
+export declare function getUsageCacheDir(): string;
+/** Deletes all but the `keep` most recently used cache files (by mtime). Best-effort. */
+export declare function pruneUsageCache(keep?: number, dir?: string): number;
+/**
+ * Collect priced usage events for every session touched in the window.
+ *
+ * Sessions are enumerated with `listSessionPreviewsAsync` (the `since`
+ * cutoff applies to the session mtime there and to the event timestamp
+ * here), read once each unless the cache already holds their fingerprint,
+ * and yielded between reads so long-lived hosts stay responsive.
+ */
+export declare function collectUsageEvents(options: CollectUsageEventsOptions): Promise<CollectUsageEventsResult>;

package/dist/usage/usageEvents.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * Usage events collected from session logs, cached per session.
+ *
+ * Feeds the billing-block view and the log-derived daily/weekly/monthly
+ * reports, so CLI-only users get numbers without the extension's history
+ * store. Each session is read once through its provider reader; the
+ * extracted usage is cached under `<configDir>/usage-cache/` keyed by the
+ * session's size and mtime, so a repeat run only re-reads sessions that
+ * changed. Token counts are cached raw and priced at load time, so a pricing
+ * catalog refresh never leaves stale costs behind. Cache files are touched on
+ * every hit and pruned least-recently-used, once per collection.
+ *
+ * Node-only: reads session files and the cache directory.
+ *
+ * @module usage/usageEvents
+ */
+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.MAX_USAGE_CACHE_FILES = exports.USAGE_CACHE_VERSION = void 0;
+exports.getUsageCacheDir = getUsageCacheDir;
+exports.pruneUsageCache = pruneUsageCache;
+exports.collectUsageEvents = collectUsageEvents;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const paths_1 = require("../paths");
+const sessionPreviews_1 = require("../sessionPreviews");
+const usageNormalization_1 = require("../usageNormalization");
+const atomic_1 = require("../writers/atomic");
+/** Bump when the cached record shape changes; older files are re-read. */
+exports.USAGE_CACHE_VERSION = 1;
+/**
+ * Most-recently-used cache files kept on disk. Sized for a busy month of
+ * sessions (files are a few KB each); a collection larger than this still
+ * completes, it just re-reads what was evicted. Pruning runs once after a
+ * collection, never during one, so a working set is never evicted mid-run.
+ */
+exports.MAX_USAGE_CACHE_FILES = 5000;
+function getUsageCacheDir() {
+    return path.join((0, paths_1.getConfigDir)(), 'usage-cache');
+}
+function cacheFilePath(dir, provider, sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(dir, `${provider}--${safe}.json`);
+}
+function toMs(value, label) {
+    if (value === undefined)
+        return null;
+    const ms = value instanceof Date ? value.getTime() : Date.parse(value);
+    if (!Number.isFinite(ms))
+        throw new RangeError(`Invalid \`${label}\` value: ${String(value)}`);
+    return ms;
+}
+/** Mark a cache file as recently used so LRU pruning keeps it. Best-effort. */
+function touch(filePath) {
+    try {
+        const now = new Date();
+        fs.utimesSync(filePath, now, now);
+    }
+    catch {
+        // Read-only cache or vanished file; the next miss rewrites it.
+    }
+}
+function readCache(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed?.version !== exports.USAGE_CACHE_VERSION || !Array.isArray(parsed.events))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Deletes all but the `keep` most recently used cache files (by mtime). Best-effort. */
+function pruneUsageCache(keep = exports.MAX_USAGE_CACHE_FILES, dir = getUsageCacheDir()) {
+    try {
+        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; skip.
+            }
+        }
+        return removed;
+    }
+    catch {
+        return 0;
+    }
+}
+function cachedEventFromUsage(usage, timestamp, model) {
+    const record = {
+        t: timestamp,
+        m: model,
+        i: usage.uncachedInputTokens,
+        o: usage.outputTokens,
+        cw: usage.cacheWriteTokens,
+        cr: usage.cacheReadTokens,
+        bo: usage.billableOutputTokens,
+        tt: usage.totalTokens,
+    };
+    if (usage.reportedCostUsd !== undefined)
+        record.rc = usage.reportedCostUsd;
+    return record;
+}
+/** Price a cached event with the current catalog (or its provider-reported cost). */
+function priceCachedEvent(cached, provider, sessionId, project) {
+    const usage = {
+        uncachedInputTokens: cached.i,
+        cacheReadTokens: cached.cr,
+        cacheWriteTokens: cached.cw,
+        outputTokens: cached.o,
+        reasoningTokens: 0,
+        reasoningIncludedInOutput: true,
+        cacheInclusiveInputTokens: cached.i + cached.cr + cached.cw,
+        billableOutputTokens: cached.bo,
+        totalTokens: cached.tt,
+        ...(cached.rc !== undefined ? { reportedCostUsd: cached.rc } : {}),
+        provenance: { semantics: 'sidekick-disjoint' },
+    };
+    const priced = (0, usageNormalization_1.calculateNormalizedUsageCost)({
+        usage,
+        modelId: cached.m === 'unknown' ? undefined : cached.m,
+    });
+    return {
+        timestamp: cached.t,
+        provider,
+        sessionId,
+        project,
+        model: cached.m,
+        tokens: {
+            inputTokens: cached.i,
+            outputTokens: cached.o,
+            cacheWriteTokens: cached.cw,
+            cacheReadTokens: cached.cr,
+            totalTokens: cached.tt,
+        },
+        costUsd: priced.costUsd,
+        costProvenance: priced.source,
+    };
+}
+function readSessionUsage(provider, preview) {
+    const reader = provider.createReader(preview.filePath);
+    const events = reader.readAll();
+    reader.flush();
+    const cached = [];
+    for (const event of events) {
+        const usage = (0, usageNormalization_1.extractNormalizedUsage)(event);
+        if (!usage)
+            continue;
+        const timestamp = Date.parse(event.timestamp);
+        if (!Number.isFinite(timestamp))
+            continue;
+        cached.push(cachedEventFromUsage(usage, timestamp, event.message?.model ?? usage.model ?? 'unknown'));
+    }
+    return cached;
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+/**
+ * Collect priced usage events for every session touched in the window.
+ *
+ * Sessions are enumerated with `listSessionPreviewsAsync` (the `since`
+ * cutoff applies to the session mtime there and to the event timestamp
+ * here), read once each unless the cache already holds their fingerprint,
+ * and yielded between reads so long-lived hosts stay responsive.
+ */
+async function collectUsageEvents(options) {
+    const sinceMs = toMs(options.since, 'since');
+    const untilMs = toMs(options.until, 'until');
+    const cacheDir = options.cacheDir ?? getUsageCacheDir();
+    const useCache = !options.noCache;
+    const listed = await (0, sessionPreviews_1.listSessionPreviewsAsync)(options.providers, {
+        since: options.since,
+        workspacePath: options.workspacePath,
+        limit: Number.MAX_SAFE_INTEGER,
+        concurrency: options.concurrency,
+    });
+    const diagnostics = [...listed.diagnostics];
+    for (const diagnostic of listed.diagnostics)
+        options.onDiagnostic?.(diagnostic);
+    const providerById = new Map(options.providers.map((provider) => [provider.id, provider]));
+    const events = [];
+    const sessions = [];
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    let wroteCache = false;
+    for (const preview of listed.previews) {
+        const provider = providerById.get(preview.provider);
+        if (!provider)
+            continue;
+        const fingerprint = `${preview.sizeBytes}:${preview.modifiedAt}`;
+        const filePath = cacheFilePath(cacheDir, preview.provider, preview.sessionId);
+        let cachedEvents = null;
+        let project = preview.workspacePath;
+        let fromCache = false;
+        if (useCache) {
+            const cached = readCache(filePath);
+            if (cached && cached.fingerprint === fingerprint && cached.sessionId === preview.sessionId) {
+                cachedEvents = cached.events;
+                project = project ?? cached.project;
+                fromCache = true;
+                cacheHits += 1;
+                touch(filePath);
+            }
+        }
+        if (!cachedEvents) {
+            cacheMisses += 1;
+            try {
+                cachedEvents = readSessionUsage(provider, preview);
+            }
+            catch (error) {
+                const diagnostic = {
+                    providerId: preview.provider,
+                    kind: 'read_failed',
+                    severity: 'warning',
+                    phase: 'read',
+                    message: `Could not read usage for ${preview.provider} session ${preview.sessionId}: ${error instanceof Error ? error.message : String(error)}`,
+                };
+                diagnostics.push(diagnostic);
+                options.onDiagnostic?.(diagnostic);
+                continue;
+            }
+            if (useCache) {
+                const record = {
+                    version: exports.USAGE_CACHE_VERSION,
+                    provider: preview.provider,
+                    sessionId: preview.sessionId,
+                    fingerprint,
+                    project,
+                    events: cachedEvents,
+                };
+                try {
+                    await (0, atomic_1.atomicWriteJson)(filePath, record);
+                    wroteCache = true;
+                }
+                catch {
+                    // The cache is an accelerator; a failed write only costs a re-read.
+                }
+            }
+            await yieldToEventLoop();
+        }
+        let first = null;
+        let last = null;
+        let count = 0;
+        for (const cached of cachedEvents) {
+            if (sinceMs !== null && cached.t < sinceMs)
+                continue;
+            if (untilMs !== null && cached.t > untilMs)
+                continue;
+            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project));
+            first = first === null ? cached.t : Math.min(first, cached.t);
+            last = last === null ? cached.t : Math.max(last, cached.t);
+            count += 1;
+        }
+        sessions.push({
+            provider: preview.provider,
+            sessionId: preview.sessionId,
+            filePath: preview.filePath,
+            project,
+            fingerprint,
+            firstTimestamp: first,
+            lastTimestamp: last,
+            eventCount: count,
+            fromCache,
+        });
+    }
+    if (wroteCache)
+        pruneUsageCache(exports.MAX_USAGE_CACHE_FILES, cacheDir);
+    events.sort((a, b) => a.timestamp - b.timestamp);
+    return { events, sessions, diagnostics, cacheHits, cacheMisses };
+}

package/dist/usage/usageReports.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Daily, weekly, monthly, and per-session usage rows bucketed from usage
+ * events by the time of each event, so a session that crosses midnight is
+ * split across the days it actually ran in. Browser-safe: no Node imports.
+ *
+ * @module usage/usageReports
+ */
+import type { AggregatedCostProvenance } from '../aggregation/types';
+import type { ProviderId } from '../providers/types';
+import type { TokenTotals } from '../types/historicalData';
+import type { UsageEventRecord } from './usageEvents';
+export type UsageGranularity = 'day' | 'week' | 'month' | 'session';
+/** Extra dimensions a bucket is split by, beyond the time key. */
+export type UsageGroupDimension = 'provider' | 'project' | 'model';
+export interface BucketUsageOptions {
+    granularity: UsageGranularity;
+    /** Key by the UTC calendar instead of the local calendar (default false). */
+    utc?: boolean;
+    /** First day of the week for `week` keys: 0 = Sunday, 1 = Monday (default). */
+    weekStartsOn?: 0 | 1;
+    /** Dimensions to group by in addition to the time key (default `['provider']`). */
+    groupBy?: readonly UsageGroupDimension[];
+}
+export interface UsageBucketRow {
+    /** `YYYY-MM-DD` for days and week starts, `YYYY-MM` for months, the session id for sessions. */
+    key: string;
+    granularity: UsageGranularity;
+    provider: ProviderId | null;
+    project: string | null;
+    /** Set when grouping by model; null for rows spanning every model. */
+    model: string | null;
+    /** Session id for `session` rows; null otherwise. */
+    sessionId: string | null;
+    /** Models seen in the row, most tokens first. */
+    models: string[];
+    calls: number;
+    /** Distinct sessions contributing to the row. */
+    sessions: number;
+    tokens: TokenTotals;
+    /** Provider-semantics-aware total (`summarizeTokens().total`). */
+    totalTokens: number;
+    /** Priced portion of the cost; read `costProvenance` before labelling it. */
+    costUsd: number;
+    costProvenance: AggregatedCostProvenance;
+    unpricedCalls: number;
+    /** First and last event in the row, ms since epoch. */
+    firstTimestamp: number;
+    lastTimestamp: number;
+}
+export interface UsageTotals {
+    calls: number;
+    sessions: number;
+    tokens: TokenTotals;
+    totalTokens: number;
+    costUsd: number;
+    costProvenance: AggregatedCostProvenance;
+    unpricedCalls: number;
+}
+/** The `YYYY-MM-DD` key of the week containing `ms`, starting on `weekStartsOn`. */
+export declare function weekKey(ms: number, options?: {
+    utc?: boolean;
+    weekStartsOn?: 0 | 1;
+}): string;
+/** The time key for one event at the requested granularity. */
+export declare function usageBucketKey(event: Pick<UsageEventRecord, 'timestamp' | 'sessionId'>, options: BucketUsageOptions): string;
+/**
+ * Group usage events into rows. Rows are sorted by key (sessions by first
+ * event), then provider, project, and model, so tables read oldest first.
+ */
+export declare function bucketUsage(events: readonly UsageEventRecord[], options: BucketUsageOptions): UsageBucketRow[];
+/**
+ * Sum rows that do not overlap (for example every row of one `bucketUsage`
+ * call). Pass the events too when rows are not per-session, so distinct
+ * sessions are counted once instead of once per row they appear in.
+ */
+export declare function summarizeUsageRows(rows: readonly UsageBucketRow[], events?: readonly UsageEventRecord[]): UsageTotals;