sidekick-shared 0.24.5 → 0.26.0

package/dist/tokenSummary.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One vocabulary for token totals across every Sidekick surface.
+ *
+ * Every report, dashboard, status bar, and export derives its headline token
+ * numbers from here so "Total" means the same thing everywhere:
+ *
+ * - `total`   — every token the provider billed: uncached input, cache writes,
+ *               cache reads, and output. Matches `NormalizedUsage.totalTokens`
+ *               and the per-model `tokens` the `EventAggregator` keeps.
+ * - `context` — tokens that occupied the context window on the last request:
+ *               uncached input, cache writes, and cache reads. Output is
+ *               excluded, matching the input-only formula Claude Code uses for
+ *               its status-line `used_percentage`.
+ * - `output`  — output tokens as billed.
+ *
+ * Cache reads are usually the majority of a coding-agent session's tokens, so
+ * an "input + output" total silently drops most of the work. Sidekick used to
+ * do that on some surfaces and not others; this helper is the single place the
+ * arithmetic lives.
+ *
+ * Browser-safe: no Node imports.
+ *
+ * @module tokenSummary
+ */
+/** Any object carrying the four billable token buckets. */
+export interface TokenTotalsLike {
+    inputTokens: number;
+    outputTokens: number;
+    cacheWriteTokens?: number;
+    cacheReadTokens?: number;
+    /**
+     * A provider-semantics-aware total, when the source already computed one
+     * (for example `AggregatedTokens.totalTokens`). Preferred over the
+     * four-bucket sum because it already accounts for whether reasoning tokens
+     * were billed inside or outside `outputTokens`.
+     */
+    totalTokens?: number;
+}
+export interface TokenSummary {
+    /** Everything billed: uncached input + cache writes + cache reads + output. */
+    total: number;
+    /** Tokens occupying the context window: uncached input + cache writes + cache reads. */
+    context: number;
+    /** Uncached input tokens. */
+    input: number;
+    /** Output tokens as billed. */
+    output: number;
+    /** Tokens read from the prompt cache. */
+    cacheRead: number;
+    /** Tokens written to the prompt cache. */
+    cacheWrite: number;
+    /** Fraction of context tokens that came from cache reads (0..1), or null with no input. */
+    cacheHitRatio: number | null;
+}
+/** Column label for `TokenSummary.total` on any surface. */
+export declare const TOKEN_TOTAL_LABEL = "Total (incl. cache)";
+/** Column label for `TokenSummary.context` on any surface. */
+export declare const TOKEN_CONTEXT_LABEL = "Context";
+/** Derive the shared token vocabulary from any four-bucket token record. */
+export declare function summarizeTokens(totals: TokenTotalsLike): TokenSummary;
+/** Sum several token records bucket-by-bucket before summarizing. */
+export declare function sumTokenTotals(records: readonly TokenTotalsLike[]): TokenTotalsLike;

package/dist/tokenSummary.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * One vocabulary for token totals across every Sidekick surface.
+ *
+ * Every report, dashboard, status bar, and export derives its headline token
+ * numbers from here so "Total" means the same thing everywhere:
+ *
+ * - `total`   — every token the provider billed: uncached input, cache writes,
+ *               cache reads, and output. Matches `NormalizedUsage.totalTokens`
+ *               and the per-model `tokens` the `EventAggregator` keeps.
+ * - `context` — tokens that occupied the context window on the last request:
+ *               uncached input, cache writes, and cache reads. Output is
+ *               excluded, matching the input-only formula Claude Code uses for
+ *               its status-line `used_percentage`.
+ * - `output`  — output tokens as billed.
+ *
+ * Cache reads are usually the majority of a coding-agent session's tokens, so
+ * an "input + output" total silently drops most of the work. Sidekick used to
+ * do that on some surfaces and not others; this helper is the single place the
+ * arithmetic lives.
+ *
+ * Browser-safe: no Node imports.
+ *
+ * @module tokenSummary
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_CONTEXT_LABEL = exports.TOKEN_TOTAL_LABEL = void 0;
+exports.summarizeTokens = summarizeTokens;
+exports.sumTokenTotals = sumTokenTotals;
+/** Column label for `TokenSummary.total` on any surface. */
+exports.TOKEN_TOTAL_LABEL = 'Total (incl. cache)';
+/** Column label for `TokenSummary.context` on any surface. */
+exports.TOKEN_CONTEXT_LABEL = 'Context';
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/** Derive the shared token vocabulary from any four-bucket token record. */
+function summarizeTokens(totals) {
+    const input = count(totals.inputTokens);
+    const output = count(totals.outputTokens);
+    const cacheRead = count(totals.cacheReadTokens);
+    const cacheWrite = count(totals.cacheWriteTokens);
+    const context = input + cacheWrite + cacheRead;
+    const fourBucket = context + output;
+    const provided = totals.totalTokens;
+    const total = typeof provided === 'number' && Number.isFinite(provided) && provided >= 0
+        ? Math.floor(provided)
+        : fourBucket;
+    return {
+        total,
+        context,
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        cacheHitRatio: context > 0 ? cacheRead / context : null,
+    };
+}
+/** Sum several token records bucket-by-bucket before summarizing. */
+function sumTokenTotals(records) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheWriteTokens = 0;
+    let cacheReadTokens = 0;
+    for (const record of records) {
+        inputTokens += count(record.inputTokens);
+        outputTokens += count(record.outputTokens);
+        cacheWriteTokens += count(record.cacheWriteTokens);
+        cacheReadTokens += count(record.cacheReadTokens);
+    }
+    return { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens };
+}

