@phnx-labs/agents-cli 1.22.57 → 1.22.58

package/dist/lib/installations/shims.d.ts

@@ -1,30 +1,13 @@
 import type { AgentId } from '../types.js';
 import { getShimsDir } from '../state.js';
 export { getShimsDir };
-/**
- * Strategy for handling file conflicts during config migration.
- */
 export type ConflictStrategy = 'keep-dest' | 'overwrite' | 'ask-per-file';
-/**
- * Information about conflicts found during config migration.
- */
 export interface ConflictInfo {
     agent: AgentId;
     version: string;
     conflicts: string[];
 }
-/**
- * Generate the shim script content for an agent.
- *
- * The shim resolves the version in order:
- * 1. agents.yaml in project root (walk up from $PWD, skip ~/.agents/agents.yaml)
- * 2. ~/.agents/agents.yaml default
- *
- * If version is specified but not installed, auto-installs it.
- *
- * Config isolation is handled via symlinks:
- * ~/.{agent} -> ~/.agents/versions/{agent}/{version}/home/.{agent}/
- */
+/** Generate the shim script content for an agent. Resolves project/default version, auto-installs if missing, and execs the binary. */
 /**
  * Current shim schema version. Bump whenever `generateShimScript` changes
  * in a way that requires existing on-disk shims to be regenerated (new
@@ -95,9 +78,7 @@ export declare function shimTargetsFor(platform: NodeJS.Platform): {
     bash: boolean;
     cmd: boolean;
 };
-/**
- * Create a shim for an agent.
- */
+/** Create the shim(s) for an agent. */
 export declare function createShim(agent: AgentId): string;
 /** The POSIX pass-through shim for a brand. */
 export declare function generateBrandShim(name: string): string;
@@ -107,9 +88,7 @@ export declare function createBrandShim(name: string): string;
 export declare function isBrandShim(filePath: string): boolean;
 /** Remove a brand's shim companions. Returns true if anything was removed. */
 export declare function removeBrandShim(name: string): boolean;
-/**
- * Remove the shim for an agent.
- */
+/** Remove the shim(s) for an agent. */
 export declare function removeShim(agent: AgentId): boolean;
 /**
  * Current versioned-alias schema. Bump whenever `generateVersionedAliasScript`
@@ -252,10 +231,7 @@ export declare function removeVersionedAlias(agent: AgentId, version: string): b
  * Check if a versioned alias exists (the on-disk artifact for this platform).
  */
 export declare function versionedAliasExists(agent: AgentId, version: string): boolean;
-/**
- * Get the path to the agent's config directory in HOME.
- * e.g., ~/.claude for claude, ~/.codex for codex
- */
+/** Get the agent's config directory path in HOME (e.g. ~/.claude). */
 export declare function getAgentConfigPath(agent: AgentId): string;
 /**
  * Read the user's configured Codex model from their active `~/.codex/config.toml`.
@@ -274,41 +250,11 @@ export declare function getAgentConfigPath(agent: AgentId): string;
  * a missing/unreadable/unset config yields `undefined` (caller keeps prior behaviour).
  */
 export declare function readCodexConfiguredModel(): string | undefined;
-/**
- * Switch the agent's config symlink to point to a specific version.
- * e.g., ~/.claude -> ~/.agents/versions/claude/2.0.65/home/.claude/
- *
- * If a real directory exists at the config path, it will be backed up
- * to ~/.agents/backups/{agent}/{timestamp}/ and replaced with a symlink.
- *
- * @param agent - The agent ID
- * @param version - The version to switch to
- *
- * Returns: { success: boolean, backupPath?: string, error?: string }
- */
-/**
- * Seed a version's config home with the account credential so switching versions
- * doesn't log the CLI out. Droid/antigravity/kimi (registry `authFiles`) store
- * login as files inside the per-version config dir; sign-in is account-global,
- * so we copy the FRESHEST existing copy (by mtime, across all installed version
- * homes) into `toConfigDir` when its copy is missing or older. mtime is
- * preserved so the "freshest" comparison stays stable and switches don't
- * ping-pong. Best-effort: a failed copy just means the user re-logs in.
- */
-/**
- * Best-effort account identity for the credential *directory* of a file-auth
- * agent (droid / kimi / antigravity), or null when the directory holds no
- * decodable account claim. Delegates to readAuthAccountIdentity, which decrypts
- * / decodes each agent's REAL on-disk format (droid AES-256-GCM + WorkOS JWT,
- * kimi access-token JWT, antigravity refresh-token) — the earlier plaintext
- * top-level-key scan matched NO real credential file, so the guard below never
- * engaged. Two dirs for the SAME account compare equal; DIFFERENT accounts
- * compare distinct. Used by carryForwardAuthFiles to refuse overwriting one
- * account's login with a credential that belongs to a DIFFERENT account
- * (RUSH-1764).
- */
+/** Best-effort account identity for a file-auth agent's credential directory; null when no decodable account claim exists. */
 export declare function readAuthFileIdentity(agent: AgentId, configDir: string): string | null;
