@agentage/cli 0.39.0 → 0.40.0

package/dist/core/installer/latest.js

@@ -0,0 +1,88 @@
+import { join } from 'node:path';
+import { isRecord, readJson } from '../../lib/fs/json-file.js';
+import { manifestInfo } from '../loader/manifest.js';
+import { extensionsDir } from '../paths.js';
+import { fitsApi } from './compat.js';
+import { lockEntries, lockedVersion, parseLock, rootDependencies } from './compare-lock.js';
+import { planInstall, refuseDrift, runNpmInto, } from './installer.js';
+import {} from './npm.js';
+import { clearStaging, collectTrees, commitTree, discardTree, pointCurrent, promoteFiles, readText, stageTree, treePath, withInstallLock, } from './tree.js';
+const diff = (names, before, after) => names
+    .map((name) => ({ name, from: lockedVersion(before, name), to: lockedVersion(after, name) }))
+    .filter((change) => change.from !== change.to);
+// Every extension the profile names or the old lock installed, sorted.
+const namesOf = (plan, before) => {
+    const installed = before === null ? [] : Object.keys(rootDependencies(before));
+    return [...new Set([...Object.keys(plan.install), ...installed])].sort();
+};
+const update = async (plan, npm, packages = []) => {
+    const staging = stageTree(plan.extensionsDir, plan);
+    try {
+        const { tree, lock } = await runNpmInto(staging, 'update', npm, packages);
+        return { staging, tree, lock: parseLock(lock), raw: lock };
+    }
+    catch (err) {
+        discardTree(staging);
+        throw err;
+    }
+};
+const engineIn = (staging, name) => manifestInfo(readJson(join(staging, 'node_modules', name, 'package.json'), isRecord) ?? {})
+    .engine;
+// An extension whose new version needs another extension API stays where it was.
+const heldIn = (built, changes) => changes.flatMap(({ name, from, to }) => {
+    if (from === null || to === null)
+        return [];
+    const engine = engineIn(built.staging, name);
+    return fitsApi(engine) ? [] : [{ name, version: from, newer: to, engine }];
+});
+const unchanged = (plan, changes) => Object.keys(plan.install).filter((name) => !changes.some((c) => c.name === name)).length;
+// One update; when it moved an extension past the extension API, again without moving that one.
+const settle = async (plan, npm, names, before) => {
+    const first = await update(plan, npm);
+    const changes = diff(names, before, first.lock);
+    const held = heldIn(first, changes);
+    if (held.length === 0)
+        return { built: first, held };
+    discardTree(first.staging);
+    const moving = changes.map((c) => c.name).filter((name) => !held.some((h) => h.name === name));
+    return { built: moving.length === 0 ? null : await update(plan, npm, moving), held };
+};
+const sameEntries = (a, b) => (a ? lockEntries(a).join('\n') : '') === (b ? lockEntries(b).join('\n') : '');
+// A tree that failed its check goes, unless extensions/current already names it.
+const dropUnlessCurrent = (dir, tree) => {
+    if (readText(join(dir, 'current'))?.trim() !== tree)
+        discardTree(treePath(dir, tree));
+};
+// The new tree becomes current only once it passed the check; then it is the only tree left.
+const commit = async (plan, built, staged, check) => {
+    commitTree(plan.extensionsDir, built.staging, built.tree);
+    if (!(await check(staged))) {
+        dropUnlessCurrent(plan.extensionsDir, built.tree);
+        return false;
+    }
+    pointCurrent(plan.extensionsDir, built.tree);
+    promoteFiles(plan.extensionsDir, { manifest: plan.manifest, lock: built.raw });
+    collectTrees(plan.extensionsDir, built.tree);
+    return true;
+};
+const run = async (plan, prepare, check) => {
+    refuseDrift(plan.extensionsDir);
+    clearStaging(plan.extensionsDir);
+    const before = parseLock(plan.lock);
+    const names = namesOf(plan, before);
+    const none = { changes: [], held: [], unchanged: 0, tree: null, current: false };
+    if (names.length === 0)
+        return none;
+    const { built, held } = await settle(plan, await prepare(), names, before);
+    const changes = built === null ? [] : diff(names, before, built.lock);
+    const result = { ...none, changes, held, unchanged: unchanged(plan, changes) };
+    if (built === null || sameEntries(before, built.lock)) {
+        if (built !== null)
+            discardTree(built.staging);
+        return result;
+    }
+    const staged = { ...result, tree: built.tree, dir: treePath(plan.extensionsDir, built.tree) };
+    return { ...result, tree: built.tree, current: await commit(plan, built, staged, check) };
+};
+// `setup --latest`: npm update from the current lock, under the install lock for the whole run.
+export const updateLatest = (set, prepare, check) => withInstallLock(extensionsDir(), () => run(planInstall(set), prepare, check));

