@phnx-labs/agents-cli 1.20.87 → 1.20.89

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

@@ -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,

package/dist/lib/versions.js

@@ -43,7 +43,7 @@ import { discoverPlugins, marketplaceSpecForName } from './plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
 import { emit } from './events.js';
 import { safeJoin } from './paths.js';
-import { readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
+import { readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from './command-skills.js';
 import { getWriter, getDetector } from './staleness/registry.js';
 import { syncMemoryToVersionHome } from './memory.js';
 import { listPluginSkillNames, resolveCommandSource, resolveSkillSource } from './staleness/writers/sources.js';
@@ -2555,21 +2555,30 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     };
     const trustedCommandNames = (names) => names.filter((name) => resolveCommandSource(name) !== null);
     // Sync commands — dispatch through WRITERS.commands. The writer dispatches
-    // between native (file copy / TOML conversion) and commands-as-skills
-    // (grok, Codex >= 0.117.0) based on `shouldInstallCommandAsSkill`. The
-    // previous COMMANDS_CAPABLE_AGENTS gate excluded grok even though it
-    // takes the commands-as-skills path — silently dropping every command.
+    // between native (file copy / TOML conversion), commands-as-skills, and the
+    // registry-driven dual-write path based on the command-skill predicates. The
+    // previous COMMANDS_CAPABLE_AGENTS gate excluded skills-only targets such as
+    // Kimi, silently dropping every converted command.
     const commandsWriter = getWriter('commands', agent);
     const commandsToSync = selection
         ? trustedCommandNames(resolveSelection(selection.commands, available.commands))
         : trustedCommandNames(available.commands); // No selection = sync all trusted commands, excluding project-only commands
     const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+    const commandsAlsoAsSkills = shouldAlsoInstallCommandAsSkill(agent, version);
+    const commandsInstallAsSkills = commandsAsSkills || commandsAlsoAsSkills;
+    let writtenCommands = [];
     if (commandsToSync.length > 0 && commandsWriter) {
-        const commandsTarget = path.join(agentDir, agentConfig.commandsSubdir);
+        // Agents that replace native command files with skills (codex >= 0.117.0,
+        // kimi) must have their legacy command dir removed, or files written by an
+        // older version linger forever: the orphan sweep below is gated off for
+        // them, and `agents prune` only sees their skills. Gated on
+        // `commandsAsSkills`, never `commandsAlsoAsSkills` -- a dual-write agent's
+        // native dir is a live product surface (Cursor IDE) and must not be wiped.
         if (commandsAsSkills && agentConfig.commandsSubdir) {
-            removePath(commandsTarget);
+            removePath(path.join(agentDir, agentConfig.commandsSubdir));
         }
         const r = commandsWriter.write({ version, versionHome, selection: commandsToSync, cwd });
+        writtenCommands = r.synced;
         result.commands = r.synced.length > 0;
     }
     // Orphan-sweep stale top-level command files from previous syncs under a
@@ -2584,13 +2593,19 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         if (fs.existsSync(commandsTargetSweep)) {
             const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
             const trustedCommands = new Set(commandsToSync);
+            // A dual-write target's native directory also belongs to another product
+            // surface (Cursor IDE). Delete only names the command writer recorded as
+            // successfully emitted during the preceding full sync.
+            const previouslyManagedCommands = commandsAlsoAsSkills
+                ? new Set(loadManifest(agent, version)?.writtenCommands ?? [])
+                : null;
             for (const entry of fs.readdirSync(commandsTargetSweep, { withFileTypes: true })) {
                 if (!entry.isFile() || entry.name.startsWith('.'))
                     continue;
                 if (!entry.name.endsWith(ext))
                     continue;
                 const name = entry.name.slice(0, -ext.length);
-                if (!trustedCommands.has(name)) {
+                if (!trustedCommands.has(name) && (!previouslyManagedCommands || previouslyManagedCommands.has(name))) {
                     removePath(safeJoin(commandsTargetSweep, entry.name));
                 }
             }
@@ -2612,7 +2627,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     let skillsToSync = userPassedSelection
         ? selectedSkillsToSync
         : Array.from(new Set([...selectedSkillsToSync, ...pluginSkillsToSync]));
-    if (commandsAsSkills && commandsToSync.length > 0 && skillsToSync.length > 0) {
+    if (commandsInstallAsSkills && commandsToSync.length > 0 && skillsToSync.length > 0) {
         const commandNames = new Set(commandsToSync);
         const skillRoots = [
             path.join(getUserAgentsDir(), 'skills'),
@@ -2639,13 +2654,13 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         // dot-dirs to keep plugin-managed subtrees (.plugins/, .promptcuts) intact.
         const skillsTargetSweep = path.join(agentDir, 'skills');
         if (!userPassedSelection && fs.existsSync(skillsTargetSweep) && !fs.lstatSync(skillsTargetSweep).isSymbolicLink()) {
-            // Trust real skills AND command-skills: when commandsAsSkills, the
+            // Trust real skills AND command-skills: when commandsInstallAsSkills, the
             // commands writer (above) materialized each command as a skill dir under
             // skills/. Those names are not in skillsToSync, so without this they'd be
             // swept as orphans — silently deleting every converted command (e.g.
-            // /recap on kimi/grok).
+            // /recap on Kimi or newer Codex releases).
             const trustedSkills = new Set(skillsToSync);
-            if (commandsAsSkills)
+            if (commandsInstallAsSkills)
                 for (const cmd of commandsToSync)
                     trustedSkills.add(cmd);
             for (const entry of fs.readdirSync(skillsTargetSweep, { withFileTypes: true })) {
@@ -2866,7 +2881,9 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // one-off override, so the resulting state matches what the manifest
     // records as the synced set.
     if (!userPassedSelection) {
-        saveManifest(agent, version, buildSyncManifest(agent, version, cwd));
+        const manifest = buildSyncManifest(agent, version, cwd);
+        manifest.writtenCommands = writtenCommands;
+        saveManifest(agent, version, manifest);
     }
     return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.87",
+  "version": "1.20.89",
   "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",