@phnx-labs/agents-cli 1.20.89 → 1.20.90

package/dist/lib/usage-backoff.d.ts

@@ -0,0 +1,29 @@
+import type { AgentId } from './types.js';
+export declare function setUsageBackoffDirForTest(dir: string | null): string | null;
+/**
+ * Parse a `Retry-After` header. HTTP allows either delta-seconds or an HTTP
+ * date; both appear in the wild, so handle both and ignore anything else.
+ * Returns milliseconds from `now`, or null when there is nothing usable.
+ */
+export declare function parseRetryAfterMs(header: string | null | undefined, now?: number): number | null;
+/**
+ * Record that `agent`'s usage endpoint threw a 429. `retryAfter` is the raw
+ * header; when it is absent or unparseable we still back off for `fallbackMs`,
+ * because continuing to poll an endpoint that just said no is what created the
+ * loop in the first place.
+ */
+export declare function noteUsageRateLimited(agent: AgentId, retryAfter: string | null | undefined, opts?: {
+    now?: number;
+    fallbackMs?: number;
+}): void;
+/**
+ * Epoch ms until which `agent`'s usage endpoint should not be called, or null
+ * when it is free — the furthest recorded deadline still in the future, so a
+ * concurrently-written shorter one can never pull it in.
+ *
+ * Sweeps elapsed files while it is here: they can only accumulate at the rate
+ * penalties are issued, and this is the one place that already lists them.
+ */
+export declare function usageRateLimitedUntil(agent: AgentId, now?: number): number | null;
+/** Human-readable remaining backoff, for the error a skipped read returns. */
+export declare function formatBackoffRemaining(untilMs: number, now?: number): string;

package/dist/lib/usage-backoff.js

