@phnx-labs/agents-cli 1.20.86 → 1.20.88

package/dist/lib/session/team-filter.js

@@ -9,6 +9,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { sanitizeForTerminal } from './parse.js';
 import { getTeamsAgentsDir } from '../state.js';
 const HOME = os.homedir();
 // Default path; tests can override via AGENTS_TEAMS_DIR env var.
@@ -21,33 +22,121 @@ function teamsAgentsDir() {
  *
  * Primary signal is `session.isTeamOrigin`, captured at scan time from the
  * JSONL `entrypoint` field ('sdk-cli' for team spawns, 'cli' for real CLI).
- * When a team meta.json exists we additionally enrich with handle/mode — but
- * its absence no longer demotes a session: older team runs whose meta dir
- * was cleaned up still get recognized via the entrypoint flag.
+ * When a team meta.json exists we additionally enrich with handle/mode/team and
+ * the orchestrator that spawned it — but its absence no longer demotes a
+ * session: older team runs whose meta dir was cleaned up still get recognized
+ * via the entrypoint flag.
  *
  * Returns the TeamOrigin metadata when the session is team-origin, or null
  * when it is a normal interactive session.
  */
 export function classifyTeamSession(session) {
-    const metaPath = path.join(teamsAgentsDir(), session.id, 'meta.json');
-    if (fs.existsSync(metaPath)) {
-        try {
-            const raw = fs.readFileSync(metaPath, 'utf-8');
-            const meta = JSON.parse(raw);
-            const name = typeof meta.name === 'string' && meta.name ? meta.name : undefined;
-            const handle = name ?? session.id.slice(0, 8);
-            const mode = typeof meta.mode === 'string' ? meta.mode : undefined;
-            return { handle, mode };
-        }
-        catch {
-            return { handle: session.id.slice(0, 8) };
-        }
-    }
+    const origin = teamOriginIndex().get(session.id);
+    if (origin)
+        return origin;
     if (session.isTeamOrigin) {
         return { handle: session.id.slice(0, 8) };
     }
     return null;
 }
+/**
+ * Parse one teammate `meta.json` into a {@link TeamOrigin}. Degrades to a bare
+ * handle when the file is unreadable or malformed — a teammate whose record we
+ * can't parse is still a teammate.
+ */
+function readTeamOrigin(metaPath, agentId) {
+    try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        const str = (v) => (typeof v === 'string' && v ? v : undefined);
+        return {
+            origin: {
+                handle: str(meta.name) ?? agentId.slice(0, 8),
+                mode: str(meta.mode),
+                team: str(meta.task_name),
+                parentSessionId: str(meta.parent_session_id),
+            },
+            sessionId: str(meta.remote_session_id),
+        };
+    }
+    catch {
+        return { origin: { handle: agentId.slice(0, 8) } };
+    }
+}
+/**
+ * A team name / handle as it is safe to render: a real string, terminal escapes
+ * stripped, or undefined.
+ *
+ * These values reach the row and the preview pane, and for a peer's row they are
+ * whatever JSON that machine sent — `parseRemoteList` copies the object through
+ * without inspecting its fields, so neither the type nor the content is ours to
+ * assume. A non-string `spawnedTeam` used to throw out of `teamBadge`, which runs
+ * on every row, taking down the whole listing rather than one entry.
+ */
+export function safeTeamText(value) {
+    if (typeof value !== 'string' || value === '')
+        return undefined;
+    return sanitizeForTerminal(value);
+}
+/** Cached teammate index; the directory is small (teams GC it after 7 days). */
+let originIndexCache = null;
+/** Drop the cached teammate index — for tests that rewrite AGENTS_TEAMS_DIR. */
+export function _resetTeamOriginIndex() {
+    originIndexCache = null;
+}
+/**
+ * Every teammate record, keyed by the session ids it can be reached under.
+ *
+ * A teammate's directory name is its **agent id**, which is only sometimes the
+ * id of the transcript it produced: the harness mints its own session id, and
+ * the spawn records it separately as `remote_session_id`. Keying the lookup on
+ * the directory name alone therefore missed most teammates — on a live box, 14
+ * of 16 records were reachable only by `remote_session_id` — so a teammate row
+ * could not name its team however good the record was. Both keys are registered.
+ *
+ * Read once per process rather than per row: the old per-session `existsSync` +
+ * `readFileSync` cost a pair of syscalls for every row in the pool, which the
+ * interactive browser re-pays on each hotkey.
+ */
+function teamOriginIndex() {
+    if (originIndexCache)
+        return originIndexCache;
+    const dir = teamsAgentsDir();
+    const index = new Map();
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        entries = [];
+    }
+    for (const agentId of entries) {
+        const metaPath = path.join(dir, agentId, 'meta.json');
+        if (!fs.existsSync(metaPath))
+            continue;
+        const { origin, sessionId } = readTeamOrigin(metaPath, agentId);
+        index.set(agentId, origin);
+        if (sessionId)
+            index.set(sessionId, origin);
+    }
+    originIndexCache = index;
+    return index;
+}
+/**
+ * Attach `teamOrigin` to every team-spawned row in `sessions`, from the shared
+ * teammate index rather than a stat per row.
+ */
+export function enrichTeamOrigins(sessions) {
+    const index = teamOriginIndex();
+    return sessions.map((session) => {
+        // A peer's rows are classified on the peer (its meta.json is on its disk, not
+        // ours) and ride across in the --json fan-out already populated. Re-deriving
+        // here would find no local record and downgrade a named teammate to a bare id.
+        if (session.teamOrigin)
+            return session;
+        const origin = index.get(session.id) ?? (session.isTeamOrigin ? { handle: session.id.slice(0, 8) } : null);
+        return origin ? { ...session, teamOrigin: origin } : session;
+    });
+}
 /**
  * Split `sessions` into visible and hidden (team-origin) groups.
  * When `showTeams` is true every session is visible and `teamOrigin` is

package/dist/lib/session/types.d.ts

@@ -7,7 +7,7 @@
  * speaks these types.
  */
 /** Agents that store session data on disk and can be discovered by `agents sessions`. */
