@sreetej510/pi-usage 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 omega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @sreetej510/pi-usage
+
+A [pi](https://github.com/earendil-works/pi) coding agent extension that reports provider
+usage / rate-limit budgets — OpenAI Codex, Anthropic OAuth, and pi-auth-backed providers — via
+`/usage`, with an optional live statusline widget.
+
+## What it does
+
+- Queries the active model's provider usage endpoint (Codex app-server usage/rate-limit-reset
+  APIs, or Anthropic's OAuth usage API) and renders remaining budget/reset windows.
+- Caches results on disk (`~/.pi/agent/usage-cache.json`) for a few minutes so multiple
+  concurrent pi sessions don't hammer the provider APIs.
+- Can push a compact usage summary into the statusline, refreshed automatically with retry/backoff
+  on rate limits (`429`).
+- Supports listing and consuming Codex "banked" rate-limit resets.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/usage` | Show cached usage (fetches fresh data if the cache is stale) |
+| `/usage --refresh` | Force a fresh fetch, bypassing the cache |
+| `/usage --no-statusline` | Don't update the statusline widget |
+| `/usage --clear-statusline` | Clear the usage statusline widget |
+| `/usage --timeout <seconds>` | Set the query timeout |
+| `/usage --raw` | Show raw usage API responses (debugging) |
+| `/usage --list-banked-resets` | List available Codex banked resets and expiry dates |
+| `/usage --consume-banked-reset <id>` | Consume a specific Codex banked reset |
+
+## Install
+
+```bash
+npm install -g @sreetej510/pi-usage
+```
+
+Then add it to your pi `settings.json`:
+
+```json
+{
+  "packages": ["npm:@sreetej510/pi-usage"]
+}
+```
+
+Or, for local development, point at the file directly:
+
+```json
+{
+  "extensions": ["/absolute/path/to/pi-extensions/extensions/pi-usage/src/index.ts"]
+}
+```
+
+## File layout
+
+| File | Responsibility |
+|---|---|
+| `src/index.ts` | Extension entry point + session event wiring |
+| `src/command.ts` | `/usage` command handler |
+| `src/statusline.ts` | Statusline state, timers, background refresh |
+| `src/footer.ts` | Custom footer with right-aligned usage status |
+| `src/query.ts` | Top-level usage query orchestration |
+| `src/codex-query.ts` | Codex pi-auth + app-server fallback queries |
+| `src/anthropic-query.ts` | Anthropic OAuth usage queries |
+| `src/codex-auth.ts` | Codex auth header resolution |
+| `src/anthropic-auth.ts` | Anthropic auth header resolution |
+| `src/codex-app-server.ts` | `codex app-server` RPC client |
+| `src/codex-reset-credits.ts` | Banked reset list/consume/format |
+| `src/normalize-codex.ts` | Codex backend + app-server payload normalization |
+| `src/normalize-anthropic.ts` | Anthropic usage payload normalization |
+| `src/format.ts` | Report/statusline formatting and display |
+| `src/shared-cache.ts` | On-disk shared usage cache |
+| `src/models.ts` | Provider/model matching helpers |
+| `src/args.ts` | `/usage` argument parsing and completions |
+| `src/constants.ts` | Shared constants |
+| `src/types.ts` | Shared TypeScript types |
+| `src/utils.ts` | Small parsing/formatting helpers |
+| `src/errors.ts` | HTTP/rate-limit error helpers |
+| `src/http.ts` | `fetchWithTimeout` wrapper |
+
+## Development
+
+```bash
+npm install
+npm run --workspace @sreetej510/pi-usage check     # biome + typecheck
+npm run --workspace @sreetej510/pi-usage format
+```

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@sreetej510/pi-usage",
+  "version": "0.1.1",
+  "description": "Pi extension that reports provider usage/rate-limit budgets (Codex, Anthropic OAuth, etc.) via /usage, with an optional statusline widget.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "usage",
+    "rate-limit",
+    "statusline"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "biome check . && npm run typecheck",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.3",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@earendil-works/pi-tui": "^0.80.3",
+    "typescript": "^5.7.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sreetej510/pi-extensions",
+    "directory": "extensions/pi-usage"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/anthropic-auth.ts

@@ -0,0 +1,33 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { anthropicAuthCandidateModels } from "./models.js";
+import { hasHeader } from "./utils.js";
+
+export async function resolvePiAnthropicAuth(
+  ctx: ExtensionContext,
+): Promise<{ headers: Record<string, string> } | undefined> {
+  const models = anthropicAuthCandidateModels(ctx);
+  const errors: string[] = [];
+
+  for (const model of models) {
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) {
+      errors.push(auth.error);
+      continue;
+    }
+
+    const headers = { ...(auth.headers ?? {}) };
+    if (!hasHeader(headers, "Authorization") && auth.apiKey) {
+      headers.Authorization = `Bearer ${auth.apiKey}`;
+    }
+    if (!hasHeader(headers, "Accept")) headers.Accept = "application/json";
+    if (!hasHeader(headers, "User-Agent")) headers["User-Agent"] = "pi-usage";
+    if (hasHeader(headers, "Authorization")) {
+      return { headers };
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join("; "));
+  }
+  return undefined;
+}

package/src/anthropic-query.ts

@@ -0,0 +1,72 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolvePiAnthropicAuth } from "./anthropic-auth.js";
+import { resolvePiCodexAuth } from "./codex-auth.js";
+import { ANTHROPIC_OAUTH_USAGE_URL, CODEX_USAGE_URL } from "./constants.js";
+import { isStaleExtensionContextError, throwUsageEndpointError } from "./errors.js";
+import { fetchWithTimeout } from "./http.js";
+import { anthropicAuthCandidateModels, codexAuthCandidateModels } from "./models.js";
+import { normalizeAnthropicUsagePayload } from "./normalize-anthropic.js";
+import type { AnthropicOAuthUsagePayload, AnthropicUsageReport } from "./types.js";
+import { errorMessage, parseJsonObject, prettyJson } from "./utils.js";
+
+export async function queryAnthropicUsage(ctx: ExtensionContext, timeoutMs: number): Promise<AnthropicUsageReport> {
+  const auth = await resolvePiAnthropicAuth(ctx);
+  if (!auth) {
+    throw new Error(
+      "No Pi Anthropic subscription auth was available. Use a Pi Anthropic model and run /login for Anthropic.",
+    );
+  }
+
+  const response = await fetchWithTimeout(
+    ANTHROPIC_OAUTH_USAGE_URL,
+    { headers: auth.headers },
+    timeoutMs,
+    "Anthropic usage",
+  );
+  const text = await response.text();
+  if (!response.ok) {
+    throwUsageEndpointError("Anthropic", response, text);
+  }
+
+  const payload = parseJsonObject(text, "Anthropic usage endpoint response");
+  return normalizeAnthropicUsagePayload(payload as AnthropicOAuthUsagePayload, Date.now());
+}
+
+/** Fetch and pretty-print the raw usage API responses for debugging (/usage --raw). */
+export async function fetchRawUsagePayloads(ctx: ExtensionContext, timeoutMs: number): Promise<string> {
+  const sections: string[] = [];
+
+  if (anthropicAuthCandidateModels(ctx).length > 0) {
+    try {
+      const auth = await resolvePiAnthropicAuth(ctx);
+      if (!auth) throw new Error("No Anthropic auth available.");
+      const response = await fetchWithTimeout(
+        ANTHROPIC_OAUTH_USAGE_URL,
+        { headers: auth.headers },
+        timeoutMs,
+        "Anthropic usage",
+      );
+      const text = await response.text();
+      sections.push(`>_ Anthropic raw (${response.status}):\n${prettyJson(text)}`);
+    } catch (error) {
+      if (isStaleExtensionContextError(error)) throw error;
+      sections.push(`>_ Anthropic raw: error \u2014 ${errorMessage(error)}`);
+    }
+  }
+
+  if (codexAuthCandidateModels(ctx).length > 0) {
+    try {
+      const auth = await resolvePiCodexAuth(ctx);
+      if (!auth) throw new Error("No Codex auth available.");
+      const response = await fetchWithTimeout(CODEX_USAGE_URL, { headers: auth.headers }, timeoutMs, "Codex usage");
+      const text = await response.text();
+      sections.push(`>_ Codex raw (${response.status}):\n${prettyJson(text)}`);
+    } catch (error) {
+      if (isStaleExtensionContextError(error)) throw error;
+      sections.push(`>_ Codex raw: error \u2014 ${errorMessage(error)}`);
+    }
+  }
+
+  if (sections.length === 0) return "No providers with usable auth found.";
+  return sections.join("\n\n");
+}

package/src/args.ts

@@ -0,0 +1,110 @@
+import { COMMAND_COMPLETIONS, DEFAULT_TIMEOUT_MS } from "./constants.js";
+import type { CommandArgumentCompletion, QueryUsageOptions } from "./types.js";
+
+export function completeCodexStatusArguments(argumentPrefix: string): CommandArgumentCompletion[] | null {
+  const prefix = argumentPrefix.trimStart();
+  if (prefix === "") return [...COMMAND_COMPLETIONS];
+
+  const trailingSpace = /\s$/.test(prefix);
+  const tokens = prefix.trimEnd().split(/\s+/).filter(Boolean);
+  const previous = tokens.at(-1);
+  if (previous === "--timeout" && trailingSpace) return null;
+  if (previous === "--consume-banked-reset" && trailingSpace) return null;
+  if (!trailingSpace && tokens.at(-2) === "--timeout") return null;
+  if (!trailingSpace && tokens.at(-2) === "--consume-banked-reset") return null;
+
+  const current = trailingSpace ? "" : (previous ?? "");
+  if (current && !current.startsWith("-")) return null;
+
+  const currentRaw = trailingSpace ? "" : (prefix.match(/\S+$/)?.[0] ?? "");
+  const completionPrefix = trailingSpace ? prefix : prefix.slice(0, prefix.length - currentRaw.length);
+  const matches = COMMAND_COMPLETIONS.filter((item) => item.value.startsWith(current));
+  return matches.length > 0 ? matches.map((item) => ({ ...item, value: `${completionPrefix}${item.value}` })) : null;
+}
+
+export function parseArgs(args: string): { ok: true; value: QueryUsageOptions } | { ok: false; error: string } {
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+  let clearStatusline = false;
+  let consumeBankedReset = false;
+  let consumeBankedResetId: string | undefined;
+  let listBankedResets = false;
+  let raw = false;
+  let refresh = false;
+  let statusline = true;
+  let timeoutMs = DEFAULT_TIMEOUT_MS;
+
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index];
+    if (token === "--clear-statusline") {
+      clearStatusline = true;
+      continue;
+    }
+    if (token === "--raw") {
+      raw = true;
+      continue;
+    }
+    if (token === "--list-banked-resets") {
+      listBankedResets = true;
+      continue;
+    }
+    if (token === "--consume-banked-reset") {
+      consumeBankedReset = true;
+      const rawValue = tokens[index + 1];
+      if (rawValue && !rawValue.startsWith("-")) {
+        consumeBankedResetId = rawValue;
+        index += 1;
+      }
+      continue;
+    }
+    if (token === "--no-statusline") {
+      statusline = false;
+      continue;
+    }
+    if (token === "--refresh") {
+      refresh = true;
+      continue;
+    }
+    if (token === "--timeout") {
+      const rawValue = tokens[index + 1];
+      if (!rawValue)
+        return {
+          ok: false,
+          error:
+            "Usage: /usage [--refresh] [--raw] [--list-banked-resets] [--consume-banked-reset <id>] [--timeout seconds]",
+        };
+      const parsed = Number(rawValue);
+      if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 120) {
+        return { ok: false, error: "--timeout must be a number of seconds between 1 and 120." };
+      }
+      timeoutMs = Math.round(parsed * 1000);
+      index += 1;
+      continue;
+    }
+    return {
+      ok: false,
+      error: `Unknown option: ${token}. Usage: /usage [--refresh] [--raw] [--list-banked-resets] [--consume-banked-reset <id>] [--no-statusline] [--clear-statusline] [--timeout seconds]`,
+    };
+  }
+
+  const exclusiveActionCount = [clearStatusline, raw, listBankedResets, consumeBankedReset].filter(Boolean).length;
+  if (exclusiveActionCount > 1) {
+    return {
+      ok: false,
+      error: "Choose only one of: --clear-statusline, --raw, --list-banked-resets, --consume-banked-reset.",
+    };
+  }
+
+  return {
+    ok: true,
+    value: {
+      clearStatusline,
+      consumeBankedReset,
+      consumeBankedResetId,
+      listBankedResets,
+      raw,
+      refresh,
+      statusline,
+      timeoutMs,
+    },
+  };
+}

package/src/codex-app-server.ts

@@ -0,0 +1,165 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { MAX_ERROR_BODY_CHARS } from "./constants.js";
+import { normalizeAppServerResponse } from "./normalize-codex.js";
+import type { CodexUsageReport, PendingRpc, RpcResponse } from "./types.js";
+import { assertObject, redactErrorBody, truncateEnd } from "./utils.js";
+
+export async function queryViaCodexAppServer(timeoutMs: number): Promise<CodexUsageReport> {
+  const client = new CodexAppServerClient(timeoutMs);
+  try {
+    await client.start();
+    await client.request("initialize", {
+      clientInfo: {
+        name: "pi_codex_usage",
+        title: "Pi Codex Usage",
+        version: "0.1.0",
+      },
+      capabilities: {
+        experimentalApi: false,
+        requestAttestation: false,
+        optOutNotificationMethods: [],
+      },
+    });
+    client.notify("initialized");
+    const result = await client.request("account/rateLimits/read", undefined);
+    return normalizeAppServerResponse(assertObject(result, "account/rateLimits/read result"), Date.now());
+  } finally {
+    client.dispose();
+  }
+}
+
+class CodexAppServerClient {
+  private child?: ChildProcessWithoutNullStreams;
+  private nextId = 1;
+  private stderr = "";
+  private readonly pending = new Map<number, PendingRpc>();
+  private startPromise?: Promise<void>;
+  private exitError?: Error;
+  private readonly timeoutMs: number;
+
+  constructor(timeoutMs: number) {
+    this.timeoutMs = timeoutMs;
+  }
+
+  start(): Promise<void> {
+    if (this.startPromise) return this.startPromise;
+
+    this.startPromise = new Promise((resolve, reject) => {
+      const child = spawn("codex", ["app-server", "--listen", "stdio://"], {
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      this.child = child;
+
+      const startupTimeout = setTimeout(() => {
+        reject(new Error(`Timed out after ${Math.round(this.timeoutMs / 1000)}s starting codex app-server.`));
+      }, this.timeoutMs);
+
+      child.once("spawn", () => {
+        clearTimeout(startupTimeout);
+        resolve();
+      });
+
+      child.once("error", (error) => {
+        clearTimeout(startupTimeout);
+        reject(new Error(`Failed to start codex app-server: ${error.message}`));
+        this.rejectAll(error);
+      });
+
+      child.once("exit", (code, signal) => {
+        const suffix = this.stderr ? ` stderr: ${redactErrorBody(this.stderr)}` : "";
+        this.exitError = new Error(
+          `codex app-server exited before completing the request (code ${code ?? "unknown"}, signal ${signal ?? "none"}).${suffix}`,
+        );
+        this.rejectAll(this.exitError);
+      });
+
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (chunk: string) => {
+        this.stderr = truncateEnd(this.stderr + chunk, MAX_ERROR_BODY_CHARS);
+      });
+
+      const lines = createInterface({ input: child.stdout });
+      lines.on("line", (line) => this.handleLine(line));
+    });
+
+    return this.startPromise;
+  }
+
+  request(method: string, params: unknown): Promise<unknown> {
+    const child = this.child;
+    if (!child?.stdin.writable) {
+      throw new Error("codex app-server is not running.");
+    }
+    if (this.exitError) throw this.exitError;
+
+    const id = this.nextId++;
+    const payload = params === undefined ? { method, id } : { method, id, params };
+    const response = new Promise<unknown>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out after ${Math.round(this.timeoutMs / 1000)}s waiting for ${method}.`));
+      }, this.timeoutMs);
+
+      this.pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timeout);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        },
+      });
+    });
+
+    child.stdin.write(`${JSON.stringify(payload)}\n`);
+    return response;
+  }
+
+  notify(method: string): void {
+    const child = this.child;
+    if (!child?.stdin.writable) return;
+    child.stdin.write(`${JSON.stringify({ method })}\n`);
+  }
+
+  dispose(): void {
+    for (const [id, pending] of this.pending) {
+      pending.reject(new Error(`codex app-server request ${id} cancelled.`));
+    }
+    this.pending.clear();
+
+    const child = this.child;
+    if (!child) return;
+    child.stdin.end();
+    if (!child.killed) child.kill();
+    this.child = undefined;
+  }
+
+  private handleLine(line: string): void {
+    let parsed: RpcResponse;
+    try {
+      parsed = JSON.parse(line) as RpcResponse;
+    } catch {
+      return;
+    }
+
+    if (typeof parsed.id !== "number") return;
+    const pending = this.pending.get(parsed.id);
+    if (!pending) return;
+    this.pending.delete(parsed.id);
+
+    if (parsed.error) {
+      const message = typeof parsed.error.message === "string" ? parsed.error.message : "unknown error";
+      pending.reject(new Error(`codex app-server request failed: ${message}`));
+      return;
+    }
+
+    pending.resolve(parsed.result);
+  }
+
+  private rejectAll(error: Error): void {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+  }
+}

