@sreetej510/pi-usage 0.1.1

package/src/normalize-codex.ts

@@ -0,0 +1,187 @@
+import type {
+  AppServerCreditsSnapshot,
+  AppServerRateLimitResetCredits,
+  AppServerRateLimitResponse,
+  AppServerRateLimitSnapshot,
+  AppServerWindowSnapshot,
+  BackendAdditionalRateLimit,
+  BackendCreditsSnapshot,
+  BackendRateLimitDetails,
+  BackendRateLimitResetCredits,
+  BackendWindowSnapshot,
+  CodexUsageReport,
+  NormalizedCredits,
+  NormalizedRateLimitSnapshot,
+  NormalizedRateLimitWindow,
+  RateLimitStatusPayload,
+} from "./types.js";
+import { asBoolean, asNumber, asString, assertObject } from "./utils.js";
+
+export function normalizeBackendPayload(
+  payload: RateLimitStatusPayload,
+  capturedAt: number,
+  source: "pi-auth" | "codex-app-server",
+): CodexUsageReport {
+  const snapshots: NormalizedRateLimitSnapshot[] = [];
+  const planType = asString(payload.plan_type);
+  const bankedResetsAvailable = normalizeResetCreditCount(payload.rate_limit_reset_credits);
+  const primary = normalizeBackendSnapshot("codex", undefined, payload.rate_limit, payload.credits);
+  if (primary) snapshots.push(primary);
+
+  const additional = Array.isArray(payload.additional_rate_limits) ? payload.additional_rate_limits : [];
+  for (const item of additional) {
+    const additionalLimit = assertObject(item, "additional rate limit") as BackendAdditionalRateLimit;
+    const limitId = asString(additionalLimit.metered_feature) ?? asString(additionalLimit.limit_name);
+    if (!limitId) continue;
+    const snapshot = normalizeBackendSnapshot(
+      limitId,
+      asString(additionalLimit.limit_name),
+      additionalLimit.rate_limit,
+      undefined,
+    );
+    if (snapshot) snapshots.push(snapshot);
+  }
+
+  if (snapshots.length === 0) {
+    throw new Error("Codex usage endpoint returned no displayable rate-limit windows.");
+  }
+
+  return { provider: "codex", source, capturedAt, planType, bankedResetsAvailable, snapshots };
+}
+
+function normalizeBackendSnapshot(
+  limitId: string,
+  limitName: string | undefined,
+  rateLimit: unknown,
+  credits: unknown,
+): NormalizedRateLimitSnapshot | undefined {
+  if (rateLimit === null || rateLimit === undefined) {
+    const normalizedCredits = normalizeBackendCredits(credits);
+    return normalizedCredits ? { limitId, limitName, credits: normalizedCredits } : undefined;
+  }
+
+  const details = assertObject(rateLimit, "rate limit") as BackendRateLimitDetails;
+  const primary = normalizeBackendWindow(details.primary_window);
+  const secondary = normalizeBackendWindow(details.secondary_window);
+  const normalizedCredits = normalizeBackendCredits(credits);
+
+  if (!primary && !secondary && !normalizedCredits) return undefined;
+  return { limitId, limitName, primary, secondary, credits: normalizedCredits };
+}
+
+function normalizeBackendWindow(value: unknown): NormalizedRateLimitWindow | undefined {
+  if (value === null || value === undefined) return undefined;
+  const window = assertObject(value, "rate-limit window") as BackendWindowSnapshot;
+  const usedPercent = asNumber(window.used_percent);
+  if (usedPercent === undefined) return undefined;
+  const limitSeconds = asNumber(window.limit_window_seconds);
+  const resetsAt = asNumber(window.reset_at);
+  return {
+    usedPercent,
+    windowMinutes: limitSeconds && limitSeconds > 0 ? Math.ceil(limitSeconds / 60) : undefined,
+    resetsAt,
+  };
+}
+
+function normalizeBackendCredits(value: unknown): NormalizedCredits | undefined {
+  if (value === null || value === undefined) return undefined;
+  const credits = assertObject(value, "credits") as BackendCreditsSnapshot;
+  const hasCredits = asBoolean(credits.has_credits);
+  const unlimited = asBoolean(credits.unlimited);
+  if (hasCredits === undefined || unlimited === undefined) return undefined;
+  return { hasCredits, unlimited, balance: asString(credits.balance) };
+}
+
+export function normalizeAppServerResponse(response: AppServerRateLimitResponse, capturedAt: number): CodexUsageReport {
+  const snapshots: NormalizedRateLimitSnapshot[] = [];
+  const bankedResetsAvailable = normalizeResetCreditCount(response.rateLimitResetCredits);
+  const addSnapshot = (raw: unknown, fallbackId: string) => {
+    const snapshot = normalizeAppServerSnapshot(raw, fallbackId);
+    if (!snapshot) return;
+    const existingIndex = snapshots.findIndex((item) => item.limitId === snapshot.limitId);
+    if (existingIndex >= 0) snapshots[existingIndex] = mergeSnapshot(snapshots[existingIndex], snapshot);
+    else snapshots.push(snapshot);
+  };
+
+  addSnapshot(response.rateLimits, "codex");
+  if (response.rateLimitsByLimitId && typeof response.rateLimitsByLimitId === "object") {
+    for (const [limitId, raw] of Object.entries(response.rateLimitsByLimitId)) {
+      addSnapshot(raw, limitId);
+    }
+  }
+
+  if (snapshots.length === 0) {
+    throw new Error("codex app-server returned no displayable rate-limit windows.");
+  }
+
+  const planType = asAppServerPlanType(response.rateLimits);
+  return {
+    provider: "codex",
+    source: "codex-app-server",
+    capturedAt,
+    planType,
+    bankedResetsAvailable,
+    snapshots,
+  };
+}
+
+function asAppServerPlanType(raw: unknown): string | undefined {
+  if (raw === null || raw === undefined) return undefined;
+  const snapshot = assertObject(raw, "app-server rate-limit snapshot") as AppServerRateLimitSnapshot;
+  return asString(snapshot.planType);
+}
+
+function normalizeAppServerSnapshot(raw: unknown, fallbackId: string): NormalizedRateLimitSnapshot | undefined {
+  if (raw === null || raw === undefined) return undefined;
+  const snapshot = assertObject(raw, "app-server rate-limit snapshot") as AppServerRateLimitSnapshot;
+  const limitId = asString(snapshot.limitId) ?? fallbackId;
+  const limitName = asString(snapshot.limitName);
+  const primary = normalizeAppServerWindow(snapshot.primary);
+  const secondary = normalizeAppServerWindow(snapshot.secondary);
+  const credits = normalizeAppServerCredits(snapshot.credits);
+  if (!primary && !secondary && !credits) return undefined;
+  return { limitId, limitName, primary, secondary, credits };
+}
+
+function normalizeAppServerWindow(value: unknown): NormalizedRateLimitWindow | undefined {
+  if (value === null || value === undefined) return undefined;
+  const window = assertObject(value, "app-server rate-limit window") as AppServerWindowSnapshot;
+  const usedPercent = asNumber(window.usedPercent);
+  if (usedPercent === undefined) return undefined;
+  return {
+    usedPercent,
+    windowMinutes: asNumber(window.windowDurationMins),
+    resetsAt: asNumber(window.resetsAt),
+  };
+}
+
+function normalizeAppServerCredits(value: unknown): NormalizedCredits | undefined {
+  if (value === null || value === undefined) return undefined;
+  const credits = assertObject(value, "app-server credits") as AppServerCreditsSnapshot;
+  const hasCredits = asBoolean(credits.hasCredits);
+  const unlimited = asBoolean(credits.unlimited);
+  if (hasCredits === undefined || unlimited === undefined) return undefined;
+  return { hasCredits, unlimited, balance: asString(credits.balance) };
+}
+
+function normalizeResetCreditCount(value: unknown): number | undefined {
+  if (value === null || value === undefined) return undefined;
+  const credits = assertObject(value, "rate limit reset credits") as
+    | BackendRateLimitResetCredits
+    | AppServerRateLimitResetCredits;
+  const count = asNumber(credits.available_count) ?? asNumber(credits.availableCount);
+  return count !== undefined ? Math.max(0, Math.trunc(count)) : undefined;
+}
+
+function mergeSnapshot(
+  left: NormalizedRateLimitSnapshot,
+  right: NormalizedRateLimitSnapshot,
+): NormalizedRateLimitSnapshot {
+  return {
+    limitId: right.limitId || left.limitId,
+    limitName: right.limitName ?? left.limitName,
+    primary: right.primary ?? left.primary,
+    secondary: right.secondary ?? left.secondary,
+    credits: right.credits ?? left.credits,
+  };
+}