package/dist/core/installer/npm.d.ts

@@ -0,0 +1,11 @@
+import { type NpmResult } from '../../lib/npm/npm-cli.js';
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export type NpmCommand = 'ci' | 'install' | 'update';
+export type Npm = (command: NpmCommand, tree: string, packages?: string[]) => Promise<NpmResult>;
+export type LookupCommand = 'pack' | 'view';
+export type NpmManifest = (command: LookupCommand, spec: string, registries: Record<string, string>) => Promise<NpmResult>;
+export declare const npmArgs: (command: NpmCommand, tree: string, env?: NodeJS.ProcessEnv, packages?: string[]) => string[];
+export declare const manifestArgs: (command: LookupCommand, spec: string, registries: Record<string, string>, prefix: string, env?: NodeJS.ProcessEnv) => string[];
+export declare const npmMajor: (env?: NodeJS.ProcessEnv) => Promise<number>;
+export declare const prepareNpm: (env?: NodeJS.ProcessEnv) => Promise<Npm>;
+export declare const prepareManifest: (env?: NodeJS.ProcessEnv) => Promise<NpmManifest>;

package/dist/core/installer/npm.js

@@ -0,0 +1,76 @@
+import { requireNpm10, resolveNpmCli, runNpm } from '../../lib/npm/npm-cli.js';
+import { extensionsDir } from '../paths.js';
+// Every package whose scope the profile's `registries` does not name comes from here.
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const NPM_TIMEOUT_MS = 10 * 60_000;
+const LOOKUP_TIMEOUT_MS = 2 * 60_000;
+// `name` keeps every version an object: npm view unwraps to bare values when the first has one field.
+const LOOKUP_FLAGS = {
+    pack: ['--dry-run', '--json'],
+    view: ['name', 'version', 'engines', '--json'],
+};
+// npm reads its env config case-insensitively, so either spelling may carry these paths.
+const npmConfig = (env, key) => {
+    const name = `npm_config_${key}`;
+    const found = Object.keys(env).find((k) => k.toLowerCase() === name);
+    return (found && env[found]) || null;
+};
+// Carried as flags: runNpm drops every npm_config_* variable from the child env.
+const configFlags = (env) => {
+    const userconfig = npmConfig(env, 'userconfig');
+    const cache = npmConfig(env, 'cache');
+    return [
+        ...(userconfig ? ['--userconfig', userconfig] : []),
+        ...(cache ? ['--cache', cache] : []),
+    ];
+};
+// Scoped registries come from the tree's own .npmrc; runNpm appends --no-audit --no-fund.
+export const npmArgs = (command, tree, env = process.env, packages = []) => [
+    command,
+    ...packages,
+    '--prefix',
+    tree,
+    '--registry',
+    DEFAULT_REGISTRY,
+    '--ignore-scripts',
+    '--no-update-notifier',
+    ...configFlags(env),
+];
+// `--prefix` keeps a project .npmrc in the working directory out of it; scopes go as flags.
+export const manifestArgs = (command, spec, registries, prefix, env = process.env) => [
+    command,
+    spec,
+    ...LOOKUP_FLAGS[command],
+    '--ignore-scripts',
+    '--prefix',
+    prefix,
+    '--registry',
+    DEFAULT_REGISTRY,
+    ...Object.entries(registries).map(([scope, url]) => `--${scope}:registry=${url}`),
+    '--no-update-notifier',
+    ...configFlags(env),
+];
+// Resolves npm-cli.js once and refuses npm below 10 before anything runs.
+const checkedNpm = async (env) => {
+    const npmCli = resolveNpmCli({ env });
+    const run = (args, opts) => runNpm([...args, ...configFlags(env)], { ...opts, npmCli });
+    return { npmCli, version: await requireNpm10(run) };
+};
+const checkedNpmCli = async (env) => (await checkedNpm(env)).npmCli;
+// The npm major that writes the lock, pushed next to it.
+export const npmMajor = async (env = process.env) => Number.parseInt((await checkedNpm(env)).version, 10);
+export const prepareNpm = async (env = process.env) => {
+    const npmCli = await checkedNpmCli(env);
+    return (command, tree, packages = []) => runNpm(npmArgs(command, tree, env, packages), {
+        cwd: tree,
+        timeoutMs: NPM_TIMEOUT_MS,
+        npmCli,
+    });
+};
+export const prepareManifest = async (env = process.env) => {
+    const npmCli = await checkedNpmCli(env);
+    return (command, spec, registries) => runNpm(manifestArgs(command, spec, registries, extensionsDir(), env), {
+        timeoutMs: LOOKUP_TIMEOUT_MS,
+        npmCli,
+    });
+};

