sidekick-shared 0.25.0 → 0.26.1

package/dist/statusline/formatter.d.ts

@@ -1,9 +1,15 @@
 import type { ActiveAccountStatus } from '../accountStatus';
 import type { QuotaState } from '../quota';
+import type { ClaudeStatuslinePayload } from './claudeStatuslinePayload';
 export interface StatuslineInput {
     accounts: ActiveAccountStatus;
     claudeQuota?: QuotaState | null;
     codexQuota?: QuotaState | null;
+    /**
+     * The document Claude Code piped to the status-line command, when running
+     * as one. Adds context usage, session cost, and prompt-cache hit rate.
+     */
+    live?: ClaudeStatuslinePayload | null;
     now?: Date;
 }
 export interface StatuslineSelection {
@@ -13,4 +19,11 @@ export interface StatuslineSelection {
     quota: QuotaState | null;
 }
 export declare function selectStatuslineAccount(input: StatuslineInput): StatuslineSelection | null;
+/**
+ * One-line status. Segments, in order, each omitted when unknown:
+ * `acct:<label> · 5h 42% resets 14:00 · ~1h20m left · 7d 61% · (2h ago) · ctx 37% · $0.42 · cache 92%`
+ *
+ * The age segment appears only for cached quota older than five minutes, so
+ * a snapshot from yesterday can no longer read like a live figure.
+ */
 export declare function formatStatusline(input: StatuslineInput): string;

package/dist/statusline/formatter.js

@@ -23,20 +23,62 @@ function selectStatuslineAccount(input) {
     }
     return null;
 }
