@phnx-labs/agents-cli 1.20.67 → 1.20.69

package/dist/lib/usage.d.ts

@@ -66,8 +66,18 @@ export declare function buildCanonicalUsageContext(inputs: UsageIdentityInput[])
     canonicalByUsageKey: Map<string, AccountInfo>;
     usageFetchInputs: Map<string, UsageFetchInput>;
 };
+/**
+ * Whether an agent exposes usage/limit data we can render — Claude/Kimi/Droid via
+ * a live API, Codex 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, Grok, 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[]): Promise<{
+export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: {
+    forceRefresh?: boolean;
+}): Promise<{
     canonicalByUsageKey: Map<string, AccountInfo>;
     usageByKey: Map<string, UsageInfo>;
 }>;
@@ -83,9 +93,13 @@ export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[]): Pr
  * cache; every run after that returns instantly while the cache silently
  * refreshes in the background.
  */
-export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Promise<UsageInfo>;
+export declare function getUsageInfoForIdentity(input: UsageIdentityInput, opts?: {
+    forceRefresh?: 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): string;
+export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number, opts?: {
+    unavailable?: boolean;
+}): 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
@@ -170,6 +184,29 @@ export interface DroidBillingLimitsResponse {
         } | null;
     } | null;
 }
+/**
+ * Live auth probes — the same authenticated GET the usage fetchers above do,
+ * but surfacing the raw HTTP status instead of swallowing 401/expired to null.
+ * These back `agents fleet ping` and the fleet auth-health cache: completing a
+ * real request is the only proof a token is accepted. The local "signed in"
+ * flag cannot tell a revoked-but-unexpired token from a good one. Classification
+ * of the returned status into a verdict lives in lib/auth-health.ts (kept there
+ * so it stays pure/testable and to avoid an import cycle).
+ */
+export interface ProviderProbe {
+    /** HTTP status of the probe request, or null when no request was made (missing/expired token) or the request threw. */
+    status: number | null;
+    /** Local credential state observed before the request. */
+    token: 'present' | 'missing' | 'expired';
+    /** Network/parse error message when status is null but a token was present. */
+    error?: string;
+}
+/** Probe Claude's OAuth token against the usage endpoint. Refreshes an expired access token (safe for Claude). */
+export declare function probeClaudeStatus(home?: string, cliVersion?: 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>;
+/** 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>;
 /**
  * Normalize the Factory billing-limits payload into the common UsageWindow
  * shape. Orgs on the legacy (non token-rate-limit) billing model have no

package/dist/lib/usage.js

@@ -87,8 +87,18 @@ export function buildCanonicalUsageContext(inputs) {
     }
     return { canonicalByUsageKey, usageFetchInputs };
 }
+/**
+ * Whether an agent exposes usage/limit data we can render — Claude/Kimi/Droid via
+ * a live API, Codex 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, Grok, OpenCode).
+ */
+export function agentReportsUsage(agentId) {
+    return agentId === 'claude' || agentId === 'codex' || agentId === 'kimi' || agentId === 'droid';
+}
 /** Fetch usage info for all unique accounts in parallel, keyed by usage key. */
-export async function getUsageInfoByIdentity(inputs) {
+export async function getUsageInfoByIdentity(inputs, opts) {
     const { canonicalByUsageKey, usageFetchInputs } = buildCanonicalUsageContext(inputs);
     const usageResults = await Promise.all([...usageFetchInputs.entries()].map(async ([key, input]) => ({
         key,
@@ -97,7 +107,7 @@ export async function getUsageInfoByIdentity(inputs) {
             home: input.home,
             cliVersion: input.cliVersion,
             info: canonicalByUsageKey.get(key),
-        }),
+        }, opts),
     })));
     return {
         canonicalByUsageKey,
@@ -120,8 +130,9 @@ const inFlightRefreshes = new Map();
  * cache; every run after that returns instantly while the cache silently
  * refreshes in the background.
  */
-export async function getUsageInfoForIdentity(input) {
+export async function getUsageInfoForIdentity(input, opts) {
     const usageKey = getUsageLookupKey(input.info);
+    const forceRefresh = opts?.forceRefresh === true;
     // Agents whose usage comes from a live network call (Claude, Kimi, Droid) go
     // through the stale-while-revalidate cache below so `agents run`/`agents view`
     // stay off the network on the hot path. Everything else (Codex reads local
@@ -139,15 +150,20 @@ export async function getUsageInfoForIdentity(input) {
     }
     const cached = readClaudeUsageCache(usageKey);
     const ageMs = cached?.capturedAt ? Date.now() - cached.capturedAt.getTime() : Infinity;
-    // Fresh: cache is recent enough, skip network entirely.
-    if (cached && ageMs < USAGE_CACHE_FRESH_MS) {
-        return { snapshot: cached, error: null };
-    }
-    // Stale-while-revalidate: cache exists and isn't ancient, return it now and
-    // refresh in the background so the next invocation has fresh data.
-    if (cached && ageMs < USAGE_CACHE_SWR_MS) {
-        triggerBackgroundUsageRefresh(input, usageKey);
-        return { snapshot: cached, error: null };
+    // `--refresh` (forceRefresh) skips both cache short-circuits and blocks on a
+    // live fetch below, so `agents view --refresh` repopulates every account we can
+    // actually reach a token for.
+    if (!forceRefresh) {
+        // Fresh: cache is recent enough, skip network entirely.
+        if (cached && ageMs < USAGE_CACHE_FRESH_MS) {
+            return { snapshot: cached, error: null };
+        }
+        // Stale-while-revalidate: cache exists and isn't ancient, return it now and
+        // refresh in the background so the next invocation has fresh data.
+        if (cached && ageMs < USAGE_CACHE_SWR_MS) {
+            triggerBackgroundUsageRefresh(input, usageKey);
+            return { snapshot: cached, error: null };
+        }
     }
     // Cold cache or > 24h old: block on live fetch.
     const usage = await getUsageInfo(input.agentId, {
@@ -201,7 +217,7 @@ function triggerBackgroundUsageRefresh(input, usageKey) {
     inFlightRefreshes.set(usageKey, promise);
 }
 /** Format a one-line usage summary with compact bars for inline display. */
-export function formatUsageSummary(plan, snapshot, planWidth = 3) {
+export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
     const parts = [];
     if (plan) {
         parts.push(chalk.gray(plan.padEnd(planWidth)));
@@ -212,14 +228,26 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
         // account throttled by its month window (Droid meters on 5h/week/month)
         // shows the bar that explains why. Claude's Sonnet week is a per-model
         // sub-limit, not a blocking window; it renders only in the full
-        // per-version usage section.
+        // per-version usage section. Each window reads "S: ███░░ 58% (3d)" — the
+        // gauge, the exact percentage, and a compact hint of when it resets.
         const windows = snapshot.windows
             .filter((window) => window.key !== 'sonnet_week')
-            .map((window) => `${chalk.gray(`${window.shortLabel}:`)} ${renderCompactUsageBar(window.usedPercent)}`);
+            .map((window) => {
+            const bar = renderCompactUsageBar(window.usedPercent);
+            const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
+            const reset = window.resetsAt ? chalk.dim(` (${formatResetHint(window.resetsAt)})`) : '';
+            return `${chalk.gray(`${window.shortLabel}:`)} ${bar} ${pct}${reset}`;
+        });
         if (windows.length > 0) {
-            parts.push(windows.join(' '));
+            parts.push(windows.join('  '));
         }
     }
+    else if (opts?.unavailable) {
+        // Signed-in account we could NOT fetch usage for (no live token in a reachable
+        // home / org mismatch / fetch error). Say so explicitly instead of drawing a
+        // blank gauge that reads like "0% used".
+        parts.push(chalk.dim('usage unavailable'));
+    }
     return parts.join('  ');
 }
 /**
@@ -581,6 +609,90 @@ async function getDroidUsageInfo(options) {
         return { snapshot: null, error: null };
     }
 }
+/** Probe Claude's OAuth token against the usage endpoint. Refreshes an expired access token (safe for Claude). */
+export async function probeClaudeStatus(home, cliVersion) {
+    const oauth = await loadClaudeOauth(home);
+    if (!oauth?.accessToken)
+        return { status: null, token: 'missing' };
+    let access = null;
+    try {
+        access = await getClaudeAccessToken(oauth, home);
+    }
+    catch {
+        access = null;
+    }
+    // Fall back to the stored (possibly stale) token so the server returns the
+    // real verdict — a 401 here IS the revoked/expired signal we want to surface.
+    const bearer = access || oauth.accessToken.trim();
+    try {
+        const response = await fetch(CLAUDE_USAGE_URL, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${bearer}`,
+                'Content-Type': 'application/json',
+                'anthropic-beta': CLAUDE_OAUTH_BETA_HEADER,
+                'User-Agent': getClaudeUserAgent(cliVersion),
+            },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
+export async function probeKimiStatus(home) {
+    const credPath = resolveKimiCredentialPath(home);
+    if (!credPath)
+        return { status: null, token: 'missing' };
+    let accessToken;
+    let expiresAt = null;
+    try {
+        const cred = JSON.parse(fs.readFileSync(credPath, 'utf-8'));
+        accessToken = typeof cred?.access_token === 'string' ? cred.access_token : undefined;
+        expiresAt = typeof cred?.expires_at === 'number' ? cred.expires_at : null;
+    }
+    catch {
+        return { status: null, token: 'missing' };
+    }
+    if (!accessToken)
+        return { status: null, token: 'missing' };
+    if (expiresAt !== null && Date.now() / 1000 >= expiresAt)
+        return { status: null, token: 'expired' };
+    try {
+        const response = await fetch(KIMI_USAGES_URL, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Probe Droid's WorkOS token against the billing-limits endpoint. Never refreshes (single-use rotation — see getDroidUsageInfo). */
+export async function probeDroidStatus(home) {
+    const cred = decryptDroidAuthPayload(home || os.homedir());
+    const accessToken = cred?.access_token;
+    if (typeof accessToken !== 'string' || !accessToken)
+        return { status: null, token: 'missing' };
+    const exp = decodeJwtPayload(accessToken)?.exp;
+    if (typeof exp === 'number' && Date.now() / 1000 >= exp)
+        return { status: null, token: 'expired' };
+    try {
+        const response = await fetch(DROID_USAGE_URL, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
 /**
  * Normalize the Factory billing-limits payload into the common UsageWindow
  * shape. Orgs on the legacy (non token-rate-limit) billing model have no
@@ -1096,6 +1208,25 @@ function formatPercent(value) {
     const rounded = Math.round(value * 10) / 10;
     return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
 }
+/**
+ * Compact "time until reset" hint for the inline usage bars: "5m", "2h", "3d",
+ * or "now" once elapsed. Deliberately coarse (single unit, whole numbers) so it
+ * fits after a bar without wrapping the row — the detailed section
+ * (`formatResetAt`) carries the precise clock time.
+ */
+function formatResetHint(date) {
+    const diffMs = date.getTime() - Date.now();
+    if (diffMs <= 0)
+        return 'now';
+    const mins = Math.round(diffMs / 60000);
+    if (mins < 60)
+        return `${Math.max(1, mins)}m`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.round(hours / 24);
+    return `${days}d`;
+}
 /** Format a reset timestamp as a human-readable relative or absolute time. */
 function formatResetAt(date) {
     const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.67",
+  "version": "1.20.69",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",