package/dist/core/installer/plan.d.ts

@@ -0,0 +1,25 @@
+export type PlanVerb = 'add' | 'update' | 'remove' | 'off' | 'unchanged';
+export interface PlanEntry {
+    verb: PlanVerb;
+    name: string;
+    wanted: string | null;
+    current: string | null;
+}
+export type PlanSummary = Record<PlanVerb, number>;
+export interface Plan {
+    extensions: PlanEntry[];
+    summary: PlanSummary;
+}
+export interface Desired {
+    install: Record<string, string>;
+    off: string[];
+}
+export interface LockDrift {
+    integrity: string[];
+    matches: boolean;
+}
+export declare const planChanges: (desired: Desired, current: Record<string, string>) => Plan;
+export declare const pendingChanges: (summary: PlanSummary) => string[];
+export declare const currentDependencies: (dir?: string) => Record<string, string>;
+export declare const lockDrift: (dir?: string) => LockDrift;
+export declare const driftLines: (integrity: string[]) => string[];

package/dist/core/installer/plan.js

@@ -0,0 +1,52 @@
+import { join } from 'node:path';
+import { currentTree } from '../loader/discover.js';
+import { extensionsDir } from '../paths.js';
+import { integrityDrift, lockEntries, parseLock, rootDependencies } from './compare-lock.js';
+import { LOCK_FILE, readText } from './tree.js';
+// A changed range is an update: npm would resolve it again.
+const verbOf = (wanted, current, off) => {
+    if (current === null)
+        return 'add';
+    if (wanted === null)
+        return 'remove';
+    if (wanted !== current)
+        return 'update';
+    return off ? 'off' : 'unchanged';
+};
+const entryOf = (name, desired, current) => {
+    const wanted = desired.install[name] ?? null;
+    const now = current[name] ?? null;
+    return { verb: verbOf(wanted, now, desired.off.includes(name)), name, wanted, current: now };
+};
+// One entry per package the profile or the current tree names, sorted by name.
+export const planChanges = (desired, current) => {
+    const names = [...new Set([...Object.keys(desired.install), ...Object.keys(current)])].sort();
+    const extensions = names.map((name) => entryOf(name, desired, current));
+    const summary = { add: 0, update: 0, remove: 0, off: 0, unchanged: 0 };
+    for (const entry of extensions)
+        summary[entry.verb] += 1;
+    return { extensions, summary };
+};
+// What setup would change, e.g. ["1 to add"]; `off` stays installed, so it is never pending.
+export const pendingChanges = (summary) => ['add', 'update', 'remove']
+    .filter((verb) => summary[verb] > 0)
+    .map((verb) => `${summary[verb]} to ${verb}`);
+const treeLock = (dir) => {
+    const tree = currentTree(dir).dir;
+    return tree === null ? null : parseLock(readText(join(tree, LOCK_FILE)));
+};
+// What the last install asked npm for; a tree reused for the same packages keeps its first lock.
+export const currentDependencies = (dir = extensionsDir()) => {
+    const finished = currentTree(dir).dir !== null;
+    const lock = finished ? parseLock(readText(join(dir, LOCK_FILE))) : null;
+    return lock === null ? {} : rootDependencies(lock);
+};
+// extensions/package-lock.json describes the current tree; anything else was changed by hand.
+export const lockDrift = (dir = extensionsDir()) => {
+    const root = parseLock(readText(join(dir, LOCK_FILE)));
+    const tree = treeLock(dir);
+    const entries = (lock) => (lock === null ? '' : lockEntries(lock).join('\n'));
+    const integrity = root && tree ? integrityDrift(root, tree) : [];
+    return { integrity, matches: entries(root) === entries(tree) };
+};
+export const driftLines = (integrity) => integrity.map((key) => `integrity drift: ${key}`);

