@leo000001/opencode-quota-sidebar 3.0.9 → 4.0.0

package/dist/quota_service.js

@@ -3,15 +3,27 @@ import { TtlValueCache } from './cache.js';
 import { isRecord, swallow } from './helpers.js';
 import { listDefaultQuotaProviderIDs, loadAuthMap, quotaSort } from './quota.js';
 export function createQuotaService(deps) {
-    const ERROR_CACHE_TTL_MS = 30_000;
+    const ERROR_CACHE_TTL_MS = 15_000;
     const ZERO_QUOTA_CACHE_TTL_MS = 15_000;
+    const CRITICAL_QUOTA_CACHE_TTL_MS = 20_000;
     const LOW_QUOTA_CACHE_TTL_MS = 30_000;
+    const MODERATE_QUOTA_CACHE_TTL_MS = 45_000;
     const SOON_RESET_CACHE_TTL_MS = 15_000;
     const SOON_RESET_WINDOW_MS = 2 * 60 * 1000;
+    const MIN_STALE_MAX_AGE_MS = 5 * 60 * 1000;
+    const MAX_STALE_MAX_AGE_MS = 15 * 60 * 1000;
+    const RESET_PASSED_STALE_GRACE_MS = 60_000;
     const authCache = new TtlValueCache();
     const providerOptionsCache = new TtlValueCache();
     const inFlight = new Map();
+    const invalidatedCacheKeys = new Map();
+    const latestFetchGeneration = new Map();
+    let requestGeneration = 0;
     let lastSuccessfulProviderOptionsMap = {};
+    const nextRequestGeneration = () => {
+        requestGeneration += 1;
+        return requestGeneration;
+    };
     const authFingerprint = (auth) => {
         if (!auth || typeof auth !== 'object')
             return undefined;
@@ -78,7 +90,8 @@ export function createQuotaService(deps) {
             })
                 .catch(swallow('getProviderOptionsMap:providerList'));
         }
-        const data = isRecord(response) && Object.prototype.hasOwnProperty.call(response, 'data')
+        const data = isRecord(response) &&
+            Object.prototype.hasOwnProperty.call(response, 'data')
             ? response.data
             : undefined;
         if (!response || data === undefined) {
@@ -89,7 +102,8 @@ export function createQuotaService(deps) {
                     throwOnError: true,
                 })
                     .catch(swallow('getProviderOptionsMap:providerListNoDataFallback'));
-                const fallbackData = isRecord(response) && Object.prototype.hasOwnProperty.call(response, 'data')
+                const fallbackData = isRecord(response) &&
+                    Object.prototype.hasOwnProperty.call(response, 'data')
                     ? response.data
                     : undefined;
                 const fallbackRecord = isRecord(fallbackData) ? fallbackData : undefined;