package/src/query.ts

@@ -0,0 +1,121 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { queryAnthropicUsage } from "./anthropic-query.js";
+import { queryViaCodexAppServer } from "./codex-app-server.js";
+import { queryCodexUsageWithFallback, queryViaPiAuth } from "./codex-query.js";
+import { STATUSLINE_RETRY_ATTEMPTS, STATUSLINE_RETRY_DELAY_MS } from "./constants.js";
+import { isRateLimitErrorMessage, isStaleExtensionContextError } from "./errors.js";
+import {
+  anthropicAuthCandidateModels,
+  codexAuthCandidateModels,
+  isAnthropicModel,
+  isOpenAICodexModel,
+} from "./models.js";
+import type { QueryUsageOptions, QueryUsageResult, UsageQueryError, UsageReport, UsageSource } from "./types.js";
+import { delay, errorMessage } from "./utils.js";
+
+export async function queryAllUsage(
+  ctx: ExtensionContext,
+  options: Pick<QueryUsageOptions, "timeoutMs">,
+): Promise<{ reports: UsageReport[]; errors: UsageQueryError[] }> {
+  const hasCodex = codexAuthCandidateModels(ctx).length > 0;
+  const hasAnthropic = anthropicAuthCandidateModels(ctx).length > 0;
+
+  type ProviderResult = { report?: UsageReport; errors: UsageQueryError[] };
+  const empty: ProviderResult = { errors: [] };
+
+  const [codexSettled, anthropicSettled] = await Promise.allSettled([
+    hasCodex ? queryCodexUsageWithFallback(ctx, options.timeoutMs) : Promise.resolve<ProviderResult>(empty),
+    hasAnthropic
+      ? queryAnthropicUsage(ctx, options.timeoutMs).then((report): ProviderResult => ({ report, errors: [] }))
+      : Promise.resolve<ProviderResult>(empty),
+  ]);
+
+  const reports: UsageReport[] = [];
+  const errors: UsageQueryError[] = [];
+
+  const collect = (
+    settled: PromiseSettledResult<{ report?: UsageReport; errors: UsageQueryError[] }>,
+    source: UsageSource,
+  ) => {
+    if (settled.status === "rejected") {
+      if (isStaleExtensionContextError(settled.reason)) throw settled.reason;
+      errors.push({ source, message: errorMessage(settled.reason), cause: settled.reason });
+    } else {
+      if (settled.value.report) reports.push(settled.value.report);
+      errors.push(...settled.value.errors);
+    }
+  };
+  collect(codexSettled, "pi-auth");
+  collect(anthropicSettled, "anthropic-oauth");
+
+  return { reports, errors };
+}
+
+export async function queryUsageWithRetries(
+  ctx: ExtensionContext,
+  options: Pick<QueryUsageOptions, "timeoutMs">,
+): Promise<QueryUsageResult> {
+  let lastResult: QueryUsageResult | undefined;
+  for (let attempt = 1; attempt <= STATUSLINE_RETRY_ATTEMPTS; attempt += 1) {
+    lastResult = await queryUsage(ctx, options);
+    if (lastResult.ok) return lastResult;
+    // Retrying a 429 seconds later only makes the rate limiting worse.
+    if (lastResult.errors.some((error) => isRateLimitErrorMessage(error.message))) {
+      return lastResult;
+    }
+    if (attempt < STATUSLINE_RETRY_ATTEMPTS) {
+      await delay(STATUSLINE_RETRY_DELAY_MS);
+    }
+  }
+  return (
+    lastResult ?? {
+      ok: false,
+      errors: [{ source: "pi-auth", message: "Usage query failed." }],
+    }
+  );
+}
+
+export async function queryUsage(
+  ctx: ExtensionContext,
+  options: Pick<QueryUsageOptions, "timeoutMs">,
+): Promise<QueryUsageResult> {
+  if (isAnthropicModel(ctx.model)) {
+    try {
+      const report = await queryAnthropicUsage(ctx, options.timeoutMs);
+      return { ok: true, report };
+    } catch (cause) {
+      if (isStaleExtensionContextError(cause)) throw cause;
+      return {
+        ok: false,
+        errors: [{ source: "anthropic-oauth", message: errorMessage(cause), cause }],
+      };
+    }
+  }
+
+  if (!isOpenAICodexModel(ctx.model)) {
+    return {
+      ok: false,
+      errors: [{ source: "pi-auth", message: "Current model provider is not supported." }],
+    };
+  }
+
+  const errors: UsageQueryError[] = [];
+
+  try {
+    const report = await queryViaPiAuth(ctx, options.timeoutMs);
+    return { ok: true, report };
+  } catch (cause) {
+    if (isStaleExtensionContextError(cause)) throw cause;
+    errors.push({ source: "pi-auth", message: errorMessage(cause), cause });
+  }
+
+  try {
+    const report = await queryViaCodexAppServer(options.timeoutMs);
+    return { ok: true, report };
+  } catch (cause) {
+    if (isStaleExtensionContextError(cause)) throw cause;
+    errors.push({ source: "codex-app-server", message: errorMessage(cause), cause });
+  }
+
+  return { ok: false, errors };
+}