package/dist/core/installer/resolve.d.ts

@@ -0,0 +1,25 @@
+import { type Published } from './compat.js';
+import { type NpmManifest } from './npm.js';
+export type Resolved = {
+    kind: 'package';
+    name: string;
+    spec: string;
+    skipped: Published[];
+} | {
+    kind: 'dev';
+    name: string;
+    path: string;
+};
+export interface Found {
+    name: string;
+    version: string;
+}
+export type Lookup = (spec: string) => Promise<Found | null>;
+export type Versions = (name: string) => Promise<Published[] | null>;
+export interface Registry {
+    find: Lookup;
+    versions: Versions;
+}
+export declare const candidatesFor: (name: string) => string[];
+export declare const resolveName: (input: string, registry: Registry) => Promise<Resolved>;
+export declare const registryLookup: (prepare: () => Promise<NpmManifest>, registries: Record<string, string>) => Registry;

package/dist/core/installer/resolve.js

@@ -0,0 +1,139 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { EXTENSION_API_VERSION } from '../../extension.js';
+import { isRecord, readJson } from '../../lib/fs/json-file.js';
+import {} from '../../lib/npm/npm-cli.js';
+import { PACKAGE_NAME, specProblem } from '../profile/schema.js';
+import { needs, newestCompatible, parsePublished } from './compat.js';
+import { lastLines } from './installer.js';
+import {} from './npm.js';
+// Every release: a range, not `*`, which npm view reads as the `latest` tag alone.
+const EVERY_RELEASE = '>=0.0.0';
+const LOCAL = /^\.{1,2}(?:[/\\]|$)/;
+const REFUSED = /^(npm|github|file|http):/i;
+const PROTOCOL = /^[a-z][a-z0-9+.-]*:/i;
+const HTTPS = /^https:/i;
+const FULL_PREFIX = 'agentage-extension-';
+const INSTEAD = 'install a package name, an https: tarball URL or a local path (./path)';
+// `memory` -> the two names it may be published under; any other name stands for itself.
+export const candidatesFor = (name) => name.startsWith('@') || name.startsWith(FULL_PREFIX)
+    ? [name]
+    : [`@agentage/extension-${name}`, `${FULL_PREFIX}${name}`];
+const refusal = (input) => {
+    const scheme = REFUSED.exec(input)?.[1];
+    if (scheme)
+        return `${scheme.toLowerCase()}: is refused; ${INSTEAD}`;
+    return PROTOCOL.test(input) && !HTTPS.test(input) ? `unsupported; ${INSTEAD}` : null;
+};
+const folder = (input) => {
+    try {
+        return realpathSync(resolve(input));
+    }
+    catch {
+        return null;
+    }
+};
+// Its own package.json names the package and declares agentage.id, as discovery will check.
+const devExtension = (input) => {
+    const path = folder(input);
+    const manifest = path === null ? null : readJson(join(path, 'package.json'), isRecord);
+    const agentage = manifest?.['agentage'];
+    const name = manifest?.['name'];
+    if (path === null || typeof name !== 'string' || !isRecord(agentage) || !agentage['id'])
+        throw new Error(`${input}: not an extension folder (no package.json with a name and agentage.id)`);
+    return { kind: 'dev', name, path };
+};
+// The first candidate the registry has; a missing one moves on to the next.
+const firstFound = async (specs, input, look) => {
+    for (const spec of specs) {
+        const found = await look(spec);
+        if (found)
+            return found;
+    }
+    throw new Error(`${input}: not found; tried ${specs.join(', ')}`);
+};
+const fromUrl = async (url, look) => {
+    const problem = specProblem(url);
+    if (problem)
+        throw new Error(`${url}: ${problem}`);
+    const { name } = await firstFound([url], url, look);
+    return { kind: 'package', name, spec: url, skipped: [] };
+};
+const pinned = (input, name, published) => {
+    const { version, skipped } = newestCompatible(published);
+    if (version !== null)
+        return { kind: 'package', name, spec: `^${version}`, skipped };
+    const newest = skipped[0] === undefined ? '' : ` (${needs(skipped[0])})`;
+    const api = `extension API ${EXTENSION_API_VERSION}`;
+    throw new Error(`${input}: no published version works with ${api}${newest}`);
+};
+// The first candidate the registry has, at its newest version this CLI can load.
+const compatible = async (input, name, versions) => {
+    const names = candidatesFor(name);
+    for (const candidate of names) {
+        const published = await versions(candidate);
+        if (published !== null)
+            return pinned(input, candidate, published);
+    }
+    throw new Error(`${input}: not found; tried ${names.join(', ')}`);
+};
+// `name@range` keeps the range; without one, the newest compatible version as `^<version>`.
+const fromName = async (input, registry) => {
+    const at = input.indexOf('@', 1);
+    const name = at === -1 ? input : input.slice(0, at);
+    const range = at === -1 ? null : input.slice(at + 1);
+    if (!PACKAGE_NAME.test(name))
+        throw new Error(`${input}: not a package name`);
+    const problem = range === null ? null : specProblem(range);
+    if (problem)
+        throw new Error(`${input}: ${problem}`);
+    if (range === null)
+        return compatible(input, name, registry.versions);
+    const specs = candidatesFor(name).map((c) => `${c}@${range}`);
+    const found = await firstFound(specs, input, registry.find);
+    return { kind: 'package', name: found.name, spec: range, skipped: [] };
+};
+// A local path, then refused schemes, then a tarball URL, then a package or short name.
+export const resolveName = async (input, registry) => {
+    if (LOCAL.test(input) || isAbsolute(input))
+        return devExtension(input);
+    const refused = refusal(input);
+    if (refused)
+        throw new Error(`${input}: ${refused}`);
+    return HTTPS.test(input) ? fromUrl(input, registry.find) : fromName(input, registry);
+};
+const parseFound = (stdout) => {
+    try {
+        const [first] = JSON.parse(stdout);
+        const { name, version } = isRecord(first) ? first : {};
+        return typeof name === 'string' && typeof version === 'string' ? { name, version } : null;
+    }
+    catch {
+        return null;
+    }
+};
+// E404 means absent; any other failure, or an answer that does not parse, stops the install.
+const answerOf = (spec, res, parse) => {
+    if (res.code !== 0 && /\bE404\b/.test(`${res.stdout}\n${res.stderr}`))
+        return null;
+    const parsed = res.code === 0 ? parse(res.stdout) : null;
+    if (parsed !== null)
+        return parsed;
+    // With --json, npm repeats its stderr lines as a JSON object on stdout.
+    const why = lastLines(res.stderr.trim() === '' ? res.stdout : res.stderr);
+    throw new Error(`npm could not read ${spec} (exit ${res.code})\n${why}`);
+};
+// npm is prepared on the first question, through the registries the profile routes.
+export const registryLookup = (prepare, registries) => {
+    let manifest;
+    const ask = async (command, spec) => {
+        manifest ??= prepare();
+        return (await manifest)(command, spec, registries);
+    };
+    const versions = async (name) => {
+        const spec = `${name}@${EVERY_RELEASE}`;
+        return answerOf(spec, await ask('view', spec), parsePublished);
+    };
+    const find = async (spec) => answerOf(spec, await ask('pack', spec), parseFound);
+    return { find, versions };
+};

