@phnx-labs/agents-cli 1.22.31 → 1.22.32

package/dist/lib/installations/store.js

@@ -0,0 +1,196 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { atomicWriteFileSync } from '../fs-atomic.js';
+import { getVersionsDir } from '../state.js';
+import { VERSION_RE } from '../agent-spec/primitives.js';
+import { INSTALLATION_RECORD_FILE, INSTALLATION_SCHEMA } from './types.js';
+/**
+ * Persistence for {@link Installation} records.
+ *
+ * The record lives at `<versionDir>/installation.json` rather than in one
+ * central index: the version dir is what `agents trash`/`agents prune` move,
+ * copy and restore wholesale, so keeping identity inside it means identity
+ * travels with the install instead of dangling in a registry that forgets to
+ * 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.
+ */
+/** Directory holding one installation. Mirrors versions.ts `getVersionDir`. */
+export function installationDir(agent, label) {
+    return path.join(getVersionsDir(), agent, label);
+}
+export function installationRecordPath(agent, label) {
+    return path.join(installationDir(agent, label), INSTALLATION_RECORD_FILE);
+}
+/** Mint an opaque installation id. Random, never derived from the release. */
+export function mintInstallationId() {
+    return `ins_${crypto.randomBytes(12).toString('hex')}`;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function assertValidRecord(value, file) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Installation record corrupted at ${file}: expected a JSON object.`);
+    }
+    const record = value;
+    if (typeof record.schema !== 'number') {
+        throw new Error(`Installation record corrupted at ${file}: missing numeric "schema".`);
+    }
+    if (record.schema > INSTALLATION_SCHEMA) {
+        throw new Error(`Installation record at ${file} was written by a newer agents-cli (schema ${record.schema} > ${INSTALLATION_SCHEMA}). Upgrade agents-cli.`);
+    }
+    for (const key of ['id', 'agent', 'label', 'releaseVersion', 'createdAt', 'updatedAt']) {
+        if (typeof record[key] !== 'string' || !record[key]) {
+            throw new Error(`Installation record corrupted at ${file}: missing string "${key}".`);
+        }
+    }
+    if (!Array.isArray(record.history) || record.history.length === 0) {
+        throw new Error(`Installation record corrupted at ${file}: "history" must be a non-empty array.`);
+    }
+    return record;
+}
+/**
+ * Read the record for one installation, or null when the version dir has none.
+ * Never mints — use {@link ensureInstallation} for the migrating read.
+ */
+export function readInstallation(agent, label) {
+    const file = installationRecordPath(agent, label);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Installation record corrupted at ${file}: not valid JSON.`);
+    }
+    return assertValidRecord(parsed, file);
+}
+export function writeInstallation(installation) {
+    const file = installationRecordPath(installation.agent, installation.label);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteFileSync(file, `${JSON.stringify(installation, null, 2)}\n`);
+}
+/**
+ * Read the record for an existing version dir, minting and persisting one on
+ * first sight. This is the migration path for every installation created before
+ * frozen identity existed: their directory name IS their release, so the
+ * migrated record seeds `label === releaseVersion` and dates the install from
+ * the directory's own mtime rather than pretending it was created now.
+ *
+ * Throws when the version dir does not exist — an installation record must never
+ * describe an install that isn't there.
+ */
+export function ensureInstallation(agent, label) {
+    const existing = readInstallation(agent, label);
+    if (existing)
+        return existing;
+    const dir = installationDir(agent, label);
+    if (!fs.existsSync(dir)) {
+        throw new Error(`No installation directory for ${agent}@${label} at ${dir}.`);
+    }
+    let createdAt;
+    try {
+        createdAt = fs.statSync(dir).mtime.toISOString();
+    }
+    catch {
+        createdAt = nowIso();
+    }
+    const migrated = {
+        schema: INSTALLATION_SCHEMA,
+        id: mintInstallationId(),
+        agent,
+        label,
+        releaseVersion: label,
+        createdAt,
+        updatedAt: createdAt,
+        history: [{ releaseVersion: label, at: createdAt }],
+    };
+    writeInstallation(migrated);
+    return migrated;
+}
+/**
+ * Create the record for a freshly-installed version dir. Idempotent: a repeat
+ * `agents add` of the same label keeps the original id (identity is frozen) and
+ * only records the release if it actually moved.
+ */
+export function createInstallation(agent, label, releaseVersion) {
+    if (!VERSION_RE.test(label)) {
+        throw new Error(`Invalid installation label: ${JSON.stringify(label)}`);
+    }
+    const existing = readInstallation(agent, label);
+    if (existing) {
+        return existing.releaseVersion === releaseVersion
+            ? existing
+            : recordRelease(existing, releaseVersion);
+    }
+    const at = nowIso();
+    const created = {
+        schema: INSTALLATION_SCHEMA,
+        id: mintInstallationId(),
+        agent,
+        label,
+        releaseVersion,
+        createdAt: at,
+        updatedAt: at,
+        history: [{ releaseVersion, at }],
+    };
+    writeInstallation(created);
+    return created;
+}
+/**
+ * Move an installation's recorded release forward, preserving identity. Returns
+ * the persisted record. Call only AFTER the new release is live on disk — the
+ * record is the claim that it is.
+ */
+export function recordRelease(installation, releaseVersion) {
+    const at = nowIso();
+    const next = {
+        ...installation,
+        releaseVersion,
+        updatedAt: at,
+        history: [...installation.history, { releaseVersion, at }],
+    };
+    writeInstallation(next);
+    return next;
+}
+/** Version-dir basenames present for an agent, oldest-first by directory name. */
+export function listInstallationLabels(agent) {
+    const agentDir = path.join(getVersionsDir(), agent);
+    let entries;
+    try {
+        entries = fs.readdirSync(agentDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isDirectory() && VERSION_RE.test(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+}
+/**
+ * Every installation of an agent, migrating records as needed. A version dir
+ * that disappears mid-scan is skipped rather than failing the whole listing.
+ */
+export function listInstallations(agent) {
+    const out = [];
+    for (const label of listInstallationLabels(agent)) {
+        try {
+            out.push(ensureInstallation(agent, label));
+        }
+        catch {
+            /* dir vanished or unreadable — not an installation we can act on */
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,73 @@
+import type { AgentId } from '../types.js';
+import type { Installation, UpdateStrategyId } from './types.js';
+export interface UpdateContext {
+    agent: AgentId;
+    installation: Installation;
+    /** What the user asked for: `latest`, `oldest`, or a concrete release. */
+    requested: string;
+    onProgress?: (message: string) => void;
+}
+/** A release fetched but not yet live. */
+export interface StagedRelease {
+    release: string;
+    /** Extensionless launch target to probe. Windows appends `.cmd` (see verifyBinaryLaunches). */
+    binary: string;
+    /** HOME the probe runs under — always the installation's own home. */
+    home: string;
+    /** Scratch dir to delete once the run finishes, or null when nothing was staged. */
+    stagingDir: string | null;
+}
+/** Undo/finish handles returned by a commit, so update.ts owns the transaction. */
+export interface CommitHandles {
+    /** Put the previous release back. Must be safe to call once, immediately after commit. */
+    undo: () => void;
+    /** Discard the undo material. Called only once the update is durable. */
+    finalize: () => void;
+}
+/**
+ * How one class of harness replaces the release inside a frozen installation.
+ *
+ * Chosen from the registry's declared capabilities — never from an agent id — so
+ * a harness added to `AGENTS` is covered the day it lands. See
+ * {@link selectUpdateStrategy}.
+ */
+export interface UpdateStrategy {
+    readonly id: UpdateStrategyId;
+    /**
+     * True only when `undo` can restore the PREVIOUS RELEASE in full — i.e. the
+     * vendor artifact lives inside this installation's own directory and was
+     * fetched without mutating anything global.
+     *
+     * It is not a switch for whether the orchestrator rolls back: `undo` always
+     * runs on a post-commit failure, because every strategy that displaces
+     * something must put it back. What this flag changes is what the user is
+     * told, since for an installer-driven harness the global binary the vendor
+     * replaced is not ours to restore.
+     */
+    readonly transactional: boolean;
+    /** True when several installations of this agent share one binary on disk. */
+    readonly sharedBinary: boolean;
+    /** Turn `requested` into the concrete release this run will install. */
+    resolveTarget(ctx: UpdateContext): Promise<string>;
+    /** Fetch the target release into a place that is not yet live. */
+    stage(ctx: UpdateContext, target: string): Promise<StagedRelease>;
+    /** Make the staged release the live one. */
+    commit(ctx: UpdateContext, staged: StagedRelease): Promise<CommitHandles>;
+}
+/**
+ * Pick the update strategy for an agent from the registry's declared shape.
+ *
+ * The ordering mirrors `installVersion`: an npm package wins whenever one is
+ * declared (kimi declares both a package and a script, and its package is what
+ * `agents add` installs), then a single shared global binary, then a per-install
+ * script. Anything else is an integration boundary we do not handle — it throws
+ * rather than silently no-opping and reporting success.
+ */
+export declare function selectUpdateStrategy(agent: AgentId): UpdateStrategy;
+/**
+ * Whether a concrete release can be requested for this agent at all. False for
+ * every self-updating harness — their installers carry no version token.
+ */
+export declare function supportsPinnedUpdate(agent: AgentId): boolean;
+/** Guard a user-supplied release token before it reaches a path or a package spec. */
+export declare function assertValidRelease(requested: string): void;

package/dist/lib/installations/strategies.js

@@ -0,0 +1,293 @@
+import * as crypto from 'crypto';
+import { promisify } from 'util';
+import { exec, execFile } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, findInPath, isSelfUpdatingAgent } from '../agents.js';
+import { VERSION_RE } from '../agent-spec/primitives.js';
+import { importInstallScriptBinary } from '../import.js';
+import { getBinaryPath, getLatestNpmVersion, getOldestNpmVersion, getLiveVersion, getVersionHomePath, invalidateLiveVersionCache, isGlobalBinaryAgent, } from '../versions.js';
+import { installationDir } from './store.js';
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+/** npm install timeout, matching the install path's own installer budget. */
+const INSTALL_TIMEOUT_MS = 120_000;
+function runId() {
+    return `${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+}
+function moveDir(from, to) {
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    try {
+        fs.renameSync(from, to);
+    }
+    catch (err) {
+        // Windows refuses a rename while any file in the tree is open, and a
+        // cross-device staging dir cannot be renamed at all. Copy+remove is the same
+        // observable move; it is slower, so it is the fallback, not the default.
+        const code = err.code;
+        if (code !== 'EPERM' && code !== 'EACCES' && code !== 'EXDEV')
+            throw err;
+        fs.cpSync(from, to, { recursive: true });
+        fs.rmSync(from, { recursive: true, force: true });
+    }
+}
+/**
+ * Entries a swap replaces: everything npm owns inside a version dir. The lockfile
+ * is included deliberately — leaving the previous release's `package-lock.json`
+ * beside the new `node_modules` would make the directory describe a release it no
+ * longer contains, and the next repair reinstall would resolve from that stale lock.
+ * Entries absent on either side are skipped, so a dir without a lockfile is fine.
+ */
+const NPM_LIVE_ENTRIES = ['node_modules', 'package.json', 'package-lock.json'];
+/**
+ * npm-packaged harnesses (claude, codex, kimi, opencode, …). The only fully
+ * transactional class: a pinned release can be fetched into a sibling directory,
+ * probed there, and swapped in, with the displaced tree kept until the swap is
+ * proven — so a failed update leaves the previous release running.
+ */
+const npmPackageStrategy = {
+    id: 'npm-package',
+    transactional: true,
+    sharedBinary: false,
+    async resolveTarget(ctx) {
+        if (ctx.requested === 'latest' || ctx.requested === 'oldest') {
+            const resolved = ctx.requested === 'latest'
+                ? await getLatestNpmVersion(ctx.agent)
+                : await getOldestNpmVersion(ctx.agent);
+            if (!resolved) {
+                throw new Error(`Could not resolve the ${ctx.requested} published version for ${AGENTS[ctx.agent].name} from npm.`);
+            }
+            return resolved;
+        }
+        return ctx.requested;
+    },
+    async stage(ctx, target) {
+        const pkg = AGENTS[ctx.agent].npmPackage;
+        const dir = installationDir(ctx.agent, ctx.installation.label);
+        const stagingDir = path.join(dir, `.staging-${runId()}`);
+        fs.mkdirSync(stagingDir, { recursive: true });
+        fs.writeFileSync(path.join(stagingDir, 'package.json'), JSON.stringify({ name: `agents-${ctx.agent}-${target}`, version: '1.0.0', private: true }, null, 2));
+        const winShell = process.platform === 'win32';
+        ctx.onProgress?.(`Staging ${pkg}@${target}...`);
+        // `--ignore-scripts` for the dependency tree; the first-party package's own
+        // postinstall is re-run below, exactly as the install path does — several
+        // harnesses ship their native binary via that script and are unlaunchable
+        // without it.
+        await execFileAsync('npm', ['install', `${pkg}@${target}`, '--ignore-scripts'], {
+            cwd: stagingDir,
+            shell: winShell,
+            timeout: INSTALL_TIMEOUT_MS,
+        });
+        const pkgRoot = path.join(stagingDir, 'node_modules', pkg);
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
+            const postinstall = manifest?.scripts?.postinstall;
+            if (typeof postinstall === 'string' && postinstall.trim()) {
+                ctx.onProgress?.(`Running ${AGENTS[ctx.agent].name} postinstall...`);
+                await execFileAsync(postinstall, [], { cwd: pkgRoot, shell: true, timeout: INSTALL_TIMEOUT_MS });
+            }
+        }
+        catch {
+            /* non-fatal: the launch probe in update.ts is the real gate */
+        }
+        return {
+            release: target,
+            binary: path.join(stagingDir, 'node_modules', '.bin', AGENTS[ctx.agent].cliCommand),
+            home: getVersionHomePath(ctx.agent, ctx.installation.label),
+            stagingDir,
+        };
+    },
+    async commit(ctx, staged) {
+        const dir = installationDir(ctx.agent, ctx.installation.label);
+        const rollbackDir = path.join(dir, `.rollback-${runId()}`);
+        const displaced = [];
+        // Move the live tree aside first, then move the staged tree in. Doing it in
+        // this order means the failure window contains no half-merged tree: either
+        // the old entries are all aside (undo restores them) or the new ones are all
+        // in place.
+        for (const entry of NPM_LIVE_ENTRIES) {
+            const live = path.join(dir, entry);
+            if (!fs.existsSync(live))
+                continue;
+            moveDir(live, path.join(rollbackDir, entry));
+            displaced.push(entry);
+        }
+        for (const entry of NPM_LIVE_ENTRIES) {
+            const from = path.join(staged.stagingDir, entry);
+            if (fs.existsSync(from))
+                moveDir(from, path.join(dir, entry));
+        }
+        return {
+            undo: () => {
+                for (const entry of NPM_LIVE_ENTRIES) {
+                    fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
+                }
+                for (const entry of displaced) {
+                    moveDir(path.join(rollbackDir, entry), path.join(dir, entry));
+                }
+                fs.rmSync(rollbackDir, { recursive: true, force: true });
+            },
+            finalize: () => fs.rmSync(rollbackDir, { recursive: true, force: true }),
+        };
+    },
+};
+/**
+ * Harnesses that are ONE global self-updating binary (droid, muse, warp): every
+ * installation of the agent points at the same file, so there is nothing
+ * per-installation to stage or swap, and updating one necessarily updates all.
+ * The honest model is therefore: run the official installer, probe the live
+ * binary, and record the new release on every installation that shares it.
+ */
+const globalBinaryStrategy = {
+    id: 'global-binary',
+    transactional: false,
+    sharedBinary: true,
+    async resolveTarget(ctx) {
+        // The installer for these carries no version token, so a requested release
+        // cannot be honoured. Fail loud rather than install something else and
+        // report it as the pin the user asked for.
+        if (ctx.requested !== 'latest') {
+            throw new Error(`${AGENTS[ctx.agent].name} is a single self-updating binary with no pinnable releases — `
+                + `it can only be updated to the current one. Re-run: agents update ${ctx.agent}@${ctx.installation.label} --to latest`);
+        }
+        // Resolved after the installer runs — `latest` here is whatever it fetches.
+        return 'latest';
+    },
+    async stage(ctx) {
+        const script = AGENTS[ctx.agent].installScript;
+        ctx.onProgress?.(`Updating ${AGENTS[ctx.agent].name} via official installer...`);
+        await execAsync(script, { timeout: INSTALL_TIMEOUT_MS });
+        invalidateLiveVersionCache(ctx.agent);
+        const live = await getLiveVersion(ctx.agent);
+        if (!live) {
+            throw new Error(`${AGENTS[ctx.agent].name} installer finished but its version could not be determined.`);
+        }
+        return {
+            release: live,
+            binary: getBinaryPath(ctx.agent, ctx.installation.label),
+            home: getVersionHomePath(ctx.agent, ctx.installation.label),
+            stagingDir: null,
+        };
+    },
+    async commit() {
+        // The installer already replaced the shared binary; there is no per-install
+        // swap to perform and no previous copy to restore.
+        return { undo: () => { }, finalize: () => { } };
+    },
+};
+/**
+ * Harnesses installed by an official script that keeps a per-installation copy
+ * or symlink farm (grok, cursor, antigravity, hermes, kiro, goose, …). The
+ * vendor artifact lands in a global location the installer owns, so the fetch
+ * itself is not reversible; what IS per-installation — the version dir's binary
+ * link farm — is staged and swapped so a failed re-import cannot strand the
+ * installation without a launch target.
+ */
+const installScriptStrategy = {
+    id: 'install-script',
+    transactional: false,
+    sharedBinary: false,
+    async resolveTarget(ctx) {
+        const script = AGENTS[ctx.agent].installScript;
+        if (!script.includes('VERSION') && ctx.requested !== 'latest') {
+            throw new Error(`${AGENTS[ctx.agent].name}'s installer takes no version, so it can only be updated to the current release. `
+                + `Re-run: agents update ${ctx.agent}@${ctx.installation.label} --to latest`);
+        }
+        return ctx.requested;
+    },
+    async stage(ctx, target) {
+        const config = AGENTS[ctx.agent];
+        const script = config.installScript.replaceAll('VERSION', target === 'latest' ? 'latest' : target);
+        ctx.onProgress?.(`Updating ${config.name} via official installer...`);
+        await execAsync(script, { timeout: INSTALL_TIMEOUT_MS });
+        invalidateLiveVersionCache(ctx.agent);
+        // findInPath skips our own shims dir, so this is the genuine vendor binary
+        // and never our dispatcher (which would produce a self-execing link farm).
+        const installed = findInPath(config.cliCommand);
+        if (!installed) {
+            throw new Error(`${config.name} installer finished but ${config.cliCommand} is not on PATH — the install did not complete.`);
+        }
+        // On Windows there is no `.cmd` wrapper beside an imported install-script
+        // binary, so the staged launch probe cannot run and reports healthy. The
+        // gate is therefore weaker here than on POSIX; the unconditional undo in
+        // update.ts is what keeps a bad swap recoverable.
+        const release = target === 'latest'
+            ? (await getLiveVersion(ctx.agent)) ?? target
+            : target;
+        const dir = installationDir(ctx.agent, ctx.installation.label);
+        const stagingDir = path.join(dir, `.staging-${runId()}`);
+        fs.mkdirSync(stagingDir, { recursive: true });
+        const imported = importInstallScriptBinary({ agentId: ctx.agent, npmPackage: config.npmPackage, cliCommand: config.cliCommand }, ctx.installation.label, installed, stagingDir);
+        if (!imported.success) {
+            // Swallowing this reported the launch probe's generic "binary not found"
+            // instead of the real reason the import failed.
+            throw new Error(`${config.name} ${release} was installed but could not be linked into the version directory: ${imported.error ?? 'unknown error'}`);
+        }
+        return {
+            release,
+            binary: path.join(stagingDir, 'node_modules', '.bin', config.cliCommand),
+            home: getVersionHomePath(ctx.agent, ctx.installation.label),
+            stagingDir,
+        };
+    },
+    commit: npmPackageStrategy.commit,
+};
+/**
+ * Pick the update strategy for an agent from the registry's declared shape.
+ *
+ * The ordering mirrors `installVersion`: an npm package wins whenever one is
+ * declared (kimi declares both a package and a script, and its package is what
+ * `agents add` installs), then a single shared global binary, then a per-install
+ * script. Anything else is an integration boundary we do not handle — it throws
+ * rather than silently no-opping and reporting success.
+ */
+export function selectUpdateStrategy(agent) {
+    const config = AGENTS[agent];
+    if (config.npmPackage)
+        return npmPackageStrategy;
+    if (config.installScript && isGlobalBinaryAgent(agent))
+        return globalBinaryStrategy;
+    if (config.installScript) {
+        if (!usesVersionDirLinkFarm(agent)) {
+            // The install path resolves this harness's binary somewhere the version
+            // dir's link farm does not describe (grok keeps a real per-release copy
+            // under its version home). Staging and swapping the link farm would leave
+            // the launch target untouched, so the update would record a release that
+            // is not actually installed. Refuse instead of reporting a false success.
+            throw new Error(`${config.name} keeps its binary outside the managed version directory, so agents-cli cannot yet update an `
+                + `installation in place. Install the current release as a new installation: agents add ${agent}@latest`);
+        }
+        return installScriptStrategy;
+    }
+    throw new Error(`${config.name} is not installed by agents-cli (it declares no npm package and no installer), so there is nothing to update. `
+        + `Update it with its own tooling.`);
+}
+/**
+ * Does this harness's launch target live in the version dir's own
+ * `node_modules/.bin` link farm — the thing an installation can stage and swap?
+ *
+ * Probed through `getBinaryPath`, the single resolver the shims and `agents run`
+ * use, rather than tested against an agent id, so a harness that resolves its
+ * binary elsewhere is recognised without being enumerated here.
+ */
+function usesVersionDirLinkFarm(agent) {
+    const probe = '0.0.0-probe';
+    const expected = path.join(installationDir(agent, probe), 'node_modules', '.bin', AGENTS[agent].cliCommand);
+    return getBinaryPath(agent, probe) === expected;
+}
+/**
+ * Whether a concrete release can be requested for this agent at all. False for
+ * every self-updating harness — their installers carry no version token.
+ */
+export function supportsPinnedUpdate(agent) {
+    const config = AGENTS[agent];
+    if (config.npmPackage)
+        return true;
+    return !isSelfUpdatingAgent(agent);
+}
+/** Guard a user-supplied release token before it reaches a path or a package spec. */
+export function assertValidRelease(requested) {
+    if (!VERSION_RE.test(requested)) {
+        throw new Error(`Invalid release: ${JSON.stringify(requested)}`);
+    }
+}

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

@@ -0,0 +1,78 @@
+import type { AgentId } from '../types.js';
+/**
+ * Schema version of the on-disk installation record. Bump only for a change a
+ * previous CLI could not read; {@link INSTALLATION_SCHEMA} is asserted on read
+ * so a newer record fails loud instead of being silently misinterpreted.
+ */
+export declare const INSTALLATION_SCHEMA = 1;
+/** File name of the record, written at the root of a version dir. */
+export declare const INSTALLATION_RECORD_FILE = "installation.json";
+/**
+ * One entry in an installation's release history — appended on every successful
+ * update so `agents update --json` can report where a frozen installation came
+ * from without consulting the vendor.
+ */
+export interface InstallationRelease {
+    /** The vendor release that was live for this span. */
+    releaseVersion: string;
+    /** ISO-8601 timestamp at which this release became live. */
+    at: string;
+}
+/**
+ * A frozen agent installation.
+ *
+ * The load-bearing idea: an installation's IDENTITY ({@link id}, {@link label})
+ * is stable for the life of the install, while the vendor release it carries
+ * ({@link releaseVersion}) moves only on an explicit `agents update`. Every
+ * persisted reference — the global default, an isolated default, a project pin,
+ * a routine's agent spec — names the {@link label}, so a release change never
+ * invalidates a reference.
+ *
+ * Before this record existed the version-dir NAME was the only identity, which
+ * made those two concepts the same string: updating a release necessarily
+ * renamed the directory and broke every reference pointing at it, and two
+ * installations of the same release could not coexist at all. Splitting them is
+ * what makes both possible.
+ */
+export interface Installation {
+    schema: number;
+    /** Opaque, stable, never reused. Survives every update. */
+    id: string;
+    agent: AgentId;
+    /**
+     * The addressable name of this installation — the version-dir basename, and
+     * the token users type in `agents update <agent>@<label>`. Frozen at creation.
+     */
+    label: string;
+    /** The vendor release currently installed on disk. Moves on update. */
+    releaseVersion: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Newest last. Always non-empty: creation seeds it with the first release. */
+    history: InstallationRelease[];
+}
+/**
+ * How an installation's release is replaced. Selected from the agent registry's
+ * capabilities, never from an agent id — see `selectUpdateStrategy`.
+ */
+export type UpdateStrategyId = 
+/** Agent ships an npm package: a pinnable release staged into the version dir. */
+'npm-package'
+/** One global self-updating binary shared by every installation of the agent. */
+ | 'global-binary'
+/** An official install script with no pinnable version, re-imported per install. */
+ | 'install-script';
+/** Outcome of a single `agents update` run against one installation. */
+export interface UpdateOutcome {
+    installation: Installation;
+    strategy: UpdateStrategyId;
+    fromRelease: string;
+    toRelease: string;
+    /** True when the resolved target already matched the installed release. */
+    unchanged: boolean;
+    /**
+     * Installations other than the target whose recorded release also moved,
+     * because the strategy replaced a binary they share (global-binary only).
+     */
+    alsoUpdated: Installation[];
+}

package/dist/lib/installations/types.js

@@ -0,0 +1,8 @@
+/**
+ * Schema version of the on-disk installation record. Bump only for a change a
+ * previous CLI could not read; {@link INSTALLATION_SCHEMA} is asserted on read
+ * so a newer record fails loud instead of being silently misinterpreted.
+ */
+export const INSTALLATION_SCHEMA = 1;
+/** File name of the record, written at the root of a version dir. */
+export const INSTALLATION_RECORD_FILE = 'installation.json';