@leo000001/opencode-quota-sidebar 2.0.0 → 2.0.1

package/dist/storage_chunks.js

@@ -45,14 +45,17 @@ class ChunkCache {
     constructor(maxSize = 64) {
         this.maxSize = maxSize;
     }
-    get(dateKey) {
-        const entry = this.cache.get(dateKey);
+    key(rootPath, dateKey) {
+        return `${path.resolve(rootPath)}::${dateKey}`;
+    }
+    get(rootPath, dateKey) {
+        const entry = this.cache.get(this.key(rootPath, dateKey));
         if (!entry)
             return undefined;
         entry.accessedAt = Date.now();
         return entry.sessions;
     }
-    set(dateKey, sessions) {
+    set(rootPath, dateKey, sessions) {
         if (this.cache.size >= this.maxSize) {
             // Evict least recently accessed
             let oldestKey;
@@ -66,17 +69,20 @@ class ChunkCache {
             if (oldestKey)
                 this.cache.delete(oldestKey);
         }
-        this.cache.set(dateKey, { sessions, accessedAt: Date.now() });
+        this.cache.set(this.key(rootPath, dateKey), {
+            sessions,
+            accessedAt: Date.now(),
+        });
     }
-    invalidate(dateKey) {
-        this.cache.delete(dateKey);
+    invalidate(rootPath, dateKey) {
+        this.cache.delete(this.key(rootPath, dateKey));
     }
 }
 const chunkCache = new ChunkCache();
 export async function readDayChunk(rootPath, dateKey) {
     if (!isDateKey(dateKey))
         return {};
-    const cached = chunkCache.get(dateKey);
+    const cached = chunkCache.get(rootPath, dateKey);
     if (cached)
         return cached;
     const filePath = chunkFilePath(rootPath, dateKey);
@@ -101,7 +107,7 @@ export async function readDayChunk(rootPath, dateKey) {
         acc[sessionID] = parsedSession;
         return acc;
     }, {});
-    chunkCache.set(dateKey, sessions);
+    chunkCache.set(rootPath, dateKey, sessions);
     return sessions;
 }
 /**
@@ -174,13 +180,18 @@ export async function writeDayChunk(rootPath, dateKey, sessions) {
         throw new Error(`unsafe chunk root at ${rootPath}`);
     }
     await mkdirpNoSymlink(rootPath, path.dirname(filePath));
+    if (Object.keys(sessions).length === 0) {
+        await fs.rm(filePath, { force: true }).catch(() => undefined);
+        chunkCache.invalidate(rootPath, dateKey);
+        return;
+    }
     const chunk = {
         version: 1,
         dateKey,
         sessions,
     };
     await safeWriteFile(filePath, `${JSON.stringify(chunk, null, 2)}\n`);
-    chunkCache.invalidate(dateKey);
+    chunkCache.invalidate(rootPath, dateKey);
 }
 export async function discoverChunks(rootPath) {
     const years = await fs.readdir(rootPath).catch(() => []);

package/dist/storage_parse.js

@@ -1,4 +1,5 @@
 import { asNumber, isRecord } from './helpers.js';
+import { normalizeTimestampMs } from './storage_dates.js';
 function parseSessionTitleState(value) {
     if (!isRecord(value))
         return undefined;
@@ -107,7 +108,7 @@ export function parseSessionState(value) {
     const title = parseSessionTitleState(value);
     if (!title)
         return undefined;
-    const createdAt = asNumber(value.createdAt, 0);
+    const createdAt = normalizeTimestampMs(value.createdAt, 0);
     if (!createdAt)
         return undefined;
     return {
@@ -115,6 +116,7 @@ export function parseSessionState(value) {
         createdAt,
         parentID: typeof value.parentID === 'string' ? value.parentID : undefined,
         usage: parseCachedUsage(value.usage),
+        dirty: value.dirty === true,
         cursor: parseCursor(value.cursor),
     };
 }

package/dist/title.js

@@ -3,16 +3,15 @@ function sanitizeTitleFragment(value) {
         .replace(/[\x00-\x1F\x7F-\x9F]/g, ' ')
         .trimEnd();
 }
-function isStrongDecoratedDetail(line) {
+function isCoreDecoratedDetail(line) {
     if (!line)
         return false;
-    if (/^Input\s+\S+\s+Output(?:\s+\S+)?/.test(line))
+    if (/^Input\s+\$?[\d.,]+[kKmM]?(?:\s+Output(?:\s+\$?[\d.,]+[kKmM]?)?)?~?$/.test(line)) {
         return true;
-    if (/^Cache\s+(Read|Write)\s+\S+/.test(line))
-        return true;
-    if (/^Cache(?:\s+Read)?\s+Coverage\s+\S+/.test(line))
+    }
+    if (/^Cache\s+(Read|Write)\s+\$?\d[\d.,]*[kKmM]?$/.test(line))
         return true;
-    if (/^\$\S+\s+as API cost\b/.test(line))
+    if (/^\$\S+\s+as API cost$/.test(line))
         return true;
     // Single-line compact mode compatibility.
     if (/^I(?:nput)?\s+\$?\d[\d.,]*[kKmM]?\s+O(?:utput)?\s+\$?\d[\d.,]*[kKmM]?$/.test(line))
@@ -23,12 +22,26 @@ function isStrongDecoratedDetail(line) {
         return true;
     return false;
 }
-function isQuotaLikeProviderDetail(line) {
+function isSingleLineDecoratedPrefix(line) {
     if (!line)
         return false;
-    if (!/^(OpenAI|Copilot|Anthropic|RightCode|RC)\b/.test(line))
-        return false;
-    return /\b(Rst|Exp\+?|Balance|Remaining)\b|\d{1,3}%/.test(line);
+    if (/^Input\s+\$?[\d.,]+[kKmM]?~?$/.test(line))
+        return true;
+    if (/^Input\s+\$?[\d.,]+[kKmM]?\s+Output(?:\s+\$?[\d.,]+[kKmM]?~?)?$/.test(line)) {
+        return true;
+    }
+    if (/^Cache\s+(Read|Write)\s+\$?\d[\d.,]*[kKmM]?(?:~|$)/.test(line)) {
+        return true;
+    }
+    if (/^Cache(?:\s+Read)?\s+Coverage\s+\d[\d.,]*(?:%|~)$/.test(line)) {
+        return true;
+    }
+    if (/^\$\S+\s+as API cost(?:~|$)/.test(line))
+        return true;
+    return false;
+}
+function isSingleLineDetailPrefix(line) {
+    return isCoreDecoratedDetail(line) || isSingleLineDecoratedPrefix(line);
 }
 function decoratedSingleLineBase(line) {
     const parts = sanitizeTitleFragment(line)
@@ -36,18 +49,28 @@ function decoratedSingleLineBase(line) {
         .map((part) => part.trim());
     if (parts.length < 2)
         return undefined;
+    if (isSingleLineDetailPrefix(parts[0] || ''))
+        return undefined;
     const details = parts.slice(1);
-    if (!details.some((detail) => isStrongDecoratedDetail(detail))) {
+    if (!details.some((detail) => isSingleLineDetailPrefix(detail))) {
         return undefined;
     }
     return parts[0] || 'Session';
 }
 export function normalizeBaseTitle(title) {
-    const firstLine = stripAnsi(title).split(/\r?\n/, 1)[0] || 'Session';
+    const safeTitle = canonicalizeTitle(title) || 'Session';
+    const firstLine = stripAnsi(safeTitle).split(/\r?\n/, 1)[0] || 'Session';
     const decoratedBase = decoratedSingleLineBase(firstLine);
     if (decoratedBase)
         return decoratedBase;
-    return sanitizeTitleFragment(firstLine) || 'Session';
+    const lines = stripAnsi(safeTitle).split(/\r?\n/);
+    if (lines.length > 1) {
+        const detail = lines.slice(1).map((line) => sanitizeTitleFragment(line).trim());
+        if (detail.some((line) => isCoreDecoratedDetail(line))) {
+            return sanitizeTitleFragment(firstLine) || 'Session';
+        }
+    }
+    return safeTitle;
 }
 export function stripAnsi(value) {
     // Remove terminal escape sequences. Sidebar titles must be plain text.
@@ -93,6 +116,5 @@ export function looksDecorated(title) {
     const detail = lines
         .slice(1)
         .map((line) => sanitizeTitleFragment(line).trim());
-    return (detail.some((line) => isStrongDecoratedDetail(line)) ||
-        detail.some((line) => isQuotaLikeProviderDetail(line)));
+    return detail.some((line) => isCoreDecoratedDetail(line));
 }

package/dist/title_apply.d.ts

@@ -26,5 +26,7 @@ export declare function createTitleApplicator(deps: {
     }) => Promise<void>;
     restoreSessionTitle: (sessionID: string) => Promise<void>;
     restoreAllVisibleTitles: () => Promise<void>;
+    refreshAllTouchedTitles: () => Promise<void>;
+    refreshAllVisibleTitles: () => Promise<void>;
     forgetSession: (sessionID: string) => void;
 };

package/dist/title_apply.js

@@ -1,4 +1,4 @@
-import { canonicalizeTitle, canonicalizeTitleForCompare, looksDecorated, normalizeBaseTitle, } from './title.js';
+import { canonicalizeTitle, canonicalizeTitleForCompare, looksDecorated, } from './title.js';
 import { swallow, debug, mapConcurrent } from './helpers.js';
 export function createTitleApplicator(deps) {
     const pendingAppliedTitle = new Map();
@@ -44,7 +44,7 @@ export function createTitleApplicator(deps) {
                 }
             }
             else {
-                const nextBase = normalizeBaseTitle(currentTitle);
+                const nextBase = canonicalizeTitle(currentTitle) || 'Session';
                 if (sessionState.baseTitle !== nextBase) {
                     sessionState.baseTitle = nextBase;
                     stateMutated = true;
@@ -61,6 +61,8 @@ export function createTitleApplicator(deps) {
             ? await deps.getQuotaSnapshots(quotaProviders)
             : [];
         const nextTitle = deps.renderSidebarTitle(sessionState.baseTitle, usage, quotas, deps.config);
+        if (!deps.config.sidebar.enabled || !deps.state.titleEnabled)
+            return;
         if (canonicalizeTitleForCompare(nextTitle) ===
             canonicalizeTitleForCompare(session.data.title)) {
             if (looksDecorated(session.data.title)) {
@@ -129,11 +131,14 @@ export function createTitleApplicator(deps) {
             canonicalizeTitleForCompare(args.sessionState.lastAppliedTitle || '')) {
             return;
         }
-        if (looksDecorated(args.incomingTitle)) {
-            debug(`ignoring late decorated echo for session ${args.sessionID}`);
-            return;
+        if (looksDecorated(args.incomingTitle) && args.sessionState.lastAppliedTitle) {
+            if (canonicalizeTitleForCompare(args.incomingTitle) ===
+                canonicalizeTitleForCompare(args.sessionState.lastAppliedTitle)) {
+                debug(`ignoring late decorated echo for session ${args.sessionID}`);
+                return;
+            }
         }
-        args.sessionState.baseTitle = normalizeBaseTitle(args.incomingTitle);
+        args.sessionState.baseTitle = canonicalizeTitle(args.incomingTitle) || 'Session';
         args.sessionState.lastAppliedTitle = undefined;
         deps.markDirty(deps.state.sessionDateMap[args.sessionID]);
         deps.scheduleSave();
@@ -150,10 +155,16 @@ export function createTitleApplicator(deps) {
         if (!session)
             return;
         const sessionState = deps.ensureSessionState(sessionID, session.data.title, session.data.time.created, session.data.parentID ?? null);
-        const baseTitle = normalizeBaseTitle(sessionState.baseTitle);
-        if (session.data.title === baseTitle)
+        const baseTitle = canonicalizeTitle(sessionState.baseTitle) || 'Session';
+        if (session.data.title === baseTitle) {
+            if (sessionState.lastAppliedTitle !== undefined) {
+                sessionState.lastAppliedTitle = undefined;
+                deps.markDirty(deps.state.sessionDateMap[sessionID]);
+                deps.scheduleSave();
+            }
             return;
-        await deps.client.session
+        }
+        const updated = await deps.client.session
             .update({
             path: { id: sessionID },
             query: { directory: deps.directory },
@@ -161,22 +172,39 @@ export function createTitleApplicator(deps) {
             throwOnError: true,
         })
             .catch(swallow('restoreSessionTitle:update'));
+        if (!updated)
+            return;
         sessionState.lastAppliedTitle = undefined;
         deps.markDirty(deps.state.sessionDateMap[sessionID]);
         deps.scheduleSave();
     };
     const restoreAllVisibleTitles = async () => {
+        const touched = Object.entries(deps.state.sessions)
+            .filter(([, sessionState]) => Boolean(sessionState.lastAppliedTitle))
+            .map(([sessionID]) => sessionID);
+        await mapConcurrent(touched, deps.restoreConcurrency, async (sessionID) => {
+            await restoreSessionTitle(sessionID);
+        });
+    };
+    const refreshAllTouchedTitles = async () => {
+        const touched = Object.entries(deps.state.sessions)
+            .filter(([, sessionState]) => Boolean(sessionState.lastAppliedTitle))
+            .map(([sessionID]) => sessionID);
+        await mapConcurrent(touched, deps.restoreConcurrency, async (sessionID) => {
+            await applyTitle(sessionID);
+        });
+    };
+    const refreshAllVisibleTitles = async () => {
         const list = await deps.client.session
             .list({
             query: { directory: deps.directory },
             throwOnError: true,
         })
-            .catch(swallow('restoreAllVisibleTitles:list'));
+            .catch(swallow('refreshAllVisibleTitles:list'));
         if (!list?.data)
             return;
-        const touched = list.data.filter((s) => deps.state.sessions[s.id]?.lastAppliedTitle);
-        await mapConcurrent(touched, deps.restoreConcurrency, async (s) => {
-            await restoreSessionTitle(s.id);
+        await mapConcurrent(list.data, deps.restoreConcurrency, async (session) => {
+            await applyTitle(session.id);
         });
     };
     return {
@@ -184,6 +212,8 @@ export function createTitleApplicator(deps) {
         handleSessionUpdatedTitle,
         restoreSessionTitle,
         restoreAllVisibleTitles,
+        refreshAllTouchedTitles,
+        refreshAllVisibleTitles,
         forgetSession,
     };
 }

package/dist/title_refresh.d.ts

@@ -5,5 +5,7 @@ export declare function createTitleRefreshScheduler(options: {
     schedule: (sessionID: string, delay?: number) => void;
     apply: (sessionID: string) => Promise<void>;
     cancel: (sessionID: string) => void;
+    cancelAll: () => void;
+    waitForIdle: () => Promise<void>;
     dispose: () => void;
 };

package/dist/title_refresh.js

@@ -31,16 +31,27 @@ export function createTitleRefreshScheduler(options) {
             clearTimeout(timer);
         refreshTimer.delete(sessionID);
     };
-    const dispose = () => {
+    const cancelAll = () => {
         for (const timer of refreshTimer.values())
             clearTimeout(timer);
         refreshTimer.clear();
+    };
+    const waitForIdle = async () => {
+        const inflight = Array.from(applyLocks.values());
+        if (inflight.length === 0)
+            return;
+        await Promise.allSettled(inflight);
+    };
+    const dispose = () => {
+        cancelAll();
         applyLocks.clear();
     };
     return {
         schedule,
         apply: applyLocked,
         cancel,
+        cancelAll,
+        waitForIdle,
         dispose,
     };
 }

package/dist/tools.d.ts

@@ -4,8 +4,13 @@ export declare function createQuotaSidebarTools(deps: {
     getTitleEnabled: () => boolean;
     setTitleEnabled: (enabled: boolean) => void;
     scheduleSave: () => void;
+    flushSave: () => Promise<void>;
     refreshSessionTitle: (sessionID: string, delay?: number) => void;
+    cancelAllTitleRefreshes: () => void;
+    waitForTitleRefreshIdle: () => Promise<void>;
     restoreAllVisibleTitles: () => Promise<void>;
+    refreshAllTouchedTitles: () => Promise<void>;
+    refreshAllVisibleTitles: () => Promise<void>;
     showToast: (period: 'session' | 'day' | 'week' | 'month' | 'toggle', message: string) => Promise<void>;
     summarizeForTool: (period: 'session' | 'day' | 'week' | 'month', sessionID: string, includeChildren: boolean) => Promise<UsageSummary>;
     getQuotaSnapshots: (providerIDs: string[], options?: {

package/dist/tools.js

@@ -18,7 +18,6 @@ export function createQuotaSidebarTools(deps) {
                     ? (args.includeChildren ?? deps.config.sidebar.includeChildren)
                     : false;
                 const usage = await deps.summarizeForTool(period, context.sessionID, includeChildren);
-                deps.scheduleSave();
                 // For quota_summary, always show all subscription quota balances,
                 // regardless of which providers were used in the session.
                 const quotas = await deps.getQuotaSnapshots([], { allowDefault: true });
@@ -47,16 +46,21 @@ export function createQuotaSidebarTools(deps) {
                 const next = args.enabled !== undefined ? args.enabled : !current;
                 deps.setTitleEnabled(next);
                 deps.scheduleSave();
+                await deps.flushSave();
                 if (next) {
-                    // Turning on — re-render current session immediately
+                    // Turning on — refresh visible sessions, plus touched sessions as backup.
+                    await deps.refreshAllVisibleTitles();
+                    await deps.refreshAllTouchedTitles();
                     deps.refreshSessionTitle(context.sessionID, 0);
                     await deps.showToast('toggle', 'Sidebar usage display: ON');
-                    return 'Sidebar usage display is now ON. Session titles will show token usage and quota.';
+                    return 'Sidebar usage display is now ON. Visible session titles are refreshing to show token usage and quota.';
                 }
                 // Turning off — restore all touched sessions to base titles
+                deps.cancelAllTitleRefreshes();
+                await deps.waitForTitleRefreshIdle();
                 await deps.restoreAllVisibleTitles();
                 await deps.showToast('toggle', 'Sidebar usage display: OFF');
-                return 'Sidebar usage display is now OFF. Session titles restored to original.';
+                return 'Sidebar usage display is now OFF. Restore was attempted for touched session titles.';
             },
         }),
     };

package/dist/types.d.ts

@@ -47,6 +47,20 @@ export type CacheUsageBuckets = {
     readOnly: CacheUsageBucket;
     readWrite: CacheUsageBucket;
 };
+/**
+ * Derived cache coverage metrics.
+ *
+ * - `cacheCoverage`: fraction of prompt surface covered by read-write cache
+ *   (`(cacheRead + cacheWrite) / (input + cacheRead + cacheWrite)`).
+ *   Only defined when the read-write bucket has traffic.
+ * - `cacheReadCoverage`: fraction of prompt surface served from read-only cache
+ *   (`cacheRead / (input + cacheRead)`).
+ *   Only defined when the read-only bucket has traffic.
+ */
+export type CacheCoverageMetrics = {
+    cacheCoverage: number | undefined;
+    cacheReadCoverage: number | undefined;
+};
 export type CachedProviderUsage = {
     input: number;
     output: number;
@@ -72,7 +86,13 @@ export type CachedSessionUsage = {
     /** Equivalent API billing cost (USD) computed from model pricing. */
     apiCost: number;
     assistantMessages: number;
-    /** Cache coverage buckets grouped by model cache behavior. */
+    /**
+     * Cache coverage buckets grouped by model cache behavior.
+     *
+     * `undefined` when no cache-capable models were used or data predates
+     * billingVersion 3. The fallback in `resolvedCacheUsageBuckets()` derives
+     * approximate buckets from top-level `cacheRead`/`cacheWrite` when missing.
+     */
     cacheBuckets?: CacheUsageBuckets;
     providers: Record<string, CachedProviderUsage>;
 };
@@ -90,6 +110,8 @@ export type SessionState = SessionTitleState & {
     /** Parent session ID for subagent child sessions. */
     parentID?: string;
     usage?: CachedSessionUsage;
+    /** Persisted dirtiness flag so descendant aggregation survives restart. */
+    dirty?: boolean;
     /** Incremental aggregation cursor (P1). */
     cursor?: IncrementalCursor;
 };
@@ -104,6 +126,8 @@ export type QuotaSidebarState = {
     titleEnabled: boolean;
     sessionDateMap: Record<string, string>;
     sessions: Record<string, SessionState>;
+    /** Tombstones for sessions deleted from memory but not yet purged from day chunks. */
+    deletedSessionDateMap: Record<string, string>;
     quotaCache: Record<string, QuotaSnapshot>;
 };
 export type QuotaSidebarConfig = {

package/dist/usage.d.ts

@@ -1,6 +1,12 @@
 import type { AssistantMessage, Message } from '@opencode-ai/sdk';
-import type { CacheCoverageMode, CacheUsageBuckets, CachedSessionUsage, IncrementalCursor } from './types.js';
-export declare const USAGE_BILLING_CACHE_VERSION = 3;
+import type { CacheCoverageMetrics, CacheCoverageMode, CacheUsageBuckets, CachedSessionUsage, IncrementalCursor } from './types.js';
+/**
+ * Billing cache version — bump this whenever the persisted `CachedSessionUsage`
+ * shape changes in a way that requires recomputation (e.g. new aggregate
+ * fields).  This is distinct from the plugin *state* version managed by the
+ * persistence layer; billing version only governs usage-cache staleness.
+ */
+export declare const USAGE_BILLING_CACHE_VERSION = 4;
 export type ProviderUsage = {
     providerID: string;
     input: number;
@@ -35,14 +41,14 @@ export type UsageOptions = {
     /** Cache-behavior classifier for the message model/provider. */
     classifyCacheMode?: (message: AssistantMessage) => CacheCoverageMode;
 };
-export declare function getCacheCoverageMetrics(usage: Pick<UsageSummary, 'input' | 'cacheRead' | 'cacheWrite' | 'assistantMessages' | 'cacheBuckets'>): {
-    cacheCoverage: number | undefined;
-    cacheReadCoverage: number | undefined;
-};
+export declare function getCacheCoverageMetrics(usage: Pick<UsageSummary, 'input' | 'cacheRead' | 'cacheWrite' | 'assistantMessages' | 'cacheBuckets'>): CacheCoverageMetrics;
 export declare function emptyUsageSummary(): UsageSummary;
 export declare function summarizeMessages(entries: Array<{
     info: Message;
 }>, startAt?: number, sessionCount?: number, options?: UsageOptions): UsageSummary;
+export declare function summarizeMessagesInCompletedRange(entries: Array<{
+    info: Message;
+}>, startAt: number, endAt: number, sessionCount?: number, options?: UsageOptions): UsageSummary;
 /**
  * P1: Incremental usage aggregation.
  * Only processes messages newer than the cursor. Returns updated cursor.

package/dist/usage.js

@@ -1,4 +1,10 @@
-export const USAGE_BILLING_CACHE_VERSION = 3;
+/**
+ * Billing cache version — bump this whenever the persisted `CachedSessionUsage`
+ * shape changes in a way that requires recomputation (e.g. new aggregate
+ * fields).  This is distinct from the plugin *state* version managed by the
+ * persistence layer; billing version only governs usage-cache staleness.
+ */
+export const USAGE_BILLING_CACHE_VERSION = 4;
 function emptyCacheUsageBucket() {
     return {
         input: 0,
@@ -25,8 +31,8 @@ function cloneCacheUsageBuckets(buckets) {
     if (!buckets)
         return undefined;
     return {
-        readOnly: cloneCacheUsageBucket(buckets?.readOnly),
-        readWrite: cloneCacheUsageBucket(buckets?.readWrite),
+        readOnly: cloneCacheUsageBucket(buckets.readOnly),
+        readWrite: cloneCacheUsageBucket(buckets.readWrite),
     };
 }
 function mergeCacheUsageBucket(target, source) {
@@ -44,6 +50,14 @@ function addMessageCacheUsage(target, message) {
     target.cacheWrite += message.tokens.cache.write;
     target.assistantMessages += 1;
 }
+/**
+ * Best-effort fallback for legacy cached data that lacks per-message cache
+ * buckets.  When `cacheWrite > 0` we assume all tokens came from a read-write
+ * model (Anthropic-like); when only `cacheRead > 0` we assume read-only
+ * (OpenAI-like).  Mixed-provider sessions that were cached before v3 will be
+ * attributed to a single bucket — this is a known limitation; new sessions
+ * classify per-message and are not affected.
+ */
 function fallbackCacheUsageBuckets(usage) {
     if (usage.cacheWrite > 0) {
         return {
@@ -70,8 +84,25 @@ function fallbackCacheUsageBuckets(usage) {
     return undefined;
 }
 function resolvedCacheUsageBuckets(usage) {
-    return (cloneCacheUsageBuckets(usage.cacheBuckets || fallbackCacheUsageBuckets(usage)) ||
-        emptyCacheUsageBuckets());
+    const explicit = cloneCacheUsageBuckets(usage.cacheBuckets);
+    if (!explicit) {
+        return cloneCacheUsageBuckets(fallbackCacheUsageBuckets(usage)) || emptyCacheUsageBuckets();
+    }
+    const accountedInput = explicit.readOnly.input + explicit.readWrite.input;
+    const accountedCacheRead = explicit.readOnly.cacheRead + explicit.readWrite.cacheRead;
+    const accountedCacheWrite = explicit.readOnly.cacheWrite + explicit.readWrite.cacheWrite;
+    const accountedAssistantMessages = explicit.readOnly.assistantMessages + explicit.readWrite.assistantMessages;
+    const residual = fallbackCacheUsageBuckets({
+        input: Math.max(0, usage.input - accountedInput),
+        cacheRead: Math.max(0, usage.cacheRead - accountedCacheRead),
+        cacheWrite: Math.max(0, usage.cacheWrite - accountedCacheWrite),
+        assistantMessages: Math.max(0, usage.assistantMessages - accountedAssistantMessages),
+    });
+    if (residual) {
+        mergeCacheUsageBucket(explicit.readOnly, residual.readOnly);
+        mergeCacheUsageBucket(explicit.readWrite, residual.readWrite);
+    }
+    return explicit;
 }
 export function getCacheCoverageMetrics(usage) {
     const buckets = resolvedCacheUsageBuckets(usage);
@@ -101,7 +132,6 @@ export function emptyUsageSummary() {
         apiCost: 0,
         assistantMessages: 0,
         sessionCount: 0,
-        cacheBuckets: emptyCacheUsageBuckets(),
         providers: {},
     };
 }
@@ -170,17 +200,37 @@ function addMessageUsage(target, message, options) {
         addMessageCacheUsage(buckets.readWrite, message);
     }
 }
+function completedTimeOf(message) {
+    const completed = message.time.completed;
+    if (typeof completed !== 'number')
+        return undefined;
+    if (!Number.isFinite(completed))
+        return undefined;
+    return completed;
+}
+function isCompletedAssistantInRange(message, startAt = 0, endAt = Number.POSITIVE_INFINITY) {
+    if (!isAssistant(message))
+        return false;
+    const completed = completedTimeOf(message);
+    if (completed === undefined)
+        return false;
+    return completed >= startAt && completed <= endAt;
+}
 export function summarizeMessages(entries, startAt = 0, sessionCount = 1, options) {
     const summary = emptyUsageSummary();
     summary.sessionCount = sessionCount;
     for (const entry of entries) {
-        if (!isAssistant(entry.info))
+        if (!isCompletedAssistantInRange(entry.info, startAt))
             continue;
-        if (typeof entry.info.time.completed !== 'number')
-            continue;
-        if (!Number.isFinite(entry.info.time.completed))
-            continue;
-        if (entry.info.time.created < startAt)
+        addMessageUsage(summary, entry.info, options);
+    }
+    return summary;
+}
+export function summarizeMessagesInCompletedRange(entries, startAt, endAt, sessionCount = 1, options) {
+    const summary = emptyUsageSummary();
+    summary.sessionCount = sessionCount;
+    for (const entry of entries) {
+        if (!isCompletedAssistantInRange(entry.info, startAt, endAt))
             continue;
         addMessageUsage(summary, entry.info, options);
     }
@@ -376,9 +426,9 @@ export function mergeUsage(target, source, options) {
     target.apiCost += source.apiCost;
     target.assistantMessages += source.assistantMessages;
     target.sessionCount += source.sessionCount;
-    const targetBuckets = (target.cacheBuckets ||= emptyCacheUsageBuckets());
     const sourceBuckets = source.cacheBuckets;
     if (sourceBuckets) {
+        const targetBuckets = (target.cacheBuckets ||= emptyCacheUsageBuckets());
         mergeCacheUsageBucket(targetBuckets.readOnly, sourceBuckets.readOnly);
         mergeCacheUsageBucket(targetBuckets.readWrite, sourceBuckets.readWrite);
     }