@phnx-labs/agents-cli 1.20.32 → 1.20.34

package/dist/lib/sync-status.js

@@ -0,0 +1,135 @@
+/**
+ * Unified sync-status engine — the SINGLE source of truth for "is this resource
+ * synced to this agent version?" consumed by `agents doctor`, `agents view`, the
+ * menu-bar app, and any Agency surface.
+ *
+ * Why this exists: before this module there were four different notions of
+ * "synced" living in four files:
+ *   - doctor:  isStale() vs .sync-manifest.json  — catches SOURCE drift only.
+ *   - view:    git working-tree state of ~/.agents/ — a resource can show green
+ *              while its installed copy is stale/deleted/corrupted (false positive).
+ *   - lists:   file-exists-in-home — never reports content drift at all.
+ *   - menubar: read doctor --json (so it inherited doctor's source-only blind spot).
+ *
+ * The reliable signal is diffVersionResources() (src/lib/doctor-diff.ts): it reads
+ * the ACTUAL version home and compares it to the resolved sources, so it catches
+ * every drift class — source-side changes AND home-side rot (deleted / corrupted /
+ * hand-edited installed copies) AND orphans. This module wraps it once, maps its
+ * per-resource DiffStatus onto one stable enum, folds in `.system` repo freshness,
+ * and lets every surface render the same warnings instead of re-deriving them.
+ */
+import simpleGit from 'simple-git';
+import { ALL_AGENT_IDS } from './agents.js';
+import { diffVersionResources, } from './doctor-diff.js';
+import { listInstalledVersions, getGlobalDefault } from './versions.js';
+import { loadManifest } from './staleness/index.js';
+import { getSystemAgentsDir } from './state.js';
+import { isGitRepo } from './git.js';
+const STATUS_MAP = {
+    ok: 'synced',
+    diff: 'drifted',
+    missing: 'missing',
+    extra: 'orphan',
+};
+function rowsFromReport(agent, version, report) {
+    const out = [];
+    for (const list of Object.values(report.kinds)) {
+        for (const r of list) {
+            out.push({
+                agent,
+                version,
+                kind: r.kind,
+                name: r.name,
+                status: STATUS_MAP[r.status],
+                ...(r.detail ? { detail: r.detail } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Read `.system` repo freshness WITHOUT touching the network. `git status`
+ * reports ahead/behind against the remote-tracking ref, which the detached
+ * auto-pull worker keeps warm via periodic `git fetch`. This is the same number
+ * the menu-bar surfaces; we read it once, here, so every surface agrees.
+ */
+export async function getSystemRepoStatus() {
+    const dir = getSystemAgentsDir();
+    const base = { dir, behind: 0, ahead: 0, branch: null, unknown: true };
+    if (!isGitRepo(dir))
+        return base;
+    try {
+        const status = await simpleGit(dir).status();
+        return {
+            dir,
+            behind: status.behind ?? 0,
+            ahead: status.ahead ?? 0,
+            branch: status.tracking ?? status.current ?? null,
+            // Without a tracking branch there's no upstream to compare against.
+            unknown: !status.tracking,
+        };
+    }
+    catch {
+        return base;
+    }
+}
+/**
+ * Compute unified sync status across the fleet. Resolves against non-project
+ * layers only (`excludeProject: true`) — the GLOBAL version home is never
+ * reconciled against per-cwd `<cwd>/.agents/` resources, so counting them as
+ * "missing" there would be a false gap (matches doctor's overview semantics).
+ */
+export async function computeSyncStatus(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const agentIds = options.agents ?? ALL_AGENT_IDS;
+    const agents = [];
+    for (const agent of agentIds) {
+        const def = getGlobalDefault(agent);
+        for (const version of listInstalledVersions(agent)) {
+            const report = diffVersionResources(agent, version, {
+                cwd,
+                excludeProject: true,
+                ...(options.kinds ? { kinds: options.kinds } : {}),
+            });
+            const resources = rowsFromReport(agent, version, report);
+            const counts = { synced: 0, drifted: 0, missing: 0, orphan: 0 };
+            for (const r of resources)
+                counts[r.status]++;
+            agents.push({
+                agent,
+                version,
+                isDefault: version === def,
+                everSynced: loadManifest(agent, version) !== null,
+                counts,
+                needsSync: counts.drifted + counts.missing > 0,
+                resources,
+            });
+        }
+    }
+    const system = await getSystemRepoStatus();
+    const agentsNeedingSync = new Set();
+    let drifted = 0, missing = 0, orphan = 0, versionsNeedingSync = 0, versionsNeverSynced = 0;
+    for (const v of agents) {
+        drifted += v.counts.drifted;
+        missing += v.counts.missing;
+        orphan += v.counts.orphan;
+        if (!v.everSynced)
+            versionsNeverSynced++;
+        if (v.needsSync) {
+            versionsNeedingSync++;
+            agentsNeedingSync.add(v.agent);
+        }
+    }
+    return {
+        system,
+        agents,
+        totals: {
+            drifted,
+            missing,
+            orphan,
+            versionsNeedingSync,
+            versionsNeverSynced,
+            agentsNeedingSync: agentsNeedingSync.size,
+        },
+    };
+}

package/dist/lib/teams/agents.d.ts

@@ -68,6 +68,30 @@ export declare function checkAllClis(): Record<string, {
     path: string | null;
     error: string | null;
 }>;
+/**
+ * Advisory sign-in probe for a teammate's agent. Reads the account-global login
+ * (no `home` → active config) via `getAccountInfo`. Deliberately best-effort:
+ * sign-in detection is UNRELIABLE for opaque-credential agents (Kimi/Antigravity
+ * store an OAuth/JWT with no email claim) and for keychain-probed agents, so a
+ * `false` here is often a false negative. Callers must WARN and continue — never
+ * block a team on this result. Never throws (returns false on any error).
+ */
+export declare function checkCliSignedIn(agentType: AgentType): Promise<boolean>;
+/** Advisory sign-in status for a `teams doctor` row. */
+export interface SignInAdvisory {
+    /** true / false from the probe, or null when the agent isn't installed. */
+    signedIn: boolean | null;
+    /** Whether the agent is currently a running teammate. */
+    running: boolean;
+}
+/**
+ * Resolve the advisory sign-in status shown by `teams doctor`. An agent that is
+ * currently RUNNING in a team is live proof it works, so it overrides a
+ * (frequently false-negative) sign-in probe — doctor must never report a
+ * working agent as logged out. Not installed → `signedIn: null` (nothing to
+ * probe). Never flips the authoritative installed/ready column.
+ */
+export declare function resolveSignInAdvisory(installed: boolean, running: boolean, probeSignedIn: boolean): SignInAdvisory;
 /** Resolve and cache the base directory where teammate process data is stored. */
 export declare function getAgentsDir(): Promise<string>;
 /**

package/dist/lib/teams/agents.js

@@ -19,7 +19,7 @@ import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
 import { getAgentsDir as getSystemAgentsDir, getShimsDir } from '../state.js';
-import { AGENTS } from '../agents.js';
+import { AGENTS, getAccountInfo } from '../agents.js';
 import { sanitizeProcessEnv } from '../secrets/bundles.js';
 let lastMemoryWarnAt = 0;
 // On macOS, os.freemem() returns only the truly-free pool and ignores the
@@ -353,6 +353,35 @@ export function checkAllClis() {
     }
     return results;
 }
+/**
+ * Advisory sign-in probe for a teammate's agent. Reads the account-global login
+ * (no `home` → active config) via `getAccountInfo`. Deliberately best-effort:
+ * sign-in detection is UNRELIABLE for opaque-credential agents (Kimi/Antigravity
+ * store an OAuth/JWT with no email claim) and for keychain-probed agents, so a
+ * `false` here is often a false negative. Callers must WARN and continue — never
+ * block a team on this result. Never throws (returns false on any error).
+ */
+export async function checkCliSignedIn(agentType) {
+    try {
+        const info = await getAccountInfo(agentType);
+        return info.signedIn;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the advisory sign-in status shown by `teams doctor`. An agent that is
+ * currently RUNNING in a team is live proof it works, so it overrides a
+ * (frequently false-negative) sign-in probe — doctor must never report a
+ * working agent as logged out. Not installed → `signedIn: null` (nothing to
+ * probe). Never flips the authoritative installed/ready column.
+ */
+export function resolveSignInAdvisory(installed, running, probeSignedIn) {
+    if (!installed)
+        return { signedIn: null, running: false };
+    return { signedIn: running ? true : probeSignedIn, running };
+}
 let AGENTS_DIR = null;
 /** Resolve and cache the base directory where teammate process data is stored. */
 export async function getAgentsDir() {

package/dist/lib/types.d.ts

@@ -7,7 +7,7 @@
  */
 import type { CloudProviderId } from './cloud/types.js';
 /** Unique identifier for a supported AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi' | 'droid';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /** Per-agent run strategy config. */
@@ -99,6 +99,25 @@ export interface AgentConfig {
      * cloud and falls back to the configured default.
      */
     cloudProvider?: CloudProviderId;
+    /**
+     * Set when the upstream vendor has retired this agent's CLI. Presence marks
+     * the agent deprecated (it is never blocked from use); `warnAgentDeprecated`
+     * surfaces this in yellow whenever a user installs the agent or adds it to a
+     * team. Point `replacement` at the successor agent so the warning can suggest
+     * a migration path.
+     */
+    deprecated?: {
+        /** Vendor that retired it, e.g. "Google". */
+        by: string;
+        /** Human date it stopped working / was retired, e.g. "June 18, 2026". */
+        date: string;
+        /** One-line explanation shown under the warning header. */
+        reason: string;
+        /** Successor agent id to suggest instead (e.g. 'antigravity'). */
+        replacement?: AgentId;
+        /** Announcement URL for the deprecation. */
+        url?: string;
+    };
     capabilities: {
         hooks: Capability;
         mcp: Capability;

package/dist/lib/usage.d.ts

@@ -17,6 +17,7 @@ export interface UsageSnapshot {
     sourceLabel: string;
     capturedAt: Date | null;
     windows: UsageWindow[];
+    plan?: string | null;
 }
 /** Usage data plus any error encountered while fetching. */
 export interface UsageInfo {
@@ -122,6 +123,35 @@ 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[];
+/** Raw quota bucket from the Kimi /usages response (numbers arrive as strings). */
+interface KimiUsageQuota {
+    limit?: string | number | null;
+    used?: string | number | null;
+    remaining?: string | number | null;
+    resetTime?: string | null;
+}
+/** Response shape from the Kimi Code /usages endpoint (subset we render). */
+export interface KimiUsagesResponse {
+    user?: {
+        userId?: string | null;
+        membership?: {
+            level?: string | null;
+        } | null;
+    } | null;
+    usage?: KimiUsageQuota | null;
+    limits?: Array<{
+        window?: {
+            duration?: number | null;
+            timeUnit?: string | null;
+        } | null;
+        detail?: KimiUsageQuota | null;
+    } | null> | null;
+    subType?: string | null;
+}
+/** 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. */
+export declare function formatKimiPlan(data: KimiUsagesResponse): string | null;
 /** Load Claude OAuth credentials from the system keychain/keyring. */
 export declare function loadClaudeOauth(home?: string): Promise<ClaudeOauthCredentials | null>;
 /**

package/dist/lib/usage.js

@@ -33,6 +33,7 @@ const CLAUDE_SCOPES = [
 const CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
 const getClaudeUsageCachePath = () => path.join(getCacheDir(), 'claude-usage.json');
 const CACHED_CLAUDE_USAGE_SOURCE_LABEL = 'last seen live account data';
+const KIMI_USAGES_URL = 'https://api.kimi.com/coding/v1/usages';
 const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
@@ -44,6 +45,8 @@ export async function getUsageInfo(agentId, options) {
             return getClaudeUsageInfo(options);
         case 'codex':
             return getCodexUsageInfo(options);
+        case 'kimi':
+            return getKimiUsageInfo(options);
         default:
             return { snapshot: null, error: null };
     }
@@ -114,8 +117,14 @@ const inFlightRefreshes = new Map();
  */
 export async function getUsageInfoForIdentity(input) {
     const usageKey = getUsageLookupKey(input.info);
-    // Non-Claude or no identity: legacy path, blocking fetch.
-    if (input.agentId !== 'claude' || !usageKey) {
+    // Agents whose usage comes from a live network call (Claude, Kimi) 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=…`),
+    // so one cache file holds every account without collision.
+    const usesNetworkUsage = input.agentId === 'claude' || input.agentId === 'kimi';
+    if (!usesNetworkUsage || !usageKey) {
         return getUsageInfo(input.agentId, {
             home: input.home,
             cliVersion: input.cliVersion,
@@ -356,6 +365,152 @@ async function getClaudeUsageInfo(options) {
         return { snapshot: null, error: 'Usage data unavailable right now.' };
     }
 }
+/**
+ * Resolve Kimi's OAuth credential file. Sign-in is account-global but each
+ * installed version has an isolated home; the file physically lives only in the
+ * home the user logged in under. Check the per-version home first, then the
+ * active location under the real HOME — mirrors resolveAccountCredentialPath in
+ * agents.ts so every version reflects the true account state.
+ */
+function resolveKimiCredentialPath(home) {
+    const rel = ['.kimi-code', 'credentials', 'kimi-code.json'];
+    const perVersion = path.join(home || os.homedir(), ...rel);
+    try {
+        if (fs.existsSync(perVersion))
+            return perVersion;
+    }
+    catch { /* unreadable */ }
+    const active = path.join(process.env.AGENTS_REAL_HOME || os.homedir(), ...rel);
+    if (active !== perVersion) {
+        try {
+            if (fs.existsSync(active))
+                return active;
+        }
+        catch { /* unreadable */ }
+    }
+    return 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.
+ */
+async function getKimiUsageInfo(options) {
+    try {
+        const credPath = resolveKimiCredentialPath(options?.home);
+        if (!credPath)
+            return { snapshot: null, error: null };
+        const cred = JSON.parse(fs.readFileSync(credPath, 'utf-8'));
+        const accessToken = cred?.access_token;
+        if (typeof accessToken !== 'string' || !accessToken) {
+            return { snapshot: null, error: null };
+        }
+        const expiresAt = typeof cred?.expires_at === 'number' ? cred.expires_at : null;
+        if (expiresAt !== null && Date.now() / 1000 >= expiresAt) {
+            return { snapshot: null, error: null };
+        }
+        const response = await fetch(KIMI_USAGES_URL, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: 'application/json',
+            },
+            signal: AbortSignal.timeout(5000),
+        });
+        // 401/403/404 => expired token or no Kimi For Coding subscription; render
+        // nothing rather than a misleading empty bar.
+        if (!response.ok) {
+            return { snapshot: null, error: null };
+        }
+        const data = await response.json();
+        const windows = normalizeKimiWindows(data);
+        if (windows.length === 0) {
+            return { snapshot: null, error: null };
+        }
+        return {
+            snapshot: {
+                source: 'live',
+                sourceLabel: 'live account data',
+                capturedAt: new Date(),
+                windows,
+                plan: formatKimiPlan(data),
+            },
+            error: null,
+        };
+    }
+    catch {
+        return { snapshot: null, error: null };
+    }
+}
+/** Normalize the Kimi /usages payload into the common UsageWindow shape. */
+export function normalizeKimiWindows(data) {
+    const windows = [];
+    // Per-window rate limit (e.g. a 300-minute bucket) -> "session".
+    const shortLimit = Array.isArray(data.limits)
+        ? data.limits.find((entry) => entry?.detail)
+        : null;
+    const session = normalizeKimiWindow(shortLimit?.detail, 'session', 'Current session', 'S', kimiWindowMinutes(shortLimit?.window));
+    if (session)
+        windows.push(session);
+    // Rolling account quota -> "week".
+    const period = normalizeKimiWindow(data.usage, 'week', 'Current period', 'W', null);
+    if (period)
+        windows.push(period);
+    return windows;
+}
+/** Normalize a single Kimi quota bucket (used/limit strings) into a UsageWindow. */
+function normalizeKimiWindow(quota, key, label, shortLabel, windowMinutes) {
+    const limit = kimiNumber(quota?.limit);
+    const used = kimiNumber(quota?.used);
+    if (limit === null || used === null || limit <= 0)
+        return null;
+    const usedPercent = normalizePercent((used / limit) * 100);
+    if (usedPercent === null)
+        return null;
+    return {
+        key,
+        label,
+        shortLabel,
+        usedPercent,
+        resetsAt: parseDateValue(quota?.resetTime),
+        windowMinutes: windowMinutes ?? inferWindowMinutes(key),
+    };
+}
+/** Parse a numeric field that Kimi serializes as a string (e.g. "100"). */
+function kimiNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))) {
+        return Number(value);
+    }
+    return null;
+}
+/** Convert a Kimi limit window (duration + timeUnit enum) to minutes. */
+function kimiWindowMinutes(window) {
+    const duration = typeof window?.duration === 'number' ? window.duration : null;
+    if (duration === null || duration <= 0)
+        return null;
+    switch (window?.timeUnit) {
+        case 'TIME_UNIT_HOUR': return duration * 60;
+        case 'TIME_UNIT_SECOND': return duration / 60;
+        default: return duration; // TIME_UNIT_MINUTE or unknown -> minutes
+    }
+}
+/** Derive a display plan label from Kimi's membership tier or subscription type. */
+export function formatKimiPlan(data) {
+    const level = data.user?.membership?.level;
+    const raw = (typeof level === 'string' && level) || (typeof data.subType === 'string' && data.subType) || '';
+    const tail = raw.split('_').pop() || ''; // LEVEL_INTERMEDIATE -> INTERMEDIATE
+    if (!tail)
+        return null;
+    return tail.charAt(0).toUpperCase() + tail.slice(1).toLowerCase();
+}
 /** Collect Codex JSONL session files sorted newest-first. */
 function collectCodexSessionFiles(home) {
     const base = home || os.homedir();
@@ -590,6 +745,7 @@ function writeClaudeUsageCacheFile(cache, cachePath) {
 function serializeClaudeUsageSnapshot(snapshot) {
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
+        plan: snapshot.plan ?? null,
         windows: snapshot.windows.map((window) => ({
             key: window.key,
             label: window.label,
@@ -626,6 +782,7 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         sourceLabel: CACHED_CLAUDE_USAGE_SOURCE_LABEL,
         capturedAt,
         windows,
+        plan: snapshot.plan ?? null,
     };
 }
 /** Check whether a cached usage window is still relevant (not expired or reset). */

package/dist/lib/versions.d.ts

@@ -1,4 +1,5 @@
 import type { AgentId } from './types.js';
+import { compareVersions } from './agent-spec/primitives.js';
 /**
  * Resource selection for syncing to a version.
  * Each field can be:
@@ -279,10 +280,7 @@ export declare function resolveVersionAliasLoose(agent: AgentId, raw: string | u
  * Get version specified in a project-root agents.yaml (not the user ~/.agents/.system/agents.yaml).
  */
 export declare function getProjectVersion(agent: AgentId, startPath: string): string | null;
-/**
- * Compare semver versions for sorting.
- */
-export declare function compareVersions(a: string, b: string): number;
+export { compareVersions };
 /**
  * Get actual version from an installed 'latest' directory.
  */

package/dist/lib/versions.js

@@ -24,6 +24,10 @@ import { checkbox, select } from '@inquirer/prompts';
 import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset, getHomeDir } from './state.js';
 import { defaultPatterns, expandPatterns } from './resource-patterns.js';
 import { listResources } from './resources.js';
+// VERSION_RE + compareVersions are owned by the agent-spec engine primitives
+// (single source of truth). Re-exported below so existing importers of
+// `compareVersions` from './versions.js' keep working.
+import { VERSION_RE, compareVersions } from './agent-spec/primitives.js';
 import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath } from './agents.js';
 import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { parseMcpServerConfig } from './mcp.js';
@@ -41,11 +45,6 @@ import { getWriter, getDetector } from './staleness/registry.js';
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
 const RULES_DOC_FILENAME = 'README.md';
-// Strict shape for an agent version string. Anything outside this is rejected
-// at parse time so it can't reach an exec/shell boundary or get interpolated
-// into a generated bash alias. Must allow "latest" plus npm-dist-tag /
-// semver-shaped values (digits, dots, dashes, +, _).
-const VERSION_RE = /^(?:latest|(?!.*\.\.)[A-Za-z0-9._+-]{1,64})$/;
 function getResourceBases(cwd) {
     const projectAgentsDir = getProjectAgentsDir(cwd);
     const userBase = getUserAgentsDir();
@@ -1475,21 +1474,9 @@ export function getProjectVersion(agent, startPath) {
     }
     return null;
 }
-/**
- * Compare semver versions for sorting.
- */
-export function compareVersions(a, b) {
-    const aParts = a.split('.').map((n) => parseInt(n, 10) || 0);
-    const bParts = b.split('.').map((n) => parseInt(n, 10) || 0);
-    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
-        const aVal = aParts[i] || 0;
-        const bVal = bParts[i] || 0;
-        if (aVal !== bVal) {
-            return aVal - bVal;
-        }
-    }
-    return 0;
-}
+// compareVersions is defined in ./agent-spec/primitives.ts and re-exported here
+// so existing `import { compareVersions } from './versions.js'` sites keep working.
+export { compareVersions };
 /**
  * Get actual version from an installed 'latest' directory.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.32",
+  "version": "1.20.34",
   "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",
@@ -51,6 +51,7 @@
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "test": "node ./node_modules/vitest/vitest.mjs run",
+    "test:remote": "scripts/sandbox.sh 'bun install && bun run build && bun run test'",
     "test:watch": "node ./node_modules/vitest/vitest.mjs"
   },
   "keywords": [

package/dist/lib/agent-spec.d.ts

@@ -1,36 +0,0 @@
-import type { AgentId } from './types.js';
-export interface AgentTarget {
-    agent: AgentId;
-    /** Resolved exact version, or null when the agent has no installed versions yet. */
-    version: string | null;
-}
-/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
-export declare const AGENT_QUALIFIERS: readonly ["latest", "oldest", "pinned", "default", "all"];
-export type AgentQualifier = (typeof AGENT_QUALIFIERS)[number];
-/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
-export declare const AGENT_SPEC_HELP: string;
-export declare class AgentSpecError extends Error {
-    constructor(message: string);
-}
-export interface ResolveAgentTargetsOptions {
-    /** Project dir for resolving a bare spec's project pin. Defaults to process.cwd(). */
-    cwd?: string;
-    /** Restrict the agents a spec may name (e.g. only mcp-capable). Defaults to all. */
-    availableAgents?: readonly AgentId[];
-}
-/**
- * Resolve an agent spec (single or comma-list) into concrete installed targets.
- * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
- * (`add`/`install` use a separate available-version path). Throws AgentSpecError
- * on bad input — never calls process.exit, so it is safe on the hot path and in
- * library contexts.
- */
-export declare function resolveAgentTargets(spec: string, opts?: ResolveAgentTargetsOptions): AgentTarget[];
-/**
- * Convenience for single-target commands (`use`, `run`): resolve a spec that
- * must name exactly one installed version. Rejects `@all` / multi-target specs.
- */
-export declare function resolveSingleAgentTarget(spec: string, opts?: ResolveAgentTargetsOptions): {
-    agent: AgentId;
-    version: string;
-};