package/src/codex-auth.ts

@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CODEX_OPENAI_BETA } from "./constants.js";
+import { codexAuthCandidateModels } from "./models.js";
+import { asString, hasHeader } from "./utils.js";
+
+export async function resolvePiCodexAuth(
+  ctx: ExtensionContext,
+): Promise<{ headers: Record<string, string> } | undefined> {
+  const models = codexAuthCandidateModels(ctx);
+  const errors: string[] = [];
+
+  for (const model of models) {
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) {
+      errors.push(auth.error);
+      continue;
+    }
+
+    const headers = { ...(auth.headers ?? {}) };
+    if (!hasHeader(headers, "Authorization") && auth.apiKey) {
+      headers.Authorization = `Bearer ${auth.apiKey}`;
+    }
+    if (!hasHeader(headers, "User-Agent")) {
+      headers["User-Agent"] = "pi-codex-usage";
+    }
+    if (hasHeader(headers, "Authorization")) {
+      return { headers };
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join("; "));
+  }
+  return undefined;
+}
+
+export async function resolvePiCodexWhamAuth(
+  ctx: ExtensionContext,
+): Promise<{ headers: Record<string, string> } | undefined> {
+  const auth = await resolvePiCodexAuth(ctx);
+  if (!auth) return undefined;
+  const headers = { ...auth.headers };
+  if (!hasHeader(headers, "Accept")) headers.Accept = "application/json";
+  if (!hasHeader(headers, "Content-Type")) headers["Content-Type"] = "application/json";
+  if (!hasHeader(headers, "OpenAI-Beta")) headers["OpenAI-Beta"] = CODEX_OPENAI_BETA;
+  if (!hasHeader(headers, "originator")) headers.originator = "Codex Desktop";
+  if (!hasHeader(headers, "ChatGPT-Account-ID")) {
+    const accountId = readCodexAccountIdFromAuthFile();
+    if (accountId) headers["ChatGPT-Account-ID"] = accountId;
+  }
+  return { headers };
+}
+
+export function readCodexAccountIdFromAuthFile(): string | undefined {
+  try {
+    const raw = JSON.parse(readFileSync(join(homedir(), ".codex", "auth.json"), "utf8")) as {
+      tokens?: { account_id?: unknown; accountId?: unknown };
+    };
+    return asString(raw.tokens?.account_id) ?? asString(raw.tokens?.accountId);
+  } catch {
+    return undefined;
+  }
+}

