@phnx-labs/agents-cli 1.22.40 → 1.22.42

package/dist/lib/installations/index.js

@@ -7,8 +7,7 @@
  * it, so the internal split can change without breaking callers (the Cursor
  * per-installation isolation track consumes exactly this).
  */
-export { INSTALLATION_RECORD_FILE, INSTALLATION_SCHEMA, } from './types.js';
-export { createInstallation, ensureInstallation, installationDir, installationRecordPath, listInstallationLabels, listInstallations, mintInstallationId, readInstallation, recordRelease, writeInstallation, } from './store.js';
-export { InstallationAmbiguousError, InstallationNotFoundError, describeInstallation, resolveInstallation, } from './resolve.js';
-export { assertValidRelease, selectUpdateStrategy, supportsPinnedUpdate, } from './strategies.js';
+export { createInstallation, listInstallations, recordRelease, } from './store.js';
+export { describeInstallation, resolveInstallation, } from './resolve.js';
+export { selectUpdateStrategy, supportsPinnedUpdate, } from './strategies.js';
 export { updateInstallation } from './update.js';

package/dist/lib/installations/migrate.js

@@ -23,7 +23,7 @@ import { evaluateActivationReadiness } from '../routine-readiness.js';
 import { migrateDeviceConfigStores } from '../devices/config-migration.js';
 // Two constants only, never the read/write API — migrations still operate on raw
 // YAML so they never take the meta lock or prime the meta cache mid-migration.
-import { DEFAULT_BROWSER_PROFILE_NAME } from '../browser/profiles.js';
+import { LEGACY_DEFAULT_BROWSER_PROFILE_NAME } from '../browser/profiles.js';
 import { META_HEADER as DEVICE_META_HEADER } from '../state.js';
 import { COMPILED_HEADER_PROJECT } from '../rules/compile.js';
 const HOME = process.env.HOME ?? os.homedir();
@@ -1763,7 +1763,7 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
     const browser = central.browser;
     if (!browser || typeof browser !== 'object' || Array.isArray(browser))
         return;
-    const entry = browser[DEFAULT_BROWSER_PROFILE_NAME];
+    const entry = browser[LEGACY_DEFAULT_BROWSER_PROFILE_NAME];
     if (entry === undefined)
         return;
     // Device file first — a crash before central is rewritten leaves a harmless
@@ -1777,15 +1777,15 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
     const deviceBrowser = (deviceDoc.browser && typeof deviceDoc.browser === 'object' && !Array.isArray(deviceDoc.browser))
         ? deviceDoc.browser
         : {};
-    if (deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] === undefined) {
-        deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] = entry;
+    if (deviceBrowser[LEGACY_DEFAULT_BROWSER_PROFILE_NAME] === undefined) {
+        deviceBrowser[LEGACY_DEFAULT_BROWSER_PROFILE_NAME] = entry;
         deviceDoc.browser = deviceBrowser;
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
         atomicWriteFileSync(devicePath, DEVICE_META_HEADER + yaml.stringify(deviceDoc));
     }
     // Then strip it from the synced file, dropping `browser:` entirely when the
     // machine-local entry was its only member.
