@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/usage-refresh.js

@@ -1,15 +1,17 @@
 /**
- * Daemon-owned usage refresher (per host).
+ * Daemon-owned usage refresher (publisher host).
  *
  * The routing hot path (`agents run` → collectRunCandidates) reads usage
- * CACHE-ONLY (`getUsageInfoForIdentity` `readOnly`, RUSH-2061) and never blocks
+ * CACHE-ONLY (`getUsageInfoForIdentity`, RUSH-2061) and never blocks
  * on a provider fetch. Something still has to keep that cache fresh — this
- * module is that something, running inside the daemon on **each machine**.
+ * module is that something, running inside the daemon on the configured
+ * `usage.primary-host` (or locally when no primary is configured).
  *
  * Design:
  *
- *  - **Per-host sole writer.** Only accounts whose credentials live on THIS
- *    box are listed; no fleet-wide usage sync.
+ *  - **Fleet sole writer.** Only the configured primary lists credential-backed
+ *    accounts and calls providers. It exports derived snapshots/headroom;
+ *    subscriber hosts import that token-free envelope (`usage-fleet.ts`).
  *  - **Fixed 5-minute cadence** (`REFRESH_INTERVAL_MS`). Enough to keep
  *    balanced/`agents view` off multi-hour stale data without thrashing
  *    provider APIs when the user runs agents frequently. The delay helpers
@@ -48,7 +50,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
-import { deriveUsageHeadroom, getUsageInfo, buildCanonicalUsageContext, agentUsesNetworkUsage, USAGE_SOURCE_AGENT_IDS, } from './usage.js';
+import { deriveUsageHeadroom, buildCanonicalUsageContext, USAGE_SOURCE_AGENT_IDS, } from './usage.js';
 import { getAccountInfo } from './agents.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 /**
@@ -170,18 +172,16 @@ export function nextHeadroomEntry(prev, snapshot, now) {
     };
 }
 /**
- * Enumerate the network-usage accounts whose credentials live on THIS host — one
+ * Enumerate the usage accounts whose credentials live on THIS host — one
  * per unique usage key, deduped to the most-recently-active version (the same
  * canonicalization `getUsageInfoByIdentity` uses). Each carries a closure that
  * live-fetches its usage. This is the daemon's `listAccounts`; because it only
  * ever lists local, signed-in accounts, each host is the sole writer for its own
- * accounts' caches — no cross-host coordination.
+ * accounts' caches. `runUsageRefreshTick` calls this only on the fleet publisher.
  */
 export async function buildLocalUsageAccounts() {
     const accounts = [];
     for (const agentId of USAGE_SOURCE_AGENT_IDS) {
-        if (!agentUsesNetworkUsage(agentId))
-            continue;
         const versions = listInstalledVersions(agentId);
         if (versions.length === 0)
             continue;
@@ -201,12 +201,15 @@ export async function buildLocalUsageAccounts() {
                 // that path is the Touch ID storm. Usage reads the file-based setup-token
                 // only, never the interactive login (see loadClaudeOauth); no setup-token
                 // reads as "usage pending".
-                fetch: () => getUsageInfo(agentId, {
-                    home: fetchInput.home,
-                    cliVersion: fetchInput.cliVersion,
-                    organizationId: fetchInput.organizationId,
-                    fileOnly: true,
-                }),
+                fetch: async () => {
+                    const { getUsageInfoForIdentity } = await import('./usage.js');
+                    return getUsageInfoForIdentity({
+                        agentId,
+                        home: fetchInput.home,
+                        cliVersion: fetchInput.cliVersion,
+                        info: canonical,
+                    }, { forceRefresh: true, fileOnly: true });
+                },
             });
         }
     }

package/dist/lib/usage.d.ts

@@ -23,6 +23,29 @@ import type { AgentId } from './types.js';
 export declare function usageNoCredentialError(agent: string): string;
 export declare function usageExpiredCredentialError(agent: string): string;
 export declare function usageRejectedError(agent: string, status: number): string;
