@smithers-orchestrator/usage 0.23.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+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,54 @@
+# @smithers-orchestrator/usage
+
+Report how much rate limit or subscription quota each registered Smithers account
+has consumed. Powers `smithers usage`.
+
+```
+$ smithers usage
+ACCOUNT       PROVIDER      PLAN   WINDOW          USED          RESETS IN
+claude-work   claude-code   max    5-hour session  33%           2h 41m
+claude-work   claude-code   max    weekly          13%           5d 3h
+codex-main    codex         pro    5-hour          12%           4h 02m
+codex-main    codex         pro    weekly          40%           6d 1h
+openai-ci     openai-api    —      requests/min    820/1000 left 0m 42s
+```
+
+## What it reads, per provider
+
+The numbers live in three incompatible shapes, so every adapter normalizes to one
+`UsageReport`.
+
+| Provider | Source | Auth read from |
+| --- | --- | --- |
+| `claude-code` | `GET api.anthropic.com/api/oauth/usage` (5h + weekly %) | `<configDir>/.credentials.json` or macOS Keychain `Claude Code-credentials` |
+| `codex` | `GET chatgpt.com/backend-api/wham/usage` (5h + weekly %) | `<configDir>/auth.json` |
+| `anthropic-api` | live `anthropic-ratelimit-*` headers off `count_tokens` | account `apiKey` |
+| `openai-api` | live `x-ratelimit-*` headers off a `max_tokens:1` POST | account `apiKey` |
+| `gemini` / `antigravity` / `gemini-api` | none yet (Google exposes no live quota) | — |
+| `kimi`, others | none | — |
+
+The subscription endpoints (`claude-code`, `codex`) are undocumented: they are the
+same endpoints the official CLIs call, reachable by reading the CLI's own OAuth
+token off disk. They are best-effort — any failure degrades to a `source: "none"`
+report with a readable reason, never an exception.
+
+## Design
+
+- `getAccountUsage(account)` is the dispatcher. It switches on `account.provider`,
+  mirroring `accountToProviderEnv` in `@smithers-orchestrator/accounts`.
+- `getUsageForAccounts(accounts, opts)` fans out in parallel through an on-disk
+  cache (`usage-cache.json`). Cached reports come back with `stale: true`. The
+  cache enforces a hard 180s floor for `claude-code` because its usage endpoint
+  429s aggressively below that.
+- Credentials are read on the host that owns them. Only the normalized
+  `UsageReport` ever leaves the process — no token is returned or logged.
+
+## Safety
+
+- The Claude usage endpoint requires `User-Agent: claude-code/<ver>` and
+  `anthropic-beta: oauth-2025-04-20`. Override the UA with
+  `SMITHERS_CLAUDE_CODE_UA` if the installed version matters.
+- `--fresh` bypasses the soft cache but never the hard per-provider floor.
+
+See `.smithers/specs/usage-and-limits.md` for the full design and the phased plan
+(gateway RPC, studio dashboard, Google local-estimate accounting).

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@smithers-orchestrator/usage",
+  "version": "0.23.0",
+  "description": "Report how much rate limit or subscription quota each registered Smithers account has consumed, across Claude, Codex, OpenAI, Anthropic, and Google providers.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@smithers-orchestrator/errors": "0.23.0",
+    "@smithers-orchestrator/accounts": "0.23.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --dts-only"
+  }
+}

package/src/UsageReport.ts

@@ -0,0 +1,33 @@
+import type { AccountProvider } from "@smithers-orchestrator/accounts";
+import type { UsageSource } from "./UsageSource";
+import type { UsageWindow } from "./UsageWindow";
+
+/**
+ * Normalized usage for a single registered account. Every adapter — subscription
+ * utilization, API-key headers, local estimate — produces this same shape so the
+ * CLI, gateway, and UI render one model.
+ */
+export type UsageReport = {
+  /** The account's label in `~/.smithers/accounts.json`. */
+  accountLabel: string;
+  /** The account's provider. */
+  provider: AccountProvider;
+  /** How this account authenticates. */
+  authMode: "subscription" | "api-key";
+  /** Where the numbers came from. */
+  source: UsageSource;
+  /** Quota windows, possibly empty when `source` is `none`. */
+  windows: UsageWindow[];
+  /** Plan/tier label if the provider reports one, e.g. "max", "pro". */
+  planType?: string;
+  /** Pay-as-you-go credit balance, if the provider reports one (Codex). */
+  credits?: { hasCredits: boolean; unlimited: boolean; balance?: string };
+  /** ISO-8601 timestamp of when this report was produced. */
+  fetchedAt: string;
+  /** True when served from cache past its soft TTL. */
+  stale: boolean;
+  /** True when the windows are locally estimated, not provider-authoritative. */
+  estimate: boolean;
+  /** Human-readable reason when `source` is `none` or a probe failed. */
+  error?: string;
+};