package/src/shared-cache.ts

@@ -0,0 +1,70 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { RATE_LIMIT_BACKOFF_MAX_MS, SHARED_CACHE_FILE, SHARED_CACHE_VERSION } from "./constants.js";
+import type { SharedCacheEntry, SharedUsageCache, UsageProviderKey, UsageReport } from "./types.js";
+
+export function readSharedUsageCache(): SharedUsageCache | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(SHARED_CACHE_FILE, "utf8")) as SharedUsageCache;
+    if (!parsed || parsed.version !== SHARED_CACHE_VERSION) return undefined;
+    if (!parsed.entries || typeof parsed.entries !== "object") return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeSharedUsageCache(mutate: (cacheFile: SharedUsageCache) => void): void {
+  try {
+    const cacheFile = readSharedUsageCache() ?? { version: SHARED_CACHE_VERSION, entries: {} };
+    mutate(cacheFile);
+    mkdirSync(dirname(SHARED_CACHE_FILE), { recursive: true });
+    const tmpFile = `${SHARED_CACHE_FILE}.${process.pid}.tmp`;
+    writeFileSync(tmpFile, JSON.stringify(cacheFile));
+    try {
+      renameSync(tmpFile, SHARED_CACHE_FILE);
+    } catch {
+      // Windows can refuse to rename over an open file; fall back to direct write.
+      writeFileSync(SHARED_CACHE_FILE, JSON.stringify(cacheFile));
+    }
+  } catch {
+    // Best-effort — a broken shared cache must never break usage display.
+  }
+}
+
+export function saveSharedUsageReport(report: UsageReport): void {
+  writeSharedUsageCache((cacheFile) => {
+    cacheFile.entries[report.provider] = { createdAt: Date.now(), report };
+    if (cacheFile.backoffUntil) delete cacheFile.backoffUntil[report.provider];
+  });
+}
+
+export function clearSharedUsageReport(provider: UsageProviderKey): void {
+  writeSharedUsageCache((cacheFile) => {
+    delete cacheFile.entries[provider];
+  });
+}
+
+export function saveSharedBackoff(provider: UsageProviderKey, untilMs: number): void {
+  // Never persist a backoff further out than the max — protects against
+  // clock skew between sessions producing absurd values.
+  const clamped = Math.min(untilMs, Date.now() + RATE_LIMIT_BACKOFF_MAX_MS);
+  writeSharedUsageCache((cacheFile) => {
+    cacheFile.backoffUntil = { ...(cacheFile.backoffUntil ?? {}), [provider]: clamped };
+  });
+}
+
+export function clearSharedBackoff(): void {
+  writeSharedUsageCache((cacheFile) => {
+    cacheFile.backoffUntil = undefined;
+  });
+}
+
+export function sharedBackoffRemainingMs(provider: UsageProviderKey): number {
+  const until = readSharedUsageCache()?.backoffUntil?.[provider] ?? 0;
+  // Distrust stored timestamps: a skewed clock in another session must not
+  // lock us out for hours. Cap the effective backoff at the configured max.
+  return Math.min(until - Date.now(), RATE_LIMIT_BACKOFF_MAX_MS);
+}
+
+export type { SharedCacheEntry };