@@ -0,0 +1,165 @@
+/**
+ * Respect a usage endpoint's `Retry-After` instead of hammering through it.
+ *
+ * The failure this exists to stop, measured on `yosemite-s1` (2026-08-03): every
+ * Claude account there returned `429 rate_limit_error` with `retry-after: 2678`
+ * — about 45 minutes — while the credentials themselves read healthy
+ * (`probeClaudeStatus` → `status=429 token=present`). The daemon warms
+ * auth-health every 3 minutes (`daemon.ts`, `setInterval(..., 3 * 60_000)`) and
+ * `probeLocalFleetAuth` fans out over every installed version home in one
+ * `Promise.all`, so five Claude homes meant five concurrent requests to one
+ * endpoint every three minutes — ~100/hour from a single machine. Nothing read
+ * `Retry-After`, so each tick fired deep inside the penalty window and re-armed
+ * the throttle. Measured 75 minutes apart, the box never got out: `retry-after`
+ * 2678s at 08:42Z, still 429 at 09:57Z on a freshly-issued 1208s penalty. Its
+ * usage cache froze — exactly the permanently-stale state the routing freshness
+ * rule (`rotate.ts`, `USAGE_DECISION_MAX_AGE_MS`) was written to defend against.
+ *
+ * So a 429 is recorded here with its deadline, and every usage read and health
+ * probe for that provider short-circuits until the deadline passes — no request,
+ * no renewed penalty. State is on disk rather than in memory because the
+ * offenders are separate processes: the long-lived daemon, and every one-shot
+ * `agents view` / `agents run` invocation.
+ *
+ * ## The deadline lives in the FILENAME, and that is the whole design
+ *
+ * The obvious shape — one JSON document holding `{agent: deadline}` — is
+ * read-modify-write, and without a lock two processes recording the same
+ * provider can both read the old value and let the SHORTER deadline write last,
+ * silently undoing the longer penalty. That is not a theoretical race here: the
+ * triggering condition is a batch of concurrent same-provider 429s, which is
+ * precisely what the daemon issues, and it can recur on every batch. Reading
+ * back and retrying does not fix it either — that only detects a clobber which
+ * already landed, and a stale writer can still write after the check.
+ *
+ * So no shared document. Each penalty is its own file named `<agent>.<deadline>`
+ * with empty contents, and a read takes the MAXIMUM deadline across that
+ * provider's files. Two concurrent writers create two different files and
+ * neither can erase the other, so a shorter deadline cannot displace a longer
+ * one — monotonicity is structural rather than argued, and there is no lock to
+ * go stale on a path every usage read touches. Elapsed files are swept on read.
+ *
+ * Deliberately per-provider, not per-account: the endpoint throttles the caller,
+ * and the observed 429 hit all five accounts on the box at once. Backing off one
+ * account while the others keep firing would not clear the penalty.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from './state.js';
+/** Cap a server-supplied delay so a bad header cannot park a provider forever. */
+const MAX_BACKOFF_MS = 60 * 60 * 1000;
+/**
+ * Test seam, mirroring `setKeychainBackendForTest`. The cache dir is resolved
+ * from a module-level constant at import time, so overriding `HOME` in a test
+ * does NOT redirect this state — it silently writes into the developer's real
+ * `~/.agents/.cache/` and parks their own usage reads behind a 45-minute
+ * penalty. (It did exactly that once while this was being written.) Returns the
+ * previous value so a test can restore it.
+ */
+let backoffDirOverride = null;
+export function setUsageBackoffDirForTest(dir) {
+    const prev = backoffDirOverride;
+    backoffDirOverride = dir;
+    return prev;
+}
+function backoffDir() {
+    return backoffDirOverride ?? path.join(getCacheDir(), 'usage-backoff');
+}
+/**
+ * Parse a `Retry-After` header. HTTP allows either delta-seconds or an HTTP
+ * date; both appear in the wild, so handle both and ignore anything else.
+ * Returns milliseconds from `now`, or null when there is nothing usable.
+ */
+export function parseRetryAfterMs(header, now = Date.now()) {
+    const raw = (header ?? '').trim();
+    if (!raw)
+        return null;
+    if (/^\d+$/.test(raw)) {
+        const ms = Number(raw) * 1000;
+        return ms > 0 ? Math.min(ms, MAX_BACKOFF_MS) : null;
+    }
+    const at = Date.parse(raw);
+    if (Number.isNaN(at))
+        return null;
+    const ms = at - now;
+    return ms > 0 ? Math.min(ms, MAX_BACKOFF_MS) : null;
+}
+/** Every recorded deadline for `agent`, newest-first. Never throws. */
+function deadlinesFor(agent) {
+    let names;
+    try {
+        names = fs.readdirSync(backoffDir());
+    }
+    catch {
+        // No directory yet: nothing is throttled.
+        return [];
+    }
+    const prefix = `${agent}.`;
+    const out = [];
+    for (const name of names) {
+        if (!name.startsWith(prefix))
+            continue;
+        const at = Number(name.slice(prefix.length));
+        if (Number.isFinite(at))
+            out.push(at);
+    }
+    return out;
+}
+/**
+ * Record that `agent`'s usage endpoint threw a 429. `retryAfter` is the raw
+ * header; when it is absent or unparseable we still back off for `fallbackMs`,
+ * because continuing to poll an endpoint that just said no is what created the
+ * loop in the first place.
+ */
+export function noteUsageRateLimited(agent, retryAfter, opts) {
+    const now = opts?.now ?? Date.now();
+    const fallbackMs = opts?.fallbackMs ?? 15 * 60 * 1000;
+    const ms = parseRetryAfterMs(retryAfter, now) ?? fallbackMs;
+    const deadline = now + Math.min(ms, MAX_BACKOFF_MS);
+    try {
+        fs.mkdirSync(backoffDir(), { recursive: true });
+        // Empty file: the name carries the whole value, so there is no content a
+        // concurrent reader could catch half-written, and no document to merge.
+        fs.writeFileSync(path.join(backoffDir(), `${agent}.${deadline}`), '');
+    }
+    catch {
+        // Best-effort. An unwritable cache dir costs the cross-process backoff, not
+        // the correctness of this read.
+    }
+}
+/**
+ * Epoch ms until which `agent`'s usage endpoint should not be called, or null
+ * when it is free — the furthest recorded deadline still in the future, so a
+ * concurrently-written shorter one can never pull it in.
+ *
+ * Sweeps elapsed files while it is here: they can only accumulate at the rate
+ * penalties are issued, and this is the one place that already lists them.
+ */
+export function usageRateLimitedUntil(agent, now = Date.now()) {
+    let latest = null;
+    for (const at of deadlinesFor(agent)) {
+        if (at > now) {
+            if (latest === null || at > latest)
+                latest = at;
+        }
+        else {
+            try {
+                fs.rmSync(path.join(backoffDir(), `${agent}.${at}`), { force: true });
+            }
+            catch {
+                /* another process may have swept it already */
+            }
+        }
+    }
+    return latest;
+}
+/** Human-readable remaining backoff, for the error a skipped read returns. */
+export function formatBackoffRemaining(untilMs, now = Date.now()) {
+    const mins = Math.ceil((untilMs - now) / 60_000);
+    if (mins <= 1)
+        return 'under a minute';
+    if (mins < 60)
+        return `${mins} minutes`;
+    const hours = Math.round(mins / 60);
+    return hours === 1 ? 'about an hour' : `about ${hours} hours`;
+}