package/src/UsageSource.ts

@@ -0,0 +1,9 @@
+/**
+ * Where a usage report's numbers came from.
+ *
+ * - `oauth`   — an authenticated subscription usage endpoint (Claude, Codex).
+ * - `headers` — live rate-limit response headers from an API-key request.
+ * - `local`   — estimated locally from token logs (Google providers).
+ * - `none`    — the provider exposes no usage surface, or the probe failed.
+ */
+export type UsageSource = "oauth" | "headers" | "local" | "none";

package/src/UsageWindow.ts

@@ -0,0 +1,28 @@
+/**
+ * One quota window for an account: a 5-hour session, a weekly cap, a per-minute
+ * request bucket, and so on.
+ *
+ * The `unit` decides which fields are meaningful:
+ * - `percent`   — subscription utilization; read `usedPercent` (0–100).
+ * - `count`     — API-key buckets; read `limit`, `remaining`, `used`.
+ * - `estimated` — locally estimated; read `usedPercent`/`used`/`limit`, treat as
+ *                 a lower bound, never as authoritative.
+ */
+export type UsageWindow = {
+  /** Stable id, e.g. "5h" | "weekly" | "requests-per-min" | "tokens-per-min". */
+  id: string;
+  /** Human label, e.g. "5-hour session". */
+  label: string;
+  /** Which fields below are meaningful. */
+  unit: "percent" | "count" | "estimated";
+  /** 0–100. Set for `percent` and `estimated`. */
+  usedPercent?: number;
+  /** Absolute amount consumed. Set for `count` and `estimated`. */
+  used?: number;
+  /** Absolute cap. Set for `count` and `estimated`. */
+  limit?: number;
+  /** `limit - used`. Set for `count`. */
+  remaining?: number;
+  /** ISO-8601 timestamp when this window rolls over. */
+  resetsAt?: string;
+};

package/src/anthropicHeaderUsage.js

