sidekick-shared 0.25.0 → 0.26.1

package/dist/usage/billingBlocks.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Five-hour billing blocks computed from usage events.
+ *
+ * Mirrors the ccusage convention: a block opens at the first usage event
+ * (aligned down to the UTC hour), lasts five hours, and an event that lands
+ * after the block's end or more than five hours after the previous event opens
+ * a new block. The active block also reports a burn rate and an end-of-block
+ * projection. Browser-safe: no Node imports.
+ *
+ * @module usage/billingBlocks
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BILLING_BLOCK_DURATION_MS = void 0;
+exports.computeBillingBlocks = computeBillingBlocks;
+exports.findActiveBillingBlock = findActiveBillingBlock;
+const costProvenance_1 = require("../aggregation/costProvenance");
+const BurnRateCalculator_1 = require("../statusline/BurnRateCalculator");
+const tokenSummary_1 = require("../tokenSummary");
+/** Length of one billing block. */
+exports.BILLING_BLOCK_DURATION_MS = 5 * 3_600_000;
+function toMs(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === 'number')
+        return value;
+    return Date.parse(value);
+}
+function normalizeInput(event) {
+    const timestamp = toMs(event.timestamp);
+    if (!Number.isFinite(timestamp))
+        return null;
+    const costUsd = typeof event.costUsd === 'number' && Number.isFinite(event.costUsd) ? event.costUsd : null;
+    return {
+        timestamp,
+        tokens: event.tokens,
+        costUsd,
+        costProvenance: costUsd === null ? 'unpriced' : (event.costProvenance ?? 'model-catalog'),
+        model: event.model ?? 'unknown',
+    };
+}
+function floorToUtcHour(ms) {
+    return ms - (ms % 3_600_000);
+}
+function buildBlock(events, start, durationMs, nowMs) {
+    const end = start + durationMs;
+    const first = events[0].timestamp;
+    const last = events[events.length - 1].timestamp;
+    const isActive = nowMs >= start && nowMs < end && nowMs - last < durationMs;
+    const tokens = { inputTokens: 0, outputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0 };
+    let total = 0;
+    let costUsd = 0;
+    let reportedCalls = 0;
+    let estimatedCalls = 0;
+    let unpricedCalls = 0;
+    const models = {};
+    const burn = new BurnRateCalculator_1.BurnRateCalculator(durationMs / 60_000);
+    for (const event of events) {
+        const summary = (0, tokenSummary_1.summarizeTokens)(event.tokens);
+        tokens.inputTokens += summary.input;
+        tokens.outputTokens += summary.output;
+        tokens.cacheWriteTokens += summary.cacheWrite;
+        tokens.cacheReadTokens += summary.cacheRead;
+        total += summary.total;
+        burn.addEvent(summary.total, new Date(event.timestamp));
+        const model = models[event.model] ?? { calls: 0, tokens: 0, costUsd: 0 };
+        model.calls += 1;
+        model.tokens += summary.total;
+        if (event.costUsd !== null) {
+            costUsd += event.costUsd;
+            model.costUsd += event.costUsd;
+            if (event.costProvenance === 'provider-reported')
+                reportedCalls += 1;
+            else
+                estimatedCalls += 1;
+        }
+        else {
+            unpricedCalls += 1;
+        }
+        models[event.model] = model;
+    }
+    const rateAt = isActive ? nowMs : last;
+    const elapsedMs = Math.max(0, rateAt - first);
+    const burnRatePerMinute = burn.calculateBurnRate(new Date(rateAt));
+    const remainingMs = isActive ? Math.max(0, end - nowMs) : 0;
+    const projectedTokens = isActive
+        ? Math.round(total + burnRatePerMinute * (remainingMs / 60_000))
+        : total;
+    const costPerToken = total > 0 ? costUsd / total : 0;
+    const projectedCostUsd = isActive ? costUsd + costPerToken * (projectedTokens - total) : costUsd;
+    const startIso = new Date(start).toISOString();
+    return {
+        id: startIso,
+        start: startIso,
+        end: new Date(end).toISOString(),
+        firstEvent: new Date(first).toISOString(),
+        lastEvent: new Date(last).toISOString(),
+        isActive,
+        calls: events.length,
+        tokens: { ...tokens, total },
+        costUsd,
+        costProvenance: (0, costProvenance_1.classifyCostProvenance)({ reportedCalls, estimatedCalls, unpricedCalls }),
+        unpricedCalls,
+        models,
+        elapsedMs,
+        remainingMs,
+        burnRatePerMinute,
+        projectedTokens,
+        projectedCostUsd,
+    };
+}
+/**
+ * Group usage events into billing blocks, oldest first.
+ *
+ * Events with an unparseable timestamp are ignored. Events are sorted before
+ * grouping, so callers may pass them in any order.
+ */
+function computeBillingBlocks(events, options = {}) {
+    const durationMs = options.blockDurationMs ?? exports.BILLING_BLOCK_DURATION_MS;
+    const alignToHour = options.alignToHour ?? true;
+    const nowMs = options.now === undefined ? Date.now() : toMs(options.now);
+    const sorted = events
+        .map(normalizeInput)
+        .filter((event) => event !== null)
+        .sort((a, b) => a.timestamp - b.timestamp);
+    const blocks = [];
+    let current = [];
+    let currentStart = 0;
+    for (const event of sorted) {
+        const previous = current[current.length - 1];
+        const opensNewBlock = !previous ||
+            event.timestamp >= currentStart + durationMs ||
+            event.timestamp - previous.timestamp > durationMs;
+        if (opensNewBlock) {
+            if (current.length > 0)
+                blocks.push(buildBlock(current, currentStart, durationMs, nowMs));
+            current = [];
+            currentStart = alignToHour ? floorToUtcHour(event.timestamp) : event.timestamp;
+        }
+        current.push(event);
+    }
+    if (current.length > 0)
+        blocks.push(buildBlock(current, currentStart, durationMs, nowMs));
+    return blocks;
+}
+/** The block that is still open at the calculator's `now`, if any. */
+function findActiveBillingBlock(blocks) {
+    for (let index = blocks.length - 1; index >= 0; index -= 1) {
+        if (blocks[index].isActive)
+            return blocks[index];
+    }
+    return null;
+}

