@leo000001/opencode-quota-sidebar 2.0.0 → 2.0.2

package/dist/title_apply.d.ts

@@ -17,14 +17,32 @@ export declare function createTitleApplicator(deps: {
     scheduleParentRefreshIfSafe: (sessionID: string, parentID?: string) => void;
     restoreConcurrency: number;
 }): {
-    applyTitle: (sessionID: string) => Promise<void>;
+    applyTitle: (sessionID: string) => Promise<boolean>;
     handleSessionUpdatedTitle: (args: {
         sessionID: string;
         incomingTitle: string;
         sessionState: SessionState;
         scheduleRefresh: (sessionID: string, delay?: number) => void;
     }) => Promise<void>;
-    restoreSessionTitle: (sessionID: string) => Promise<void>;
-    restoreAllVisibleTitles: () => Promise<void>;
+    restoreSessionTitle: (sessionID: string, options?: {
+        abortIfEnabled?: boolean;
+    }) => Promise<boolean>;
+    restoreAllVisibleTitles: (options?: {
+        abortIfEnabled?: boolean;
+    }) => Promise<{
+        attempted: number;
+        restored: number;
+        listFailed: boolean;
+    }>;
+    refreshAllTouchedTitles: () => Promise<{
+        attempted: number;
+        refreshed: number;
+        listFailed: boolean;
+    }>;
+    refreshAllVisibleTitles: () => Promise<{
+        attempted: number;
+        refreshed: number;
+        listFailed: boolean;
+    }>;
     forgetSession: (sessionID: string) => void;
 };

package/dist/title_apply.js