@@ -0,0 +1,51 @@
+import { parseAnthropicRateLimitHeaders } from "./parseAnthropicRateLimitHeaders.js";
+
+/** @typedef {import("./buildUsageReport.js").UsageProbe} UsageProbe */
+
+const COUNT_TOKENS_URL = "https://api.anthropic.com/v1/messages/count_tokens";
+
+/** The count_tokens probe needs a valid model id but generates no output tokens. */
+const PROBE_MODEL = process.env.SMITHERS_ANTHROPIC_PROBE_MODEL ?? "claude-sonnet-4-20250514";
+
+/**
+ * Reads live Anthropic rate-limit headers for an API-key account. Uses the
+ * `count_tokens` endpoint, which returns the rate-limit header family without
+ * producing output tokens.
+ *
+ * @param {{ apiKey?: string }} account
+ * @returns {Promise<UsageProbe>}
+ */
+export async function anthropicHeaderUsage(account) {
+    const apiKey = account.apiKey;
+    if (!apiKey) {
+        return { source: "none", error: "Account has no API key set" };
+    }
+    try {
+        const res = await fetch(COUNT_TOKENS_URL, {
+            method: "POST",
+            headers: {
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ model: PROBE_MODEL, messages: [{ role: "user", content: "hi" }] }),
+            signal: AbortSignal.timeout(6_000),
+        });
+        if (res.status === 401) {
+            return { source: "none", error: "ANTHROPIC_API_KEY rejected (401)" };
+        }
+        const get = (name) => res.headers.get(name);
+        const windows = parseAnthropicRateLimitHeaders(get);
+        if (res.status === 429) {
+            const retryAfter = res.headers.get("retry-after");
+            return {
+                source: "headers",
+                windows,
+                error: `Rate limited (429)${retryAfter ? ` — retry after ${retryAfter}s` : ""}`,
+            };
+        }
+        return { source: "headers", windows };
+    } catch (err) {
+        return { source: "none", error: `Anthropic header probe failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/src/buildUsageReport.js

@@ -0,0 +1,43 @@
+import { API_KEY_PROVIDERS } from "@smithers-orchestrator/accounts";
+
+/** @typedef {import("@smithers-orchestrator/accounts").Account} Account */
+/** @typedef {import("./UsageReport.ts").UsageReport} UsageReport */
+/** @typedef {import("./UsageWindow.ts").UsageWindow} UsageWindow */
+
+/**
+ * The partial result an adapter returns. The dispatcher wraps it with the
+ * account identity and timestamp to form a complete {@link UsageReport}.
+ *
+ * @typedef {object} UsageProbe
+ * @property {import("./UsageSource.ts").UsageSource} source
+ * @property {UsageWindow[]} [windows]
+ * @property {string} [planType]
+ * @property {{ hasCredits: boolean; unlimited: boolean; balance?: string }} [credits]
+ * @property {boolean} [estimate]
+ * @property {string} [error]
+ */
+
+/**
+ * Assembles a full usage report from an account and an adapter probe. Keeps the
+ * adapters free of repeated identity/timestamp boilerplate.
+ *
+ * @param {Account} account
+ * @param {UsageProbe} probe
+ * @param {{ nowIso?: string }} [options]
+ * @returns {UsageReport}
+ */
+export function buildUsageReport(account, probe, options = {}) {
+    return {
+        accountLabel: account.label,
+        provider: account.provider,
+        authMode: API_KEY_PROVIDERS.has(account.provider) ? "api-key" : "subscription",
+        source: probe.source,
+        windows: probe.windows ?? [],
+        planType: probe.planType,
+        credits: probe.credits,
+        fetchedAt: options.nowIso ?? new Date().toISOString(),
+        stale: false,
+        estimate: probe.estimate ?? false,
+        error: probe.error,
+    };
+}

package/src/claudeOauthUsage.js

@@ -0,0 +1,52 @@
+import { parseClaudeOauthUsage } from "./parseClaudeOauthUsage.js";
+import { readClaudeCredentials } from "./readClaudeCredentials.js";
+
+/** @typedef {import("./buildUsageReport.js").UsageProbe} UsageProbe */
+
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+
+/**
+ * The User-Agent must start with `claude-code/`; without it the endpoint drops
+ * the caller into an aggressively rate-limited bucket. Overridable for when the
+ * real installed version matters.
+ */
+const USER_AGENT = process.env.SMITHERS_CLAUDE_CODE_UA ?? "claude-code/2.0.0";
+
+/**
+ * Probes the Claude Code subscription usage endpoint for an account's 5-hour and
+ * weekly utilization. Undocumented and best-effort: any failure degrades to a
+ * `none` report with a readable reason.
+ *
+ * @param {{ configDir?: string }} account
+ * @returns {Promise<UsageProbe>}
+ */
+export async function claudeOauthUsage(account) {
+    const creds = readClaudeCredentials(account);
+    if (!creds) {
+        return { source: "none", error: "No Claude OAuth credentials in configDir or Keychain" };
+    }
+    try {
+        const res = await fetch(USAGE_URL, {
+            headers: {
+                Authorization: `Bearer ${creds.accessToken}`,
+                "anthropic-beta": "oauth-2025-04-20",
+                "User-Agent": USER_AGENT,
+                "Content-Type": "application/json",
+            },
+            signal: AbortSignal.timeout(6_000),
+        });
+        if (res.status === 401) {
+            return { source: "none", error: "Claude OAuth token rejected (401); run `claude` to refresh" };
+        }
+        if (res.status === 429) {
+            return { source: "none", error: "Claude usage endpoint rate limited (429); try again shortly" };
+        }
+        if (!res.ok) {
+            return { source: "none", error: `Claude usage endpoint returned ${res.status}` };
+        }
+        const payload = await res.json();
+        return { source: "oauth", windows: parseClaudeOauthUsage(payload) };
+    } catch (err) {
+        return { source: "none", error: `Claude usage probe failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/src/codexWhamUsage.js

@@ -0,0 +1,45 @@
+import { parseCodexUsage } from "./parseCodexUsage.js";
+import { readCodexCredentials } from "./readCodexCredentials.js";
+
+/** @typedef {import("./buildUsageReport.js").UsageProbe} UsageProbe */
+
+const USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+
+/**
+ * Probes the Codex ChatGPT-subscription usage endpoint for an account's 5-hour
+ * and weekly windows. This is the same data the Codex `/status` view shows and
+ * does not spend a turn. Undocumented and best-effort.
+ *
+ * @param {{ configDir?: string }} account
+ * @returns {Promise<UsageProbe>}
+ */
+export async function codexWhamUsage(account) {
+    const creds = readCodexCredentials(account);
+    if (!creds) {
+        return { source: "none", error: "No Codex ChatGPT credentials in configDir/auth.json" };
+    }
+    try {
+        /** @type {Record<string, string>} */
+        const headers = {
+            Authorization: `Bearer ${creds.accessToken}`,
+            "User-Agent": "codex-cli",
+            Accept: "application/json",
+        };
+        if (creds.accountId) headers["ChatGPT-Account-Id"] = creds.accountId;
+        const res = await fetch(USAGE_URL, {
+            headers,
+            signal: AbortSignal.timeout(6_000),
+        });
+        if (res.status === 401) {
+            return { source: "none", error: "Codex token rejected (401); run `codex` to refresh" };
+        }
+        if (!res.ok) {
+            return { source: "none", error: `Codex usage endpoint returned ${res.status}` };
+        }
+        const payload = await res.json();
+        const { windows, planType, credits } = parseCodexUsage(payload);
+        return { source: "oauth", windows, planType, credits };
+    } catch (err) {
+        return { source: "none", error: `Codex usage probe failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/src/decodeJwtClaims.js

@@ -0,0 +1,26 @@
+/**
+ * Decodes the claims (the middle segment) of a JWT without verifying its
+ * signature. Used to read the `chatgpt_account_id` claim out of the Codex
+ * `id_token` when `auth.json` does not carry `tokens.account_id` directly.
+ *
+ * Verification is intentionally skipped: the token already authenticated the
+ * user with the provider, and we only read a non-secret routing claim from it.
+ *
+ * Returns an empty object for anything that is not a decodable JWT.
+ *
+ * @param {string | null | undefined} token
+ * @returns {Record<string, unknown>}
+ */
+export function decodeJwtClaims(token) {
+    if (typeof token !== "string") return {};
+    const parts = token.split(".");
+    if (parts.length < 2) return {};
+    try {
+        const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const json = Buffer.from(payload, "base64").toString("utf8");
+        const claims = JSON.parse(json);
+        return claims && typeof claims === "object" ? claims : {};
+    } catch {
+        return {};
+    }
+}

package/src/formatRelativeReset.js

@@ -0,0 +1,16 @@
+import { humanizeDurationShort } from "./humanizeDurationShort.js";
+
+/**
+ * Formats an ISO reset timestamp as a relative "resets in" string. Returns an
+ * empty string when there is no timestamp, and `"now"` when it is in the past.
+ *
+ * @param {string | undefined} resetsAt
+ * @param {number} [nowMs]
+ * @returns {string}
+ */
+export function formatRelativeReset(resetsAt, nowMs = Date.now()) {
+    if (!resetsAt) return "";
+    const ms = Date.parse(resetsAt);
+    if (Number.isNaN(ms)) return "";
+    return humanizeDurationShort((ms - nowMs) / 1000);
+}

package/src/formatUsageReports.js

@@ -0,0 +1,59 @@
+import { formatRelativeReset } from "./formatRelativeReset.js";
+
+/** @typedef {import("./UsageReport.ts").UsageReport} UsageReport */
+/** @typedef {import("./UsageWindow.ts").UsageWindow} UsageWindow */
+
+/**
+ * Renders the "used" cell for one window.
+ *
+ * @param {UsageWindow} w
+ * @returns {string}
+ */
+function usedCell(w) {
+    if (w.unit === "percent") {
+        return w.usedPercent === undefined ? "" : `${Math.round(w.usedPercent)}%`;
+    }
+    if (w.unit === "estimated") {
+        if (w.used !== undefined && w.limit !== undefined) return `~${w.used}/${w.limit}`;
+        if (w.usedPercent !== undefined) return `~${Math.round(w.usedPercent)}%`;
+        return "~?";
+    }
+    // count
+    if (w.remaining !== undefined && w.limit !== undefined) return `${w.remaining}/${w.limit} left`;
+    if (w.remaining !== undefined) return `${w.remaining} left`;
+    if (w.used !== undefined && w.limit !== undefined) return `${w.used}/${w.limit}`;
+    return "";
+}
+
+/**
+ * Renders an array of usage reports as an aligned text table. Pure: pass a fixed
+ * `nowMs` in tests to get deterministic "resets in" values.
+ *
+ * @param {UsageReport[]} reports
+ * @param {number} [nowMs]
+ * @returns {string}
+ */
+export function formatUsageReports(reports, nowMs = Date.now()) {
+    if (reports.length === 0) {
+        return "No accounts registered. Add one with `smithers agents add`.";
+    }
+    const header = ["ACCOUNT", "PROVIDER", "PLAN", "WINDOW", "USED", "RESETS IN"];
+    /** @type {string[][]} */
+    const rows = [header];
+    for (const r of reports) {
+        const plan = r.planType ?? (r.authMode === "api-key" ? "—" : "");
+        if (r.windows.length === 0) {
+            const note = r.error ?? (r.source === "none" ? "not supported" : "");
+            rows.push([r.accountLabel, r.provider, plan, "—", note, ""]);
+            continue;
+        }
+        for (const w of r.windows) {
+            const used = usedCell(w) + (w.unit === "estimated" ? " (est)" : "");
+            rows.push([r.accountLabel, r.provider, plan, w.label, used, formatRelativeReset(w.resetsAt, nowMs)]);
+        }
+    }
+    const widths = header.map((_, col) => Math.max(...rows.map((row) => row[col].length)));
+    return rows
+        .map((row) => row.map((cell, col) => cell.padEnd(widths[col])).join("  ").trimEnd())
+        .join("\n");
+}

package/src/getAccountUsage.js

@@ -0,0 +1,50 @@
+import { anthropicHeaderUsage } from "./anthropicHeaderUsage.js";
+import { buildUsageReport } from "./buildUsageReport.js";
+import { claudeOauthUsage } from "./claudeOauthUsage.js";
+import { codexWhamUsage } from "./codexWhamUsage.js";
+import { googleUsage } from "./googleUsage.js";
+import { openaiHeaderUsage } from "./openaiHeaderUsage.js";
+
+/** @typedef {import("@smithers-orchestrator/accounts").Account} Account */
+/** @typedef {import("./UsageReport.ts").UsageReport} UsageReport */
+
+/**
+ * Routes an account to its usage adapter and returns a normalized report. This
+ * switch mirrors `accountToProviderEnv` in the accounts package so the two stay
+ * structurally aligned. Adapters never throw; they degrade to a `none` report.
+ *
+ * Credentials are read on the host that owns them and only the normalized report
+ * leaves this function — no token is ever returned or logged.
+ *
+ * @param {Account} account
+ * @returns {Promise<UsageReport>}
+ */
+export async function getAccountUsage(account) {
+    const probe = await probeFor(account);
+    return buildUsageReport(account, probe);
+}
+
+/**
+ * @param {Account} account
+ * @returns {Promise<import("./buildUsageReport.js").UsageProbe>}
+ */
+async function probeFor(account) {
+    switch (account.provider) {
+        case "claude-code":
+            return claudeOauthUsage(account);
+        case "codex":
+            return codexWhamUsage(account);
+        case "anthropic-api":
+            return anthropicHeaderUsage(account);
+        case "openai-api":
+            return openaiHeaderUsage(account);
+        case "gemini":
+        case "antigravity":
+        case "gemini-api":
+            return googleUsage(account);
+        case "kimi":
+            return { source: "none", error: "Kimi exposes no usage endpoint yet" };
+        default:
+            return { source: "none", error: `Usage not supported for provider "${account.provider}"` };
+    }
+}

package/src/getUsageForAccounts.js

@@ -0,0 +1,75 @@
+import { getAccountUsage } from "./getAccountUsage.js";
+import { readUsageCache, writeUsageCache } from "./usageCache.js";
+
+/** @typedef {import("@smithers-orchestrator/accounts").Account} Account */
+/** @typedef {import("./UsageReport.ts").UsageReport} UsageReport */
+
+/**
+ * Soft refresh interval: within this age a cached report is reused on a normal
+ * run. `--fresh` bypasses it.
+ *
+ * @param {string} provider
+ * @returns {number}
+ */
+function refreshIntervalMs(provider) {
+    switch (provider) {
+        case "claude-code": return 180_000;
+        case "codex": return 60_000;
+        default: return 30_000;
+    }
+}
+
+/**
+ * Hard floor: never re-probe faster than this, even with `--fresh`. The Claude
+ * usage endpoint 429s aggressively below 180s, so we protect it unconditionally.
+ *
+ * @param {string} provider
+ * @returns {number}
+ */
+function hardFloorMs(provider) {
+    return provider === "claude-code" ? 180_000 : 0;
+}
+
+/**
+ * Gathers usage for many accounts in parallel, served through the on-disk cache.
+ * Cached reports come back with `stale: true`. The cache is read once and written
+ * once, so parallel probes never race on the file.
+ *
+ * @param {Account[]} accounts
+ * @param {{ fresh?: boolean; env?: NodeJS.ProcessEnv; nowMs?: number }} [options]
+ * @returns {Promise<UsageReport[]>}
+ */
+export async function getUsageForAccounts(accounts, options = {}) {
+    const { fresh = false, env = process.env, nowMs = Date.now() } = options;
+    const cache = readUsageCache(env);
+    const decisions = accounts.map((account) => {
+        const entry = cache.entries[account.label];
+        const fetchedAt = entry?.report?.fetchedAt;
+        const parsed = typeof fetchedAt === "string" ? nowMs - Date.parse(fetchedAt) : Number.NaN;
+        const age = Number.isFinite(parsed) ? parsed : Infinity;
+        const useCache = Number.isFinite(parsed) && (
+            age < hardFloorMs(account.provider) ||
+            (!fresh && age < refreshIntervalMs(account.provider))
+        );
+        return { account, entry, useCache };
+    });
+    const reports = await Promise.all(decisions.map(async (d) => {
+        if (d.useCache && d.entry) return { ...d.entry.report, stale: true };
+        return getAccountUsage(d.account);
+    }));
+    let changed = false;
+    reports.forEach((report, i) => {
+        if (!decisions[i].useCache) {
+            cache.entries[report.accountLabel] = { report };
+            changed = true;
+        }
+    });
+    if (changed) {
+        try {
+            writeUsageCache(cache, env);
+        } catch {
+            // a cache write failure must not break the command
+        }
+    }
+    return reports;
+}

package/src/googleUsage.js

@@ -0,0 +1,20 @@
+/** @typedef {import("./buildUsageReport.js").UsageProbe} UsageProbe */
+
+/**
+ * Google (Gemini, Antigravity, Gemini API) exposes no live "remaining quota"
+ * surface to a personal-login or API-key client: there are no rate-limit
+ * response headers, only a 429 `RESOURCE_EXHAUSTED` after the wall is hit. The
+ * documented path forward is local token-log accounting against published caps
+ * (see `publishedCaps.js`), which depends on run-history integration and lands
+ * in a later phase. Until then this reports `none` honestly rather than inventing
+ * a number.
+ *
+ * @param {{ provider: string }} account
+ * @returns {Promise<UsageProbe>}
+ */
+export async function googleUsage(account) {
+    return {
+        source: "none",
+        error: "Google exposes no live usage endpoint; local estimate not yet wired",
+    };
+}

package/src/humanizeDurationShort.js

@@ -0,0 +1,20 @@
+/**
+ * Formats a number of seconds as a short human duration, e.g. `"2h 41m"`,
+ * `"5d 3h"`, `"42s"`. Used for "resets in" columns. Negative input renders as
+ * `"now"`.
+ *
+ * @param {number} seconds
+ * @returns {string}
+ */
+export function humanizeDurationShort(seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0) return "now";
+    const total = Math.round(seconds);
+    const days = Math.floor(total / 86400);
+    const hours = Math.floor((total % 86400) / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const secs = total % 60;
+    if (days > 0) return `${days}d ${hours}h`;
+    if (hours > 0) return `${hours}h ${minutes}m`;
+    if (minutes > 0) return `${minutes}m ${secs}s`;
+    return `${secs}s`;
+}