package/dist/core/installer/tree.d.ts

@@ -0,0 +1,21 @@
+export declare const LOCK_FILE = "package-lock.json";
+export interface TreeFiles {
+    manifest: string;
+    npmrc: string;
+    lock: string | null;
+}
+export declare const sortedSet: (install: Record<string, string>) => Record<string, string>;
+export declare const manifestText: (install: Record<string, string>) => string;
+export declare const npmrcText: (registries: Record<string, string>) => string;
+export declare const treeName: (entries: string[]) => string;
+export declare const treePath: (extensionsDir: string, name: string) => string;
+export declare const isComplete: (extensionsDir: string, name: string) => boolean;
+export declare const readText: (path: string) => string | null;
+export declare const clearStaging: (extensionsDir: string) => void;
+export declare const stageTree: (extensionsDir: string, files: TreeFiles) => string;
+export declare const discardTree: (dir: string) => void;
+export declare const commitTree: (extensionsDir: string, staging: string, name: string) => void;
+export declare const collectTrees: (extensionsDir: string, keep: string) => void;
+export declare const pointCurrent: (extensionsDir: string, name: string) => void;
+export declare const promoteFiles: (extensionsDir: string, files: Omit<TreeFiles, "npmrc">) => void;
+export declare const withInstallLock: <T>(extensionsDir: string, fn: () => Promise<T>) => Promise<T>;

