@phnx-labs/agents-cli 1.21.0 → 1.21.2

package/dist/lib/usage.d.ts

@@ -49,6 +49,7 @@ export declare function usageUnreachableError(agent: string, cause?: unknown): s
  * fresh" (never force a refresh on a token with no known expiry).
  */
 export declare function claudeAccessTokenNeedsRefresh(expiresAt: number | null | undefined, nowMs?: number): boolean;
+export declare function setClaudeUsageCachePathForTest(cachePath: string | null): string | null;
 /** Discriminator for usage window types. */
 export type UsageWindowKey = 'session' | 'week' | 'sonnet_week' | 'month';
 /** A single rate-limit window with utilization percentage and reset time. */
@@ -155,10 +156,37 @@ export declare function buildCanonicalUsageContext(inputs: UsageIdentityInput[])
  * 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. */
+/**
+ * Whether an agent's usage source makes a live NETWORK call (Claude/Kimi/Droid/
+ * Cursor/Antigravity) versus reading local session logs (Codex/Grok). Only the
+ * networked ones go through the on-disk cache, and only they need the daemon's
+ * background refresher to keep that cache warm for the routing hot path.
+ */
+export declare function agentUsesNetworkUsage(agentId: AgentId): boolean;
+/**
+ * Concurrent live usage fetches for a single `agents view` / rotation pass.
+ * High enough to finish a multi-account refresh in one round-trip window; low
+ * enough that a cold cache of 10+ accounts cannot open 10+ HTTP calls at once
+ * (and cannot stack behind delayed responses until the process is pegged).
+ */
+export declare const USAGE_FETCH_CONCURRENCY = 3;
+/**
+ * How long a cached snapshot is treated as fresh enough that we skip the network
+ * entirely. Five minutes balances "still accurate enough to glance at" against
+ * "don't re-hit every account on every `agents view` in a tight loop". Was 2
+ * minutes; that re-fired too often when delayed responses stacked.
+ */
+export declare const USAGE_CACHE_FRESH_MS: number;
+/**
+ * Unified entry for every multi-account usage lookup (`agents view`, rotation,
+ * JSON export). Deduplicates by usage identity, then fans out through the
+ * shared SWR + timeout path with a hard concurrency cap so delayed calls
+ * cannot pile up.
+ */
 export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: {
     forceRefresh?: boolean;
     maxAgeMs?: number;
+    readOnly?: boolean;
 }): Promise<{
     canonicalByUsageKey: Map<string, AccountInfo>;
     usageByKey: Map<string, UsageInfo>;
@@ -174,24 +202,46 @@ export declare function swrWindowMsFor(maxAgeMs?: number): number;
 /**
  * Fetch usage for a single identity using stale-while-revalidate.
  *
- * - Cache fresh (< 2 min): return cached snapshot, NO network.
- * - Cache stale but < 24h: return cached snapshot instantly, fire background refresh.
- * - Cache too stale or absent: block on live fetch, fall back to cache on error.
+ * - Cache fresh (< 5 min): return cached snapshot, NO network.
+ * - Cache stale but < 24h: return cached snapshot instantly, enqueue a
+ *   concurrency-capped background refresh.
+ * - Cache too stale or absent: block on live fetch (shared in-flight promise),
+ *   fall back to cache on error.
  *
- * This keeps `agents run` startup off the network on the hot path. The first
- * invocation after a cold install or 24h gap still blocks once to seed the
- * cache; every run after that returns instantly while the cache silently
- * refreshes in the background.
+ * This keeps `agents run` / `agents view` off the network on the hot path. The
+ * first invocation after a cold install or 24h gap still blocks once to seed
+ * the cache; every run after that returns instantly while the cache silently
+ * refreshes in the background — never more than {@link USAGE_BG_REFRESH_CONCURRENCY}
+ * at a time.
  */
 export declare function getUsageInfoForIdentity(input: UsageIdentityInput, opts?: {
     forceRefresh?: boolean;
     maxAgeMs?: number;
+    readOnly?: boolean;
 }): 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?: {
+/**
+ * Pick which usage windows to render in a compact one-line summary.
+ *
+ * Overview rows (`agents view` all agents) must stay narrow enough that one
+ * multi-window agent (Antigravity's four model quotas, Droid's three buckets)
+ * does not force every other row to pad to ~200 columns and wrap. Prefer the
+ * canonical session + week windows when present; otherwise take the highest
+ * utilization remaining. Returns the full set when `maxWindows` is unset.
+ */
+export declare function pickCompactUsageWindows(windows: UsageWindow[], maxWindows?: number): UsageWindow[];
+/** Options for {@link formatUsageSummary}. */
+export interface FormatUsageSummaryOpts {
     unavailable?: boolean;
     unverified?: boolean;
-}): string;
+    /**
+     * Cap how many usage windows render on one line. Overview (`agents view`
+     * with no agent filter) passes 2 so multi-window agents cannot blow out
+     * column width; single-agent and detail views leave this unset.
+     */
+    maxWindows?: number;
+}
+/** 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?: FormatUsageSummaryOpts): string;
 /**
  * Derive an account's real throttle state from its live usage windows — the
  * single signal both the `agents view` badge and run-rotation eligibility share
@@ -212,6 +262,39 @@ export declare function formatUsageSummary(plan: string | null, snapshot: UsageS
  * one model, not the account, so it shouldn't flip the whole row to throttled.
  */
 export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot | null | undefined): 'available' | 'rate_limited' | null;