+/**
+ * Canonical phrase for the Anthropic setup-token scope gap (RUSH-2392).
+ * `claude setup-token` mints `user:inference` only; the usage endpoint requires
+ * `user:profile`. The account can still run; usage bars cannot populate via
+ * that token. Callers detect this string with {@link isUsageHeadlessScopeError}
+ * so the UI can render it distinctly from a generic "unverified" failure.
+ */
+export declare const USAGE_HEADLESS_SCOPE_MARKER = "usage unavailable (headless)";
+/**
+ * Distinct error when Claude's usage API returns 403 because the setup-token
+ * lacks `user:profile` (RUSH-2392). Not a revocation, not a missing mint —
+ * a permanent tradeoff of the headless credential.
+ */
+export declare function usageHeadlessScopeError(agent?: string): string;
+/** True when an error string is the setup-token scope gap (RUSH-2392). */
+export declare function isUsageHeadlessScopeError(error: string | null | undefined): boolean;
+/**
+ * Detect Anthropic's usage-endpoint scope denial: HTTP 403 whose body names
+ * `user:profile` (or "scope requirement"). A bare 403 without that body stays
+ * classified as a real rejection — only the known setup-token shape is special
+ * (RUSH-2392).
+ */
+export declare function isClaudeUsageScopeDenied(status: number, bodyText: string | null | undefined): boolean;
 /**
  * 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
@@ -169,9 +192,9 @@ export declare function buildCanonicalUsageContext(inputs: UsageIdentityInput[])
 export declare function agentReportsUsage(agentId: AgentId): boolean;
 /**
  * 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.
+ * Cursor/Antigravity) versus reading local session logs (Codex/Grok). Both
+ * kinds publish through the shared cache; callers use this only to distinguish
+ * provider I/O from local collection.
  */
 export declare function agentUsesNetworkUsage(agentId: AgentId): boolean;
 /**
@@ -181,56 +204,24 @@ export declare function agentUsesNetworkUsage(agentId: AgentId): boolean;
  * (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;
-export declare const USAGE_CACHE_SWR_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.
+ * JSON export). Deduplicates by usage identity and reads the shared snapshot.
+ * Only an explicit `forceRefresh` call may collect provider or local-log state.
  */
-export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: {
+export interface UsageLookupOptions {
     forceRefresh?: boolean;
-    maxAgeMs?: number;
-    readOnly?: boolean;
-}): Promise<{
+    fileOnly?: boolean;
+}
+export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: UsageLookupOptions): 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.
+ * Fetch usage for one identity. Ordinary callers always read the shared cache;
+ * the daemon and explicit `--refresh` calls collect through one device lease.
  */
-export declare function swrWindowMsFor(maxAgeMs?: number): number;
-/**
- * Fetch usage for a single identity using stale-while-revalidate.
- *
- * - 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` / `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>;
+export declare function getUsageInfoForIdentity(input: UsageIdentityInput, opts?: UsageLookupOptions): Promise<UsageInfo>;
 /**
  * Pick which usage windows to render in a compact one-line summary.
  *
@@ -245,6 +236,12 @@ export declare function pickCompactUsageWindows(windows: UsageWindow[], maxWindo
 export interface FormatUsageSummaryOpts {
     unavailable?: boolean;
     unverified?: boolean;
+    /**
+     * Setup-token lacks `user:profile` so usage cannot be read headlessly
+     * (RUSH-2392). Distinct from generic `unverified` (cache unconfirmed) —
+     * minting again will not help; the account still runs.
+     */
+    headless?: boolean;
     /**
      * 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
@@ -392,7 +389,7 @@ interface DroidLimitWindow {
     usedPercent?: number | null;
     windowEnd?: string | null;
 }
-/** Response shape from Factory's billing limits endpoint (subset we render). */
+/** Response shape from Factory.ai's billing limits endpoint (subset we render). */
 export interface DroidBillingLimitsResponse {
     usesTokenRateLimitsBilling?: boolean | null;
     limits?: {
@@ -404,7 +401,7 @@ export interface DroidBillingLimitsResponse {
     } | null;
 }
 /**
- * Fetch Droid usage via Factory's billing limits API — the same endpoint the
+ * Fetch Droid usage via Factory.ai's billing limits API — the same endpoint the
  * droid CLI polls for its token-limit banner. The WorkOS access token comes
  * from the locally decrypted ~/.factory/auth.v2.file (the same credential
  * account identity in agents.ts reads).
@@ -435,6 +432,13 @@ export interface ProviderProbe {
     token: 'present' | 'missing' | 'expired';
     /** Network/parse error message when status is null but a token was present. */
     error?: string;
+    /**
+     * Known non-revocation cause for a non-2xx status.
+     * `usage_scope` — Anthropic returned 403 because the setup-token lacks
+     * `user:profile` (RUSH-2392). Token is valid for inference; usage is unreadable.
+     * Auth-health MUST NOT map this to `revoked`.
+     */
+    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>;
@@ -471,7 +475,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/design/credential-management.md). It is OFF by default so full-credential
+ * docs/credential-management.md). It is OFF by default so full-credential
  * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) or export
  * the full blob (`readClaudeCredentialsBlob` for Rush Cloud dispatch) still read
  * the interactive login.