@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/accounting/usage.d.ts

@@ -60,6 +60,40 @@ export declare function isClaudeUsageScopeDenied(status: number, bodyText: strin
  */
 export declare function usageThrottledError(agent: string, untilMs: number): string;
 export declare function usageUnreachableError(agent: string, cause?: unknown): string;
+/**
+ * Marker for a log-based (`network: false`) provider — Codex, Grok — that has
+ * simply never recorded a rate-limit event on this machine yet: no session
+ * log exists, or no session in it carries usage data. Distinct on purpose from
+ * `usageUnreachableError`: that one means the local log COULDN'T be read (a
+ * real failure worth surfacing distinctly); this one means there is nothing to
+ * read because the account has not run here, which is expected for a fresh
+ * install and should render as a benign state, not an error (RUSH-3040).
+ */
+export declare const USAGE_NO_RECENT_USAGE_MARKER = "no usage recorded yet";
+export declare const USAGE_BENIGN_STATE: unique symbol;
+export type UsageBenignState = 'no-recent-usage';
+/**
+ * Shared error-classification + 429 backoff for a networked usage fetch whose
+ * only signal is an HTTP status (or none at all, on a network failure) —
+ * Antigravity's :retrieveUserQuota and Muse's Meta Model API probe are both
+ * this shape. They were added to `USAGE_SOURCES` after the four original
+ * `usageXError` constructors and did not get their own scheme (usage.ts's
+ * error handling was written for "four networked providers"; RUSH-3040).
+ * Route every no-snapshot outcome for either through this one function so a
+ * future entry cannot be added second-class again — it owns noting the 429
+ * backoff, so callers must NOT also call {@link noteUsageRateLimited} for the
+ * same response.
+ */
+export declare function classifyUsageFetchFailure(agent: string, agentId: 'antigravity' | 'muse', status: number | null, retryAfterHeader: string | null | undefined, usageScope?: string | null): string;
+/**
+ * The specific cause behind a `UsageInfo.error`, so a renderer can name the
+ * exact state instead of a generic "usage unavailable" for one of several
+ * distinct causes (RUSH-3040). Matched against the canonical strings this file
+ * constructs — never re-derive these prefixes at a call site.
+ */
+export type UsageErrorKind = 'no-credential' | 'expired-credential' | 'rate-limited' | 'rejected' | 'headless-scope' | 'unreachable';
+/** Classify a `UsageInfo.error` string into its {@link UsageErrorKind}, or null when there is no error. */
+export declare function classifyUsageErrorKind(error: string | null | undefined): UsageErrorKind | null;
 /**
  * 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.
@@ -91,6 +125,8 @@ export interface UsageSnapshot {
     capturedAt: Date | null;
     windows: UsageWindow[];
     plan?: string | null;
+    /** Action that makes an event-fed source emit a current reading. */
+    refreshHint?: string | null;
     /**
      * A refusal observed from a real harness run, independent of API windows.
      * `session_limit` recovers on a clock (`resetsAt`). `out_of_credits` is a
@@ -107,7 +143,13 @@ export interface UsageSnapshot {
 export interface UsageInfo {
     snapshot: UsageSnapshot | null;
     error: string | null;
+    /** Benign local state, symbol-backed so `--json` keeps its existing shape. */
+    [USAGE_BENIGN_STATE]?: UsageBenignState;
 }