+/** A prior sample of one window's utilization, for burn-rate projection. */
+export interface UsagePriorSample {
+    /** Epoch ms the prior snapshot was captured. */
+    capturedAt: number;
+    /** The session window's `usedPercent` in that prior snapshot. */
+    usedPercent: number;
+}
+/**
+ * An account's throttle state PLUS how long until it caps, projected from the
+ * burn rate on its 5-hour `session` window — the window that throttles the next
+ * request soonest. `deriveUsageStatusFromSnapshot` answers only "maxed right
+ * now (100%)?"; this answers "and how close is it getting?", so routing can
+ * deprioritize an account burning toward its cap before it actually hits it,
+ * instead of treating 85%-and-climbing the same as 85%-and-idle.
+ *
+ * `minutesToLimit`:
+ *   - `0`      — already rate-limited (a blocking window at 100%).
+ *   - `n > 0`  — projected minutes until the session window reaches 100%, from
+ *                `(100 - used) / burnRatePerMinute`, where the burn rate is
+ *                measured between `prev` and this snapshot.
+ *   - `null`   — unknown: no snapshot, no session window, no prior sample, or
+ *                usage flat/falling since `prev` (a reset or an idle account is
+ *                not "projected to cap", so it is NOT deprioritized).
+ *
+ * Pure: the daemon's refresher supplies `prev` from the last snapshot it stored
+ * (`usage-refresh.ts`); the routing hot path reads the daemon-computed result
+ * from the headroom cache rather than recomputing (it has no `prev`).
+ */
+export interface UsageHeadroom {
+    status: 'available' | 'rate_limited' | null;
+    minutesToLimit: number | null;
+}
+export declare function deriveUsageHeadroom(snapshot: UsageSnapshot | null | undefined, prev?: UsagePriorSample | null): UsageHeadroom;
 /**
  * Compact colored badge for the account's overall usage status. Renders only
  * when the account is throttled — `available` and `null` return ''.
@@ -433,13 +516,65 @@ export interface CursorUsageResponse {
  * bar to draw here and return no windows rather than a misleading empty gauge.
  */
 export declare function normalizeCursorUsage(data: CursorUsageResponse): UsageWindow[];
+/** Per-window plan usage percentages Cursor's dashboard breaks usage into (Auto+Composer / API / Total). */
+interface CursorPlanUsage {
+    autoPercentUsed?: number | null;
+    apiPercentUsed?: number | null;
+    totalPercentUsed?: number | null;
+}
+/** Response shape from Cursor's dashboard current-period-usage endpoint (subset we render). */
+export interface CursorPeriodUsageResponse {
+    planUsage?: CursorPlanUsage | null;
+    /** ISO timestamp, or a unix-ms string, marking the end of the current billing cycle. */
+    billingCycleEnd?: string | number | null;
+}
+/** Response shape from Cursor's usage-summary endpoint (subset we render). */
+export interface CursorUsageSummaryResponse {
+    /** True on a plan with no consumption cap; only tiered self-serve plans populate the percent fields. */
+    isUnlimited?: boolean | null;
+    individualUsage?: {
+        plan?: CursorPlanUsage | null;
+    } | null;
+    billingCycleEnd?: string | number | null;
+}
+/**
+ * Normalize Cursor's dashboard `get-current-period-usage` payload — the
+ * primary usage source, giving the same Auto+Composer / API / Total breakdown
+ * the web dashboard shows.
+ */
+export declare function normalizeCursorPeriodUsage(data: CursorPeriodUsageResponse): UsageWindow[];
+/**
+ * Normalize Cursor's `usage-summary` fallback payload — the same Auto/API/Total
+ * breakdown nested under `individualUsage.plan`, used when the primary
+ * dashboard endpoint returns no usable `planUsage` (seen on some
+ * enterprise/team accounts). An unlimited plan (`isUnlimited: true`) with no
+ * usable percent has nothing to draw and returns no windows, rather than a
+ * misleading empty gauge.
+ */
+export declare function normalizeCursorUsageSummary(data: CursorUsageSummaryResponse): UsageWindow[];
 /**
- * Fetch Cursor usage from the dashboard usage endpoint. Cursor authenticates the
- * request with a `WorkosCursorSessionToken` cookie of the form
- * `<oauth-subject>::<access-token>` (the same pair the web dashboard sends), not a
- * bearer header. Free/legacy plans return a monthly request bar; usage-based plans
- * have no request cap, so they return a live-but-window-less snapshot (the account
- * row still renders, without a misleading empty gauge).
+ * Fetch Cursor usage. Cursor authenticates every one of these requests with a
+ * `WorkosCursorSessionToken` cookie of the form `<oauth-subject>::<access-token>`
+ * (the same pair the web dashboard sends), not a bearer header, so all three
+ * sources below share one resolved cookie.
+ *
+ * Three sources, tried in order, because no single endpoint carries usable data
+ * for every plan shape:
+ *
+ *  1. `get-current-period-usage` — the primary source, and the richest: the
+ *     Auto+Composer / API / Total percent breakdown the dashboard itself shows.
+ *  2. `usage-summary` — some enterprise/team accounts return no usable
+ *     `planUsage` from (1); this nests the same three percentages under
+ *     `individualUsage.plan` instead.
+ *  3. The legacy `/api/usage` request-cap endpoint — the original source,
+ *     kept as the final fallback for free/legacy plans that predate the
+ *     percent-based breakdown above and only ever exposed a monthly request cap.
+ *
+ * The first source to yield a non-empty window list wins; a source that errors
+ * or returns no usable numbers falls through to the next rather than surfacing
+ * an error — only the last resort's own response/error is surfaced when every
+ * source comes up empty, so a plan enrolled in exactly one billing model still
+ * renders instead of reporting three swallowed failures.
  */
 declare function getCursorUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 /** The OAuth token `agy` stores (inside `{ token: … }`) in the OS keyring or file. */