sidekick-shared 0.28.1 → 0.28.3

package/dist/quota.js

@@ -2,9 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QUOTA_AGING_MAX_AGE_MS = exports.QUOTA_FRESH_MAX_AGE_MS = exports.SEVEN_DAY_WINDOW_MS = exports.FIVE_HOUR_WINDOW_MS = exports.QUOTA_PROVIDER_IDS = void 0;
 exports.classifyQuotaFreshness = classifyQuotaFreshness;
+exports.quotaWindowApplies = quotaWindowApplies;
+exports.quotaWindowHasData = quotaWindowHasData;
+exports.quotaSampleExpired = quotaSampleExpired;
+exports.quotaWindowLabel = quotaWindowLabel;
+exports.quotaWindowShortLabel = quotaWindowShortLabel;
+exports.extraQuotaRows = extraQuotaRows;
+exports.claudePlanLabel = claudePlanLabel;
+exports.formatExtraUsage = formatExtraUsage;
 exports.formatQuotaAge = formatQuotaAge;
 exports.projectQuotaWindow = projectQuotaWindow;
 exports.withQuotaProjections = withQuotaProjections;
+exports.quotaStateFromClaudeUsagePayload = quotaStateFromClaudeUsagePayload;
+exports.withClaudePlan = withClaudePlan;
 exports.fetchQuota = fetchQuota;
 var providerIds_1 = require("./providerIds");
 Object.defineProperty(exports, "QUOTA_PROVIDER_IDS", { enumerable: true, get: function () { return providerIds_1.QUOTA_PROVIDER_IDS; } });