package/src/codex-query.ts

@@ -0,0 +1,52 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { queryViaCodexAppServer } from "./codex-app-server.js";
+import { resolvePiCodexAuth } from "./codex-auth.js";
+import { CODEX_USAGE_URL } from "./constants.js";
+import { isStaleExtensionContextError, throwUsageEndpointError } from "./errors.js";
+import { fetchWithTimeout } from "./http.js";
+import { normalizeBackendPayload } from "./normalize-codex.js";
+import type { CodexUsageReport, RateLimitStatusPayload, UsageQueryError, UsageReport } from "./types.js";
+import { errorMessage, parseJsonObject } from "./utils.js";
+
+export async function queryViaPiAuth(ctx: ExtensionContext, timeoutMs: number): Promise<CodexUsageReport> {
+  const auth = await resolvePiCodexAuth(ctx);
+  if (!auth) {
+    throw new Error(
+      "No Pi OpenAI Codex subscription auth was available. Use a Pi OpenAI Codex model or run /login for OpenAI ChatGPT Plus/Pro (Codex).",
+    );
+  }
+
+  const response = await fetchWithTimeout(CODEX_USAGE_URL, { headers: auth.headers }, timeoutMs);
+  const text = await response.text();
+  if (!response.ok) {
+    throwUsageEndpointError("Codex", response, text);
+  }
+
+  const payload = parseJsonObject(text, "Codex usage endpoint response");
+  return normalizeBackendPayload(payload as RateLimitStatusPayload, Date.now(), "pi-auth");
+}
+
+export async function queryCodexUsageWithFallback(
+  ctx: ExtensionContext,
+  timeoutMs: number,
+): Promise<{ report?: UsageReport; errors: UsageQueryError[] }> {
+  try {
+    const report = await queryViaPiAuth(ctx, timeoutMs);
+    return { report, errors: [] };
+  } catch (cause) {
+    if (isStaleExtensionContextError(cause)) throw cause;
+    const errors: UsageQueryError[] = [{ source: "pi-auth", message: errorMessage(cause), cause }];
+    try {
+      const report = await queryViaCodexAppServer(timeoutMs);
+      return { report, errors };
+    } catch (fallbackCause) {
+      if (isStaleExtensionContextError(fallbackCause)) throw fallbackCause;
+      errors.push({
+        source: "codex-app-server",
+        message: errorMessage(fallbackCause),
+        cause: fallbackCause,
+      });
+      return { errors };
+    }
+  }
+}