+/** Carry the freshest existing account credential into `toConfigDir` so version switches don't log out file-auth agents. */
 export declare function carryForwardAuthFiles(agent: AgentId, toConfigDir: string): void;
+/** Switch the agent's config symlink to point at a specific version, backing up any real directory first. */
 export declare function switchConfigSymlink(agent: AgentId, version: string): Promise<{
     success: boolean;
     backupPath?: string;
@@ -350,23 +296,11 @@ export declare function ensureClaudeInsideSymlink(version: string): void;
  * Get the current config symlink target version, if any.
  */
 export declare function getConfigSymlinkVersion(agent: AgentId): string | null;
-/**
- * Check if shim exists for an agent.
- */
-/**
- * The on-disk shim FILENAME for a platform — derived from `shimTargetsFor` (the
- * write-side source of truth) so the exists/remove/version checks can never
- * drift from what `createShim` actually writes: `<cmd>.cmd` on Windows (the only
- * file written there), the bare `<cmd>` script on POSIX. Pure — testable on any
- * host.
- */
+/** The on-disk shim filename for a platform: `<cmd>.cmd` on Windows, bare `<cmd>` on POSIX. */
 export declare function onDiskShimFile(cliCommand: string, platform: NodeJS.Platform): string;
+/** Check whether the on-disk shim exists for an agent. */
 export declare function shimExists(agent: AgentId): boolean;
-/**
- * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
- * False means either the shim is missing, is pre-v2 (no marker), or is an
- * older version that needs regeneration.
- */
+/** True when the on-disk shim's schema version matches the current schema. */
 export declare function isShimCurrent(agent: AgentId): boolean;
 /**
  * True when the agent shim's baked `AGENTS_BIN` is fine to keep: it either already
@@ -390,27 +324,11 @@ export declare function listShimFileNames(): string[];
  * Returns true if removed.
  */
 export declare function pruneOrphanedCommandShim(fileName: string): boolean;
-/**
- * Regenerate the shim if it's missing or outdated. Returns a status describing
- * what happened — callers can surface a one-line notice to the user ("Updated
- * shim for codex") when appropriate.
- */
+/** Regenerate the shim if missing or older than the current schema; never downgrade a newer on-disk shim. */
 export declare function ensureShimCurrent(agent: AgentId): 'created' | 'updated' | 'current';
-/**
- * Get the path to the shim for an agent.
- */
+/** Get the logical (extensionless) shim path for an agent. */
 export declare function getShimPath(agent: AgentId): string;
-/**
- * Return the first executable path that would be launched for this agent when
- * resolving against PATH, excluding the managed shim itself.
- *
- * Legacy ~/.agents/shims/<cli> (from the pre-split single-root layout) is NOT
- * treated as a shadow when a current managed shim exists at getShimPath() —
- * that file is dead weight from the old layout and the repair flow removes it
- * separately. Treating it as "shadowing" caused an infinite repair-prompt
- * loop because addShimsToPath() only edits the rc file, never the legacy
- * shim file itself.
- */
+/** Return the first executable on PATH that would shadow the managed shim, excluding the shim itself and legacy pre-split files. */
 export declare function getPathShadowingExecutable(agent: AgentId, overrides?: {
     pathDirs?: string[];
     shimPath?: string;

package/dist/lib/installations/shims.js

@@ -1,12 +1,5 @@
 /**
- * Shim generation and config symlink management for agent version switching.
- *
- * Shims are small shell scripts placed in ~/.agents/shims/ that resolve the
- * active agent version (project-level or user-default), then exec the real
- * binary. Config isolation is achieved by symlinking ~/.{agent} into the
- * per-version home directory. This module also handles versioned aliases
- * (e.g., claude@2.0.65), PATH setup, conflict detection during migration,
- * and resource diffing between versions.
+ * Shim generation, config symlink management, and versioned aliases for agent version switching.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -19,10 +12,7 @@ export { getShimsDir };
 import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from '../agents.js';
 import { codexHomeShimBash } from '../codex-home.js';
 import { resolveHarnessAdapter } from '../harness/index.js';
-/**
- * Files and directories to always skip during conflict detection and migration.
- * These are never user config that should be migrated.
- */
+/** Files and directories to always skip during conflict detection and migration. */
 const MIGRATION_IGNORE_LIST = new Set([
     'node_modules',
     '.git',
@@ -34,9 +24,6 @@ const MIGRATION_IGNORE_LIST = new Set([
     '.DS_Store',
     'Thumbs.db',
 ]);
-/**
- * Check if a file/directory should be ignored during migration.
- */
 function shouldIgnore(name) {
     if (MIGRATION_IGNORE_LIST.has(name))
         return true;
@@ -44,10 +31,7 @@ function shouldIgnore(name) {
         return true;
     return false;
 }
-/**
- * Detect conflicting files between source and destination directories.
- * Returns list of filenames that exist in both locations (excluding symlinks in dest).
- */
+/** Detect filenames that exist in both `src` and `dest`, excluding symlinks in `dest`. */
 function detectConflicts(src, dest, prefix = '') {
     const conflicts = [];
     if (!fs.existsSync(src) || !fs.existsSync(dest)) {
@@ -94,9 +78,6 @@ function detectConflicts(src, dest, prefix = '') {
     }
     return conflicts;
 }
-/**
- * Prompt user for conflict resolution strategy.
- */
 async function promptConflictStrategy(conflictInfos) {
     const totalConflicts = conflictInfos.reduce((sum, info) => sum + info.conflicts.length, 0);
     if (totalConflicts === 0) {
@@ -140,18 +121,7 @@ async function promptConflictStrategy(conflictInfos) {
     });
     return strategy;
 }
-/**
- * Generate the shim script content for an agent.
- *
- * The shim resolves the version in order:
- * 1. agents.yaml in project root (walk up from $PWD, skip ~/.agents/agents.yaml)
- * 2. ~/.agents/agents.yaml default
- *
- * If version is specified but not installed, auto-installs it.
- *
- * Config isolation is handled via symlinks:
- * ~/.{agent} -> ~/.agents/versions/{agent}/{version}/home/.{agent}/
- */
+/** Generate the shim script content for an agent. Resolves project/default version, auto-installs if missing, and execs the binary. */
 /**
  * Current shim schema version. Bump whenever `generateShimScript` changes
  * in a way that requires existing on-disk shims to be regenerated (new
@@ -745,9 +715,7 @@ export function shimTargetsFor(platform) {
         return { bash: false, cmd: true };
     return { bash: true, cmd: false };
 }
-/**
- * Create a shim for an agent.
- */
+/** Create the shim(s) for an agent. */
 export function createShim(agent) {
     // A bare shim puts agents-cli first on PATH for this agent — the opposite of what
     // an isolated-only install promises.
@@ -859,9 +827,7 @@ function writeWindowsCmdShim(cmdPath, spec, extraMarkerLines = []) {
         `node "${indexJs}" __shim ${spec} %*\r\n`;
     fs.writeFileSync(cmdPath, content);
 }
-/**
- * Remove the shim for an agent.
- */
+/** Remove the shim(s) for an agent. */
 export function removeShim(agent) {
     const shimsDir = getShimsDir();
     const agentConfig = AGENTS[agent];
@@ -1273,10 +1239,7 @@ export function removeVersionedAlias(agent, version) {
 export function versionedAliasExists(agent, version) {
     return fs.existsSync(versionedAliasOnDiskPath(agent, version));
 }
-/**
- * Get the path to the agent's config directory in HOME.
- * e.g., ~/.claude for claude, ~/.codex for codex
- */
+/** Get the agent's config directory path in HOME (e.g. ~/.claude). */
 export function getAgentConfigPath(agent) {
     const agentConfig = AGENTS[agent];
     const home = process.env.AGENTS_REAL_HOME || os.homedir();
@@ -1311,25 +1274,15 @@ export function readCodexConfiguredModel() {
         return undefined;
     }
 }
-/**
- * Get the path to the version's config directory.
- * e.g., ~/.agents/versions/claude/2.0.65/home/.claude/
- */
+/** Get the version-home config directory path. */
 function getVersionConfigPath(agent, version) {
     const agentConfig = AGENTS[agent];
     const versionsDir = getVersionsDir();
-    // Carry the agent's full configDir subpath so nested layouts work.
-    // e.g., antigravity → `.gemini/antigravity-cli`, claude → `.claude`.
+    // Use the agent's full configDir subpath so nested layouts (e.g. antigravity) work.
     const configDirName = path.relative(os.homedir(), agentConfig.configDir);
     return path.join(versionsDir, agent, version, 'home', configDirName);
 }
-/**
- * Detect conflicts that would occur when switching config symlink for an agent/version.
- * This allows collecting conflicts upfront before prompting for a strategy.
- *
- * Returns null if no migration is needed (already symlink or doesn't exist),
- * or ConflictInfo with the list of conflicting files.
- */
+/** Detect conflicts between the current config directory and the target version home. */
 function detectMigrationConflicts(agent, version) {
     const configPath = getAgentConfigPath(agent);
     const versionConfigPath = getVersionConfigPath(agent, version);
@@ -1360,42 +1313,11 @@ function detectMigrationConflicts(agent, version) {
         return null;
     }
 }
-/**
- * Switch the agent's config symlink to point to a specific version.
- * e.g., ~/.claude -> ~/.agents/versions/claude/2.0.65/home/.claude/
- *
- * If a real directory exists at the config path, it will be backed up
- * to ~/.agents/backups/{agent}/{timestamp}/ and replaced with a symlink.
- *
- * @param agent - The agent ID
- * @param version - The version to switch to
- *
- * Returns: { success: boolean, backupPath?: string, error?: string }
- */
-/**
- * Seed a version's config home with the account credential so switching versions
- * doesn't log the CLI out. Droid/antigravity/kimi (registry `authFiles`) store
- * login as files inside the per-version config dir; sign-in is account-global,
- * so we copy the FRESHEST existing copy (by mtime, across all installed version
- * homes) into `toConfigDir` when its copy is missing or older. mtime is
- * preserved so the "freshest" comparison stays stable and switches don't
- * ping-pong. Best-effort: a failed copy just means the user re-logs in.
- */
-/**
- * Best-effort account identity for the credential *directory* of a file-auth
- * agent (droid / kimi / antigravity), or null when the directory holds no
- * decodable account claim. Delegates to readAuthAccountIdentity, which decrypts
- * / decodes each agent's REAL on-disk format (droid AES-256-GCM + WorkOS JWT,
- * kimi access-token JWT, antigravity refresh-token) — the earlier plaintext
- * top-level-key scan matched NO real credential file, so the guard below never
- * engaged. Two dirs for the SAME account compare equal; DIFFERENT accounts
- * compare distinct. Used by carryForwardAuthFiles to refuse overwriting one
- * account's login with a credential that belongs to a DIFFERENT account
- * (RUSH-1764).
- */
+/** Best-effort account identity for a file-auth agent's credential directory; null when no decodable account claim exists. */
 export function readAuthFileIdentity(agent, configDir) {
     return readAuthAccountIdentity(agent, configDir);
 }
+/** Carry the freshest existing account credential into `toConfigDir` so version switches don't log out file-auth agents. */
 export function carryForwardAuthFiles(agent, toConfigDir) {
     const authFiles = AGENTS[agent].authFiles;
     if (!authFiles || authFiles.length === 0)
@@ -1476,6 +1398,7 @@ export function carryForwardAuthFiles(agent, toConfigDir) {
         catch { /* best-effort; a failed carry just means a re-login */ }
     }
 }
+/** Switch the agent's config symlink to point at a specific version, backing up any real directory first. */
 export async function switchConfigSymlink(agent, version) {
     // Moves the user's real ~/.<agent> aside and symlinks it into a version home.
     assertIsolationBoundary(agent, 'repoint your real config directory');
@@ -1907,34 +1830,19 @@ async function copyDirContents(src, dest, strategy = 'keep-dest', context) {
         }
     }
 }
-/**
- * Check if shim exists for an agent.
- */
-/**
- * The on-disk shim FILENAME for a platform — derived from `shimTargetsFor` (the
- * write-side source of truth) so the exists/remove/version checks can never
- * drift from what `createShim` actually writes: `<cmd>.cmd` on Windows (the only
- * file written there), the bare `<cmd>` script on POSIX. Pure — testable on any
- * host.
- */
+/** The on-disk shim filename for a platform: `<cmd>.cmd` on Windows, bare `<cmd>` on POSIX. */
 export function onDiskShimFile(cliCommand, platform) {
     return shimTargetsFor(platform).cmd ? `${cliCommand}.cmd` : cliCommand;
 }
-/**
- * The actual on-disk shim path for the current platform. This is what
- * exists/version checks must stat — `getShimPath` returns the logical
- * (extensionless) launch path, which is not always a real file on Windows.
- */
+/** The actual on-disk shim path for the current platform. */
 function onDiskShimPath(agent) {
     return path.join(getShimsDir(), onDiskShimFile(AGENTS[agent].cliCommand, process.platform));
 }
+/** Check whether the on-disk shim exists for an agent. */
 export function shimExists(agent) {
     return fs.existsSync(onDiskShimPath(agent));
 }
-/**
- * Read the schema version embedded in an existing on-disk shim. Returns
- * `null` if the shim doesn't exist or has no version marker (pre-v2 shim).
- */
+/** Read the schema version from the on-disk shim header, or null if missing/unreadable. */
 function readShimSchemaVersion(agent) {
     if (!shimExists(agent))
         return null;
@@ -1951,11 +1859,7 @@ function readShimSchemaVersion(agent) {
         return null;
     }
 }
-/**
- * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
- * False means either the shim is missing, is pre-v2 (no marker), or is an
- * older version that needs regeneration.
- */
+/** True when the on-disk shim's schema version matches the current schema. */
 export function isShimCurrent(agent) {
     const version = readShimSchemaVersion(agent);
     return version === SHIM_SCHEMA_VERSION;
@@ -2039,22 +1943,13 @@ export function pruneOrphanedCommandShim(fileName) {
         return false;
     }
 }
-/**
- * Regenerate the shim if it's missing or outdated. Returns a status describing
- * what happened — callers can surface a one-line notice to the user ("Updated
- * shim for codex") when appropriate.
- */
+/** Regenerate the shim if missing or older than the current schema; never downgrade a newer on-disk shim. */
 export function ensureShimCurrent(agent) {
     if (!shimExists(agent)) {
         createShim(agent);
         return 'created';
     }
-    // Upgrade-only (newest-wins): regenerate only when the on-disk shim is
-    // unversioned/unreadable (null) or OLDER than this binary. Never downgrade a
-    // shim stamped by a NEWER agents-cli install. Two installs at different
-    // SHIM_SCHEMA_VERSION sharing ~/.agents/.cache/shims/ (e.g. a dev build on
-    // PATH alongside a Hermes-bundled published copy) otherwise ping-pong —
-    // rewriting every shim on each alternating launch and adding boot latency.
+    // Upgrade-only: avoid ping-pong between two installs sharing the shims dir.
     const onDisk = readShimSchemaVersion(agent);
     if (onDisk === null || onDisk < SHIM_SCHEMA_VERSION) {
         createShim(agent);
@@ -2062,25 +1957,13 @@ export function ensureShimCurrent(agent) {
     }
     return 'current';
 }
-/**
- * Get the path to the shim for an agent.
- */
+/** Get the logical (extensionless) shim path for an agent. */
 export function getShimPath(agent) {
     const shimsDir = getShimsDir();
     const agentConfig = AGENTS[agent];
     return path.join(shimsDir, agentConfig.cliCommand);
 }
-/**
- * Return the first executable path that would be launched for this agent when
- * resolving against PATH, excluding the managed shim itself.
- *
- * Legacy ~/.agents/shims/<cli> (from the pre-split single-root layout) is NOT
- * treated as a shadow when a current managed shim exists at getShimPath() —
- * that file is dead weight from the old layout and the repair flow removes it
- * separately. Treating it as "shadowing" caused an infinite repair-prompt
- * loop because addShimsToPath() only edits the rc file, never the legacy
- * shim file itself.
- */
+/** Return the first executable on PATH that would shadow the managed shim, excluding the shim itself and legacy pre-split files. */
 export function getPathShadowingExecutable(agent, overrides) {
     const pathDirs = overrides?.pathDirs ?? (process.env.PATH || '').split(path.delimiter).filter(Boolean);
     const shimPath = path.resolve(overrides?.shimPath ?? getShimPath(agent));

package/dist/lib/installations/store.js

@@ -566,7 +566,7 @@ export function getIsolatedDefault(agent) {
  *
  * It lives at the version-dir root (a sibling of `home/`), so it is carried
  * along when `softDeleteVersionDir` moves the whole directory to trash and is
- * restored intact by `agents trash restore`. Its mere presence is the marker;
+ * restored intact by `agents restore`. Its mere presence is the marker;
  * the contents are an informational timestamp only.
  */
 function getIsolatedMarkerPath(agent, version) {