@@ -27,6 +37,126 @@ function classifyQuotaFreshness(ageMs) {
         return 'aging';
     return 'stale';
 }
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+/** Whether the provider reports this window for the account at all. */
+function quotaWindowApplies(window) {
+    return Boolean(window) && window?.absent !== true;
+}
+/** Whether the window applies and carries a reading worth showing (a reset time or any usage). */
+function quotaWindowHasData(window) {
+    if (!window || window.absent === true)
+        return false;
+    return Boolean(window.resetsAt) || window.utilization > 0;
+}
+function usableWindowMs(windowMs) {
+    return typeof windowMs === 'number' && Number.isFinite(windowMs) && windowMs > 0
+        ? windowMs
+        : undefined;
+}
+/**
+ * True when every window of a sample that has a known reset time has already
+ * reset by `nowMs`. Such a sample says nothing about current usage — showing
+ * it as live would print old percentages with "resets now". Samples without
+ * any reset time are never considered expired.
+ */
+function quotaSampleExpired(quota, nowMs = Date.now()) {
+    const resets = [quota.fiveHour, quota.sevenDay]
+        .filter((window) => !window.absent && window.resetsAt)
+        .map((window) => Date.parse(window.resetsAt))
+        .filter((ms) => Number.isFinite(ms));
+    return resets.length > 0 && resets.every((ms) => ms <= nowMs);
+}
+/**
+ * Human label for a window length: `5-Hour`, `Daily`, `Weekly`, `30-Day`, …
+ * Returns `fallback` when the length is unknown or not a whole number of hours.
+ */
+function quotaWindowLabel(windowMs, fallback) {
+    const ms = usableWindowMs(windowMs);
+    if (ms === undefined)
+        return fallback;
+    if (ms === DAY_MS)
+        return 'Daily';
+    if (ms === 7 * DAY_MS)
+        return 'Weekly';
+    if (ms % DAY_MS === 0)
+        return `${ms / DAY_MS}-Day`;
+    if (ms % HOUR_MS === 0)
+        return `${ms / HOUR_MS}-Hour`;
+    return fallback;
+}
+/** Compact label for a window length: `5h`, `1d`, `7d`. Returns `fallback` when unknown. */
+function quotaWindowShortLabel(windowMs, fallback) {
+    const ms = usableWindowMs(windowMs);
+    if (ms === undefined)
+        return fallback;
+    if (ms % DAY_MS === 0)
+        return `${ms / DAY_MS}d`;
+    if (ms % HOUR_MS === 0)
+        return `${ms / HOUR_MS}h`;
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    return fallback;
+}
+/**
+ * The reported meters that `fiveHour` and `sevenDay` do not already show —
+ * per-model or per-surface weekly caps and any future meter kind.
+ */
+function extraQuotaRows(quota) {
+    return (quota.limits ?? []).filter((row) => row.kind !== 'session' && row.kind !== 'weekly_all');
+}
+/**
+ * Display name for a Claude subscription. The 20× tier was renamed Ultra and
+ * the 5× tier Max on 2026-10-30; credentials keep the old tier ids.
+ */
+function claudePlanLabel(plan) {
+    const tier = plan?.rateLimitTier?.trim().toLowerCase() ?? '';
+    if (tier.includes('ultra') || tier.includes('max_20x'))
+        return 'Ultra';
+    if (tier.includes('max_5x'))
+        return 'Max';
+    const subscription = plan?.subscriptionType?.trim().toLowerCase();
+    if (!subscription)
+        return undefined;
+    return subscription.charAt(0).toUpperCase() + subscription.slice(1);
+}
+function formatMinorUnits(amount, currency, decimals) {
+    const value = amount / 10 ** decimals;
+    if (currency) {
+        try {
+            return new Intl.NumberFormat('en-US', {
+                style: 'currency',
+                currency,
+                minimumFractionDigits: decimals,
+                maximumFractionDigits: decimals,
+            }).format(value);
+        }
+        catch {
+            return `${value.toFixed(decimals)} ${currency}`;
+        }
+    }
+    return value.toFixed(decimals);
+}
+/**
+ * One-line extra-usage summary, e.g. `$12.40 of $200.00 used` or
+ * `$0.00 of $200.00 used · off (out of credits)`.
+ */
+function formatExtraUsage(extra) {
+    const decimals = typeof extra.decimalPlaces === 'number' &&
+        Number.isInteger(extra.decimalPlaces) &&
+        extra.decimalPlaces >= 0 &&
+        extra.decimalPlaces <= 6
+        ? extra.decimalPlaces
+        : 2;
+    const used = formatMinorUnits(extra.usedCredits ?? 0, extra.currency, decimals);
+    const amount = extra.monthlyLimit !== null
+        ? `${used} of ${formatMinorUnits(extra.monthlyLimit, extra.currency, decimals)} used`
+        : `${used} used`;
+    if (extra.enabled)
+        return amount;
+    const reason = extra.disabledReason ? ` (${extra.disabledReason.replace(/_/g, ' ')})` : '';
+    return `${amount} · off${reason}`;
+}
 /** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
 function formatQuotaAge(ageMs) {
     if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
@@ -65,21 +195,21 @@ function withQuotaProjections(state, options = {}) {
         return state;
     const next = { ...state };
     const capturedAt = options.capturedAt ?? state.capturedAt;
-    if (next.projectedFiveHour == null) {
+    if (next.projectedFiveHour == null && !next.fiveHour.absent) {
         const projected = projectQuotaWindow({
             utilization: next.fiveHour.utilization,
             resetsAt: next.fiveHour.resetsAt,
-            windowMs: options.fiveHourWindowMs ?? exports.FIVE_HOUR_WINDOW_MS,
+            windowMs: options.fiveHourWindowMs ?? usableWindowMs(next.fiveHour.windowMs) ?? exports.FIVE_HOUR_WINDOW_MS,
             capturedAt,
         });
         if (projected !== undefined)
             next.projectedFiveHour = projected;
     }
-    if (next.projectedSevenDay == null) {
+    if (next.projectedSevenDay == null && !next.sevenDay.absent) {
         const projected = projectQuotaWindow({
             utilization: next.sevenDay.utilization,
             resetsAt: next.sevenDay.resetsAt,
-            windowMs: options.sevenDayWindowMs ?? exports.SEVEN_DAY_WINDOW_MS,
+            windowMs: options.sevenDayWindowMs ?? usableWindowMs(next.sevenDay.windowMs) ?? exports.SEVEN_DAY_WINDOW_MS,
             capturedAt,
         });
         if (projected !== undefined)
@@ -87,6 +217,235 @@ function withQuotaProjections(state, options = {}) {
     }
     return next;
 }
+// ── Claude usage endpoint payload ──
+/** Hard cap on parsed meter rows, matching Claude Code's own bound. */
+const MAX_LIMIT_ROWS = 64;
+const MAX_LABEL_LENGTH = 128;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nullableFiniteNumber(value) {
+    return finiteNumber(value) ?? null;
+}
+function shortString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed && trimmed.length <= MAX_LABEL_LENGTH ? trimmed : undefined;
+}
+function displayName(value) {
+    return isRecord(value) ? shortString(value.display_name) : undefined;
+}
+function usageWindow(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        utilization: finiteNumber(value.utilization) ?? 0,
+        resetsAt: typeof value.resets_at === 'string' ? value.resets_at : '',
+    };
+}
+function absentWindow() {
+    return { utilization: 0, resetsAt: '', absent: true };
+}
+function windowMsForMeter(kind, group) {
+    if (kind === 'session' || group === 'session')
+        return exports.FIVE_HOUR_WINDOW_MS;
+    if (group === 'weekly' || kind.startsWith('weekly'))
+        return exports.SEVEN_DAY_WINDOW_MS;
+    if (group === 'daily')
+        return DAY_MS;
+    return undefined;
+}
+function titleCase(value) {
+    return value
+        .split(/[_\s-]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+function meterLabel(kind, group, scope) {
+    let base;
+    if (kind === 'session' || group === 'session')
+        base = '5-Hour';
+    else if (group === 'weekly' || kind.startsWith('weekly'))
+        base = '7-Day';
+    else if (group === 'daily')
+        base = 'Daily';
+    else
+        base = titleCase(group || kind) || kind;
+    return scope ? `${base} (${scope})` : base;
+}
+function weeklySharesByIndex(value) {
+    const shares = new Map();
+    if (!Array.isArray(value))
+        return shares;
+    for (const entry of value.slice(0, MAX_LIMIT_ROWS)) {
+        if (!isRecord(entry))
+            continue;
+        const index = finiteNumber(entry.limit_index);
+        if (index === undefined || !Number.isInteger(index) || index < 0)
+            continue;
+        shares.set(index, {
+            allowance: finiteNumber(entry.allowance_percent_of_weekly),
+            used: finiteNumber(entry.used_percent_of_weekly),
+        });
+    }
+    return shares;
+}
+function buildMeterRow(input, capturedAt) {
+    const windowMs = windowMsForMeter(input.kind, input.group);
+    const projected = windowMs !== undefined
+        ? projectQuotaWindow({
+            utilization: input.utilization,
+            resetsAt: input.resetsAt,
+            windowMs,
+            capturedAt,
+        })
+        : undefined;
+    return {
+        kind: input.kind,
+        group: input.group,
+        label: meterLabel(input.kind, input.group, input.scopeModel ?? input.scopeSurface),
+        utilization: input.utilization,
+        resetsAt: input.resetsAt,
+        ...(windowMs !== undefined ? { windowMs } : {}),
+        ...(projected !== undefined ? { projected } : {}),
+        ...(input.scopeModel ? { scopeModel: input.scopeModel } : {}),
+        ...(input.scopeSurface ? { scopeSurface: input.scopeSurface } : {}),
+        ...(input.severity ? { severity: input.severity } : {}),
+        ...(input.isActive !== undefined ? { isActive: input.isActive } : {}),
+        ...(input.share?.allowance !== undefined
+            ? { allowancePercentOfWeekly: input.share.allowance }
+            : {}),
+        ...(input.share?.used !== undefined ? { usedPercentOfWeekly: input.share.used } : {}),
+    };
+}
+function parseLimitRows(value, sharesValue, capturedAt) {
+    if (!Array.isArray(value))
+        return undefined;
+    const shares = weeklySharesByIndex(sharesValue);
+    const rows = [];
+    value.slice(0, MAX_LIMIT_ROWS).forEach((raw, index) => {
+        if (!isRecord(raw))
+            return;
+        const kind = shortString(raw.kind);
+        const percent = finiteNumber(raw.percent);
+        if (!kind || percent === undefined)
+            return;
+        const scope = isRecord(raw.scope) ? raw.scope : undefined;
+        rows.push(buildMeterRow({
+            kind,
+            group: shortString(raw.group) ?? '',
+            utilization: Math.max(0, percent),
+            resetsAt: typeof raw.resets_at === 'string' ? raw.resets_at : '',
+            scopeModel: displayName(scope?.model),
+            scopeSurface: displayName(scope?.surface),
+            severity: shortString(raw.severity),
+            isActive: typeof raw.is_active === 'boolean' ? raw.is_active : undefined,
+            share: shares.get(index),
+        }, capturedAt));
+    });
+    return rows;
+}
+/** Pre-`limits[]` per-model weekly fields, read only when the server sends no `limits[]`. */
+const LEGACY_SCOPED_WEEKLY_FIELDS = [
+    ['seven_day_opus', 'Opus'],
+    ['seven_day_sonnet', 'Sonnet'],
+    ['seven_day_overage_included', 'Fable'],
+];
+function legacyScopedRows(data, capturedAt) {
+    const rows = [];
+    for (const [field, model] of LEGACY_SCOPED_WEEKLY_FIELDS) {
+        const window = usageWindow(data[field]);
+        if (!window)
+            continue;
+        rows.push(buildMeterRow({
+            kind: 'weekly_scoped',
+            group: 'weekly',
+            utilization: window.utilization,
+            resetsAt: window.resetsAt,
+            scopeModel: model,
+        }, capturedAt));
+    }
+    return rows;
+}
+function parseExtraUsage(value) {
+    if (!isRecord(value) || typeof value.is_enabled !== 'boolean')
+        return undefined;
+    const decimalPlaces = finiteNumber(value.decimal_places);
+    return {
+        enabled: value.is_enabled,
+        monthlyLimit: nullableFiniteNumber(value.monthly_limit),
+        usedCredits: nullableFiniteNumber(value.used_credits),
+        utilization: nullableFiniteNumber(value.utilization),
+        ...(shortString(value.currency) ? { currency: shortString(value.currency) } : {}),
+        ...(decimalPlaces !== undefined ? { decimalPlaces } : {}),
+        ...(shortString(value.disabled_reason)
+            ? { disabledReason: shortString(value.disabled_reason) }
+            : {}),
+    };
+}
+function windowFromMeter(row) {
+    return row ? { utilization: row.utilization, resetsAt: row.resetsAt } : null;
+}
+/**
+ * Normalize a Claude OAuth usage-endpoint body into a `QuotaState`.
+ *
+ * - `five_hour`/`seven_day` that are null or missing become `absent` windows
+ *   (Ultra plans have no five-hour session limit), unless `limits[]` carries
+ *   the matching `session`/`weekly_all` meter.
+ * - `limits[]` is kept verbatim as `limits` (with derived labels, window
+ *   lengths, and projections); older servers' `seven_day_opus` /
+ *   `seven_day_sonnet` / `seven_day_overage_included` fill it instead.
+ * - `extra_usage` becomes `extraUsage`.
+ *
+ * Bodies in the original two-window shape produce exactly the state they did
+ * before these fields existed.
+ */
+function quotaStateFromClaudeUsagePayload(payload, options = {}) {
+    const data = isRecord(payload) ? payload : {};
+    const capturedAt = options.capturedAt;
+    const parsedLimits = parseLimitRows(data.limits, data.weekly_scoped_shares, capturedAt);
+    const legacyRows = parsedLimits === undefined ? legacyScopedRows(data, capturedAt) : [];
+    const limits = parsedLimits ?? (legacyRows.length > 0 ? legacyRows : undefined);
+    const fiveHour = usageWindow(data.five_hour) ??
+        windowFromMeter(parsedLimits?.find((row) => row.kind === 'session')) ??
+        absentWindow();
+    const sevenDay = usageWindow(data.seven_day) ??
+        windowFromMeter(parsedLimits?.find((row) => row.kind === 'weekly_all')) ??
+        absentWindow();
+    const extraUsage = parseExtraUsage(data.extra_usage);
+    const projectedFiveHour = fiveHour.absent
+        ? undefined
+        : projectQuotaWindow({ ...fiveHour, windowMs: exports.FIVE_HOUR_WINDOW_MS, capturedAt });
+    const projectedSevenDay = sevenDay.absent
+        ? undefined
+        : projectQuotaWindow({ ...sevenDay, windowMs: exports.SEVEN_DAY_WINDOW_MS, capturedAt });
+    return {
+        fiveHour,
+        sevenDay,
+        available: true,
+        projectedFiveHour,
+        projectedSevenDay,
+        ...(limits ? { limits } : {}),
+        ...(extraUsage ? { extraUsage } : {}),
+    };
+}
+/** Stamp `planType` / `planLabel` from Claude credential plan facts (no-op without them). */
+function withClaudePlan(state, plan) {
+    const planLabel = claudePlanLabel(plan);
+    const planType = plan?.subscriptionType?.trim() || undefined;
+    if (!planLabel && !planType)
+        return state;
+    return {
+        ...state,
+        ...(planType ? { planType } : {}),
+        ...(planLabel ? { planLabel } : {}),
+    };
+}
 /**
  * Helper to build an unavailable QuotaState.
  */
@@ -119,6 +478,7 @@ function parseRetryAfterMs(retryAfter) {
  *
  * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
  * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
+ * @param options.plan - Plan facts from the same credentials; stamps `planType` and `planLabel`
  * @returns QuotaState with utilization data and elapsed-time projections
  */
 async function fetchQuota(accessToken, options = {}) {
@@ -161,26 +521,8 @@ async function fetchQuota(accessToken, options = {}) {
                 httpStatus: res.status,
             });
         }
-        const data = await res.json();
-        const fiveUtil = data.five_hour?.utilization ?? 0;
-        const sevenUtil = data.seven_day?.utilization ?? 0;
-        const fiveResetsAt = data.five_hour?.resets_at ?? '';
-        const sevenResetsAt = data.seven_day?.resets_at ?? '';
-        return {
-            fiveHour: { utilization: fiveUtil, resetsAt: fiveResetsAt },
-            sevenDay: { utilization: sevenUtil, resetsAt: sevenResetsAt },
-            available: true,
-            projectedFiveHour: projectQuotaWindow({
-                utilization: fiveUtil,
-                resetsAt: fiveResetsAt,
-                windowMs: exports.FIVE_HOUR_WINDOW_MS,
-            }),
-            projectedSevenDay: projectQuotaWindow({
-                utilization: sevenUtil,
-                resetsAt: sevenResetsAt,
-                windowMs: exports.SEVEN_DAY_WINDOW_MS,
-            }),
-        };
+        const state = quotaStateFromClaudeUsagePayload(await res.json());
+        return withClaudePlan(state, options.plan);
     }
     catch {
         return unavailableState('Network error', { failureKind: 'network' });

package/dist/quotaHistory.d.ts

@@ -6,6 +6,7 @@
  * dashboard, the `sidekick quota history` CLI, external consumers) can render heatmaps and
  * trend visualisations over a 13-week window.
  */
+import type { QuotaState } from './quota';
 import type { RuntimeQuotaProviderId } from './providerIds';
 export type QuotaHistoryRuntimeProvider = RuntimeQuotaProviderId;
 export interface QuotaHistorySample {
@@ -13,13 +14,16 @@ export interface QuotaHistorySample {
     runtimeProvider: QuotaHistoryRuntimeProvider;
     providerId: string;
     workspaceId: string;
+    /** `absent` marks a window the plan does not have (e.g. Ultra's five-hour limit). */
     fiveHour: {
         utilization: number;
         resetsAt: string;
+        absent?: boolean;
     };
     sevenDay: {
         utilization: number;
         resetsAt: string;
+        absent?: boolean;
     };
     available: boolean;
     error?: string;
@@ -54,6 +58,12 @@ export interface QuotaHistoryDailyBucket {
  * Shared between the VS Code extension (workspace folder fsPath) and the CLI (process.cwd()).
  */
 export declare function getWorkspaceIdFromPath(workspacePath: string): string;
+/**
+ * Project a quota window onto the history-sample shape, keeping the `absent`
+ * marker so summaries and the derived snapshot do not mistake "no such
+ * window" for "0% used".
+ */
+export declare function quotaHistoryWindow(window: QuotaState['fiveHour']): QuotaHistorySample['fiveHour'];
 export declare function appendQuotaHistorySample(sample: QuotaHistorySample, options?: QuotaHistoryAppendOptions): Promise<void>;
 export declare function readQuotaHistoryRange(options: QuotaHistoryRangeOptions): Promise<QuotaHistorySample[]>;
 export declare function readQuotaHistoryDailyBuckets(options: QuotaHistoryRangeOptions): Promise<QuotaHistoryDailyBucket[]>;

package/dist/quotaHistory.js

@@ -42,6 +42,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getWorkspaceIdFromPath = getWorkspaceIdFromPath;
+exports.quotaHistoryWindow = quotaHistoryWindow;
 exports.appendQuotaHistorySample = appendQuotaHistorySample;
 exports.readQuotaHistoryRange = readQuotaHistoryRange;
 exports.readQuotaHistoryDailyBuckets = readQuotaHistoryDailyBuckets;
@@ -200,11 +201,26 @@ function pruneFileSync(filePath, retentionDays) {
     }
     return { kept: keptLines.length, pruned };
 }
+function historyWindowToQuota(window) {
+    return {
+        utilization: window.utilization,
+        resetsAt: window.resetsAt,
+        ...(window.absent ? { absent: true } : {}),
+    };
+}
+/**
+ * Project a quota window onto the history-sample shape, keeping the `absent`
+ * marker so summaries and the derived snapshot do not mistake "no such
+ * window" for "0% used".
+ */
+function quotaHistoryWindow(window) {
+    return historyWindowToQuota(window);
+}
 function sampleToQuotaState(sample) {
     const providerId = runtimeProviderToSnapshotProvider(sample.runtimeProvider);
     return {
-        fiveHour: { utilization: sample.fiveHour.utilization, resetsAt: sample.fiveHour.resetsAt },
-        sevenDay: { utilization: sample.sevenDay.utilization, resetsAt: sample.sevenDay.resetsAt },
+        fiveHour: historyWindowToQuota(sample.fiveHour),
+        sevenDay: historyWindowToQuota(sample.sevenDay),
         available: sample.available,
         error: sample.error,
         providerId,
@@ -370,12 +386,22 @@ async function readQuotaHistoryDailyBuckets(options) {
             let maxSeven = 0;
             let sumFive = 0;
             let sumSeven = 0;
+            // Averages count only samples where the window exists, so a plan without
+            // a five-hour limit does not drag the five-hour average toward zero.
+            let fiveCount = 0;
+            let sevenCount = 0;
             let anyUnavailable = false;
             for (const s of daySamples) {
-                maxFive = Math.max(maxFive, s.fiveHour.utilization);
-                maxSeven = Math.max(maxSeven, s.sevenDay.utilization);
-                sumFive += s.fiveHour.utilization;
-                sumSeven += s.sevenDay.utilization;
+                if (!s.fiveHour.absent) {
+                    maxFive = Math.max(maxFive, s.fiveHour.utilization);
+                    sumFive += s.fiveHour.utilization;
+                    fiveCount += 1;
+                }
+                if (!s.sevenDay.absent) {
+                    maxSeven = Math.max(maxSeven, s.sevenDay.utilization);
+                    sumSeven += s.sevenDay.utilization;
+                    sevenCount += 1;
+                }
                 if (!s.available)
                     anyUnavailable = true;
             }
@@ -385,8 +411,8 @@ async function readQuotaHistoryDailyBuckets(options) {
                 samples: n,
                 maxUtilizationFiveHour: maxFive,
                 maxUtilizationSevenDay: maxSeven,
-                avgUtilizationFiveHour: Math.round((sumFive / n) * 100) / 100,
-                avgUtilizationSevenDay: Math.round((sumSeven / n) * 100) / 100,
+                avgUtilizationFiveHour: fiveCount ? Math.round((sumFive / fiveCount) * 100) / 100 : 0,
+                avgUtilizationSevenDay: sevenCount ? Math.round((sumSeven / sevenCount) * 100) / 100 : 0,
                 anyUnavailable,
             });
         }

package/dist/quotaPoller.d.ts

@@ -6,13 +6,17 @@
  *
  * @module quotaPoller
  */
-import type { QuotaState } from './quota';
+import type { ClaudePlanInfo, QuotaState } from './quota';
 import { type AccountsChangedEvent } from './accountChanges';
 /** Disposable subscription handle. */
 export interface Disposable {
     dispose(): void;
 }
 /** Options for QuotaPoller construction. */
+/** Credential fields the poller reads when `getAccessToken` returns a record. */
+export interface QuotaPollerCredentials extends ClaudePlanInfo {
+    accessToken: string;
+}
 export interface QuotaPollerOptions {
     /** Polling interval when actively monitored (ms). Default: 60_000 (1 minute). */
     activeIntervalMs?: number;
@@ -20,8 +24,12 @@ export interface QuotaPollerOptions {
     idleIntervalMs?: number;
     /** Maximum backoff delay for retries (ms). Default: 120_000 (2 minutes). */
     maxBackoffMs?: number;
-    /** Returns the current access token. Called before each fetch. */
-    getAccessToken: () => Promise<string | null | undefined>;
+    /**
+     * Returns the current access token, or the credentials record itself so the
+     * poller can also stamp the subscription plan (`planLabel`, e.g. `Ultra`).
+     * Called before each fetch.
+     */
+    getAccessToken: () => Promise<string | QuotaPollerCredentials | null | undefined>;
     /** Optional cheap account-presence check performed before credential access. */
     hasAccount?: () => boolean | Promise<boolean>;
     /** Override the process-wide login/logout signal (primarily for embedded hosts/tests). */

package/dist/quotaPoller.js

@@ -128,7 +128,8 @@ class QuotaPoller {
                 this.dormant = true;
                 return;
             }
-            const token = await this.getAccessToken();
+            const credentials = await this.getAccessToken();
+            const token = typeof credentials === 'string' ? credentials : credentials?.accessToken;
             if (!token) {
                 if (this.hasAccount) {
                     // The account exists but its token was unreadable (locked keychain,
@@ -144,7 +145,9 @@ class QuotaPoller {
                 }
                 return;
             }
-            const state = await (0, quota_1.fetchQuota)(token);
+            const state = await (0, quota_1.fetchQuota)(token, {
+                plan: typeof credentials === 'object' && credentials !== null ? credentials : null,
+            });
             if (state.available) {
                 this.latest = state;
                 this.consecutiveFailures = 0;

package/dist/quotaResolver.js

@@ -66,9 +66,18 @@ function resolveIdentity(options) {
             return { accountId: options.accountId ?? ZAI_DEFAULT_ACCOUNT_ID, codexAccount: null };
     }
 }
-async function defaultClaudeAccessToken() {
+/** Token plus the plan facts stored beside it (the plan label needs no extra read). */
+async function claudeTokenAndPlan(options) {
+    if (options.getClaudeAccessToken) {
+        return { token: await options.getClaudeAccessToken(), plan: null };
+    }
     const credentials = await (0, credentials_1.readClaudeMaxCredentials)();
-    return credentials?.accessToken ?? null;
+    return {
+        token: credentials?.accessToken ?? null,
+        plan: credentials
+            ? { subscriptionType: credentials.subscriptionType, rateLimitTier: credentials.rateLimitTier }
+            : null,
+    };
 }
 function zeroWindows() {
     return { fiveHour: { utilization: 0, resetsAt: '' }, sevenDay: { utilization: 0, resetsAt: '' } };
@@ -87,7 +96,7 @@ function unavailableState(providerId, error, capturedAt) {
 async function fetchFromApi(options, identity, capturedAt) {
     switch (options.providerId) {
         case 'claude-code': {
-            const token = await (options.getClaudeAccessToken ?? defaultClaudeAccessToken)();
+            const { token, plan } = await claudeTokenAndPlan(options);
             if (!token) {
                 return {
                     ...zeroWindows(),
@@ -99,7 +108,7 @@ async function fetchFromApi(options, identity, capturedAt) {
                     capturedAt,
                 };
             }
-            const state = await (0, quota_1.fetchQuota)(token, { fetchImpl: options.fetchImpl });
+            const state = await (0, quota_1.fetchQuota)(token, { fetchImpl: options.fetchImpl, plan });
             return { ...state, providerId: 'claude-code', source: 'api', capturedAt };
         }
         case 'codex':
@@ -181,7 +190,10 @@ async function resolveQuota(options) {
     const stored = identity.accountId
         ? readSnapshot(snapshotProviderId(providerId), identity.accountId, now)
         : null;
-    const snapshot = stored?.available ? stored : null;
+    // A sample whose every window has reset since says nothing about current
+    // usage; it is reported as expired instead of being shown as live numbers.
+    const storedExpired = Boolean(stored?.available && (0, quota_1.quotaSampleExpired)(stored, now.getTime()));
+    const snapshot = stored?.available && !storedExpired ? stored : null;
     if (preferFresh && snapshot && snapshot.freshness === 'fresh') {
         return finish(snapshot, 'snapshot-fresh');
     }
@@ -227,8 +239,21 @@ async function resolveQuota(options) {
         const fallback = finish(snapshot, snapshotResolution(snapshot));
         return apiState ? { ...fallback, failure: (0, quotaPresentation_1.describeQuotaFailure)(apiState) } : fallback;
     }
+    if (storedExpired && stored) {
+        const expired = unavailableState(providerId, expiredSampleMessage(stored, now), capturedAt);
+        return apiState
+            ? { ...finish(expired, 'unavailable'), failure: (0, quotaPresentation_1.describeQuotaFailure)(apiState) }
+            : finish(expired, 'unavailable');
+    }
     return finish(apiState ??
         unavailableState(providerId, stored
             ? 'The last persisted quota sample was unavailable.'
             : 'No quota data is available yet; run the provider once so a sample can be recorded.', capturedAt), 'unavailable');
 }
+function expiredSampleMessage(stored, now) {
+    const capturedMs = stored.capturedAt ? Date.parse(stored.capturedAt) : NaN;
+    const when = Number.isFinite(capturedMs)
+        ? ` from ${new Date(capturedMs).toISOString().slice(0, 10)} (${(0, quota_1.formatQuotaAge)(now.getTime() - capturedMs)})`
+        : '';
+    return `The last quota sample${when} has expired: every window has reset since. No current data.`;
+}