sidekick-shared 0.25.0 → 0.26.0

package/dist/types/observedSessionV1.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.derivePendingUserRequestV1 = derivePendingUserRequestV1;
+exports.getObservedActivityReason = getObservedActivityReason;
 exports.createProviderSessionAdapterV1 = createProviderSessionAdapterV1;
 const transcript_1 = require("../transcript");
 const sessionActivityDetector_1 = require("../parsers/sessionActivityDetector");
+const sessionStats_1 = require("../sessionStats");
+const sessionFingerprint_1 = require("../sessionFingerprint");
 function evidence(provider, sessionId, sourcePath, event, eventIndex) {
     return [
         {
@@ -111,6 +114,16 @@ function providerCapabilities(provider, observationOnly) {
         assetExtraction: known(true),
     };
 }
+/**
+ * Detector reason behind each observed session's activity, kept off the
+ * versioned V1 shape so cache refreshes can tell a grace-period "active" from
+ * a genuinely ongoing one.
+ */
+const activityReasons = new WeakMap();
+/** The activity detector's reason for a session produced by this adapter, if known. */
+function getObservedActivityReason(session) {
+    return activityReasons.get(session);
+}
 function createProviderSessionAdapterV1(sessionProvider, options = {}) {
     const pollIntervalMs = options.pollIntervalMs ?? 2_000;
     const adapter = {
@@ -121,16 +134,28 @@ function createProviderSessionAdapterV1(sessionProvider, options = {}) {
             return Promise.all(sessionProvider.findAllSessions(cwd).map((sessionPath) => adapter.read(sessionPath, cwd)));
         },
         async read(sessionPath, cwd = '') {
-            const stats = sessionProvider.readSessionStats(sessionPath);
-            const events = sessionProvider.createReader(sessionPath).readAll();
+            // One reader pass feeds stats, transcript, activity, and the pending
+            // request; the reader is flushed so a trailing partial line is included.
+            const sessionId = sessionProvider.getSessionId(sessionPath);
+            const reader = sessionProvider.createReader(sessionPath);
+            const events = reader.readAll();
+            reader.flush();
+            const stats = (0, sessionStats_1.computeSessionFileStats)(events, {
+                providerId: sessionProvider.id,
+                sessionId,
+                filePath: sessionPath,
+                label: '',
+                computeContextSize: (0, sessionStats_1.providerContextSizeFn)(sessionProvider),
+            });
             const transcript = (0, transcript_1.projectSessionTranscript)(events, {
                 provider: sessionProvider.id,
-                sessionId: stats.sessionId,
+                sessionId,
                 sourcePath: sessionPath,
             });
-            const refs = evidence(sessionProvider.id, stats.sessionId, sessionPath);
+            const refs = evidence(sessionProvider.id, sessionId, sessionPath);
             const model = Object.entries(stats.modelUsage).sort((left, right) => right[1].calls - left[1].calls)[0]?.[0] ?? null;
-            const activityResult = (0, sessionActivityDetector_1.detectSessionActivity)(sessionPath);
+            const parts = (0, sessionFingerprint_1.sessionFingerprintParts)(sessionProvider, sessionPath);
+            const activityResult = (0, sessionActivityDetector_1.classifySessionActivity)({ events, mtimeMs: parts?.mtimeMs ?? null });
             const activity = activityResult.state === 'ongoing'
                 ? 'active'
                 : activityResult.state === 'stale'
@@ -139,11 +164,11 @@ function createProviderSessionAdapterV1(sessionProvider, options = {}) {
             const allCostsReported = transcript.usage.costs.length > 0 &&
                 transcript.usage.costs.every((cost) => cost.source === 'provider-reported');
             const observedAt = new Date().toISOString();
-            return {
+            const session = {
                 schemaVersion: 1,
                 identity: {
                     provider: sessionProvider.id,
-                    sessionId: stats.sessionId,
+                    sessionId,
                     sourcePath: sessionPath,
                 },
                 cwd: observed(cwd, 'inferred', cwd ? 0.95 : 0.4, refs),
@@ -161,29 +186,61 @@ function createProviderSessionAdapterV1(sessionProvider, options = {}) {
                             ? 'inferred'
                             : 'estimated', allCostsReported ? 1 : transcript.usage.totalCostUsd === null ? 0.5 : 0.9, refs),
                 },
-                pendingUserRequest: derivePendingUserRequestV1(sessionProvider.id, stats.sessionId, sessionPath, events),
+                pendingUserRequest: derivePendingUserRequestV1(sessionProvider.id, sessionId, sessionPath, events),
                 contentObservedAt: observedAt,
                 observedAt,
             };
+            activityReasons.set(session, activityResult.reason);
+            return session;
         },
         watch(sessionPath, listener, cwd) {
             let disposed = false;
             let lastSignature = '';
+            let lastFingerprint = null;
+            let lastSession = null;
+            const emitIfChanged = (session) => {
+                const signature = JSON.stringify({
+                    activity: session.activity,
+                    model: session.model,
+                    usage: session.usage,
+                    pendingUserRequest: session.pendingUserRequest,
+                });
+                if (signature !== lastSignature) {
+                    lastSignature = signature;
+                    listener(session);
+                }
+            };
             const update = async () => {
                 if (disposed)
                     return;
                 try {
-                    const session = await adapter.read(sessionPath, cwd);
-                    const signature = JSON.stringify({
-                        activity: session.activity,
-                        model: session.model,
-                        usage: session.usage,
-                        pendingUserRequest: session.pendingUserRequest,
-                    });
-                    if (signature !== lastSignature) {
-                        lastSignature = signature;
-                        listener(session);
+                    const parts = (0, sessionFingerprint_1.sessionFingerprintParts)(sessionProvider, sessionPath);
+                    const fingerprint = parts ? (0, sessionFingerprint_1.fingerprintString)(parts) : null;
+                    if (lastSession && parts && fingerprint === lastFingerprint) {
+                        // Unchanged content: only the activity can drift with time, so
+                        // refresh it from the cached classification instead of re-reading.
+                        const previousReason = activityReasons.get(lastSession);
+                        const refreshed = (0, sessionActivityDetector_1.refreshSessionActivityState)(lastSession.activity.value, parts.mtimeMs, Date.now(), previousReason);
+                        if (refreshed !== lastSession.activity.value) {
+                            const session = {
+                                ...lastSession,
+                                activity: { ...lastSession.activity, value: refreshed },
+                                observedAt: new Date().toISOString(),
+                            };
+                            activityReasons.set(session, refreshed === 'idle'
+                                ? 'mtime-stale'
+                                : previousReason === 'grace-period'
+                                    ? 'ending-event'
+                                    : 'no-activity-signal');
+                            lastSession = session;
+                            emitIfChanged(session);
+                        }
+                        return;
                     }
+                    const session = await adapter.read(sessionPath, cwd);
+                    lastFingerprint = fingerprint;
+                    lastSession = session;
+                    emitIfChanged(session);
                 }
                 catch {
                     // Observed sources can disappear between polling iterations.

package/dist/types/sessionEvent.d.ts

@@ -47,6 +47,8 @@ export interface SessionMessage {
     normalizedUsage?: import('../usageNormalization').NormalizedUsage;
     /** Message content (may be string or structured content) */
     content?: unknown;
+    /** Provider stop reason (`end_turn`, `tool_use`, …) when the transcript carries one. */
+    stop_reason?: string;
 }
 /**
  * Canonical session event from JSONL/DB log files.

package/dist/usage/billingBlocks.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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
+ */
+import type { AggregatedCostProvenance } from '../aggregation/types';
+import type { TokenTotalsLike } from '../tokenSummary';
+import type { PricingProvenance } from '../usageNormalization';
+/** Length of one billing block. */
+export declare const BILLING_BLOCK_DURATION_MS: number;
+/** Minimal usage event the block calculator needs. */
+export interface BillingBlockInput {
+    /** Event time (ms since epoch, ISO string, or Date). */
+    timestamp: number | string | Date;
+    tokens: TokenTotalsLike;
+    /** Priced cost for the event, or null when it could not be priced. */
+    costUsd: number | null;
+    costProvenance?: PricingProvenance;
+    model?: string;
+}
+export interface BillingBlockTokens {
+    inputTokens: number;
+    outputTokens: number;
+    cacheWriteTokens: number;
+    cacheReadTokens: number;
+    /** Cache-inclusive total (`summarizeTokens().total`). */
+    total: number;
+}
+export interface BillingBlockModelUsage {
+    calls: number;
+    /** Cache-inclusive tokens. */
+    tokens: number;
+    costUsd: number;
+}
+export interface BillingBlock {
+    /** Block identifier: the ISO start time. */
+    id: string;
+    /** ISO start (aligned to the hour when `alignToHour` is set). */
+    start: string;
+    /** ISO end (`start` + block duration). */
+    end: string;
+    firstEvent: string;
+    lastEvent: string;
+    /** `now` is inside the block and within one block length of the last event. */
+    isActive: boolean;
+    calls: number;
+    tokens: BillingBlockTokens;
+    costUsd: number;
+    costProvenance: AggregatedCostProvenance;
+    unpricedCalls: number;
+    models: Record<string, BillingBlockModelUsage>;
+    /** Time from the first event to `now` (active) or to the last event (closed). */
+    elapsedMs: number;
+    /** Time left until `end` for the active block; 0 otherwise. */
+    remainingMs: number;
+    /** Tokens per minute over `elapsedMs`. */
+    burnRatePerMinute: number;
+    /** Tokens expected by `end` at the current burn rate (equals `tokens.total` for closed blocks). */
+    projectedTokens: number;
+    /** Cost expected by `end` at the current cost per token (equals `costUsd` for closed blocks). */
+    projectedCostUsd: number;
+}
+export interface ComputeBillingBlocksOptions {
+    /** Clock used for activity and projections (default `Date.now()`). */
+    now?: Date | number;
+    /** Block length (default five hours). */
+    blockDurationMs?: number;
+    /** Align each block's start down to the UTC hour (default true, as ccusage does). */
+    alignToHour?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function computeBillingBlocks(events: readonly BillingBlockInput[], options?: ComputeBillingBlocksOptions): BillingBlock[];
+/** The block that is still open at the calculator's `now`, if any. */
+export declare function findActiveBillingBlock(blocks: readonly BillingBlock[]): BillingBlock | null;

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