@phnx-labs/agents-cli 1.22.41 → 1.22.43

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

@@ -1,5 +1,6 @@
 import type { AgentId } from '../types.js';
 import { compareVersions } from '../agent-spec/primitives.js';
+export * from './store.js';
 import { type PrunableKind } from '../staleness/prune.js';
 /**
  * Resource selection for syncing to a version.
@@ -107,82 +108,6 @@ export interface AgentSpec {
  *   "codex@latest" -> { agent: "codex", version: "latest" }
  */
 export declare function parseAgentSpec(spec: string): AgentSpec | null;
-/**
- * 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 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;
 /**
  * Get the latest available version from npm for an agent.
  */
@@ -205,16 +130,6 @@ export declare function isOldestInstalled(agent: AgentId): Promise<{
     installed: boolean;
     version: string | null;
 }>;
-/** Drop the installed-versions cache (call after install/remove mutations). */
-export declare function invalidateInstalledVersionsCache(agent?: AgentId): void;
-/**
- * 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[];
 /**
  * List every version directory for an agent, including ones missing the
  * binary (typically home-only leftovers from a prior `removeVersion`).
@@ -227,19 +142,10 @@ export declare function listInstalledVersionDirs(agent: AgentId): Array<{
     version: string;
     hasBinary: boolean;
 }>;
-/**
- * Get the global default version for an agent.
- */
-export declare function getGlobalDefault(agent: AgentId): string | null;
 /**
  * Set the global default version for an agent.
  */
 export declare function setGlobalDefault(agent: AgentId, version: string | undefined): void;
-/**
- * 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;
 /**
  * Set (or clear, with `undefined`) the preferred isolated version.
  *
@@ -248,22 +154,6 @@ export declare function getIsolatedDefault(agent: AgentId): string | null;
  * a pointer inside the sandbox, so it stays inside the sandbox.
  */
 export declare function setIsolatedDefault(agent: AgentId, version: string | undefined): void;
-/**
- * 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;
 /**
  * Install a specific version of an agent.
  */
@@ -340,11 +230,46 @@ export declare function printTrashFooter(moved: Array<{
  * containing only `home/`) remain under the agent dir.
  */
 export declare function removeAllVersions(agent: AgentId): number;
+export interface HealedVersionPointers {
+    /** Global default reassigned off a not-installed version (`to: null` = cleared). */
+    globalDefault?: {
+        from: string;
+        to: string | null;
+    };
+    /** Isolated default (bare `agents run <agent>`) reassigned off a not-installed version. */
+    isolatedDefault?: {
+        from: string;
+        to: string | null;
+    };
+    /** `~/.<agent>` config symlink repointed off a not-installed version. */
+    configSymlink?: {
+        from: string;
+        to: string;
+    };
+}
 /**
- * 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;
+ * Repoint an agent's version pointers — the global/isolated default and the
+ * `~/.<agent>` config symlink — off any version that is no longer installed, so
+ * neither `agents sync`/`agents run` resolution nor the conventional-path home
+ * can land on a dead version (RUSH-2471).
+ *
+ * How a pointer goes dangling: {@link removeVersion} reassigns the defaults and
+ * clears the config symlink only when IT removes the pointed-at version. A
+ * version-home whose launch binary disappears by any other route — grok
+ * self-updated its per-version binary out from under the old dir, a manual
+ * delete, a half-finished install that seeded the home but never landed the
+ * binary — leaves the default and/or the symlink pointing at something
+ * {@link isVersionInstalled} reports as gone.
+ *
+ * Called from the sync resolve path so the invariant self-heals. Mirrors
+ * {@link removeVersion}'s reassignment: the global default prefers the newest
+ * NON-isolated survivor else clears; the isolated default prefers the newest
+ * remaining isolated copy else clears. The symlink is repointed at the now-healed
+ * resolved default, else the newest installed non-isolated version. A symlink
+ * already on an installed version, a real (non-symlink) config dir, and an
+ * isolated-only agent are left untouched.
+ */
+export declare function healDanglingVersionPointers(agent: AgentId, cwd: string): Promise<HealedVersionPointers>;
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *
@@ -371,10 +296,6 @@ export declare function resolveVersionAlias(agent: AgentId, raw: string | undefi
  * remain queryable.
  */
 export declare function resolveVersionAliasLoose(agent: AgentId, raw: string | undefined | null): string | undefined;
-/**
- * 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;
 export { compareVersions };
 /**
  * Get actual version from an installed 'latest' directory.
@@ -603,12 +524,6 @@ export declare function syncResourcesToVersion(agent: AgentId, version: string,
     prune?: boolean;
     allowExecSurfaces?: boolean;
 }): SyncResult;
-/**
- * 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;
 /** Result of resolving agent/version targets from CLI input or interactive selection. */
 export interface VersionSelectionResult {
     selectedAgents: AgentId[];