package/dist/core/installer/tree.js

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { refreshFileLock, withFileLock } from '../../lib/fs/file-lock.js';
+import { writeTextAtomic } from '../../lib/fs/json-file.js';
+export const LOCK_FILE = 'package-lock.json';
+const MANIFEST_FILE = 'package.json';
+const TREES = 'trees';
+const COMPLETE = '.complete';
+// A fixed name keeps the lock's root entry identical in every tree directory.
+const MANIFEST_NAME = 'agentage-extensions';
+// Dot-prefixed: `extensions/current` only accepts names starting with a letter or digit.
+const STAGING_PREFIX = '.staging-';
+// An install runs for minutes: a long TTL plus a heartbeat keep a live holder from looking dead.
+const INSTALL_LOCK = { ttlMs: 2 * 60_000, hardStaleMs: 60 * 60_000, maxWaitMs: 30 * 60_000 };
+const HEARTBEAT_MS = 20_000;
+export const sortedSet = (install) => Object.fromEntries(Object.entries(install).sort(([a], [b]) => (a < b ? -1 : 1)));
+// Same install set, same bytes: no scripts, nothing machine-specific.
+export const manifestText = (install) => `${JSON.stringify({ name: MANIFEST_NAME, private: true, dependencies: sortedSet(install) }, null, 2)}\n`;
+// npm's own per-scope registry lines; every other package uses the --registry default.
+export const npmrcText = (registries) => Object.entries(sortedSet(registries))
+    .map(([scope, url]) => `${scope}:registry=${url}\n`)
+    .join('');
+// Content-addressed: the same normalized lock names the same tree on every machine.
+export const treeName = (entries) => createHash('sha256').update(entries.join('\n')).digest('hex').slice(0, 16);
+export const treePath = (extensionsDir, name) => join(extensionsDir, TREES, name);
+export const isComplete = (extensionsDir, name) => existsSync(join(treePath(extensionsDir, name), COMPLETE));
+export const readText = (path) => {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+};
+const remove = (path) => rmSync(path, { recursive: true, force: true });
+// Only called under the install lock, so every staging dir left over is from a dead run.
+export const clearStaging = (extensionsDir) => {
+    const trees = join(extensionsDir, TREES);
+    if (!existsSync(trees))
+        return;
+    for (const name of readdirSync(trees).filter((n) => n.startsWith(STAGING_PREFIX)))
+        remove(join(trees, name));
+};
+export const stageTree = (extensionsDir, files) => {
+    const trees = join(extensionsDir, TREES);
+    mkdirSync(trees, { recursive: true, mode: 0o700 });
+    const dir = mkdtempSync(join(trees, STAGING_PREFIX));
+    writeFileSync(join(dir, MANIFEST_FILE), files.manifest);
+    writeFileSync(join(dir, '.npmrc'), files.npmrc);
+    if (files.lock !== null)
+        writeFileSync(join(dir, LOCK_FILE), files.lock);
+    return dir;
+};
+export const discardTree = (dir) => remove(dir);
+// `.complete` lands before the rename, so a tree appears finished or not at all.
+export const commitTree = (extensionsDir, staging, name) => {
+    const target = treePath(extensionsDir, name);
+    if (existsSync(join(target, COMPLETE)))
+        return discardTree(staging);
+    remove(target);
+    writeFileSync(join(staging, COMPLETE), '');
+    renameSync(staging, target);
+};
+// Only `keep` stays: the lock in the extensions root can rebuild any other tree. Staging dirs are
+// left to clearStaging, so a run never removes another's.
+export const collectTrees = (extensionsDir, keep) => {
+    const trees = join(extensionsDir, TREES);
+    if (!existsSync(trees))
+        return;
+    for (const name of readdirSync(trees))
+        if (name !== keep && !name.startsWith(STAGING_PREFIX))
+            remove(join(trees, name));
+};
+export const pointCurrent = (extensionsDir, name) => writeTextAtomic(join(extensionsDir, 'current'), `${name}\n`);
+// The extensions root always describes the tree `current` names, never a failed attempt.
+export const promoteFiles = (extensionsDir, files) => {
+    writeTextAtomic(join(extensionsDir, MANIFEST_FILE), files.manifest);
+    const lock = join(extensionsDir, LOCK_FILE);
+    if (files.lock === null)
+        remove(lock);
+    else
+        writeTextAtomic(lock, files.lock);
+};
+const heartbeat = async (target, fn) => {
+    const beat = setInterval(() => refreshFileLock(target), HEARTBEAT_MS);
+    beat.unref();
+    try {
+        return await fn();
+    }
+    finally {
+        clearInterval(beat);
+    }
+};
+// A second run waits on `<extensionsDir>/install.lock` instead of racing the first one.
+export const withInstallLock = (extensionsDir, fn) => {
+    const target = join(extensionsDir, 'install');
+    const onWait = () => console.error(`waiting for another install to finish (${target}.lock)`);
+    return withFileLock(target, () => heartbeat(target, fn), { ...INSTALL_LOCK, onWait });
+};

