@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/account-capabilities.js

@@ -1,10 +1,21 @@
+/** Native-login selector coverage required by RUSH-3053. */
+export const NATIVE_ACCOUNT_SELECTOR_AGENTS = ['claude', 'codex', 'cursor', 'grok', 'kimi'];
+/** Explicit dispositions for config-isolated harnesses outside that selector. */
+export const NATIVE_ACCOUNT_SELECTOR_EXCLUSIONS = {
+    copilot: 'no inspectable native identity',
+    opencode: 'provider-set identity is not safely attributable to one native login',
+    muse: 'email-only conditional identity is outside the RUSH-3053 harness contract',
+};
 /** Canonical truth for native-account naming and attachment semantics. */
 export const NATIVE_ACCOUNT_CAPABILITIES = {
-    // Version-scoped with a strong account key — the only harnesses whose native
-    // identity is safe to pin per installed version.
+    // Config-isolated harnesses with a stable native identity. A labeled launch
+    // may use the auth/config home from one installed version with another binary.
     claude: { inspection: 'strong', scope: 'version', status: 'supported' },
     codex: { inspection: 'strong', scope: 'version', status: 'supported' },
     grok: { inspection: 'strong', scope: 'version', status: 'supported' },
+    cursor: { inspection: 'strong', scope: 'version', status: 'supported' },
+    // Kimi exposes a stable opaque id but no email, so it requires a manual label.
+    kimi: { inspection: 'opaque', scope: 'version', status: 'supported' },
     // Version-scoped but only an email identity — nameable only when that email is
     // present (the resolver rejects an emailless Muse login).
     muse: { inspection: 'email', scope: 'version', status: 'conditional' },
@@ -17,12 +28,8 @@ export const NATIVE_ACCOUNT_CAPABILITIES = {
     // "unsupported" is correct until a device-scoped identity key (with a stable
     // device id) exists to validate against.
     antigravity: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
-    kimi: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
     droid: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
     opencode: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
-    // Cursor multi-account isolation is unresolved (RUSH-2400) — blocked from
-    // native naming/attachment; its API-key path is a provider account instead.
-    cursor: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
     // Discoverable in the list, but not nameable.
     gemini: { inspection: 'email', scope: 'unsupported', status: 'discovery-only' },
     copilot: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
@@ -62,9 +69,6 @@ export function nativeAccountNamingRefusal(agent) {
     if (cap.scope === 'device') {
         return `${agent} accounts can't be isolated by agents-cli yet (device-scoped login). ${suffix}`;
     }
-    if (agent === 'cursor') {
-        return `${agent} accounts can't be isolated by agents-cli yet (multi-account isolation unresolved). ${suffix}`;
-    }
     if (cap.status === 'discovery-only') {
         return `${agent} native accounts are discovery-only; agents-cli cannot name or attach this login. ${suffix}`;
     }

package/dist/lib/account-registry.d.ts

@@ -48,6 +48,8 @@ export declare function listNativeAccounts(meta: Pick<Meta, 'accounts'>): Native
  */
 export declare function findUnifiedAccount(nameOrId: string, meta: Pick<Meta, 'accounts'>, doc?: AccountRegistryDocument): UnifiedAccount | null;
 export declare function addNativeAccount(name: string, agent: AgentId, identityKey: string, identityLabel: string | undefined, scope: 'version' | 'device'): NativeAccount;
+/** Create or replace the version-independent label for one native identity. */
+export declare function labelNativeAccount(agent: AgentId, identityKey: string, identityLabel: string | undefined, label: string | undefined, scope: 'version' | 'device'): NativeAccount;
 export declare function bindAccount(nameOrId: string, target: string): UnifiedAccount;
 export declare function unbindAccount(nameOrId: string, target: string): void;
 export declare function accountBindings(accountId: string, meta: Pick<Meta, 'accounts'>): string[];

package/dist/lib/account-registry.js

@@ -25,12 +25,17 @@ import { bundleExists, deleteBundle, listBundles, readBundle, renameBundle, writ
 import { getAccountProvider } from './account-provider-registry.js';
 import { accountSecretItem, buildAccountBundle, parseAccountBundle } from './account-schema.js';
 const NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const NATIVE_LABEL = /^[a-zA-Z0-9][a-zA-Z0-9@._+-]*$/;
 const AUTH_KINDS = ['api-key', 'setup-token', 'bearer-token'];
 export function accountRegistryPath(base = getUserAgentsDir()) { return path.join(base, 'accounts.yaml'); }
 function assertName(name) {
     if (!NAME.test(name))
         throw new Error('Account name must start with a letter or number and contain only letters, numbers, dot, underscore, or dash.');
 }
+function assertNativeLabel(label) {
+    if (!NATIVE_LABEL.test(label))
+        throw new Error('Account label must start with a letter or number and contain only letters, numbers, @, dot, underscore, plus, or dash.');
+}
 function isAccountAuthKind(value) {
     return typeof value === 'string' && AUTH_KINDS.includes(value);
 }
@@ -143,7 +148,8 @@ export function listNativeAccounts(meta) {
  * able to omit it.
  */
 export function findUnifiedAccount(nameOrId, meta, doc) {
-    const native = listNativeAccounts(meta).find(account => account.id === nameOrId || account.name === nameOrId);
+    const needle = nameOrId.toLowerCase();
+    const native = listNativeAccounts(meta).find(account => account.id === nameOrId || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle);
     if (native)
         return native;
     const provider = findAccount(nameOrId, doc ?? readAccountRegistry());
@@ -154,7 +160,7 @@ function assertUniqueUnifiedName(name, meta, doc) {
         throw new Error(`Account '${name}' already exists.`);
 }
 export function addNativeAccount(name, agent, identityKey, identityLabel, scope) {
-    assertName(name);
+    assertNativeLabel(name);
     const meta = readMeta();
     assertUniqueUnifiedName(name, meta);
     const duplicate = listNativeAccounts(meta).find(account => account.agent === agent && account.identityKey === identityKey);
@@ -170,6 +176,28 @@ export function addNativeAccount(name, agent, identityKey, identityLabel, scope)
     }));
     return account;
 }
+/** Create or replace the version-independent label for one native identity. */
+export function labelNativeAccount(agent, identityKey, identityLabel, label, scope) {
+    const resolvedLabel = label ?? identityLabel;
+    if (!resolvedLabel)
+        throw new Error(`${agent} does not expose an email; pass a manual label.`);
+    assertNativeLabel(resolvedLabel);
+    const meta = readMeta();
+    const existing = listNativeAccounts(meta).find(account => account.agent === agent && account.identityKey === identityKey);
+    const collision = findUnifiedAccount(resolvedLabel, meta);
+    if (collision && collision.id !== existing?.id)
+        throw new Error(`Account '${resolvedLabel}' already exists.`);
+    if (!existing)
+        return addNativeAccount(resolvedLabel, agent, identityKey, identityLabel, scope);
+    updateMeta(current => ({
+        ...current,
+        accounts: {
+            ...current.accounts,
+            native: { ...current.accounts?.native, [existing.id]: { ...current.accounts?.native?.[existing.id], name: resolvedLabel, identityLabel } },
+        },
+    }));
+    return { ...existing, name: resolvedLabel, identityLabel };
+}
 export function bindAccount(nameOrId, target) {
     const meta = readMeta();
     const account = findUnifiedAccount(nameOrId, meta);

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

@@ -118,6 +118,15 @@ export declare const USAGE_DECISION_MAX_AGE_MS: number;
 /**
  * Whether this candidate's usage number is recent enough to route on. A missing
  * snapshot is unverified by definition — there is no number to trust.
+ *
+ * A snapshot with NO windows is unverified for the same reason, however fresh
+ * it is: it carries a subscription plan and no utilization, so there is still
+ * no number. Freshness alone would make a meterless harness (Grok reports a
+ * tier and no meters) verify against nothing — and since `preferVerified`
+ * narrows the pool to verified candidates, the one account whose billing log
+ * was touched most recently would win every draw, then win again because
+ * running it refreshes that log. That self-reinforcing pin is exactly what the
+ * narrowing rule below exists to prevent.
  */
 export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
 /**

package/dist/lib/accounting/rotate.js

@@ -113,10 +113,20 @@ export const USAGE_DECISION_MAX_AGE_MS = 5 * 60 * 1000;
 /**
  * Whether this candidate's usage number is recent enough to route on. A missing
  * snapshot is unverified by definition — there is no number to trust.
+ *
+ * A snapshot with NO windows is unverified for the same reason, however fresh
+ * it is: it carries a subscription plan and no utilization, so there is still
+ * no number. Freshness alone would make a meterless harness (Grok reports a
+ * tier and no meters) verify against nothing — and since `preferVerified`
+ * narrows the pool to verified candidates, the one account whose billing log
+ * was touched most recently would win every draw, then win again because
+ * running it refreshes that log. That self-reinforcing pin is exactly what the
+ * narrowing rule below exists to prevent.
  */
 export function isUsageVerified(candidate, nowMs = Date.now()) {
-    const capturedAt = candidate.usageSnapshot?.capturedAt;
-    if (!capturedAt)
+    const snapshot = candidate.usageSnapshot;
+    const capturedAt = snapshot?.capturedAt;
+    if (!capturedAt || !snapshot?.windows.length)
         return false;
     return nowMs - capturedAt.getTime() <= USAGE_DECISION_MAX_AGE_MS;
 }

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,17 +125,29 @@ export interface UsageSnapshot {
     capturedAt: Date | null;
     windows: UsageWindow[];
     plan?: string | null;
-    /** A refusal observed from a real harness run, independent of API windows. */
+    /**
+     * A refusal observed from a real harness run, independent of API windows.
+     * `session_limit` recovers on a clock (`resetsAt`). `out_of_credits` is a
+     * tokens/balance exhaustion that does NOT reset on a clock — it has no
+     * `resetsAt` and is cleared only by a later successful run on the account
+     * (clearClaudeAccountRefusal). Both exclude the account from rotation while set.
+     */
     unavailable?: {
-        reason: 'session_limit';
-        resetsAt: Date;
+        reason: 'session_limit' | 'out_of_credits';
+        resetsAt?: Date;
     };
 }
 /** Usage data plus any error encountered while fetching. */
 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;
@@ -114,6 +160,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.
@@ -253,6 +306,26 @@ export interface FormatUsageSummaryOpts {
      * column width; single-agent and detail views leave this unset.
      */
     maxWindows?: number;
+    /**
+     * 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;
 }
 /** 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;
@@ -446,11 +519,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
@@ -515,6 +588,19 @@ 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;
+/**
+ * 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
+ * on a clock, so no reset time is stored — rotation excludes the account until a
+ * later successful run clears it via {@link clearClaudeAccountRefusal}.
+ */
+export declare function noteClaudeOutOfCredits(usageKey: string, cachePath?: string): void;
+/**
+ * Clear any persisted refusal marker for an account after a run SUCCEEDS on it.
+ * This is the recovery path for `out_of_credits` (which has no clock) and also
+ * proactively clears a stale `session_limit` the moment the account serves again.
+ */
+export declare function clearClaudeAccountRefusal(usageKey: string, cachePath?: string): void;
 /**
  * Persist a Claude session-limit refusal from a real run until its stated reset.
  * This quota is not part of Anthropic's five-hour/weekly usage response.