@@ -110,7 +124,9 @@ export function createQuotaService(deps) {
                         const key = record.key;
                         if (typeof id !== 'string')
                             return acc;
-                        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+                        if (!options ||
+                            typeof options !== 'object' ||
+                            Array.isArray(options)) {
                             acc[id] =
                                 typeof key === 'string' && key ? { apiKey: key } : {};
                             return acc;
@@ -118,7 +134,9 @@ export function createQuotaService(deps) {
                         const optionsRecord = options;
                         acc[id] = {
                             ...optionsRecord,
-                            ...(typeof key === 'string' && key && optionsRecord.apiKey === undefined
+                            ...(typeof key === 'string' &&
+                                key &&
+                                optionsRecord.apiKey === undefined
                                 ? { apiKey: key }
                                 : {}),
                         };
@@ -149,7 +167,8 @@ export function createQuotaService(deps) {
                 throwOnError: true,
             })
                 .catch(swallow('getProviderOptionsMap:providerListFallback'));
-            const fallbackData = isRecord(response) && Object.prototype.hasOwnProperty.call(response, 'data')
+            const fallbackData = isRecord(response) &&
+                Object.prototype.hasOwnProperty.call(response, 'data')
                 ? response.data
                 : undefined;
             const fallbackRecord = isRecord(fallbackData) ? fallbackData : undefined;
@@ -170,14 +189,18 @@ export function createQuotaService(deps) {
                     const key = record.key;
                     if (typeof id !== 'string')
                         return acc;
-                    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+                    if (!options ||
+                        typeof options !== 'object' ||
+                        Array.isArray(options)) {
                         acc[id] = typeof key === 'string' && key ? { apiKey: key } : {};
                         return acc;
                     }
                     const optionsRecord = options;
                     acc[id] = {
                         ...optionsRecord,
-                        ...(typeof key === 'string' && key && optionsRecord.apiKey === undefined
+                        ...(typeof key === 'string' &&
+                            key &&
+                            optionsRecord.apiKey === undefined
                             ? { apiKey: key }
                             : {}),
                     };
@@ -214,7 +237,9 @@ export function createQuotaService(deps) {
                 const optionsRecord = options;
                 acc[id] = {
                     ...optionsRecord,
-                    ...(typeof key === 'string' && key && optionsRecord.apiKey === undefined
+                    ...(typeof key === 'string' &&
+                        key &&
+                        optionsRecord.apiKey === undefined
                         ? { apiKey: key }
                         : {}),
                 };
@@ -283,8 +308,59 @@ export function createQuotaService(deps) {
         }
         return values;
     };
+    const staleMaxAgeMs = () => Math.min(MAX_STALE_MAX_AGE_MS, Math.max(MIN_STALE_MAX_AGE_MS, deps.config.quota.refreshMs * 2));
+    const staleReason = (snapshot) => {
+        if (snapshot.status !== 'error')
+            return undefined;
+        const note = snapshot.note?.trim();
+        if (!note)
+            return undefined;
+        const normalized = note.toLowerCase();
+        if (normalized === 'timeout') {
+            return { kind: 'timeout', text: note };
+        }
+        if (normalized.includes('network request failed')) {
+            return { kind: 'network', text: note };
+        }
+        if (/^http\s+5\d\d\b/i.test(note)) {
+            return { kind: 'http_5xx', text: note };
+        }
+        if (/^http\s+(408|429)\b/i.test(note)) {
+            return { kind: 'http_transient', text: note };
+        }
+        if (normalized.includes('invalid response') ||
+            normalized.includes('missing quota fields')) {
+            return { kind: 'invalid_response', text: note };
+        }
+        return undefined;
+    };
+    const canReuseStaleQuota = (snapshot, now = Date.now()) => {
+        if (snapshot.status !== 'ok')
+            return false;
+        if (now - snapshot.checkedAt > staleMaxAgeMs())
+            return false;
+        const resetTimes = snapshotResetTimes(snapshot);
+        if (resetTimes.some((resetAt) => resetAt + RESET_PASSED_STALE_GRACE_MS <= now)) {
+            return false;
+        }
+        return true;
+    };
+    const withStaleQuota = (snapshot, failure, now = Date.now()) => {
+        const reason = staleReason(failure);
+        return {
+            ...snapshot,
+            stale: {
+                staleAt: now,
+                staleReason: reason?.text || failure.note || 'error',
+                staleReasonKind: reason?.kind || 'unknown',
+            },
+        };
+    };
     const effectiveQuotaCacheTtl = (snapshot, now = Date.now()) => {
         let ttlMs = deps.config.quota.refreshMs;
+        if (snapshot.stale) {
+            ttlMs = Math.min(ttlMs, ERROR_CACHE_TTL_MS);
+        }
         if (snapshot.status !== 'ok') {
             ttlMs = Math.min(ttlMs, ERROR_CACHE_TTL_MS);
         }
@@ -292,9 +368,15 @@ export function createQuotaService(deps) {
         if (remainingPercents.some((value) => value <= 0)) {
             ttlMs = Math.min(ttlMs, ZERO_QUOTA_CACHE_TTL_MS);
         }
-        else if (remainingPercents.some((value) => value <= 1)) {
+        else if (remainingPercents.some((value) => value <= 5)) {
+            ttlMs = Math.min(ttlMs, CRITICAL_QUOTA_CACHE_TTL_MS);
+        }
+        else if (remainingPercents.some((value) => value <= 15)) {
             ttlMs = Math.min(ttlMs, LOW_QUOTA_CACHE_TTL_MS);
         }
+        else if (remainingPercents.some((value) => value <= 30)) {
+            ttlMs = Math.min(ttlMs, MODERATE_QUOTA_CACHE_TTL_MS);
+        }
         const resetTimes = snapshotResetTimes(snapshot);
         if (resetTimes.some((resetAt) => resetAt <= now))
             return 0;
@@ -391,18 +473,29 @@ export function createQuotaService(deps) {
         const fetchSnapshot = (providerID, providerOptions) => {
             const baseKey = deps.quotaRuntime.quotaCacheKey(providerID, providerOptions);
             const cacheKey = `${baseKey}#${authScopeFor(providerID, providerOptions)}`;
+            const normalizedProviderID = deps.quotaRuntime.normalizeProviderID(providerID);
             const cached = deps.state.quotaCache[cacheKey];
             const now = Date.now();
+            const invalidatedAt = invalidatedCacheKeys.get(cacheKey);
             const cacheTtl = cached ? effectiveQuotaCacheTtl(cached, now) : 0;
-            if (cached && cacheTtl > 0 && now - cached.checkedAt <= cacheTtl) {
+            const freshnessAt = cached?.stale?.staleAt ?? cached?.checkedAt ?? 0;
+            if (cached &&
+                invalidatedAt === undefined &&
+                cacheTtl > 0 &&
+                now - freshnessAt <= cacheTtl) {
                 if (isValidQuotaCache(cached))
                     return Promise.resolve(cached);
                 delete deps.state.quotaCache[cacheKey];
                 cacheChanged = true;
             }
             const existing = inFlight.get(cacheKey);
-            if (existing)
-                return existing;
+            if (existing &&
+                (invalidatedAt === undefined || existing.generation >= invalidatedAt)) {
+                return existing.promise;
+            }
+            if (invalidatedAt !== undefined)
+                invalidatedCacheKeys.delete(cacheKey);
+            const generation = nextRequestGeneration();
             const promise = deps.quotaRuntime
                 .fetchQuotaSnapshot(providerID, authMap, deps.config, async (id, next) => {
                 await deps.client.auth
@@ -421,16 +514,36 @@ export function createQuotaService(deps) {
                 .then((latest) => {
                 if (!latest)
                     return undefined;
-                deps.state.quotaCache[cacheKey] = latest;
-                cacheChanged = true;
-                return latest;
+                const cachedOk = cached &&
+                    cached.status === 'ok' &&
+                    canReuseStaleQuota(cached, Date.now())
+                    ? cached
+                    : undefined;
+                const next = cachedOk && staleReason(latest)
+                    ? withStaleQuota(cachedOk, latest, Date.now())
+                    : latest.stale
+                        ? { ...latest, stale: undefined }
+                        : latest;
+                const invalidatedGeneration = invalidatedCacheKeys.get(cacheKey) || 0;
+                if (generation >= (latestFetchGeneration.get(cacheKey) || 0) &&
+                    generation >= invalidatedGeneration) {
+                    deps.state.quotaCache[cacheKey] = next;
+                    cacheChanged = true;
+                }
+                return next;
             })
                 .finally(() => {
-                if (inFlight.get(cacheKey) === promise) {
+                if (inFlight.get(cacheKey)?.promise === promise) {
                     inFlight.delete(cacheKey);
                 }
             });
-            inFlight.set(cacheKey, promise);
+            latestFetchGeneration.set(cacheKey, generation);
+            inFlight.set(cacheKey, {
+                generation,
+                providerID,
+                normalizedProviderID,
+                promise,
+            });
             return promise;
         };
         const fetched = await Promise.all(dedupedCandidates.map(({ providerID, providerOptions }) => fetchSnapshot(providerID, providerOptions)));
@@ -440,5 +553,24 @@ export function createQuotaService(deps) {
             deps.scheduleSave();
         return snapshots;
     };
-    return { getQuotaSnapshots };
+    const invalidateForProvider = (providerID) => {
+        const normalized = deps.quotaRuntime.normalizeProviderID(providerID);
+        for (const [cacheKey, snapshot] of Object.entries(deps.state.quotaCache)) {
+            if (snapshot.providerID === providerID) {
+                invalidatedCacheKeys.set(cacheKey, nextRequestGeneration());
+                continue;
+            }
+            if (deps.quotaRuntime.normalizeProviderID(snapshot.providerID) ===
+                normalized) {
+                invalidatedCacheKeys.set(cacheKey, nextRequestGeneration());
+            }
+        }
+        for (const [cacheKey, entry] of inFlight.entries()) {
+            if (entry.providerID === providerID ||
+                entry.normalizedProviderID === normalized) {
+                invalidatedCacheKeys.set(cacheKey, nextRequestGeneration());
+            }
+        }
+    };
+    return { getQuotaSnapshots, invalidateForProvider };
 }

package/dist/storage.d.ts

@@ -26,7 +26,7 @@ export declare function evictOldSessions(state: QuotaSidebarState, retentionDays
  * M9 fix: scan from in-memory state first, only read disk for date keys
  * not represented in memory.
  */
-export declare function scanSessionsByCreatedRange(statePath: string, startAt: number, endAt?: number, memoryState?: QuotaSidebarState): Promise<{
+export declare function scanSessionsByCreatedRange(statePath: string, startAt: number, endAt?: number, memoryState?: QuotaSidebarState, retentionDays?: number): Promise<{
     sessionID: string;
     dateKey: string;
     state: SessionState;

package/dist/storage.js

@@ -38,13 +38,13 @@ export const defaultConfig = {
         },
     },
     quota: {
-        refreshMs: 5 * 60 * 1000,
+        refreshMs: 1 * 60 * 1000,
         includeOpenAI: true,
         includeCopilot: true,
         includeAnthropic: true,
         providers: {},
         refreshAccessToken: false,
-        requestTimeoutMs: 8_000,
+        requestTimeoutMs: 12_000,
     },
     toast: {
         durationMs: 12_000,
@@ -363,10 +363,10 @@ export function evictOldSessions(state, retentionDays) {
  * M9 fix: scan from in-memory state first, only read disk for date keys
  * not represented in memory.
  */
-export async function scanSessionsByCreatedRange(statePath, startAt, endAt = Date.now(), memoryState) {
+export async function scanSessionsByCreatedRange(statePath, startAt, endAt = Date.now(), memoryState, retentionDays = 730) {
     const rootPath = chunkRootPathFromStateFile(statePath);
     const deletedSessionIDs = new Set(Object.keys(memoryState?.deletedSessionDateMap || {}));
-    const dateKeys = dateKeysInRange(startAt, endAt);
+    const dateKeys = dateKeysInRange(startAt, endAt, retentionDays + 1);
     if (!dateKeys.length) {
         return [];
     }

package/dist/storage_dates.d.ts

@@ -6,4 +6,4 @@ export declare function isDateKey(value: string): boolean;
  */
 export declare function dateKeyFromTimestamp(timestampMs: number): string;
 export declare function dateStartFromKey(dateKey: string): number;
-export declare function dateKeysInRange(startAt: number, endAt: number): string[];
+export declare function dateKeysInRange(startAt: number, endAt: number, maxDays?: number): string[];

package/dist/storage_dates.js

@@ -65,9 +65,12 @@ export function dateStartFromKey(dateKey) {
     const [yearText, monthText, dayText] = dateKey.split('-');
     return new Date(Number(yearText), Number(monthText) - 1, Number(dayText)).getTime();
 }
-/** M7 fix: cap iteration at 400 days (~13 months). */
-const MAX_DATE_RANGE_DAYS = 400;
-export function dateKeysInRange(startAt, endAt) {
+/**
+ * M7 fix: cap iteration at 731 calendar dates so a rolling 730-day retention
+ * window still covers both boundary days.
+ */
+const DEFAULT_MAX_DATE_RANGE_DAYS = 731;
+export function dateKeysInRange(startAt, endAt, maxDays = DEFAULT_MAX_DATE_RANGE_DAYS) {
     const startDate = new Date(startAt);
     if (Number.isNaN(startDate.getTime()))
         return [];
@@ -77,9 +80,9 @@ export function dateKeysInRange(startAt, endAt) {
     const cursor = new Date(startDate.getFullYear(), startDate.getMonth(), startDate.getDate());
     const endDay = new Date(endDate.getFullYear(), endDate.getMonth(), endDate.getDate());
     const keys = [];
+    const safeMaxDays = Math.max(1, Math.floor(maxDays));
     let iterations = 0;
-    while (cursor.getTime() <= endDay.getTime() &&
-        iterations < MAX_DATE_RANGE_DAYS) {
+    while (cursor.getTime() <= endDay.getTime() && iterations < safeMaxDays) {
         keys.push(dateKeyFromTimestamp(cursor.getTime()));
         cursor.setDate(cursor.getDate() + 1);
         iterations++;

package/dist/storage_parse.js

@@ -1,4 +1,5 @@
 import { asNumber, isRecord } from './helpers.js';
+import { isSupportedQuotaSnapshot } from './supported_quota.js';
 import { normalizeTimestampMs } from './storage_dates.js';
 function parseSessionTitleState(value) {
     if (!isRecord(value))
@@ -152,7 +153,26 @@ function parseQuotaSnapshot(value) {
         }))
             .filter((window) => window.label || window.remainingPercent !== undefined)
         : undefined;
-    return {
+    const stale = isRecord(value.stale)
+        ? (() => {
+            const staleReasonKind = value.stale.staleReasonKind === 'timeout' ||
+                value.stale.staleReasonKind === 'network' ||
+                value.stale.staleReasonKind === 'http_5xx' ||
+                value.stale.staleReasonKind === 'http_transient' ||
+                value.stale.staleReasonKind === 'invalid_response' ||
+                value.stale.staleReasonKind === 'unknown'
+                ? value.stale.staleReasonKind
+                : 'unknown';
+            return {
+                staleAt: typeof value.stale.staleAt === 'number' ? value.stale.staleAt : 0,
+                staleReason: typeof value.stale.staleReason === 'string'
+                    ? value.stale.staleReason
+                    : '',
+                staleReasonKind,
+            };
+        })()
+        : undefined;
+    const parsed = {
         providerID: typeof value.providerID === 'string' ? value.providerID : label,
         adapterID,
         label,
@@ -169,7 +189,9 @@ function parseQuotaSnapshot(value) {
         balance,
         note: typeof value.note === 'string' ? value.note : undefined,
         windows,
+        stale: stale && stale.staleAt > 0 && stale.staleReason ? stale : undefined,
     };
+    return isSupportedQuotaSnapshot(parsed) ? parsed : undefined;
 }
 function parseQuotaSnapshots(value) {
     if (!Array.isArray(value))

package/dist/supported_quota.d.ts

@@ -0,0 +1,4 @@
+import type { QuotaSnapshot } from './types.js';
+export declare function isSupportedQuotaProviderID(providerID: string): boolean;
+export declare function isSupportedQuotaSnapshot(quota: Pick<QuotaSnapshot, 'providerID' | 'adapterID'>): boolean;
+export declare function isSupportedQuotaTitleLabel(label: string): boolean;

package/dist/supported_quota.js

@@ -0,0 +1,36 @@
+const SUPPORTED_QUOTA_PROVIDER_IDS = new Set([
+    'openai',
+    'github-copilot',
+    'anthropic',
+    'kimi-for-coding',
+    'zhipuai-coding-plan',
+    'minimax-cn-coding-plan',
+    'rightcode',
+]);
+const SUPPORTED_QUOTA_TITLE_LABELS = new Set([
+    'OAI',
+    'Cop',
+    'Ant',
+    'Kimi',
+    'Zhipu',
+    'MiniMax',
+    'RC',
+]);
+export function isSupportedQuotaProviderID(providerID) {
+    if (providerID.startsWith('github-copilot'))
+        return true;
+    if (providerID.startsWith('rightcode-'))
+        return true;
+    return SUPPORTED_QUOTA_PROVIDER_IDS.has(providerID);
+}
+export function isSupportedQuotaSnapshot(quota) {
+    if (typeof quota.adapterID === 'string' && quota.adapterID) {
+        return isSupportedQuotaProviderID(quota.adapterID);
+    }
+    return isSupportedQuotaProviderID(quota.providerID);
+}
+export function isSupportedQuotaTitleLabel(label) {
+    if (SUPPORTED_QUOTA_TITLE_LABELS.has(label))
+        return true;
+    return /^RC-[^\s]+$/.test(label);
+}

package/dist/title.js

@@ -59,28 +59,38 @@ function isQuotaDecoratedDetail(line) {
         return false;
     const resetValue = '[-:\\dhmD]+';
     const compactResetValue = '\\d[\\d:.\\-hmD]*';
-    if (/^(OAI|Cop|Ant|Kimi|XYAI|RC(?:-[^\s]+)?)(?:\s+(?:\?|unsupported|unavailable|error|(?:\d+h|D|W|M)\d{1,3}|D[\d.,]+\/[\d.,]+|B(?:[￥$-])?[\d.,]+))+$/i.test(line)) {
+    const legacyProvider = '[A-Z][A-Z0-9-]{1,15}';
+    if (/^(OAI|Cop|Ant|Kimi|RC(?:-[^\s]+)?)(?:\s+(?:\?|unsupported|unavailable|error|stale|St|(?:\d+h|D|W|M)\d{1,3}|(?:Sk5h|SkW)\d{1,3}|D[\d.,]+\/[\d.,]+|B(?:[￥$-])?[\d.,]+))+$/i.test(line)) {
         return true;
     }
-    if (/^(OpenAI|Copilot|Anthropic|Kimi|XYAI|RC(?:-[^\s]+)?)\s*$/.test(line)) {
+    if (/^(OpenAI|Copilot|Anthropic|Kimi|RC(?:-[^\s]+)?)\s*$/.test(line)) {
         return true;
     }
-    if (new RegExp(`^(?:(?:Daily\\s+\\$[\\d.,]+\\/\\$[\\d.,]+|\\$[\\d.,]+\\/\\$[\\d.,]+)(?:\\s+(?:Rst|Exp\\+?)\\s+${resetValue})?|(?:\\d+[hdw]|Weekly|Monthly)\\s+\\d{1,3}%(?:\\s+Rst\\s+${resetValue})?|Balance\\s+\\$[\\d.,]+|Remaining\\s+\\?|(?:error|unsupported|unavailable))$`).test(line)) {
+    if (new RegExp(`^(?:(?:(?:Daily\\s+\\$[\\d.,]+\\/\\$[\\d.,]+|\\$[\\d.,]+\\/\\$[\\d.,]+)(?:\\s+(?:Rst|Exp\\+?)\\s+${resetValue})?|(?:\\d+[hdw]|Weekly|Monthly)\\s+\\d{1,3}%(?:\\s+Rst\\s+${resetValue})?|Balance\\s+\\$[\\d.,]+|Remaining\\s+\\?)(?:\\s+stale)?|(?:error|unsupported|unavailable|stale))$`).test(line)) {
         return true;
     }
-    if (new RegExp(`^(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d)\\d{1,3})(?:\\s+(?:R|E\\+?)${compactResetValue})?$`).test(line)) {
+    if (new RegExp(`^(?:Spark\\s+(?:5h|Weekly)\\s+\\d{1,3}%(?:\\s+Rst\\s+${resetValue})?)(?:\\s+stale)?$`).test(line)) {
         return true;
     }
-    if (new RegExp(`^(OpenAI|Copilot|Anthropic|Kimi|XYAI|RC(?:-[^\\s]+)?)(?:\\s+(?:(?:Daily\\s+\\$[\\d.,]+\\/\\$[\\d.,]+|\\$[\\d.,]+\\/\\$[\\d.,]+)(?:\\s+(?:Rst|Exp\\+?)\\s+${resetValue})?|(?:\\d+[hdw]|Weekly|Monthly)\\s+\\d{1,3}%(?:\\s+Rst\\s+${resetValue})?|(?:error|unsupported|unavailable)))$`).test(line)) {
+    if (new RegExp(`^(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d|Sk5h|SkW)\\d{1,3}|St)(?:\\s+(?:R|E\\+?)${compactResetValue})?$`).test(line)) {
         return true;
     }
-    if (new RegExp(`^(OpenAI|Copilot|Anthropic|Kimi|XYAI|RC(?:-[^\\s]+)?)(?:\\s+(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d)\\d{1,3})(?:\\s+(?:R|E\\+?)${compactResetValue})?)$`).test(line)) {
+    if (new RegExp(`^(OpenAI|Copilot|Anthropic|Kimi|RC(?:-[^\\s]+)?)(?:\\s+(?:(?:Daily\\s+\\$[\\d.,]+\\/\\$[\\d.,]+|\\$[\\d.,]+\\/\\$[\\d.,]+)(?:\\s+(?:Rst|Exp\\+?)\\s+${resetValue})?|(?:\\d+[hdw]|Weekly|Monthly)\\s+\\d{1,3}%(?:\\s+Rst\\s+${resetValue})?)(?:\\s+stale)?|(?:error|unsupported|unavailable|stale))$`).test(line)) {
         return true;
     }
-    if (new RegExp(`^(?:(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d)\\d{1,3}|(?:R|E\\+?)${compactResetValue}))(?:\\s+(?:(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d)\\d{1,3}|(?:R|E\\+?)${compactResetValue})))*$`).test(line)) {
+    if (new RegExp(`^(OpenAI|Copilot|Anthropic|Kimi|RC(?:-[^\\s]+)?)(?:\\s+(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d|Sk5h|SkW)\\d{1,3}|St)(?:\\s+(?:R|E\\+?)${compactResetValue})?)$`).test(line)) {
         return true;
     }
-    if (new RegExp(`^(OpenAI|Copilot|Anthropic|Kimi|XYAI|RC(?:-[^\\s]+)?)(?:\\s+(?:(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d)\\d{1,3}|(?:R|E\\+?)${compactResetValue})))*$`).test(line)) {
+    if (new RegExp(`^(?:(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d|Sk5h|SkW)\\d{1,3}|St|(?:R|E\\+?)${compactResetValue}))(?:\\s+(?:(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d|Sk5h|SkW)\\d{1,3}|St|(?:R|E\\+?)${compactResetValue})))*$`).test(line)) {
+        return true;
+    }
+    if (new RegExp(`^(OpenAI|Copilot|Anthropic|Kimi|RC(?:-[^\\s]+)?)(?:\\s+(?:(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d|Sk5h|SkW)\\d{1,3}|St|(?:R|E\\+?)${compactResetValue})))*$`).test(line)) {
+        return true;
+    }
+    if (new RegExp(`^${legacyProvider}(?:\\s+(?:(?:Daily\\s+\\$[\\d.,]+\\/\\$[\\d.,]+|\\$[\\d.,]+\\/\\$[\\d.,]+)(?:\\s+(?:Rst|Exp\\+?)\\s+${resetValue})?|(?:\\d+[hdw]|Weekly|Monthly)\\s+\\d{1,3}%(?:\\s+Rst\\s+${resetValue})?|(?:error|unsupported|unavailable|stale)))$`).test(line)) {
+        return true;
+    }
+    if (new RegExp(`^${legacyProvider}(?:\\s+(?:D\\$?[\\d.,]+\\/\\$?[\\d.,]+|B(?:[￥$-])?[\\d.,]+|(?:\\d+[hdw]|[DWM])\\d{1,3}|(?:S7d|O7d|OA7d|Co7d)\\d{1,3}|St|(?:R|E\\+?)${compactResetValue}))*$`).test(line)) {
         return true;
     }
     return false;

package/dist/tools.d.ts

@@ -1,6 +1,8 @@
 import * as z from 'zod';
 import type { QuotaSnapshot } from './types.js';
 import type { UsageSummary } from './usage.js';
+import type { HistoryPeriod } from './period.js';
+import type { HistoryUsageResult } from './usage_service.js';
 type ToolContext = {
     sessionID: string;
 };
@@ -19,6 +21,8 @@ export declare function createQuotaSidebarTools(deps: {
     restoreSessionTitle?: (sessionID: string) => Promise<boolean>;
     showToast: (period: 'session' | 'day' | 'week' | 'month' | 'toggle', message: string) => Promise<void>;
     summarizeForTool: (period: 'session' | 'day' | 'week' | 'month', sessionID: string, includeChildren: boolean) => Promise<UsageSummary>;
+    summarizeHistoryForTool: (period: HistoryPeriod, since: string) => Promise<HistoryUsageResult>;
+    listCurrentProviderIDs?: () => Promise<Set<string>>;
     getQuotaSnapshots: (providerIDs: string[], options?: {
         allowDefault?: boolean;
     }) => Promise<QuotaSnapshot[]>;
@@ -29,6 +33,9 @@ export declare function createQuotaSidebarTools(deps: {
         showCost?: boolean;
         width?: number;
     }) => string;
+    renderHistoryMarkdownReport: (result: HistoryUsageResult, quotas: QuotaSnapshot[], options?: {
+        showCost?: boolean;
+    }) => string;
     config: {
         sidebar: {
             showCost: boolean;
@@ -42,16 +49,20 @@ export declare function createQuotaSidebarTools(deps: {
         description: string;
         args: {
             period: z.ZodOptional<z.ZodEnum<{
-                day: "day";
-                week: "week";
                 month: "month";
+                day: "day";
                 session: "session";
+                week: "week";
             }>>;
+            since: z.ZodOptional<z.ZodString>;
+            last: z.ZodOptional<z.ZodNumber>;
             toast: z.ZodOptional<z.ZodBoolean>;
             includeChildren: z.ZodOptional<z.ZodBoolean>;
         };
         execute: (args: {
-            period?: "day" | "week" | "month" | "session" | undefined;
+            period?: "month" | "day" | "session" | "week" | undefined;
+            since?: string | undefined;
+            last?: number | undefined;
             toast?: boolean | undefined;
             includeChildren?: boolean | undefined;
         }, context: ToolContext) => Promise<string>;

package/dist/tools.js

@@ -1,4 +1,6 @@
 import * as z from 'zod';
+import { sinceFromLast } from './period.js';
+import { filterHistoryProvidersForDisplay, filterUsageProvidersForDisplay, } from './provider_catalog.js';
 function tool(input) {
     return input;
 }
@@ -16,6 +18,16 @@ export function createQuotaSidebarTools(deps) {
             description: 'Show usage and quota summary for session/day/week/month. Returns the full markdown report with totals, highlights, provider table, and subscription quota so callers can present the report directly to the user.',
             args: {
                 period: z.enum(['session', 'day', 'week', 'month']).optional(),
+                since: z
+                    .string()
+                    .optional()
+                    .describe('Historical start date: `YYYY-MM` or `YYYY-MM-DD`.'),
+                last: z
+                    .number()
+                    .int()
+                    .positive()
+                    .optional()
+                    .describe('Relative history length. Examples: `period=day,last=7`, `period=week,last=8`, `period=month,last=6`.'),
                 toast: z.boolean().optional(),
                 includeChildren: z
                     .boolean()
@@ -23,11 +35,51 @@ export function createQuotaSidebarTools(deps) {
                     .describe('For period=session, include descendant subagent sessions in usage aggregation.'),
             },
             execute: async (args, context) => {
-                const period = args.period || 'session';
+                const period = args.period || (args.since || args.last ? 'month' : 'session');
+                const since = args.since?.trim();
+                const last = args.last;
+                if (since && last !== undefined) {
+                    throw new Error('`since` and `last` cannot be used together');
+                }
+                if (period === 'session' && since) {
+                    throw new Error('`since` is not supported when `period=session`');
+                }
+                if (period === 'session' && last !== undefined) {
+                    throw new Error('`last` is not supported when `period=session`');
+                }
+                const resolvedSince = since ||
+                    (period !== 'session' && last !== undefined
+                        ? sinceFromLast(period, last)
+                        : undefined);
+                const allowedProviderIDs = await deps
+                    .listCurrentProviderIDs?.()
+                    .catch(() => new Set());
+                if (period !== 'session' && resolvedSince) {
+                    const historyRaw = await deps.summarizeHistoryForTool(period, resolvedSince);
+                    const history = allowedProviderIDs
+                        ? filterHistoryProvidersForDisplay(historyRaw, allowedProviderIDs)
+                        : historyRaw;
+                    const quotas = await deps.getQuotaSnapshots([], {
+                        allowDefault: true,
+                    });
+                    const markdown = deps.renderHistoryMarkdownReport(history, quotas, {
+                        showCost: deps.config.sidebar.showCost,
+                    });
+                    if (args.toast === true) {
+                        await deps.showToast(period, deps.renderToastMessage(period, history.total, quotas, {
+                            showCost: deps.config.sidebar.showCost,
+                            width: Math.max(44, deps.config.sidebar.width + 18),
+                        }));
+                    }
+                    return markdown;
+                }
                 const includeChildren = period === 'session'
                     ? (args.includeChildren ?? deps.config.sidebar.includeChildren)
                     : false;
-                const usage = await deps.summarizeForTool(period, context.sessionID, includeChildren);
+                const usageRaw = await deps.summarizeForTool(period, context.sessionID, includeChildren);
+                const usage = allowedProviderIDs
+                    ? filterUsageProvidersForDisplay(usageRaw, allowedProviderIDs)
+                    : usageRaw;
                 // 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 });