+/** Construct the benign no-local-log result without overloading `error`. */
+export declare function usageNoRecentUsageInfo(): UsageInfo;
+/** Read a benign state for the human renderer; symbols are omitted by JSON serialization. */
+export declare function getUsageBenignState(info: UsageInfo): UsageBenignState | null;
 /** Input needed to identify an account for usage lookup. */
 export interface UsageIdentityInput {
     agentId: AgentId;
@@ -120,6 +162,13 @@ interface UsageOptions {
     home?: string;
     cliVersion?: string | null;
     organizationId?: string | null;
+    /**
+     * The account's usage key (`claude:org=…`, `kimi:user=…`, …) when the caller
+     * knows which account this fetch is for. Scopes the 429 backoff to that
+     * account (RUSH-3036) so one throttled account cannot park its siblings;
+     * absent, the backoff stays provider-wide.
+     */
+    usageScope?: string | null;
     /**
      * When true, never open the ACL-bound OS keychain item (macOS Touch ID).
      * Daemon usage refresh sets this so a background tick cannot pop biometrics.
@@ -259,6 +308,33 @@ export interface FormatUsageSummaryOpts {
      * column width; single-agent and detail views leave this unset.
      */
     maxWindows?: number;
+    /** Windows that must keep a visible slot even when the provider omits one. */
+    expectedWindows?: Array<{
+        key: string;
+        shortLabel: string;
+    }>;
+    /**
+     * The classified cause of `usageInfo.error` (RUSH-3040), from
+     * {@link classifyUsageErrorKind}. Lets the no-bars branch below name the
+     * SPECIFIC reason ('re-auth for usage', 'sign in / provision a long-lived
+     * token', 'rate-limited (retry ~12m)') instead of
+     * the generic 'usage unavailable' that used to cover ~6 distinct causes.
+     * Only consulted when `unavailable` is set — a snapshot WITH bars still
+     * renders 'unverified'/`headless` as before. `--json` output is unaffected:
+     * `UsageInfo.error` keeps carrying the full message; this only changes the
+     * short human string rendered here.
+     */
+    errorKind?: UsageErrorKind | null;
+    /**
+     * The raw `UsageInfo.error` string, read only to pull the retry-time hint
+     * out of a `rate-limited` classification (the exact duration lives in the
+     * message text, not the kind).
+     */
+    errorDetail?: string | null;
+    /** Benign state from {@link getUsageBenignState}; never sourced from `UsageInfo.error`. */
+    benignState?: UsageBenignState | null;
+    /** Provider-specific replacement for the generic no-local-event marker. */
+    noRecentUsageLabel?: string | null;
 }
 /** 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;
@@ -452,11 +528,11 @@ export interface ProviderProbe {
     reason?: 'usage_scope';
 }
 /** Probe Claude's OAuth token against the usage endpoint. Never refreshes — reports `expired` for a near-expiry token; see the comment below (RUSH-1822). */
-export declare function probeClaudeStatus(home?: string, cliVersion?: string | null): Promise<ProviderProbe>;
+export declare function probeClaudeStatus(home?: string, cliVersion?: string | null, usageScope?: string | null): Promise<ProviderProbe>;
 /** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
-export declare function probeKimiStatus(home?: string): Promise<ProviderProbe>;
+export declare function probeKimiStatus(home?: string, usageScope?: string | null): Promise<ProviderProbe>;
 /** Probe Droid's WorkOS token against the billing-limits endpoint. Never refreshes (single-use rotation — see getDroidUsageInfo). */
-export declare function probeDroidStatus(home?: string): Promise<ProviderProbe>;
+export declare function probeDroidStatus(home?: string, usageScope?: string | null): Promise<ProviderProbe>;
 /**
  * Normalize the Factory billing-limits payload into the common UsageWindow
  * shape. Orgs on the legacy (non token-rate-limit) billing model have no
@@ -485,7 +561,7 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * a file-based setup-token and, when none is provisioned, gets `null` — it never
  * reads Claude Code's interactive login (transmitting that ACL-bound OAuth token
  * to Anthropic's API is what gets it revoked; see the branch body and
- * docs/credential-management.md). It is OFF by default so full-credential
+ * docs/secrets.md). It is OFF by default so full-credential
  * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) still
  * read the interactive login. Rush Cloud dispatch does not call this helper
  * at all (SING-1b: the account manifest is email-only; RUSH-2359 removed the
@@ -521,6 +597,8 @@ export declare function readClaudeUsageCache(usageKey: string, cachePath?: strin
 export declare function pruneExpiredClaudeUsageCacheEntry(usageKey: string, cachePath?: string, now?: Date): void;
 /** Write a usage snapshot to the on-disk cache. */
 export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
+/** Atomically merge partial native Claude windows into the current fresh row. */
+export declare function mergeClaudeUsageCacheWindows(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
 /**
  * Persist a Claude tokens/credits exhaustion (`out of usage credits` / `monthly
  * spend limit`) from a real run. Unlike a rate/session limit this does NOT reset
@@ -547,8 +625,8 @@ export declare function parseClaudeSessionLimitReset(text: string, nowMs?: numbe
  * Returns true only when a valid access token can be obtained.
  */
 export declare function isClaudeAuthValid(home?: string): Promise<boolean>;
-/** Render a colored block-character progress bar. */
-export declare function renderBar(usedPercent: number, length: number, minimumVisible?: number): string;
+/** Render a proportional colored progress bar at one-eighth-cell resolution. */
+export declare function renderBar(usedPercent: number, length: number): string;
 /** Return a chalk color function based on the usage percentage threshold. */
 export declare function getUsageColor(usedPercent: number): (text: string) => string;
 /** Parse the latest billing info from Grok's unified log. */