-    doc.deleteIn(['browser', DEFAULT_BROWSER_PROFILE_NAME]);
+    doc.deleteIn(['browser', LEGACY_DEFAULT_BROWSER_PROFILE_NAME]);
     if (Object.keys(browser).length === 1) {
         const itemsOf = () => (doc.contents?.items) ?? [];
         const idx = itemsOf().findIndex((pair) => pair.key?.value === 'browser');
@@ -1806,7 +1806,7 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
     // the identical case (state.ts, `isEmpty ? META_HEADER : stringifyDoc(doc)`).
     const remaining = Object.keys(doc.toJSON() ?? {}).length;
     atomicWriteFileSync(metaFile, remaining === 0 ? DEVICE_META_HEADER : stringifyDoc(doc));
-    console.error(`Migrated agents.yaml: browser '${DEFAULT_BROWSER_PROFILE_NAME}' profile -> devices/${machine}/agents.yaml`);
+    console.error(`Migrated agents.yaml: browser '${LEGACY_DEFAULT_BROWSER_PROFILE_NAME}' profile -> devices/${machine}/agents.yaml`);
 }
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`

package/dist/lib/{shims.d.ts → installations/shims.d.ts}

@@ -1,5 +1,5 @@
-import type { AgentId } from './types.js';
-import { getShimsDir } from './state.js';
+import type { AgentId } from '../types.js';
+import { getShimsDir } from '../state.js';
 export { getShimsDir };
 /**
  * Strategy for handling file conflicts during config migration.

package/dist/lib/{shims.js → installations/shims.js}

@@ -13,12 +13,12 @@ import * as path from 'path';
 import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
-import { IS_WINDOWS, prependToWindowsUserPath } from './platform/index.js';
-import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgentsDir } from './state.js';
+import { IS_WINDOWS, prependToWindowsUserPath } from '../platform/index.js';
+import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgentsDir } from '../state.js';
 export { getShimsDir };
-import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from './agents.js';
-import { codexHomeShimBash } from './codex-home.js';
-import { codexPolicyArgs } from './codex-policy.js';
+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.
@@ -296,52 +296,8 @@ const GROK_RESOLVE_BINARY_FN = `_resolve_grok_binary() {
   done
   printf '%s\\n' "$best"
 }`;
-function codexShimLaunchArgs() {
-    return [
-        '-c',
-        'check_for_update_on_startup=false',
-        ...codexPolicyArgs('edit'),
-    ].map(shellQuote).join(' ');
-}
-/**
- * The `exec` tail for a generated shim. For most agents this is a plain
- * `exec "$BINARY"<launchArgs> "$@"`.
- *
- * Codex is special: its `workspace-write` sandbox hardcodes any `.agents/` (and
- * `.codex/`) directory read-only, but agents-cli keeps every worktree at
- * `<repo>/.agents/worktrees/<slug>`, so an in-repo build under a static
- * shim would hit `EROFS`. The `agents run codex` path fixes this by adding
- * `<repo>/.agents` to the profile's `workspace_roots` (see codexEditWritableRoots
- * / repoAgentsDirForCwd), but a static shim has no cwd at generation time. So the
- * shim resolves the repo's `.agents` from `$PWD` at RUN time — worktree-aware,
- * mirroring repoAgentsDirForCwd — and passes it via Codex's own `--add-dir`
- * (verified to compose with the `agents-edit` profile). The resolution is inline
- * bash because the shim is the launch hot path and must not spawn Node to compute
- * one directory. `--add-dir` is added only when the resolved `.agents` exists.
- */
-function shimExecTail(agent, launchArgs) {
-    if (agent !== 'codex')
-        return `exec "$BINARY"${launchArgs} "$@"`;
-    return `_repo_agents=""
-case "$PWD" in
-  */.agents/worktrees/*) _repo_agents="\${PWD%%/.agents/worktrees/*}/.agents" ;;
-  *)
-    _d="$PWD"
-    # Stop before $HOME so a dotfiles repo at $HOME is not treated as the project
-    # root (mirrors repoRootForCwd's home exclusion in project-key.ts).
-    while [ -n "$_d" ] && [ "$_d" != "/" ] && [ "$_d" != "$HOME" ]; do
-      if [ -e "$_d/.git" ]; then _repo_agents="$_d/.agents"; break; fi
-      _d=$(dirname "$_d")
-    done
-    ;;
-esac
-if [ -n "$_repo_agents" ] && [ -d "$_repo_agents" ]; then
-  exec "$BINARY"${launchArgs} --add-dir "$_repo_agents" "$@"
-fi
-exec "$BINARY"${launchArgs} "$@"`;
-}
 function getAgentsBinForGeneratedShim() {
-    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'index.js');
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'index.js');
 }
 /**
  * Generate the full bash shim script for the given agent. The returned string
@@ -356,66 +312,8 @@ export function generateShimScript(agent) {
     // subpath so per-version HOME symlinks reach the right place.
     const configDirName = path.relative(os.homedir(), agentConfig.configDir);
     const agentsBin = shellQuote(getAgentsBinForGeneratedShim());
-    const managedEnv = agent === 'claude'
-        ? `
-# Claude stores OAuth credentials in the macOS keychain. Scope them to the
-# selected version's config directory so switching versions also switches the
-# live Claude account.
-export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
-# Managed installs are pinned in a per-version dir; Claude Code's background
-# auto-updater would rewrite the pinned binary in place. Disable it so a pin
-# stays a pin. An explicit user value always wins.
-export DISABLE_AUTOUPDATER="\${DISABLE_AUTOUPDATER:-1}"
-# On Linux sandboxes (no keychain), fall back to a per-version token file.
-# The env var always wins if already set; no-op on macOS.
-if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -f "\$CLAUDE_CONFIG_DIR/.oauth_token" ]; then
-  CLAUDE_CODE_OAUTH_TOKEN=\$(cat "\$CLAUDE_CONFIG_DIR/.oauth_token")
-  export CLAUDE_CODE_OAUTH_TOKEN
-fi
-`
-        : agent === 'codex'
-            ? codexHomeShimBash(`$VERSION_DIR/home/${configDirName}`, `$AGENTS_USER_DIR/.codex-homes/$VERSION`)
-            : agent === 'copilot'
-                ? `
-# GitHub Copilot CLI honors COPILOT_HOME to relocate its config and state
-# (settings.json, mcp-config.json, session-state/, logs/, plugins/). Point
-# it at the versioned home so MCP servers, custom agents, and session
-# history are isolated per copilot version.
-export COPILOT_HOME="$VERSION_DIR/home/${configDirName}"
-`
-                : agent === 'grok'
-                    ? `
-# Grok Build uses GROK_HOME to isolate its entire configuration tree
-# (skills, hooks, plugins, agents, memory, sessions, config.toml, MCP, etc.).
-# This gives agents-cli full versioned isolation + resource sync for grok.
-export GROK_HOME="$VERSION_DIR/home/.grok"
-`
-                    : agent === 'opencode'
-                        ? `
-# OpenCode reads plugins, agents, commands, and other config-directory
-# resources from OPENCODE_CONFIG_DIR. Point it at the versioned global config
-# tree where agents-cli syncs OpenCode resources.
-export OPENCODE_CONFIG_DIR="$VERSION_DIR/home/.config/opencode"
-`
-                        : agent === 'kimi'
-                            ? `
-# Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
-# mcp.json, sessions, skills, hooks). Point it at the versioned home.
-export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
-`
-                            : agent === 'muse'
-                                ? `
-# Muse Code has no MUSE_CONFIG_DIR. It resolves config via XDG:
-#   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
-#   $XDG_DATA_HOME/muse    (sessions, plugins)
-# Pin XDG into the version home so managed runs never walk the adopt-time
-# ~/.config/muse -> version-home symlink — Muse refuses agent-definition
-# sources that are SymlinkOrReparse (exit 1). Same idea as CLAUDE_CONFIG_DIR.
-export XDG_CONFIG_HOME="$VERSION_DIR/home/.config"
-export XDG_DATA_HOME="$VERSION_DIR/home/.local/share"
-`
-                                : '';
-    const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
+    const managedEnv = resolveHarnessAdapter(agent).shimConfigEnvBash?.({ configDirName }) ?? '';
+    const launchArgs = resolveHarnessAdapter(agent).shimLaunchArgs?.() ?? '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # Shim for ${agentConfig.name}
@@ -831,7 +729,7 @@ if [ "\$LAUNCH_SKIP" = "0" ]; then
   "\$AGENTS_BIN" sync --agent "\$AGENT" --agent-version "\$VERSION" --launch --cwd "\$PWD" --quiet 2>/dev/null || true
 fi
 
-${shimExecTail(agent, launchArgs)}
+${resolveHarnessAdapter(agent).shimExecTail?.(launchArgs) ?? `exec "$BINARY"${launchArgs} "$@"`}
 `;
 }
 /**
@@ -1145,7 +1043,7 @@ export XDG_DATA_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.
 export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
 `
                                     : '';
-    const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
+    const launchArgs = resolveHarnessAdapter(agent).shimLaunchArgs?.() ?? '';
     // Resolve the binary the same way the main shim does (see generateShimScript).
     // Grok and Droid do NOT ship into node_modules/.bin — Grok downloads a native
     // binary to ~/.grok/downloads and Droid (Factory AI) installs a standalone
@@ -1231,7 +1129,7 @@ if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
 fi
 ${managedEnv}
 
-${shimExecTail(agent, launchArgs)}
+${resolveHarnessAdapter(agent).shimExecTail?.(launchArgs) ?? `exec "$BINARY"${launchArgs} "$@"`}
 `;
 }
 /**
@@ -1639,7 +1537,7 @@ export async function switchConfigSymlink(agent, version) {
             // Dynamic import so loading shims.ts doesn't transitively open the
             // sessions DB — many tests partially mock state.js and would break.
             try {
-                const { updateSessionFilePaths } = await import('./session/db.js');
+                const { updateSessionFilePaths } = await import('../session/db.js');
                 updateSessionFilePaths(configPath, finalBackupPath);
             }
             catch (err) {

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

@@ -10,10 +10,12 @@ import { type Installation } from './types.js';
  * follow. It is also why the file name is registered in versions.ts's
  * `PRESERVED_ON_CLEAN_REINSTALL` — a repair reinstall must not mint a new id.
  *
- * Deliberately depends on nothing but `state`/`fs-atomic`/`primitives` so
- * versions.ts can import it without an import cycle.
+ * Path/enumeration plus frozen installation records. Depends on Node builtins,
+ * installations-local modules, and base lib (`state`/`fs-atomic`/`primitives`/
+ * `agents`/`shims`/`platform`) — never `plugins/`, `rules/`, `session/`, or
+ * `devices/`, so those modules can import this file without an import cycle.
  */