+/**
+ * One-line status. Segments, in order, each omitted when unknown:
+ * `acct:<label> · 5h 42% resets 14:00 · ~1h20m left · 7d 61% · (2h ago) · ctx 37% · $0.42 · cache 92%`
+ *
+ * The age segment appears only for cached quota older than five minutes, so
+ * a snapshot from yesterday can no longer read like a live figure.
+ */
 function formatStatusline(input) {
     const selected = selectStatuslineAccount(input);
+    const now = input.now ?? new Date();
+    const liveSegments = formatLiveSegments(input.live);
     if (!selected)
-        return 'acct:none · quota unavailable';
+        return joinSegments(['acct:none', 'quota unavailable', ...liveSegments]);
     const account = compactLabel(selected.accountLabel);
     const quota = selected.quota;
-    if (!quota?.available)
-        return `acct:${account} · quota unavailable`;
-    const now = input.now ?? new Date();
+    if (!quota?.available) {
+        return joinSegments([`acct:${account}`, 'quota unavailable', ...liveSegments]);
+    }
     const utilization = clampPercent(quota.fiveHour.utilization);
     const reset = formatReset(quota.fiveHour.resetsAt, now);
     const eta = estimateWindowEta(quota, now);
-    const etaText = eta == null ? '' : ` · ~${formatMinutes(eta)} left`;
-    return `acct:${account} · 5h ${Math.round(utilization)}% resets ${reset}${etaText}`;
+    const segments = [`acct:${account}`, `5h ${Math.round(utilization)}% resets ${reset}`];
+    if (eta != null)
+        segments.push(`~${formatMinutes(eta)} left`);
+    if (quota.sevenDay.resetsAt && quota.sevenDay.utilization > 0) {
+        segments.push(`7d ${Math.round(clampPercent(quota.sevenDay.utilization))}%`);
+    }
+    if (quota.freshness && quota.freshness !== 'fresh') {
+        segments.push(`(${(0, quota_1.formatQuotaAge)(quota.ageMs)})`);
+    }
+    return joinSegments([...segments, ...liveSegments]);
+}
+function formatLiveSegments(live) {
+    if (!live)
+        return [];
+    const segments = [];
+    const context = live.contextWindow?.usedPercentage;
+    if (typeof context === 'number')
+        segments.push(`ctx ${Math.round(clampPercent(context))}%`);
+    const cost = live.cost?.totalCostUsd;
+    if (typeof cost === 'number' && cost > 0)
+        segments.push(`$${formatCost(cost)}`);
+    const hitRatio = live.promptCache?.hitRatio;
+    if (typeof hitRatio === 'number')
+        segments.push(`cache ${Math.round(clampPercent(hitRatio * 100))}%`);
+    return segments;
+}
+function joinSegments(segments) {
+    return segments.join(' · ');
+}
+function formatCost(value) {
+    if (value >= 100)
+        return value.toFixed(0);
+    if (value >= 10)
+        return value.toFixed(1);
+    return value.toFixed(2);
 }
 function estimateWindowEta(quota, now) {
     const resetAt = Date.parse(quota.fiveHour.resetsAt);

package/dist/statusline/index.d.ts

@@ -1,7 +1,15 @@
 export { getActiveAccountStatus } from '../accountStatus';
-export type { ActiveAccountStatus, ActiveProviderAccountStatus } from '../accountStatus';
-export { readQuotaSnapshot } from '../quotaSnapshots';
+export type { ActiveAccountStatus, ActiveAccountStatusOptions, ActiveProviderAccountStatus, } from '../accountStatus';
+export { readQuotaSnapshot, writeQuotaSnapshot } from '../quotaSnapshots';
 export type { QuotaSnapshotProviderId } from '../quotaSnapshots';
+export { appendQuotaHistorySample, getWorkspaceIdFromPath } from '../quotaHistory';
+export type { QuotaHistorySample } from '../quotaHistory';
+export { classifyQuotaFreshness, formatQuotaAge } from '../quota';
+export type { QuotaFreshness, QuotaState } from '../quota';
 export { BurnRateCalculator, estimateTimeToQuota } from './BurnRateCalculator';
 export { formatStatusline, selectStatuslineAccount } from './formatter';
 export type { StatuslineInput, StatuslineSelection } from './formatter';
+export { parseClaudeStatuslinePayload, quotaFromStatuslinePayload, } from './claudeStatuslinePayload';
+export type { ClaudeStatuslinePayload, ClaudeStatuslineRateLimitWindow, QuotaFromStatuslineOptions, } from './claudeStatuslinePayload';
+export { STATE_FILE_NAME, STATE_FILE_SCHEMA_VERSION, billingBlockToStateFile, getStateFilePath, quotaToStateFile, readStateFile, writeStateFile, } from '../stateFile';
+export type { SidekickStateFile, SidekickStateInput, StateFileAccount, StateFileBillingBlock, StateFileContext, StateFileQuota, StateFileQuotaWindow, StateFileSession, StateFileWriter, WriteStateFileOptions, } from '../stateFile';

package/dist/statusline/index.js

@@ -1,13 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.readQuotaSnapshot = exports.getActiveAccountStatus = void 0;
+exports.writeStateFile = exports.readStateFile = exports.quotaToStateFile = exports.getStateFilePath = exports.billingBlockToStateFile = exports.STATE_FILE_SCHEMA_VERSION = exports.STATE_FILE_NAME = exports.quotaFromStatuslinePayload = exports.parseClaudeStatuslinePayload = exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.formatQuotaAge = exports.classifyQuotaFreshness = exports.getWorkspaceIdFromPath = exports.appendQuotaHistorySample = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.getActiveAccountStatus = void 0;
 var accountStatus_1 = require("../accountStatus");
 Object.defineProperty(exports, "getActiveAccountStatus", { enumerable: true, get: function () { return accountStatus_1.getActiveAccountStatus; } });
 var quotaSnapshots_1 = require("../quotaSnapshots");
 Object.defineProperty(exports, "readQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.readQuotaSnapshot; } });
+Object.defineProperty(exports, "writeQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.writeQuotaSnapshot; } });
+var quotaHistory_1 = require("../quotaHistory");
+Object.defineProperty(exports, "appendQuotaHistorySample", { enumerable: true, get: function () { return quotaHistory_1.appendQuotaHistorySample; } });
+Object.defineProperty(exports, "getWorkspaceIdFromPath", { enumerable: true, get: function () { return quotaHistory_1.getWorkspaceIdFromPath; } });
+var quota_1 = require("../quota");
+Object.defineProperty(exports, "classifyQuotaFreshness", { enumerable: true, get: function () { return quota_1.classifyQuotaFreshness; } });
+Object.defineProperty(exports, "formatQuotaAge", { enumerable: true, get: function () { return quota_1.formatQuotaAge; } });
 var BurnRateCalculator_1 = require("./BurnRateCalculator");
 Object.defineProperty(exports, "BurnRateCalculator", { enumerable: true, get: function () { return BurnRateCalculator_1.BurnRateCalculator; } });
 Object.defineProperty(exports, "estimateTimeToQuota", { enumerable: true, get: function () { return BurnRateCalculator_1.estimateTimeToQuota; } });
 var formatter_1 = require("./formatter");
 Object.defineProperty(exports, "formatStatusline", { enumerable: true, get: function () { return formatter_1.formatStatusline; } });
 Object.defineProperty(exports, "selectStatuslineAccount", { enumerable: true, get: function () { return formatter_1.selectStatuslineAccount; } });
+var claudeStatuslinePayload_1 = require("./claudeStatuslinePayload");
+Object.defineProperty(exports, "parseClaudeStatuslinePayload", { enumerable: true, get: function () { return claudeStatuslinePayload_1.parseClaudeStatuslinePayload; } });
+Object.defineProperty(exports, "quotaFromStatuslinePayload", { enumerable: true, get: function () { return claudeStatuslinePayload_1.quotaFromStatuslinePayload; } });
+var stateFile_1 = require("../stateFile");
+Object.defineProperty(exports, "STATE_FILE_NAME", { enumerable: true, get: function () { return stateFile_1.STATE_FILE_NAME; } });
+Object.defineProperty(exports, "STATE_FILE_SCHEMA_VERSION", { enumerable: true, get: function () { return stateFile_1.STATE_FILE_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "billingBlockToStateFile", { enumerable: true, get: function () { return stateFile_1.billingBlockToStateFile; } });
+Object.defineProperty(exports, "getStateFilePath", { enumerable: true, get: function () { return stateFile_1.getStateFilePath; } });
+Object.defineProperty(exports, "quotaToStateFile", { enumerable: true, get: function () { return stateFile_1.quotaToStateFile; } });
+Object.defineProperty(exports, "readStateFile", { enumerable: true, get: function () { return stateFile_1.readStateFile; } });
+Object.defineProperty(exports, "writeStateFile", { enumerable: true, get: function () { return stateFile_1.writeStateFile; } });

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

@@ -69,6 +69,8 @@ export interface ProviderSessionAdapterV1 {
     dispose(): void;
 }
 export declare function derivePendingUserRequestV1(provider: ProviderId, sessionId: string, sourcePath: string, events: SessionEvent[]): PendingUserRequestV1 | null;
+/** 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;
     observationOnly?: boolean;

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;