package/dist/transcript.d.ts

@@ -77,7 +77,12 @@ export interface CanonicalSessionTranscript {
         events: NormalizedUsage[];
         costs: NormalizedUsageCost[];
         totals: CanonicalTranscriptUsageTotals;
+        /** Strict total: `null` unless every usage event could be priced. */
         totalCostUsd: number | null;
+        /** Sum of the events that could be priced; pair with `unpricedEvents`. */
+        pricedCostUsd: number;
+        /** Usage events with neither a reported cost nor a catalog price. */
+        unpricedEvents: number;
     };
     provenance: {
         source: 'session-events';

package/dist/transcript.js

@@ -144,6 +144,8 @@ function projectSessionTranscript(events, options = {}) {
             totalCostUsd: usageCosts.length > 0 && usageCosts.every((cost) => cost.costUsd !== null)
                 ? usageCosts.reduce((sum, cost) => sum + (cost.costUsd ?? 0), 0)
                 : null,
+            pricedCostUsd: usageCosts.reduce((sum, cost) => sum + (cost.costUsd ?? 0), 0),
+            unpricedEvents: usageCosts.filter((cost) => cost.costUsd === null).length,
         },
         provenance: { source: 'session-events', fidelity, eventCount: events.length },
     };

package/dist/types/observedSessionV1.d.ts

@@ -45,6 +45,8 @@ export interface ObservedAgentSessionV1 {
         costUsd: ObservedValueV1<number | null>;
     };
     pendingUserRequest: PendingUserRequestV1 | null;
+    /** When model/usage content was last read; unchanged on collector cache hits. */
+    contentObservedAt?: string;
     observedAt: string;
 }
 export interface ProviderCapabilitiesV1 {
@@ -67,6 +69,10 @@ export interface ProviderSessionAdapterV1 {
     dispose(): void;
 }
 export declare function derivePendingUserRequestV1(provider: ProviderId, sessionId: string, sourcePath: string, events: SessionEvent[]): PendingUserRequestV1 | null;
-export declare function createProviderSessionAdapterV1(sessionProvider: SessionProviderBase, options?: {
+/** The activity detector's reason for a session produced by this adapter, if known. */
+export declare function getObservedActivityReason(session: ObservedAgentSessionV1): string | undefined;
+export interface ProviderSessionAdapterV1Options {
     pollIntervalMs?: number;
-}): ProviderSessionAdapterV1;
+    observationOnly?: boolean;
+}
+export declare function createProviderSessionAdapterV1(sessionProvider: SessionProviderBase, options?: ProviderSessionAdapterV1Options): ProviderSessionAdapterV1;

package/dist/types/observedSessionV1.js

@@ -1,8 +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 [
         {
@@ -98,52 +102,78 @@ function waitingToolPrompt(input, toolName) {
         return 'Approve the proposed plan?';
     return null;
 }
-function providerCapabilities(provider) {
+function providerCapabilities(provider, observationOnly) {
     const refs = [];
     const known = (value) => observed(value, 'inferred', 1, refs);
     return {
         schemaVersion: 1,
         provider,
-        resume: known(true),
+        resume: known(!observationOnly),
         forkLineage: known(provider !== 'opencode'),
         quotaSource: known(provider === 'claude-code' ? 'api' : provider === 'codex' ? 'mixed' : 'none'),
         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 = {
         schemaVersion: 1,
         provider: sessionProvider.id,
-        capabilities: providerCapabilities(sessionProvider.id),
+        capabilities: providerCapabilities(sessionProvider.id, options.observationOnly === true),
         async discover(cwd) {
             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 metadata = sessionProvider.getSessionMetadata?.(sessionPath);
-            const modifiedAt = metadata?.mtime.getTime() ?? Date.parse(stats.endTime);
-            const recent = Number.isFinite(modifiedAt) && Date.now() - modifiedAt < 2 * 60_000;
+            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'
+                    ? 'idle'
+                    : 'ended';
             const allCostsReported = transcript.usage.costs.length > 0 &&
                 transcript.usage.costs.every((cost) => cost.source === 'provider-reported');
-            return {
+            const observedAt = new Date().toISOString();
+            const session = {
                 schemaVersion: 1,
                 identity: {
                     provider: sessionProvider.id,
-                    sessionId: stats.sessionId,
+                    sessionId,
                     sourcePath: sessionPath,
                 },
                 cwd: observed(cwd, 'inferred', cwd ? 0.95 : 0.4, refs),
                 model: observed(model, model ? 'reported' : 'inferred', model ? 1 : 0.2, refs),
-                activity: observed(recent ? 'active' : 'idle', 'inferred', 0.8, refs),
+                activity: observed(activity, 'inferred', 0.85, refs),
                 usage: {
                     inputTokens: observed(stats.tokens.input, 'reported', 1, refs),
                     outputTokens: observed(stats.tokens.output, 'reported', 1, refs),
@@ -156,28 +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),
-                observedAt: new Date().toISOString(),
+                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>;