package/dist/usage/importSessionHistory.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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
+ */
+import type { SessionProviderBase, SessionProviderDiagnostic } from '../providers/types';
+import type { SessionSummary } from '../types/historicalData';
+/** Files modified more recently than this are skipped: they may still be live. */
+export declare const ACTIVE_SESSION_MTIME_THRESHOLD_MS = 60000;
+export interface ImportSessionHistoryOptions {
+    providers: SessionProviderBase[];
+    /** Only sessions modified after this instant. */
+    since?: Date | string;
+    /** Restrict to one workspace's sessions. */
+    workspacePath?: string;
+    /** Clock used for the active-file check (default `new Date()`). */
+    now?: Date;
+    /** Override of {@link ACTIVE_SESSION_MTIME_THRESHOLD_MS}. */
+    activeFileThresholdMs?: number;
+    /** Already imported? Checked before the session is read. */
+    isImported: (sessionId: string, filePath: string) => boolean;
+    /** Apply one credited session to the store. */
+    applySummary: (summary: SessionSummary, filePath: string) => void;
+    /** Record a file as imported (called after `applySummary`, and alone for usage-free files). */
+    markImported: (filePath: string) => void;
+    onProgress?: (loaded: number, total: number) => void;
+}
+export interface ImportSessionHistoryResult {
+    /** Session files the providers listed in the window. */
+    filesFound: number;
+    /** Files read and applied. */
+    filesProcessed: number;
+    /** Files skipped because they were already imported or still live. */
+    filesSkipped: number;
+    /** Files that could not be read (`availability: 'unavailable'`) or held no usage. */
+    filesUnavailable: number;
+    sessionsImported: number;
+    /** Messages across the imported sessions. */
+    messagesImported: number;
+    diagnostics: SessionProviderDiagnostic[];
+}
+export declare function importSessionHistory(options: ImportSessionHistoryOptions): Promise<ImportSessionHistoryResult>;

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>;