-/** Directory holding one installation. Mirrors versions.ts `getVersionDir`. */
+/** Directory holding one installation. Same path as {@link getVersionDir}. */
 export declare function installationDir(agent: AgentId, label: string): string;
 export declare function installationRecordPath(agent: AgentId, label: string): string;
 /** Mint an opaque installation id. Random, never derived from the release. */
@@ -54,3 +56,139 @@ export declare function listInstallationLabels(agent: AgentId): string[];
  * that disappears mid-scan is skipped rather than failing the whole listing.
  */
 export declare function listInstallations(agent: AgentId): Installation[];
+/**
+ * Get the directory where a specific version is installed.
+ */
+export declare function getVersionDir(agent: AgentId, version: string): string;
+/**
+ * Pick the real grok binary among `grok-*` entries in `downloadsDir` when NO
+ * filename carries the pinned version string. Grok self-updates its binary in
+ * place while running under the shim, so a version-home's downloads dir can
+ * accumulate several `grok-*` files whose names have drifted away from that
+ * version-home's pinned version (RUSH-2459: on yosemite-s0, version-home
+ * `0.2.82` held `grok-1.0.0-linux-aarch64` after grok self-updated, plus a
+ * stale, unrelated 99-byte `grok-0.2.118-linux-aarch64` wrapper script that
+ * happened to sort alphabetically first).
+ *
+ * Never blindly take whatever `fs.readdirSync` returns first — that is exactly
+ * the bug this replaces. Instead: exclude anything under
+ * {@link MIN_GROK_BINARY_BYTES} (rejects wrapper/alias artifacts on size
+ * alone, no content sniffing needed) and, among the survivors, prefer the most
+ * recently modified — the file grok's self-updater actually wrote last.
+ * Returns null (fail loud, never guess) when nothing survives the size filter.
+ */
+export declare function resolveGrokFallbackBinary(downloadsDir: string): string | null;
+/**
+ * Get the binary path for a specific agent version.
+ */
+export declare function getBinaryPath(agent: AgentId, version: string): string;
+/**
+ * Does this agent resolve to ONE global binary that is the same file regardless
+ * of the `version` argument? (droid → always `~/.local/bin/droid`.) Computed
+ * generically by probing `getBinaryPath` with two distinct versions rather than
+ * hardcoding an agent id, so it stays correct if another global-binary agent is
+ * added.
+ *
+ * This is the narrower cousin of `isSelfUpdatingAgent`: every global-binary
+ * agent is self-updating, but grok is self-updating WITHOUT a global binary — it
+ * stores a real per-version binary copy under each version-home
+ * (`versions/grok/<v>/home/.grok/downloads/grok-<v>`), so its version-homes are
+ * genuinely distinct and must NOT be collapsed. Gate the single-binary
+ * collapse/live-version logic on THIS predicate; gate pin-refusal / "switch
+ * profile" copy on `isSelfUpdatingAgent`.
+ */
+export declare function isGlobalBinaryAgent(agent: AgentId): boolean;
+/** Drop the live-version cache (call after an install/remove that changes the
+ * running binary, e.g. `agents add droid@latest`). */
+export declare function invalidateLiveVersionCache(agent?: AgentId): void;
+/**
+ * Resolve the version the ONE globally-installed binary actually reports via
+ * `<cli> --version`, cached for {@link LIVE_VERSION_TTL_MS}. For a self-updating
+ * global-binary agent (droid) this is the single source of truth for "which
+ * version is installed" — the on-disk version-dir NAMES are just stale labels
+ * left behind by successive `agents add`/self-update cycles. Returns null when
+ * the binary isn't on PATH or the probe fails.
+ */
+export declare function getCliVersionFromPath(agent: AgentId): Promise<string | null>;
+export declare function getLiveVersion(agent: AgentId): Promise<string | null>;
+/**
+ * Synchronous, non-blocking read of the live-version cache — returns the value
+ * only if a recent {@link getLiveVersion} call already warmed it, else null.
+ * `listInstalledVersions` is sync and must not shell out, so it prefers this
+ * warm value (accurate) and otherwise falls back to the newest on-disk dir.
+ */
+export declare function getCachedLiveVersion(agent: AgentId): string | null;
+/**
+ * Get the isolated HOME directory for a specific agent version.
+ * Each version has its own config isolation (like jobs sandbox).
+ */
+export declare function getVersionHomePath(agent: AgentId, version: string): string;
+/**
+ * Check if a specific version is installed.
+ *
+ * Probes the actual launch binary (the same executable the shims run), not just
+ * the version dir or the node_modules/.bin/<cli> wrapper. For npm agents that
+ * means statting the package's real `bin` target (getPackageBinaryPath), so a
+ * present-but-gutted install (vendor auto-updater destroyed the binary) reports
+ * as NOT installed and `agents add` re-runs its install step to repair it.
+ */
+export declare function isVersionInstalled(agent: AgentId, version: string): boolean;
+/** Drop the installed-versions cache (call after install/remove mutations). */
+export declare function invalidateInstalledVersionsCache(agent?: AgentId): void;
+/**
+ * Choose the single canonical version-dir to represent a self-updating
+ * global-binary agent (droid). All its version dirs map to ONE binary, so
+ * exactly one is real; the rest are stale labels. Prefer, in order: the dir the
+ * live config symlink points at (what actually runs), the recorded global
+ * default, the live `--version` (when the cache is warm), else the newest dir.
+ * `versions` MUST be sorted ascending. Callers guarantee it is non-empty.
+ */
+export declare function pickCanonicalGlobalBinaryVersion(agent: AgentId, versions: string[]): string;
+/**
+ * List all installed versions for an agent (cached by versions-dir mtime).
+ *
+ * For a self-updating global-binary agent (droid) every version dir resolves to
+ * the SAME binary, so this collapses them to a single canonical entry — one
+ * install, one row in `agents view`, never the phantom set of semver dir names.
+ */
+export declare function listInstalledVersions(agent: AgentId): string[];
+/**
+ * Get the global default version for an agent.
+ */
+export declare function getGlobalDefault(agent: AgentId): string | null;
+/**
+ * Get the preferred ISOLATED version for an agent — the copy a bare
+ * `agents run <agent>` falls back to when there is no global default.
+ */
+export declare function getIsolatedDefault(agent: AgentId): string | null;
+/**
+ * Mark an installed version as an isolated install (`agents add --isolated`).
+ *
+ * Isolated versions are fully self-contained: they never become the global
+ * default and never own the user's real `~/.<agent>` config directory. This
+ * flag is what keeps every "adopting" code path away from them.
+ */
+export declare function markVersionIsolated(agent: AgentId, version: string): void;
+/**
+ * Whether a version was installed as an isolated install (`agents add --isolated`).
+ *
+ * Used to exclude such versions from global-default promotion and from any
+ * flow that would touch the user's real `~/.<agent>` directory, and to gate the
+ * `--isolated` safety check on `agents remove`.
+ */
+export declare function isVersionIsolated(agent: AgentId, version: string): boolean;
+/**
+ * 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;
+/**
+ * Get the resolved version for an agent in the current context.
+ * Checks project manifest first, then global default.
+ */
+export declare function resolveVersion(agent: AgentId, projectPath?: string): string | null;
+/**
+ * Get the effective HOME directory for an agent.
+ * If version-managed with a resolved version, returns the version's home directory.
+ * Otherwise returns the real HOME.
+ */
+export declare function getEffectiveHome(agentId: AgentId): string;