package/dist/core/loader/config.d.ts

@@ -0,0 +1,7 @@
+export interface CheckedConfig {
+    config: Record<string, unknown>;
+    secrets: string[];
+    descriptions: Record<string, string>;
+    problem: string | null;
+}
+export declare const checkConfig: (id: string, configuration: Record<string, unknown>, slice: Record<string, unknown>) => CheckedConfig;

package/dist/core/loader/config.js

@@ -0,0 +1,59 @@
+import { isRecord } from '../../lib/fs/json-file.js';
+const TYPES = {
+    string: (value) => typeof value === 'string',
+    number: (value) => typeof value === 'number',
+    boolean: (value) => typeof value === 'boolean',
+    array: (value) => Array.isArray(value),
+    object: isRecord,
+};
+const typeOf = (value) => {
+    if (value === null)
+        return 'null';
+    return Array.isArray(value) ? 'array' : typeof value;
+};
+const quoted = (value) => JSON.stringify(value);
+const declarationProblem = (key, declared) => {
+    const type = declared['type'];
+    if (typeof type !== 'string' || !TYPES[type])
+        return `agentage.configuration.${key}.type must be one of ${Object.keys(TYPES).join(', ')}`;
+    const allowed = declared['enum'];
+    if (allowed !== undefined && !Array.isArray(allowed))
+        return `agentage.configuration.${key}.enum must be an array`;
+    return null;
+};
+// Compared as JSON, so an enum of arrays or objects works too.
+const valueProblem = (name, declared, value) => {
+    const type = String(declared['type']);
+    if (value === undefined)
+        return null;
+    if (!TYPES[type]?.(value))
+        return `${name}: must be of type ${type} (got ${typeOf(value)})`;
+    const allowed = declared['enum'];
+    if (!Array.isArray(allowed) || allowed.some((v) => quoted(v) === quoted(value)))
+        return null;
+    return `${name}: must be one of ${allowed.map(quoted).join(', ')} (got ${quoted(value)})`;
+};
+const declarations = (configuration) => Object.entries(configuration).map(([key, entry]) => ({
+    key,
+    declared: isRecord(entry) ? entry : {},
+}));
+const descriptionsOf = (all) => Object.fromEntries(all.flatMap(({ key, declared }) => {
+    const text = declared['description'];
+    return typeof text === 'string' ? [[key, text]] : [];
+}));
+// The profile's slice for one extension, checked against what its manifest declares.
+export const checkConfig = (id, configuration, slice) => {
+    const all = declarations(configuration);
+    const secrets = all.filter((d) => d.declared['secret'] === true).map((d) => d.key);
+    const config = Object.fromEntries(Object.entries(slice).filter(([k]) => !secrets.includes(k)));
+    const descriptions = descriptionsOf(all);
+    for (const { key, declared } of all.filter((d) => !secrets.includes(d.key))) {
+        const value = key in slice ? slice[key] : declared['default'];
+        const problem = declarationProblem(key, declared) ?? valueProblem(`config.${id}.${key}`, declared, value);
+        if (problem)
+            return { config: {}, secrets: [], descriptions: {}, problem };
+        if (value !== undefined)
+            config[key] = value;
+    }
+    return { config, secrets, descriptions, problem: null };
+};

package/dist/core/loader/ctx.d.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { type Disposable, type ExtensionContext, type ExtensionUse } from '../../extension.js';
+import { type DiscoveredExtension } from './discover.js';
+export interface StagedContext {
+    ctx: ExtensionContext;
+    program: Command;
+    subscriptions: Disposable[];
+    revoke: () => void;
+    close: () => void;
+}
+export interface ContextInput {
+    ext: DiscoveredExtension;
+    use: ExtensionUse;
+    template: Command;
+}
+export declare const createContext: ({ ext, use, template }: ContextInput) => StagedContext;