package/dist/lib/usage.d.ts

@@ -1,5 +1,42 @@
 import { type AccountInfo } from './agents.js';
 import type { AgentId } from './types.js';
+/**
+ * Why a usage read produced no snapshot, when the cause is the credential or the
+ * server rather than the payload. Every provider used to return `error: null`
+ * for all three, which made an account nobody can read indistinguishable from a
+ * healthy one: the caller fell back to whatever was in the SWR cache and
+ * rendered its bars as fact. On `yosemite-s1` that hid five Claude accounts
+ * whose stored access token had expired — one of them eleven days earlier —
+ * behind a cache frozen for 26h, and balanced routing launched into an account
+ * that was actually at its weekly cap.
+ *
+ * No usage read ever refreshes a token (RUSH-1822 for Claude; the same rule for
+ * Kimi/Droid/Cursor, whose own CLIs rotate on their next launch), so an expired
+ * credential cannot heal on its own — the account stays unreadable until that
+ * agent actually runs, or a long-lived token is provisioned for it.
+ *
+ * Shared across all four networked providers on purpose: the failure shape is
+ * identical, and wiring only Claude would leave `agents view --refresh`
+ * reporting Claude accounts while silently presenting stale Kimi, Droid, and
+ * Cursor readings as confirmed.
+ */
+export declare function usageNoCredentialError(agent: string): string;
+export declare function usageExpiredCredentialError(agent: string): string;
+export declare function usageRejectedError(agent: string, status: number): string;
+/**
+ * The read threw rather than answering — a timeout, DNS/TLS failure, a payload
+ * that would not parse, a credential that would not decrypt. Every provider
+ * swallowed these into `error: null`, which is the same silence as an expired
+ * token: the caller renders a stale snapshot as confirmed. The cause is carried
+ * verbatim because these are the failures a user cannot otherwise see.
+ */
+/**
+ * The provider told us to back off and we are still inside that window, so this
+ * read made no request at all. Distinct from `usageRejectedError(agent, 429)`,
+ * which is the 429 itself: this one says we are *honouring* it.
+ */
+export declare function usageThrottledError(agent: string, untilMs: number): string;
+export declare function usageUnreachableError(agent: string, cause?: unknown): string;
 /**
  * True when a Claude OAuth access token is within the refresh leeway of expiry
  * (or already expired) — i.e. it "would need a refresh" before the next use.
@@ -92,6 +129,10 @@ declare const USAGE_SOURCES: {
         readonly fetch: typeof getCursorUsageInfo;
         readonly network: true;
     };
+    readonly antigravity: {
+        readonly fetch: typeof getAntigravityUsageInfo;
+        readonly network: true;
+    };
 };
 export declare const USAGE_SOURCE_AGENT_IDS: (keyof typeof USAGE_SOURCES)[];
 /** Fetch usage info for a given agent through the canonical source registry. */
@@ -107,20 +148,29 @@ export declare function buildCanonicalUsageContext(inputs: UsageIdentityInput[])
     usageFetchInputs: Map<string, UsageFetchInput>;
 };
 /**
- * Whether an agent exposes usage/limit data we can render — Claude/Kimi/Droid/Cursor
- * via a live API, Codex/Grok via local session logs. Everything else has no usage
- * concept, so callers use this to decide whether a missing snapshot is worth
- * flagging as "usage unavailable" (a signed-in Claude account with no data)
- * versus simply not applicable (Antigravity, OpenCode).
+ * Whether an agent exposes usage/limit data we can render — Claude/Kimi/Droid/
+ * Cursor/Antigravity via a live API, Codex/Grok via local session logs.
+ * Everything else has no usage concept, so callers use this to decide whether
+ * a missing snapshot is worth flagging as "usage unavailable" (a signed-in
+ * Claude account with no data) versus simply not applicable (OpenCode).
  */
 export declare function agentReportsUsage(agentId: AgentId): boolean;
 /** Fetch usage info for all unique accounts in parallel, keyed by usage key. */
 export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: {
     forceRefresh?: boolean;
+    maxAgeMs?: number;
 }): Promise<{
     canonicalByUsageKey: Map<string, AccountInfo>;
     usageByKey: Map<string, UsageInfo>;
 }>;