@@ -1,13 +1,15 @@
-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();
+    const recentRestore = new Map();
     const forgetSession = (sessionID) => {
         pendingAppliedTitle.delete(sessionID);
+        recentRestore.delete(sessionID);
     };
     const applyTitle = async (sessionID) => {
         if (!deps.config.sidebar.enabled || !deps.state.titleEnabled)
-            return;
+            return false;
         let stateMutated = false;
         const session = await deps.client.session
             .get({
@@ -17,7 +19,14 @@ export function createTitleApplicator(deps) {
         })
             .catch(swallow('applyTitle:getSession'));
         if (!session)
-            return;
+            return false;
+        if (!session.data ||
+            typeof session.data.title !== 'string' ||
+            !session.data.time ||
+            typeof session.data.time.created !== 'number') {
+            debug(`applyTitle skipped malformed session payload for ${sessionID}`);
+            return false;
+        }
         const sessionState = deps.ensureSessionState(sessionID, session.data.title, session.data.time.created, session.data.parentID ?? null);
         // Detect whether the current title is our own decorated form.
         const currentTitle = session.data.title;
@@ -44,7 +53,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 +70,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 false;
         if (canonicalizeTitleForCompare(nextTitle) ===
             canonicalizeTitleForCompare(session.data.title)) {
             if (looksDecorated(session.data.title)) {
@@ -74,7 +85,7 @@ export function createTitleApplicator(deps) {
             }
             deps.scheduleSave();
             deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
-            return;
+            return true;
         }
         // Mark pending title to ignore the immediate echo `session.updated` event.
         // H3 fix: use longer TTL (15s) and add decoration detection as backup.
@@ -98,11 +109,12 @@ export function createTitleApplicator(deps) {
             sessionState.lastAppliedTitle = previousApplied;
             deps.scheduleSave();
             deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
-            return;
+            return false;
         }
         pendingAppliedTitle.delete(sessionID);
         deps.scheduleSave();
         deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
+        return true;
     };
     const handleSessionUpdatedTitle = async (args) => {
         const pending = pendingAppliedTitle.get(args.sessionID);
@@ -129,17 +141,39 @@ export function createTitleApplicator(deps) {
             canonicalizeTitleForCompare(args.sessionState.lastAppliedTitle || '')) {
             return;
         }
-        if (looksDecorated(args.incomingTitle)) {
-            debug(`ignoring late decorated echo for session ${args.sessionID}`);
+        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;
+            }
+        }
+        if (looksDecorated(args.incomingTitle) && !args.sessionState.lastAppliedTitle) {
+            debug(`ignoring untracked decorated title for session ${args.sessionID}`);
             return;
         }
-        args.sessionState.baseTitle = normalizeBaseTitle(args.incomingTitle);
+        const restored = recentRestore.get(args.sessionID);
+        if (restored) {
+            if (restored.expiresAt <= Date.now()) {
+                recentRestore.delete(args.sessionID);
+            }
+            else if (looksDecorated(args.incomingTitle) &&
+                (!restored.decoratedTitle ||
+                    canonicalizeTitleForCompare(args.incomingTitle) ===
+                        canonicalizeTitleForCompare(restored.decoratedTitle))) {
+                debug(`ignoring decorated echo after restore for session ${args.sessionID}`);
+                return;
+            }
+        }
+        args.sessionState.baseTitle = canonicalizeTitle(args.incomingTitle) || 'Session';
         args.sessionState.lastAppliedTitle = undefined;
         deps.markDirty(deps.state.sessionDateMap[args.sessionID]);
         deps.scheduleSave();
         args.scheduleRefresh(args.sessionID);
     };
-    const restoreSessionTitle = async (sessionID) => {
+    const restoreSessionTitle = async (sessionID, options) => {
+        if (options?.abortIfEnabled && deps.state.titleEnabled)
+            return false;
         const session = await deps.client.session
             .get({
             path: { id: sessionID },
@@ -148,12 +182,27 @@ export function createTitleApplicator(deps) {
         })
             .catch(swallow('restoreSessionTitle:get'));
         if (!session)
-            return;
+            return false;
+        if (!session.data ||
+            typeof session.data.title !== 'string' ||
+            !session.data.time ||
+            typeof session.data.time.created !== 'number') {
+            debug(`restoreSessionTitle skipped malformed session payload for ${sessionID}`);
+            return false;
+        }
         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)
-            return;
-        await deps.client.session
+        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 true;
+        }
+        if (options?.abortIfEnabled && deps.state.titleEnabled)
+            return false;
+        const updated = await deps.client.session
             .update({
             path: { id: sessionID },
             query: { directory: deps.directory },
@@ -161,29 +210,66 @@ export function createTitleApplicator(deps) {
             throwOnError: true,
         })
             .catch(swallow('restoreSessionTitle:update'));
+        if (!updated)
+            return false;
+        pendingAppliedTitle.delete(sessionID);
+        recentRestore.set(sessionID, {
+            baseTitle,
+            decoratedTitle: sessionState.lastAppliedTitle,
+            expiresAt: Date.now() + 15_000,
+        });
         sessionState.lastAppliedTitle = undefined;
         deps.markDirty(deps.state.sessionDateMap[sessionID]);
         deps.scheduleSave();
+        return true;
+    };
+    const restoreAllVisibleTitles = async (options) => {
+        const touched = Object.entries(deps.state.sessions)
+            .filter(([, sessionState]) => Boolean(sessionState.lastAppliedTitle))
+            .map(([sessionID]) => sessionID);
+        const results = await mapConcurrent(touched, deps.restoreConcurrency, async (sessionID) => restoreSessionTitle(sessionID, options));
+        return {
+            attempted: touched.length,
+            restored: results.filter(Boolean).length,
+            listFailed: false,
+        };
+    };
+    const refreshAllTouchedTitles = async () => {
+        const touched = Object.entries(deps.state.sessions)
+            .filter(([, sessionState]) => Boolean(sessionState.lastAppliedTitle))
+            .map(([sessionID]) => sessionID);
+        const results = await mapConcurrent(touched, deps.restoreConcurrency, async (sessionID) => applyTitle(sessionID));
+        return {
+            attempted: touched.length,
+            refreshed: results.filter(Boolean).length,
+            listFailed: false,
+        };
     };
-    const restoreAllVisibleTitles = async () => {
+    const refreshAllVisibleTitles = async () => {
         const list = await deps.client.session
             .list({
             query: { directory: deps.directory },
             throwOnError: true,
         })
-            .catch(swallow('restoreAllVisibleTitles: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);
-        });
+            .catch(swallow('refreshAllVisibleTitles:list'));
+        if (!list?.data || !Array.isArray(list.data)) {
+            return { attempted: 0, refreshed: 0, listFailed: true };
+        }
+        const sessions = list.data.filter((session) => Boolean(session && typeof session.id === 'string'));
+        const results = await mapConcurrent(sessions, deps.restoreConcurrency, async (session) => applyTitle(session.id));
+        return {
+            attempted: sessions.length,
+            refreshed: results.filter(Boolean).length,
+            listFailed: false,
+        };
     };
     return {
         applyTitle,
         handleSessionUpdatedTitle,
         restoreSessionTitle,
         restoreAllVisibleTitles,
+        refreshAllTouchedTitles,
+        refreshAllVisibleTitles,
         forgetSession,
     };
 }

package/dist/title_refresh.d.ts

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

package/dist/title_refresh.js

@@ -31,16 +31,50 @@ export function createTitleRefreshScheduler(options) {
             clearTimeout(timer);
         refreshTimer.delete(sessionID);
     };
-    const dispose = () => {
+    const cancelAll = () => {
         for (const timer of refreshTimer.values())
             clearTimeout(timer);
         refreshTimer.clear();
+    };
+    const flushScheduled = async () => {
+        const pending = Array.from(refreshTimer.keys());
+        cancelAll();
+        await Promise.allSettled(pending.map((sessionID) => applyLocked(sessionID)));
+    };
+    const waitForIdle = async (timeoutMs) => {
+        const inflight = Array.from(applyLocks.values());
+        if (inflight.length === 0)
+            return;
+        if (timeoutMs === undefined) {
+            await Promise.allSettled(inflight);
+            return;
+        }
+        await Promise.race([
+            Promise.allSettled(inflight),
+            new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+        ]);
+    };
+    const waitForQuiescence = async (budgetMs = 10_000) => {
+        const deadline = Date.now() + budgetMs;
+        while (Date.now() < deadline) {
+            await flushScheduled();
+            await waitForIdle(Math.max(0, deadline - Date.now()));
+            if (refreshTimer.size === 0 && applyLocks.size === 0)
+                return;
+        }
+    };
+    const dispose = () => {
+        cancelAll();
         applyLocks.clear();
     };
     return {
         schedule,
         apply: applyLocked,
         cancel,
+        cancelAll,
+        flushScheduled,
+        waitForIdle,
+        waitForQuiescence,
         dispose,
     };
 }

package/dist/tools.d.ts

@@ -4,8 +4,28 @@ export declare function createQuotaSidebarTools(deps: {
     getTitleEnabled: () => boolean;
     setTitleEnabled: (enabled: boolean) => void;
     scheduleSave: () => void;
+    flushSave: () => Promise<void>;
+    waitForStartupTitleWork: () => Promise<void>;
     refreshSessionTitle: (sessionID: string, delay?: number) => void;
-    restoreAllVisibleTitles: () => Promise<void>;
+    cancelAllTitleRefreshes: () => void;
+    flushScheduledTitleRefreshes: () => Promise<void>;
+    waitForTitleRefreshIdle: () => Promise<void>;
+    waitForTitleRefreshQuiescence: () => Promise<void>;
+    restoreAllVisibleTitles: () => Promise<{
+        attempted: number;
+        restored: number;
+        listFailed: boolean;
+    }>;
+    refreshAllTouchedTitles: () => Promise<{
+        attempted: number;
+        refreshed: number;
+        listFailed: boolean;
+    }>;
+    refreshAllVisibleTitles: () => Promise<{
+        attempted: number;
+        refreshed: number;
+        listFailed: boolean;
+    }>;
     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?: {
@@ -24,6 +44,7 @@ export declare function createQuotaSidebarTools(deps: {
             width: number;
             includeChildren: boolean;
         };
+        sidebarEnabled: boolean;
     };
 }): {
     quota_summary: {

package/dist/tools.js

@@ -1,6 +1,14 @@
 import { tool } from '@opencode-ai/plugin/tool';
 const z = tool.schema;
 export function createQuotaSidebarTools(deps) {
+    let toggleLock = Promise.resolve();
+    const waitForStartupTitleWork = async () => {
+        const timedOut = await Promise.race([
+            deps.waitForStartupTitleWork(),
+            new Promise((resolve) => setTimeout(() => resolve('timeout'), 3_000)),
+        ]);
+        return timedOut === 'timeout';
+    };
     return {
         quota_summary: tool({
             description: 'Show usage and quota summary for session/day/week/month.',
@@ -18,7 +26,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 });
@@ -43,20 +50,59 @@ export function createQuotaSidebarTools(deps) {
                     .describe('Explicit on/off. Omit to toggle current state.'),
             },
             execute: async (args, context) => {
-                const current = deps.getTitleEnabled();
-                const next = args.enabled !== undefined ? args.enabled : !current;
-                deps.setTitleEnabled(next);
-                deps.scheduleSave();
-                if (next) {
-                    // Turning on — re-render current session immediately
+                const run = async () => {
+                    const current = deps.getTitleEnabled();
+                    const next = args.enabled !== undefined ? args.enabled : !current;
+                    if (next) {
+                        if (!deps.config.sidebarEnabled) {
+                            return 'Sidebar usage display cannot be enabled because `sidebar.enabled=false` in config. Re-enable the sidebar feature first.';
+                        }
+                        const startupTimedOut = await waitForStartupTitleWork();
+                        deps.setTitleEnabled(true);
+                        deps.scheduleSave();
+                        await deps.flushSave();
+                        const visible = await deps.refreshAllVisibleTitles();
+                        const touched = await deps.refreshAllTouchedTitles();
+                        deps.refreshSessionTitle(context.sessionID, 0);
+                        if (startupTimedOut) {
+                            void deps.waitForStartupTitleWork().then(() => {
+                                if (!deps.getTitleEnabled())
+                                    return;
+                                void deps.refreshAllVisibleTitles();
+                                void deps.refreshAllTouchedTitles();
+                                deps.refreshSessionTitle(context.sessionID, 0);
+                            });
+                        }
+                        await deps.showToast('toggle', 'Sidebar usage display: ON');
+                        if (visible.listFailed ||
+                            visible.refreshed < visible.attempted ||
+                            touched.refreshed < touched.attempted) {
+                            return 'Sidebar usage display is now ON. Visible-session refresh failed, so only touched/current session titles are guaranteed to refresh immediately.';
+                        }
+                        return 'Sidebar usage display is now ON. Visible session titles are refreshing to show token usage and quota.';
+                    }
+                    deps.setTitleEnabled(false);
+                    deps.scheduleSave();
+                    await deps.flushSave();
+                    deps.cancelAllTitleRefreshes();
+                    await deps.waitForTitleRefreshQuiescence();
+                    const restore = await deps.restoreAllVisibleTitles();
+                    if (restore.restored === restore.attempted) {
+                        await deps.showToast('toggle', 'Sidebar usage display: OFF');
+                        return 'Sidebar usage display is now OFF. Touched session titles were restored to base titles.';
+                    }
+                    deps.setTitleEnabled(true);
+                    deps.scheduleSave();
+                    await deps.flushSave();
+                    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.';
-                }
-                // Turning off — restore all touched sessions to base titles
-                await deps.restoreAllVisibleTitles();
-                await deps.showToast('toggle', 'Sidebar usage display: OFF');
-                return 'Sidebar usage display is now OFF. Session titles restored to original.';
+                    await deps.showToast('toggle', 'Sidebar usage display: OFF failed');
+                    return 'Sidebar usage display remains ON because some touched session titles could not be restored. Try again after the session service recovers.';
+                };
+                const pending = toggleLock.then(run, run);
+                toggleLock = pending.then(() => undefined, () => undefined);
+                return pending;
             },
         }),
     };

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;
@@ -58,6 +72,8 @@ export type CachedProviderUsage = {
     /** Equivalent API billing cost (USD) computed from model pricing. */
     apiCost: number;
     assistantMessages: number;
+    /** Provider-level cache coverage buckets grouped by model cache behavior. */
+    cacheBuckets?: CacheUsageBuckets;
 };
 export type CachedSessionUsage = {
     /** Billing aggregation cache version for cost/apiCost refresh migrations. */
@@ -72,7 +88,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 +112,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 +128,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;
@@ -13,6 +19,7 @@ export type ProviderUsage = {
     cost: number;
     apiCost: number;
     assistantMessages: number;
+    cacheBuckets?: CacheUsageBuckets;
 };
 export type UsageSummary = {
     input: number;
@@ -35,14 +42,15 @@ 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 getProviderCacheCoverageMetrics(usage: Pick<ProviderUsage, '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.