@phnx-labs/agents-cli 1.22.31 → 1.22.33

package/dist/lib/installations/resolve.js

@@ -0,0 +1,93 @@
+import { resolveAccountLabel } from '../account-labels.js';
+import { AGENTS } from '../agents.js';
+import { getGlobalDefault } from '../versions.js';
+import { listInstallations } from './store.js';
+/**
+ * Addressing a frozen installation.
+ *
+ * A selector matches either the installation's stable {@link Installation.label}
+ * or the vendor release it currently carries — the label because that is what
+ * every persisted reference and every `agents add` invocation uses, the release
+ * because after an update the two differ and a user reading `agents view` may
+ * name either. Matching both is also precisely what makes duplicate same-release
+ * installations addressable at all: two installs can share a release, so the
+ * release alone is not an identifier and the ambiguity has to be reported rather
+ * than silently resolved to whichever sorted first.
+ */
+export class InstallationNotFoundError extends Error {
+    agent;
+    selector;
+    available;
+    constructor(agent, selector, available) {
+        // Nothing installed is a different problem from "your selector missed", and
+        // the remedy differs — say which one it is rather than printing an empty list.
+        super(available.length === 0
+            ? `No ${AGENTS[agent].name} installations are managed by agents-cli. Install one with: agents add ${agent}@latest`
+            : `No ${AGENTS[agent].name} installation matches '${selector}'. Installed: ${available.map((i) => describeInstallation(i)).join(', ')}`);
+        this.agent = agent;
+        this.selector = selector;
+        this.available = available;
+        this.name = 'InstallationNotFoundError';
+    }
+}
+export class InstallationAmbiguousError extends Error {
+    agent;
+    selector;
+    candidates;
+    constructor(agent, selector, candidates) {
+        super(`'${selector ?? agent}' matches ${candidates.length} ${AGENTS[agent].name} installations `
+            + `(${candidates.map((i) => describeInstallation(i)).join(', ')}). `
+            + `Name one by its installation label, or disambiguate with --account <label>.`);
+        this.agent = agent;
+        this.selector = selector;
+        this.candidates = candidates;
+        this.name = 'InstallationAmbiguousError';
+    }
+}
+/** `2.0.65` when frozen at its original release, `2.0.65 (release 2.0.71)` after an update. */
+export function describeInstallation(installation) {
+    return installation.releaseVersion === installation.label
+        ? installation.label
+        : `${installation.label} (release ${installation.releaseVersion})`;
+}
+/**
+ * Resolve `<agent>[@<selector>]` to exactly one installation.
+ *
+ * With no selector: the agent's default installation when one is pinned, else
+ * the sole installation. Never a "newest wins" guess — picking for the user
+ * across several installs is how an update lands on the wrong one.
+ */
+export async function resolveInstallation(agent, selector, options = {}) {
+    const all = listInstallations(agent);
+    if (all.length === 0)
+        throw new InstallationNotFoundError(agent, selector, all);
+    let candidates = all;
+    if (options.account) {
+        // resolveAccountLabel answers with the version-dir label of the install that
+        // is signed into that account — i.e. an installation label.
+        const label = await resolveAccountLabel(agent, options.account);
+        candidates = candidates.filter((i) => i.label === label);
+        if (candidates.length === 0)
+            throw new InstallationNotFoundError(agent, selector, all);
+    }
+    if (selector) {
+        const byLabel = candidates.filter((i) => i.label === selector);
+        // A label is unique by construction (it is a directory name), so a label hit
+        // is decisive and never competes with a release hit on another installation.
+        if (byLabel.length === 1)
+            return byLabel[0];
+        const byRelease = candidates.filter((i) => i.releaseVersion === selector);
+        if (byRelease.length === 1)
+            return byRelease[0];
+        if (byRelease.length > 1)
+            throw new InstallationAmbiguousError(agent, selector, byRelease);
+        throw new InstallationNotFoundError(agent, selector, all);
+    }
+    if (candidates.length === 1)
+        return candidates[0];
+    const defaultLabel = getGlobalDefault(agent);
+    const pinned = defaultLabel ? candidates.find((i) => i.label === defaultLabel) : undefined;
+    if (pinned)
+        return pinned;
+    throw new InstallationAmbiguousError(agent, selector, candidates);
+}

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

@@ -0,0 +1,56 @@
+import type { AgentId } from '../types.js';
+import { type Installation } 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 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. */
+export declare function mintInstallationId(): string;
+/**
+ * Read the record for one installation, or null when the version dir has none.
+ * Never mints — use {@link ensureInstallation} for the migrating read.
+ */
+export declare function readInstallation(agent: AgentId, label: string): Installation | null;
+export declare function writeInstallation(installation: Installation): void;
+/**
+ * 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 declare function ensureInstallation(agent: AgentId, label: string): Installation;
+/**
+ * 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 declare function createInstallation(agent: AgentId, label: string, releaseVersion: string): Installation;
+/**
+ * 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 declare function recordRelease(installation: Installation, releaseVersion: string): Installation;
+/** Version-dir basenames present for an agent, oldest-first by directory name. */
+export declare function listInstallationLabels(agent: AgentId): string[];
+/**
+ * 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 declare function listInstallations(agent: AgentId): Installation[];

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;