+/**
+ * How stale a cached snapshot may be before the read stops serving it and blocks
+ * on the network. Defaults to the full 24h stale-while-revalidate window; a
+ * caller that is about to ROUTE on the number passes a shorter `maxAgeMs` and
+ * gets a live read instead of a day-old one. Never widens past 24h — a caller
+ * cannot opt into more staleness than the cache policy allows.
+ */
+export declare function swrWindowMsFor(maxAgeMs?: number): number;
 /**
  * Fetch usage for a single identity using stale-while-revalidate.
  *
@@ -135,10 +185,12 @@ export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opt
  */
 export declare function getUsageInfoForIdentity(input: UsageIdentityInput, opts?: {
     forceRefresh?: boolean;
+    maxAgeMs?: number;
 }): Promise<UsageInfo>;
 /** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number, opts?: {
     unavailable?: boolean;
+    unverified?: boolean;
 }): string;
 /**
  * Derive an account's real throttle state from its live usage windows — the
@@ -390,4 +442,59 @@ export declare function normalizeCursorUsage(data: CursorUsageResponse): UsageWi
  * row still renders, without a misleading empty gauge).
  */
 declare function getCursorUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
+/** The OAuth token `agy` stores (inside `{ token: … }`) in the OS keyring or file. */
+interface AntigravityOauthToken {
+    access_token?: string | null;
+    refresh_token?: string | null;
+    /** RFC3339 expiry timestamp for the access token. */
+    expiry?: string | null;
+}
+/** One per-model quota bucket from the :retrieveUserQuota response. */
+export interface AntigravityQuotaBucket {
+    modelId?: string | null;
+    tokenType?: string | null;
+    remainingFraction?: number | null;
+    resetTime?: string | null;
+}
+/** Response shape from the Code Assist :retrieveUserQuota endpoint. */
+export interface AntigravityQuotaResponse {
+    buckets?: AntigravityQuotaBucket[] | null;
+}
+/**
+ * Parse a stored `agy` OAuth payload into its token. Handles both on-disk
+ * shapes: the raw `{ token: {…} }` JSON (Linux file fallback) and the
+ * `go-keyring-base64:<base64>` wrapper zalando/go-keyring writes into the
+ * macOS Keychain item (service `gemini`, account `antigravity`). Never throws
+ * (malformed input => null).
+ */
+export declare function parseAntigravityOauthPayload(raw: string): AntigravityOauthToken | null;
+/**
+ * True when the stored access token is expired (or inside the refresh leeway).
+ * A missing/unparseable expiry is treated as still-fresh — the quota call
+ * below is the source of truth if the token is actually dead (401 => render
+ * nothing), and we never want to force a refresh without evidence.
+ */
+export declare function antigravityTokenNeedsRefresh(expiry: string | null | undefined, nowMs?: number): boolean;
+/** Compact model tag for the inline bar — 'gemini-2.5-flash-lite' => '2.5FL'. */
+export declare function antigravityModelShortLabel(modelId: string): string;
+/**
+ * Normalize the per-model quota buckets into the common UsageWindow shape —
+ * one window per model (`gemini-3.1-pro`, `gemini-2.5-flash`, …), keyed
+ * `session` since each bucket is a short-cycle quota with its own reset time.
+ * Duplicate buckets for one model keep the LOWEST remaining fraction (the
+ * most conservative read). Sorted most-used first so the bar closest to
+ * throttling leads the row. `windowMinutes` stays null: the API reports only
+ * the reset timestamp, not the window length, and an inferred 5h session
+ * length would wrongly zero the SWR cache between resets.
+ */
+export declare function normalizeAntigravityWindows(buckets: AntigravityQuotaBucket[]): UsageWindow[];
+/**
+ * Fetch Antigravity usage via Google Code Assist's :retrieveUserQuota — the
+ * quota API `agy` itself talks to (its log shows the sibling :loadCodeAssist
+ * and :fetchAvailableModels calls on the same host). Auth is the stored `agy`
+ * OAuth token (OS keyring on macOS, file fallback on Linux), refreshed
+ * in-memory when expired — safe because Google's refresh tokens are
+ * non-rotating (see refreshAntigravityAccessToken).
+ */
+declare function getAntigravityUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 export {};