package/src/statusline.ts

@@ -0,0 +1,244 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CACHE_TTL_MS, DEFAULT_TIMEOUT_MS, STATUS_KEY } from "./constants.js";
+import { isRateLimitErrorMessage, isStaleExtensionContextError, rateLimitBackoffMs } from "./errors.js";
+import { formatUsageStatusline } from "./format.js";
+import { isUsageSupportedModel, providerKeyForModel, reportMatchesModel } from "./models.js";
+import { queryUsageWithRetries } from "./query.js";
+import {
+  readSharedUsageCache,
+  saveSharedBackoff,
+  saveSharedUsageReport,
+  sharedBackoffRemainingMs,
+} from "./shared-cache.js";
+import type { CachedReport, ProviderUsageModel, UsageReport } from "./types.js";
+import { formatAgeShort } from "./utils.js";
+
+let cache: CachedReport | undefined;
+let combinedCache: { createdAt: number; reports: UsageReport[] } | undefined;
+let statuslineClearTimer: ReturnType<typeof setTimeout> | undefined;
+let statuslineRefreshTimer: ReturnType<typeof setTimeout> | undefined;
+let statuslineRequestId = 0;
+let sessionActive = false;
+let activeStatuslineContext: ExtensionContext | undefined;
+
+export function isSessionActive(): boolean {
+  return sessionActive;
+}
+
+export function setSessionActive(value: boolean): void {
+  sessionActive = value;
+}
+
+export function getCombinedCache(): { createdAt: number; reports: UsageReport[] } | undefined {
+  return combinedCache;
+}
+
+export function setCombinedCache(value: { createdAt: number; reports: UsageReport[] } | undefined): void {
+  combinedCache = value;
+}
+
+export function clearCodexMemoryCache(): void {
+  cache = undefined;
+}
+
+const clearStatuslineTimers = () => {
+  if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
+  if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
+  statuslineClearTimer = undefined;
+  statuslineRefreshTimer = undefined;
+};
+
+export function handleStaleContextError(ctx: ExtensionContext, error: unknown): boolean {
+  if (!isStaleExtensionContextError(error)) return false;
+  if (ctx === activeStatuslineContext) {
+    statuslineRequestId += 1;
+    clearStatuslineTimers();
+    activeStatuslineContext = undefined;
+  }
+  return true;
+}
+
+export const rethrowUnlessStaleContextError = (ctx: ExtensionContext) => (error: unknown) => {
+  if (!handleStaleContextError(ctx, error)) throw error;
+};
+
+const setStatuslineValue = (ctx: ExtensionContext, value: string | undefined): boolean => {
+  try {
+    ctx.ui.setStatus(STATUS_KEY, value);
+    return true;
+  } catch (error) {
+    if (handleStaleContextError(ctx, error)) return false;
+    throw error;
+  }
+};
+
+export function clearUsageStatusline(ctx: ExtensionContext) {
+  statuslineRequestId += 1;
+  clearStatuslineTimers();
+  activeStatuslineContext = undefined;
+  setStatuslineValue(ctx, undefined);
+}
+
+const scheduleTemporaryStatuslineClear = (ctx: ExtensionContext) => {
+  if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
+  const requestId = statuslineRequestId;
+  statuslineClearTimer = setTimeout(() => {
+    statuslineClearTimer = undefined;
+    if (!sessionActive || requestId !== statuslineRequestId) return;
+    setStatuslineValue(ctx, undefined);
+  }, CACHE_TTL_MS);
+  statuslineClearTimer.unref?.();
+};
+
+const scheduleStatuslineRefresh = (
+  ctx: ExtensionContext,
+  model: ProviderUsageModel | undefined,
+  delayMs: number = CACHE_TTL_MS,
+) => {
+  if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
+  const requestId = statuslineRequestId;
+  statuslineRefreshTimer = setTimeout(() => {
+    statuslineRefreshTimer = undefined;
+    if (!sessionActive || requestId !== statuslineRequestId) return;
+    void refreshCurrentUsageStatusline(ctx, model).catch(rethrowUnlessStaleContextError(ctx));
+  }, delayMs);
+  statuslineRefreshTimer.unref?.();
+};
+
+const setUsageStatusline = (
+  ctx: ExtensionContext,
+  report: UsageReport,
+  options: {
+    autoRefresh: boolean;
+    model: ProviderUsageModel | undefined;
+    staleAgeMs?: number;
+    refreshDelayMs?: number;
+  },
+) => {
+  let text = formatUsageStatusline(report, options.model);
+  if (options.staleAgeMs !== undefined && options.staleAgeMs > CACHE_TTL_MS) {
+    text = `${text} (${formatAgeShort(options.staleAgeMs)} old)`;
+  }
+  if (!setStatuslineValue(ctx, text)) return;
+  activeStatuslineContext = ctx;
+  if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
+  statuslineClearTimer = undefined;
+  if (options.autoRefresh) scheduleStatuslineRefresh(ctx, options.model, options.refreshDelayMs);
+  else scheduleTemporaryStatuslineClear(ctx);
+};
+
+const getCachedReportForModel = (model: ProviderUsageModel | undefined): CachedReport | undefined => {
+  let best = cache && reportMatchesModel(cache.report, model) ? cache : undefined;
+  if (combinedCache) {
+    const report = combinedCache.reports.find((item) => reportMatchesModel(item, model));
+    if (report) {
+      const candidate = { createdAt: combinedCache.createdAt, report };
+      if (!best || candidate.createdAt > best.createdAt) best = candidate;
+    }
+  }
+  // Another pi session may have fetched more recently — use its data.
+  const shared = readSharedUsageCache()?.entries?.[providerKeyForModel(model)];
+  if (shared?.report && reportMatchesModel(shared.report, model)) {
+    if (!best || shared.createdAt > best.createdAt) best = shared;
+  }
+  return best;
+};
+
+export async function refreshCurrentUsageStatusline(ctx: ExtensionContext, model?: ProviderUsageModel) {
+  if (!sessionActive) return;
+  activeStatuslineContext = ctx;
+  const selectedModel = model ?? ctx.model;
+  if (!isUsageSupportedModel(selectedModel)) {
+    clearUsageStatusline(ctx);
+    return;
+  }
+
+  const requestId = statuslineRequestId + 1;
+  statuslineRequestId = requestId;
+  const cached = getCachedReportForModel(selectedModel);
+  const freshCached = cached && Date.now() - cached.createdAt < CACHE_TTL_MS ? cached : undefined;
+  // Fresh cache is always good enough — avoids double-fetching when /usage
+  // just updated it or another pi session already fetched. The scheduled
+  // timer fires when the TTL actually expires.
+  if (freshCached) {
+    const remainingMs = CACHE_TTL_MS - (Date.now() - freshCached.createdAt);
+    setUsageStatusline(ctx, freshCached.report, {
+      autoRefresh: true,
+      model: selectedModel,
+      refreshDelayMs: Math.max(remainingMs, 10_000),
+    });
+    return;
+  }
+
+  // Respect a shared rate-limit backoff set by any session.
+  const providerKey = providerKeyForModel(selectedModel);
+  const backoffRemaining = sharedBackoffRemainingMs(providerKey);
+  if (backoffRemaining > 0) {
+    if (cached) {
+      setUsageStatusline(ctx, cached.report, {
+        autoRefresh: true,
+        model: selectedModel,
+        staleAgeMs: Date.now() - cached.report.capturedAt,
+        refreshDelayMs: Math.max(backoffRemaining, 10_000),
+      });
+    } else if (setStatuslineValue(ctx, `usage rate-limited (${formatAgeShort(backoffRemaining)})`)) {
+      scheduleStatuslineRefresh(ctx, selectedModel, Math.max(backoffRemaining, 10_000));
+    }
+    return;
+  }
+
+  if (!cached && !setStatuslineValue(ctx, "checking")) return;
+  const result = await queryUsageWithRetries(ctx, { timeoutMs: DEFAULT_TIMEOUT_MS });
+  if (!sessionActive || requestId !== statuslineRequestId) return;
+
+  if (!result.ok) {
+    const rateLimited = result.errors.some((error) => isRateLimitErrorMessage(error.message));
+    // Honor the server's Retry-After when it sends one; fall back to default.
+    const retryDelayMs = rateLimited ? rateLimitBackoffMs(result.errors) : CACHE_TTL_MS;
+    if (rateLimited) {
+      saveSharedBackoff(providerKey, Date.now() + retryDelayMs);
+    }
+    // Background refreshes fail silently — the statusline text is the only
+    // indicator. Detailed errors are shown when /usage is run explicitly.
+    if (cached) {
+      setUsageStatusline(ctx, cached.report, {
+        autoRefresh: true,
+        model: selectedModel,
+        staleAgeMs: Date.now() - cached.report.capturedAt,
+        refreshDelayMs: retryDelayMs,
+      });
+      return;
+    }
+    const errorLabel = rateLimited ? `usage rate-limited (${formatAgeShort(retryDelayMs)})` : "usage error";
+    if (setStatuslineValue(ctx, errorLabel)) {
+      scheduleStatuslineRefresh(ctx, selectedModel, retryDelayMs);
+    }
+    return;
+  }
+
+  cache = { createdAt: Date.now(), report: result.report };
+  saveSharedUsageReport(result.report);
+  setUsageStatusline(ctx, result.report, { autoRefresh: true, model: selectedModel });
+}
+
+export function applyCurrentProviderStatusline(ctx: ExtensionContext, reports: UsageReport[]): boolean {
+  const current = reports.find((report) => reportMatchesModel(report, ctx.model));
+  if (!current) {
+    setStatuslineValue(ctx, undefined);
+    return false;
+  }
+  cache = { createdAt: Date.now(), report: current };
+  setUsageStatusline(ctx, current, {
+    autoRefresh: isUsageSupportedModel(ctx.model),
+    model: ctx.model,
+  });
+  return true;
+}
+
+export function setStatuslineChecking(ctx: ExtensionContext): boolean {
+  return setStatuslineValue(ctx, "checking");
+}
+
+export function clearStatuslineValue(ctx: ExtensionContext): boolean {
+  return setStatuslineValue(ctx, undefined);
+}