-export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'antigravity' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi' | 'droid';
+export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'antigravity' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi' | 'droid' | 'cursor';
 /** All agents with session discovery support, in display order. */
 export declare const SESSION_AGENTS: SessionAgentId[];
 /**
@@ -88,6 +88,14 @@ export interface TeamOrigin {
     handle?: string;
     /** Agent mode: 'plan', 'edit', 'auto', or 'skip' ('full' accepted as legacy alias for 'skip'). */
     mode?: string;
+    /** The team this teammate belongs to (`task_name` in its meta.json). */
+    team?: string;
+    /**
+     * The orchestrator session that spawned this teammate (`parent_session_id`).
+     * Absent for a team started outside any agent session, and for teammates whose
+     * meta dir has aged past the teams cleanup window.
+     */
+    parentSessionId?: string;
 }
 /** Lightweight metadata for a discovered session, used in listings and pickers. */
 export interface SessionMeta {

package/dist/lib/session/types.js

@@ -7,7 +7,7 @@
  * speaks these types.
  */
 /** All agents with session discovery support, in display order. */
-export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'antigravity', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid'];
+export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'antigravity', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid', 'cursor'];
 /**
  * True when `agent` stores session data `agents sessions` can discover (a member
  * of {@link SESSION_AGENTS}). The single predicate every session-index writer

package/dist/lib/signin-badge.d.ts

@@ -23,6 +23,23 @@ export declare function loginHint(agentId: AgentId): string;
  * agents (the ones the feature is for), so the resume's `forceInteractive` flag is
  * consulted directly.
  */
+/**
+ * Is a Claude run on this box going to authenticate from an ambient
+ * `CLAUDE_CODE_OAUTH_TOKEN` rather than a per-version login?
+ *
+ * `AccountInfo.signedIn` is `!!email` read from a version home's `.claude.json`
+ * (agents.ts), so a version with no account written there reports signed-out —
+ * even though Claude Code authenticates fine from the env token and the run
+ * succeeds. Rendering that as "logged out" sends people hunting a login that is
+ * not missing (a real fleet incident: every version on a box read as locked out
+ * while all of them answered a live prompt).
+ *
+ * It is also the more useful warning: an ambient token is ONE account, so every
+ * version on the box resolves to it and balanced rotation across them rotates
+ * nothing. `env` is a parameter so the branch is testable without mutating the
+ * process environment.
+ */
+export declare function ambientClaudeToken(agentId: AgentId | string, env?: NodeJS.ProcessEnv): boolean;
 export declare function shouldCheckLoginBeforeLaunch(o: {
     interactive?: boolean;
     forceInteractive?: boolean;

package/dist/lib/signin-badge.js

@@ -46,6 +46,25 @@ export function loginHint(agentId) {
  * agents (the ones the feature is for), so the resume's `forceInteractive` flag is
  * consulted directly.
  */
+/**
+ * Is a Claude run on this box going to authenticate from an ambient
+ * `CLAUDE_CODE_OAUTH_TOKEN` rather than a per-version login?
+ *
+ * `AccountInfo.signedIn` is `!!email` read from a version home's `.claude.json`
+ * (agents.ts), so a version with no account written there reports signed-out —
+ * even though Claude Code authenticates fine from the env token and the run
+ * succeeds. Rendering that as "logged out" sends people hunting a login that is
+ * not missing (a real fleet incident: every version on a box read as locked out
+ * while all of them answered a live prompt).
+ *
+ * It is also the more useful warning: an ambient token is ONE account, so every
+ * version on the box resolves to it and balanced rotation across them rotates
+ * nothing. `env` is a parameter so the branch is testable without mutating the
+ * process environment.
+ */
+export function ambientClaudeToken(agentId, env = process.env) {
+    return agentId === 'claude' && (env.CLAUDE_CODE_OAUTH_TOKEN ?? '').trim().length > 0;
+}
 export function shouldCheckLoginBeforeLaunch(o) {
     if (o.json || o.quiet || o.authCheckDisabled || o.rotated)
         return false;

package/dist/lib/staleness/detectors/commands.js

@@ -1,13 +1,14 @@
 /**
- * Commands detector — mirrors versions.ts:343-357. Inspects the version home,
+ * Commands detector — mirrors the command dispatch in versions.ts. Inspects the version home,
  * returns command names. Honors the commands-as-skills marker for skills-only
- * agents (kimi, Codex >= 0.117.0, …); falls back to scanning
- * `{agentDir}/<commandsSubdir>/` for the native path.
+ * agents (Kimi, Codex >= 0.117.0, …), treats the native file as authoritative
+ * for dual-write targets (the skill copy is deliberately absent on a name
+ * collision), and scans `{agentDir}/<commandsSubdir>/` for native-only targets.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, MANAGED_AGENT_IDS, agentConfigDirName } from '../../agents.js';
-import { shouldInstallCommandAsSkill, listCommandSkillsInVersion } from '../../command-skills.js';
+import { listCommandSkillsInVersion, shouldInstallCommandAsSkill, } from '../../command-skills.js';
 import { lazyAgentMap } from '../writers/lazy-map.js';
 function buildCommandsDetector(agent) {
     return {
@@ -23,9 +24,17 @@ function buildCommandsDetector(agent) {
             if (!fs.existsSync(commandsDir))
                 return [];
             const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
-            return fs.readdirSync(commandsDir)
+            const nativeCommands = fs.readdirSync(commandsDir)
                 .filter(f => f.endsWith(ext))
                 .map(f => f.replace(new RegExp(`\\${ext}$`), ''));
+            // For a dual-write target the native file is the authoritative record that
+            // the command synced. The skill copy is derived, and
+            // installCommandSkillToVersion deliberately writes none when a real skill
+            // source already owns the name -- requiring both copies reported those
+            // commands missing forever and drove an `agents refresh` loop no sync could
+            // clear. This also matches `agents doctor`/`prune`, which read the
+            // unfiltered listCommandsInVersionHome.
+            return nativeCommands;
         },
     };
 }

package/dist/lib/staleness/types.d.ts

@@ -44,6 +44,8 @@ export interface SyncManifest {
     v: typeof MANIFEST_VERSION;
     syncedAt: string;
     commands: Record<string, FileEntry>;
+    /** Command names the version writer emitted during the preceding full sync. */
+    writtenCommands?: string[];
     skills: Record<string, DirEntry>;
     hooks: Record<string, FileEntry>;
     rules: RulesEntry;

package/dist/lib/staleness/writers/commands.js

@@ -1,12 +1,14 @@
 /**
  * Commands writer.
  *
- * Two physical formats, picked per-(agent, version) at write time:
+ * Two physical formats, selected per-(agent, version) at write time. Most
+ * agents receive one format; dual-write registry targets receive both:
  *
  *  - command-as-skill — fires when `shouldInstallCommandAsSkill(agent, version)`
  *    is true. Used for Codex >= 0.117.0 (commands capability ends, skills
  *    capability remains) and agents with skills but no native command-file dir
- *    such as kimi. Writes `{agentDir}/skills/<name>/SKILL.md` with the
+ *    such as Kimi. Cursor also receives this format in addition to its IDE
+ *    command file. Writes `{agentDir}/skills/<name>/SKILL.md` with the
  *    `agents_command` marker; the agent picks it up as a slash-command equivalent.
  *
  *  - native command file — `{agentDir}/<commandsSubdir>/<name>.md` (or .toml
@@ -23,7 +25,7 @@ import { supports } from '../../capabilities.js';
 import { safeJoin } from '../../paths.js';
 import { markdownToToml } from '../../convert.js';
 import { commandAppliesTo, parseCommandMetadata } from '../../commands.js';
-import { installCommandSkillToVersion, shouldInstallCommandAsSkill } from '../../command-skills.js';
+import { installCommandSkillToVersion, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../../command-skills.js';
 import { installGooseCommandToVersion } from '../../goose-commands.js';
 import { resolveCommandSource, trustedSkillRoots } from './sources.js';
 import { lazyAgentMap } from './lazy-map.js';
@@ -35,6 +37,7 @@ function buildCommandsWriter(agent) {
             const agentConfig = AGENTS[agent];
             const agentDir = path.join(versionHome, agentConfigDirName(agent));
             const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+            const commandsAlsoAsSkills = shouldAlsoInstallCommandAsSkill(agent, version);
             const supportsCommands = supports(agent, 'commands', version).ok;
             // Version-gated agents (e.g. goose skills >= 1.25.0) are registered but
             // may be called at a version too old for both paths — skip gracefully.
@@ -54,23 +57,25 @@ function buildCommandsWriter(agent) {
                 const metadata = parseCommandMetadata(srcFile);
                 if (!commandAppliesTo(agent, version, metadata).ok)
                     continue;
-                if (commandsAsSkills) {
+                if (commandsAsSkills || commandsAlsoAsSkills) {
                     const installed = installCommandSkillToVersion(agentDir, cmd, srcFile, skillRoots);
+                    // installed.skipped means a real skill source already owns this name,
+                    // which is a deliberate no-op, not a failure — the native file is still written.
                     if (!installed.success)
                         continue;
                 }
-                else if (agent === 'goose') {
+                if (supportsCommands && agent === 'goose') {
                     // Goose: recipe YAML + config.yaml slash_commands entry, not a file copy.
                     const installed = installGooseCommandToVersion(versionHome, cmd, srcFile);
                     if (!installed.success)
                         continue;
                 }
-                else if (agentConfig.format === 'toml') {
+                else if (supportsCommands && agentConfig.format === 'toml') {
                     const content = fs.readFileSync(srcFile, 'utf-8');
                     const tomlContent = markdownToToml(cmd, content);
                     fs.writeFileSync(safeJoin(commandsTarget, `${cmd}.toml`), tomlContent);
                 }
-                else {
+                else if (supportsCommands) {
                     fs.copyFileSync(srcFile, safeJoin(commandsTarget, `${cmd}.md`));
                 }
                 synced.push(cmd);
@@ -84,6 +89,7 @@ function buildCommandsWriter(agent) {
 // Registration covers two cases:
 //   - native commands (claude, codex < 0.117.0, grok, etc.) — `commands` cap
 //   - commands-as-skills (kimi, codex >= 0.117.0)
+//   - dual-write commands plus command-skills (cursor)
 //
 // Agents that have skills but use a NATIVE non-file slash-command system
 // (openclaw → Gateway-based commands) are NOT registered. They declare

package/dist/lib/state.d.ts

@@ -181,6 +181,8 @@ export declare function getTeamsRegistryPath(): string;
 export declare function getDevicesRegistryPath(): string;
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export declare function getDevicesIgnoredPath(): string;
+/** Path to the device auto-launch preference file — which registered devices are eligible/preferred for Factory's auto-host selection. Per-machine, same dir as the registry. */
+export declare function getDevicesAutoLaunchPath(): string;
 /** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
 export declare function getDevicesPendingDir(): string;
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */

package/dist/lib/state.js

@@ -402,6 +402,8 @@ function getDevicesDir() {
 export function getDevicesRegistryPath() { return path.join(getDevicesDir(), 'registry.json'); }
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export function getDevicesIgnoredPath() { return path.join(getDevicesDir(), 'ignored.json'); }
+/** Path to the device auto-launch preference file — which registered devices are eligible/preferred for Factory's auto-host selection. Per-machine, same dir as the registry. */
+export function getDevicesAutoLaunchPath() { return path.join(getDevicesDir(), 'auto-launch.json'); }
 /** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
 export function getDevicesPendingDir() { return path.join(RUNTIME_STATE_DIR, 'devices-pending'); }
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */

package/dist/lib/usage.d.ts

@@ -66,7 +66,35 @@ interface ClaudeOauthCredentials {
     rateLimitTier?: string | null;
     organizationUuid?: string | null;
 }
-/** Fetch usage info for a given agent, dispatching to the agent-specific implementation. */
+/** The single registry of agent usage sources and their transport. */
+declare const USAGE_SOURCES: {
+    readonly claude: {
+        readonly fetch: typeof getClaudeUsageInfo;
+        readonly network: true;
+    };
+    readonly codex: {
+        readonly fetch: typeof getCodexUsageInfo;
+        readonly network: false;
+    };
+    readonly kimi: {
+        readonly fetch: typeof getKimiUsageInfo;
+        readonly network: true;
+    };
+    readonly droid: {
+        readonly fetch: typeof getDroidUsageInfo;
+        readonly network: true;
+    };
+    readonly grok: {
+        readonly fetch: typeof getGrokUsageInfo;
+        readonly network: false;
+    };
+    readonly cursor: {
+        readonly fetch: typeof getCursorUsageInfo;
+        readonly network: true;
+    };
+};
+export declare const USAGE_SOURCE_AGENT_IDS: (keyof typeof USAGE_SOURCES)[];
+/** Fetch usage info for a given agent through the canonical source registry. */
 export declare function getUsageInfo(agentId: AgentId, options?: UsageOptions): Promise<UsageInfo>;
 /** Derive a stable lookup key from account info for usage deduplication. */
 export declare function getUsageLookupKey(info?: Pick<AccountInfo, 'usageKey' | 'accountKey'> | null): string | null;
@@ -151,6 +179,8 @@ export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot |
 export declare function formatUsageStatusBadge(usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null | undefined): string;
 /** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
+/** Fetch Codex usage by scanning the most recent session files for rate-limit events. */
+declare function getCodexUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 /**
  * The access token to use for a READ-ONLY Claude usage fetch, or null when the
  * stored token is within the refresh leeway.
@@ -167,6 +197,8 @@ export declare function formatUsageSection(usage: UsageInfo): string[];
  * Pure — unit-tested.
  */
 export declare function claudeUsageAccessTokenNoRefresh(oauth: Pick<ClaudeOauthCredentials, 'accessToken' | 'expiresAt'>): string | null;
+/** Fetch Claude usage via the Anthropic OAuth usage API. */
+declare function getClaudeUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 /** Raw quota bucket from the Kimi /usages response (numbers arrive as strings). */
 interface KimiUsageQuota {
     limit?: string | number | null;
@@ -192,6 +224,18 @@ export interface KimiUsagesResponse {
     } | null> | null;
     subType?: string | null;
 }
+/**
+ * Fetch Kimi usage via the Kimi Code /usages API. Kimi's JWT has no email
+ * claim, so the account row can't show an address — but /usages returns quota
+ * windows and the membership tier, which is what we render.
+ *
+ * Deliberately NO token refresh: `agents view` is a read/inspect command and
+ * must not rotate the user's Kimi OAuth credential (rewriting the file,
+ * invalidating the old refresh token, racing a concurrently-running kimi CLI).
+ * The kimi CLI refreshes on its own launch; if the stored token is expired we
+ * skip the live fetch and let the SWR cache serve the last-seen snapshot.
+ */
+declare function getKimiUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 /** Normalize the Kimi /usages payload into the common UsageWindow shape. */
 export declare function normalizeKimiWindows(data: KimiUsagesResponse): UsageWindow[];
 /** Derive a display plan label from Kimi's membership tier or subscription type. */
@@ -212,6 +256,22 @@ export interface DroidBillingLimitsResponse {
         } | null;
     } | null;
 }
+/**
+ * Fetch Droid usage via Factory'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).
+ *
+ * Deliberately NO token refresh, for a sharper reason than Kimi's: WorkOS
+ * refresh tokens are single-use and rotate on every exchange, so refreshing
+ * here would race a concurrently running droid session and can permanently
+ * invalidate the user's login chain. Droid refreshes its own credential when
+ * it runs; if the stored token is expired we skip the live fetch and let the
+ * SWR cache serve the last-seen snapshot. This same single-use-rotation property
+ * is why `agents apply` refuses to propagate droid credentials across machines
+ * (see `isCredentialSafeToPropagate` in `../fleet/auth-sync.ts`).
+ */
+declare function getDroidUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 /**
  * 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.
@@ -296,6 +356,8 @@ export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageS
  * Returns true only when a valid access token can be obtained.
  */
 export declare function isClaudeAuthValid(home?: string): Promise<boolean>;
+/** Parse the latest billing info from Grok's unified log. */
+declare function getGrokUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 /** Per-model bucket in Cursor's /api/usage response. */
 interface CursorUsageModel {
     numRequests?: number | null;
@@ -319,4 +381,13 @@ export interface CursorUsageResponse {
  * bar to draw here and return no windows rather than a misleading empty gauge.
  */
 export declare function normalizeCursorUsage(data: CursorUsageResponse): 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).
+ */
+declare function getCursorUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 export {};

package/dist/lib/usage.js

@@ -18,7 +18,7 @@ import chalk from 'chalk';
 import { decodeJwtPayload, decryptDroidAuthPayload } from './agents.js';
 import { walkForFiles } from './fs-walk.js';
 import { getKeychainToken, setKeychainToken, deleteKeychainToken, isKeychainBackendOverridden, } from './secrets/index.js';
-import { bundleExists, bundleBackend, readAndResolveBundleEnv } from './secrets/bundles.js';
+import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { getCacheDir } from './state.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
@@ -59,24 +59,23 @@ const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
 const EMPTY = '\u2591';
-/** Fetch usage info for a given agent, dispatching to the agent-specific implementation. */
+/** The single registry of agent usage sources and their transport. */
+const USAGE_SOURCES = {
+    claude: { fetch: getClaudeUsageInfo, network: true },
+    codex: { fetch: getCodexUsageInfo, network: false },
+    kimi: { fetch: getKimiUsageInfo, network: true },
+    droid: { fetch: getDroidUsageInfo, network: true },
+    grok: { fetch: getGrokUsageInfo, network: false },
+    cursor: { fetch: getCursorUsageInfo, network: true },
+};
+export const USAGE_SOURCE_AGENT_IDS = Object.keys(USAGE_SOURCES);
+function getUsageSource(agentId) {
+    return USAGE_SOURCES[agentId];
+}
+/** Fetch usage info for a given agent through the canonical source registry. */
 export async function getUsageInfo(agentId, options) {
-    switch (agentId) {
-        case 'claude':
-            return getClaudeUsageInfo(options);
-        case 'codex':
-            return getCodexUsageInfo(options);
-        case 'kimi':
-            return getKimiUsageInfo(options);
-        case 'droid':
-            return getDroidUsageInfo(options);
-        case 'grok':
-            return getGrokUsageInfo(options);
-        case 'cursor':
-            return getCursorUsageInfo(options);
-        default:
-            return { snapshot: null, error: null };
-    }
+    const source = getUsageSource(agentId);
+    return source ? source.fetch(options) : { snapshot: null, error: null };
 }
 /** Derive a stable lookup key from account info for usage deduplication. */
 export function getUsageLookupKey(info) {
@@ -117,12 +116,7 @@ export function buildCanonicalUsageContext(inputs) {
  * versus simply not applicable (Antigravity, OpenCode).
  */
 export function agentReportsUsage(agentId) {
-    return (agentId === 'claude' ||
-        agentId === 'codex' ||
-        agentId === 'kimi' ||
-        agentId === 'droid' ||
-        agentId === 'grok' ||
-        agentId === 'cursor');
+    return getUsageSource(agentId) !== undefined;
 }
 /** Fetch usage info for all unique accounts in parallel, keyed by usage key. */
 export async function getUsageInfoByIdentity(inputs, opts) {
@@ -160,14 +154,14 @@ const inFlightRefreshes = new Map();
 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
+    // Agents whose registered usage source makes a live network call 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
     // session logs) takes the legacy blocking path. The on-disk cache is shared and
     // keyed by usageKey, which is namespaced per agent (`claude:org=…`,
-    // `kimi:user=…`, `droid:org=…`), so one cache file holds every account without
-    // collision.
-    const usesNetworkUsage = input.agentId === 'claude' || input.agentId === 'kimi' || input.agentId === 'droid';
+    // `kimi:user=…`, `droid:org=…`, `cursor:user=…`), so one cache file holds every
+    // account without collision.
+    const usesNetworkUsage = getUsageSource(input.agentId)?.network === true;
     if (!usesNetworkUsage || !usageKey) {
         return getUsageInfo(input.agentId, {
             home: input.home,
@@ -999,65 +993,6 @@ function deleteCachedClaudeOauth(service) {
         /* best-effort — cache is an optimization */
     }
 }
-/**
- * Reserved FILE-BASED secrets bundle holding long-lived, non-rotating Claude
- * setup-tokens. Usage/probe reads authenticate with these instead of Claude
- * Code's ACL-bound login item, so they never pop Touch ID. Keyed strictly
- * per-account (`CLAUDE_CODE_OAUTH_TOKEN_<slug>` from the account email) — never a
- * bare key, so one account's token can't be misapplied to another in a
- * multi-account fleet.
- */
-const AUTH_BUNDLE = 'auth';
-/** The per-account key an email maps to inside the `auth` bundle. */
-function claudeAccountTokenKey(account) {
-    const slug = account
-        .trim()
-        .toUpperCase()
-        .replace(/@/g, '_AT_')
-        .replace(/\./g, '_DOT_')
-        .replace(/[^A-Z0-9_]/g, '_');
-    return `CLAUDE_CODE_OAUTH_TOKEN_${slug}`;
-}
-/** Signed-in account email for a version home, from `.claude.json` (no keychain). */
-function readClaudeAccountEmail(home) {
-    const base = home ?? os.homedir();
-    for (const p of [path.join(base, '.claude', '.claude.json'), path.join(base, '.claude.json')]) {
-        try {
-            const email = JSON.parse(fs.readFileSync(p, 'utf-8')).oauthAccount?.emailAddress;
-            if (typeof email === 'string' && email.trim().length > 0)
-                return email.trim();
-        }
-        catch {
-            // Missing/unreadable at this location — try the next.
-        }
-    }
-    return null;
-}
-/**
- * Resolve a long-lived `claude setup-token` for the account signed into `home`
- * from the reserved FILE-BASED `auth` bundle. Returns the token or null. Reads
- * ONLY when the bundle is file-backed (never keychain), so this path itself can
- * never trigger a Touch ID prompt — that is the entire point: usage/probe reads
- * authenticate with the shareable setup-token, not the ACL-bound login item.
- */
-function resolveClaudeSetupToken(home) {
-    try {
-        // Require a known account (email) up front: without it we cannot key a
-        // per-account token, and we must NOT fall back to a bare shared key that
-        // would misapply one account's setup-token to another.
-        const email = readClaudeAccountEmail(home);
-        if (!email)
-            return null;
-        if (!bundleExists(AUTH_BUNDLE) || bundleBackend(AUTH_BUNDLE) !== 'file')
-            return null;
-        const { env } = readAndResolveBundleEnv(AUTH_BUNDLE, { caller: 'usage', agentOnly: true });
-        const v = (env[claudeAccountTokenKey(email)] ?? '').trim();
-        return v.length > 0 ? v : null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Load a version home's Claude OAuth credential from the two stores Claude Code
  * uses, tried in order: