@agentage/cli 0.39.0 → 0.41.0

package/dist/core/loader/discover.js

@@ -1,6 +1,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { isRecord } from '../../lib/fs/json-file.js';
+import {} from '../profile/schema.js';
+import { checkConfig } from './config.js';
+import { unsafeDevPath } from './dev-path.js';
+import {} from './kit-manifest.js';
 import { manifestInfo, manifestProblem } from './manifest.js';
 const readText = (path) => {
     try {
@@ -10,10 +14,9 @@ const readText = (path) => {
         return null;
     }
 };
-const defaultDeps = { readText, exists: existsSync };
 const TREE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const readManifest = (dir, deps) => {
-    const raw = deps.readText(join(dir, 'package.json'));
+const readManifest = (dir) => {
+    const raw = readText(join(dir, 'package.json'));
     try {
         const value = raw === null ? null : JSON.parse(raw);
         return isRecord(value) ? value : null;
@@ -22,59 +25,68 @@ const readManifest = (dir, deps) => {
         return null;
     }
 };
-// `plugins/current` names the tree; one without its `.complete` marker was never finished.
-export const currentTree = (pluginsDir, deps = defaultDeps) => {
-    const name = deps.readText(join(pluginsDir, 'current'))?.trim() ?? '';
+// `extensions/current` names the tree; one without its `.complete` marker was never finished.
+export const currentTree = (extensionsDir) => {
+    const name = readText(join(extensionsDir, 'current'))?.trim() ?? '';
     if (name === '')
         return { dir: null, warning: null };
     if (!TREE_NAME.test(name))
-        return { dir: null, warning: `plugins/current: bad tree "${name}"` };
-    const dir = join(pluginsDir, 'trees', name);
-    if (deps.exists(join(dir, '.complete')))
+        return { dir: null, warning: `extensions/current: bad tree "${name}"` };
+    const dir = join(extensionsDir, 'trees', name);
+    if (existsSync(join(dir, '.complete')))
         return { dir, warning: null };
-    return { dir: null, warning: `plugins tree "${name}" is incomplete and was ignored` };
+    return { dir: null, warning: `extensions tree "${name}" is incomplete and was ignored` };
 };
 const inside = (dir, entry) => {
     const path = resolve(dir, entry);
     const rel = relative(dir, path);
     return rel === '' || rel.startsWith('..') || isAbsolute(rel) ? null : path;
 };
-const entryProblem = (info, path, deps) => {
+const entryProblem = (info, path) => {
     if (info.entry === null)
         return null;
     if (path === null)
         return `entry ${info.entry} is outside the package`;
-    return deps.exists(path) ? null : `entry ${info.entry} not found`;
+    return existsSync(path) ? null : `entry ${info.entry} not found`;
 };
 const blank = (pkg, source, dir) => ({
     pkg,
+    kind: 'api',
     source,
     dir,
     version: null,
     id: null,
     entry: null,
     commands: [],
+    kitCommands: [],
     peers: [],
     optionalPeers: [],
+    config: {},
+    secrets: [],
+    descriptions: {},
     problem: null,
     missing: false,
 });
-const inspect = (pkg, source, dir, deps) => {
+const inspect = ({ pkg, source, dir }, configs) => {
     const base = blank(pkg, source, dir ?? '');
     if (source === 'dev' && !isAbsolute(base.dir))
         return { ...base, problem: 'dev path not absolute' };
-    const manifest = dir === null ? null : readManifest(dir, deps);
+    const manifest = dir === null ? null : readManifest(dir);
     if (dir === null || manifest === null)
         return { ...base, missing: true };
     const info = manifestInfo(manifest);
     const entry = info.entry === null ? null : inside(dir, info.entry);
-    const problem = manifestProblem(pkg, info) ?? entryProblem(info, entry, deps);
-    const { version, id, commands, peers, optionalPeers } = info;
-    return { ...base, version, id, entry, commands, peers, optionalPeers, problem };
+    const { kind, version, id, commands, kitCommands, peers, optionalPeers } = info;
+    const slice = configs[id ?? ''] ?? {};
+    const { problem: badConfig, ...declared } = checkConfig(id ?? '', info.configuration, slice);
+    const unsafe = source === 'dev' ? unsafeDevPath(dir, process.getuid?.()) : null;
+    const problem = unsafe ?? manifestProblem(pkg, info) ?? entryProblem(info, entry) ?? badConfig;
+    const read = { kind, version, id, entry, commands, kitCommands, peers, optionalPeers };
+    return { ...base, ...read, ...declared, problem };
 };
 // Every claimant of a shared id is invalid; a dev copy of the same package never reaches here.
-const markDuplicates = (plugins) => plugins.map((p) => {
-    const others = plugins.filter((o) => o !== p && p.id !== null && o.id === p.id);
+const markDuplicates = (extensions) => extensions.map((p) => {
+    const others = extensions.filter((o) => o !== p && p.id !== null && o.id === p.id);
     if (others.length === 0 || p.problem)
         return p;
     return {
@@ -82,22 +94,29 @@ const markDuplicates = (plugins) => plugins.map((p) => {
         problem: `duplicate id "${p.id}" (also ${others.map((o) => o.pkg).join(', ')})`,
     };
 });
-// A peer counts as a plugin unless the tree holds it as a plain library without `agentage`.
-const pluginPeers = (p, known, modules, deps) => p.peers.filter((peer) => {
-    if (known.has(peer) || modules === null)
+// A peer counts as an extension unless the tree holds it as a plain library without `agentage`.
+const extensionPeers = (p, known, nodeModules) => p.peers.filter((peer) => {
+    if (known.has(peer) || nodeModules === null)
         return true;
-    const manifest = readManifest(join(modules, peer), deps);
+    const manifest = readManifest(join(nodeModules, peer));
     return manifest === null || isRecord(manifest['agentage']);
 });
-export const discover = (input, deps = defaultDeps) => {
-    const tree = currentTree(input.pluginsDir, deps);
-    const modules = tree.dir === null ? null : join(tree.dir, 'node_modules');
+export const discover = (input) => {
+    const tree = input.tree ? { dir: input.tree, warning: null } : currentTree(input.extensionsDir);
+    const nodeModules = tree.dir === null ? null : join(tree.dir, 'node_modules');
     const installed = input.names.filter((name) => !(name in input.dev));
     const found = markDuplicates([
-        ...installed.map((name) => inspect(name, 'tree', modules && join(modules, name), deps)),
-        ...Object.entries(input.dev).map(([name, path]) => inspect(name, 'dev', path, deps)),
-    ]);
+        ...installed.map((pkg) => ({
+            pkg,
+            source: 'tree',
+            dir: nodeModules && join(nodeModules, pkg),
+        })),
+        ...Object.entries(input.dev).map(([pkg, dir]) => ({ pkg, source: 'dev', dir })),
+    ].map((candidate) => inspect(candidate, input.config)));
     const known = new Set(found.map((p) => p.pkg));
-    const plugins = found.map((p) => ({ ...p, peers: pluginPeers(p, known, modules, deps) }));
-    return { plugins, warnings: tree.warning === null ? [] : [tree.warning] };
+    const extensions = found.map((p) => ({
+        ...p,
+        peers: extensionPeers(p, known, nodeModules),
+    }));
+    return { extensions, warnings: tree.warning === null ? [] : [tree.warning] };
 };

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

@@ -0,0 +1,4 @@
+import { type Disposable } from '../../extension.js';
+export declare const DISPOSE_TIMEOUT_MS = 5000;
+export declare const disposeAll: (id: string, subscriptions: Disposable[]) => Promise<void>;
+export declare const holdSignals: (dispose: () => Promise<void>) => (() => void);

package/dist/core/loader/dispose.js

@@ -0,0 +1,24 @@
+import {} from '../../extension.js';
+import { extensionLog } from './log.js';
+import { withTimeout } from './timeout.js';
+export const DISPOSE_TIMEOUT_MS = 5_000;
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+// Each subscription gets its 5 s at once; one that hangs is abandoned, and every result is logged.
+export const disposeAll = async (id, subscriptions) => {
+    const log = extensionLog(id);
+    await Promise.all(subscriptions.map(async (subscription, index) => {
+        const disposing = Promise.resolve().then(() => subscription.dispose());
+        const result = await withTimeout(disposing, DISPOSE_TIMEOUT_MS).then(() => 'done', messageOf);
+        log('dispose', { subscription: index, result });
+    }));
+};
+const SIGNALS = ['SIGINT', 'SIGTERM'];
+// The signal waits for disposal, then is raised again with no handler: the exit it would have had.
+export const holdSignals = (dispose) => {
+    const handlers = SIGNALS.map((signal) => {
+        const handler = () => void dispose().finally(() => process.kill(process.pid, signal));
+        process.once(signal, handler);
+        return { signal, handler };
+    });
+    return () => handlers.forEach(({ signal, handler }) => process.off(signal, handler));
+};

package/dist/core/loader/kit-manifest.d.ts

@@ -0,0 +1,9 @@
+export interface KitCommand {
+    name: string;
+    summary: string;
+}
+export declare const DEFAULT_CLI_ENTRY = "./dist/cli/index.js";
+export declare const isKitShaped: (agentage: Record<string, unknown>) => boolean;
+export declare const cliEntryOf: (parts: unknown) => string | null;
+export declare const kitCommandsOf: (value: unknown) => KitCommand[];
+export declare const kitShapeProblem: (agentage: Record<string, unknown>) => string | null;

package/dist/core/loader/kit-manifest.js

@@ -0,0 +1,52 @@
+import { isRecord } from '../../lib/fs/json-file.js';
+export const DEFAULT_CLI_ENTRY = './dist/cli/index.js';
+const COMMAND = /^[a-z0-9][a-z0-9-]*$/;
+// A manifest with agentage.parts is built on the extension kit and is never register-loaded.
+export const isKitShaped = (agentage) => agentage['parts'] !== undefined;
+// parts.cli is true or { entry }; without an entry it is the kit's build output.
+export const cliEntryOf = (parts) => {
+    const cli = isRecord(parts) ? parts['cli'] : undefined;
+    if (cli === true)
+        return DEFAULT_CLI_ENTRY;
+    if (!isRecord(cli))
+        return null;
+    return typeof cli['entry'] === 'string' ? cli['entry'] : DEFAULT_CLI_ENTRY;
+};
+const text = (value) => (typeof value === 'string' ? value : '');
+export const kitCommandsOf = (value) => (Array.isArray(value) ? value : [])
+    .filter(isRecord)
+    .map((command) => ({ name: text(command['name']), summary: text(command['summary']) }));
+const commandProblem = (value, seen) => {
+    const name = isRecord(value) ? value['name'] : undefined;
+    if (typeof name !== 'string' || !COMMAND.test(name))
+        return `agentage.commands: ${JSON.stringify(name ?? null)} must match [a-z0-9][a-z0-9-]*`;
+    if (seen.has(name))
+        return `agentage.commands: "${name}" is declared twice`;
+    seen.add(name);
+    return isRecord(value) && typeof value['summary'] === 'string'
+        ? null
+        : `agentage.commands: "${name}" has no summary`;
+};
+const commandsProblem = (commands) => {
+    const seen = new Set();
+    for (const command of commands) {
+        const problem = commandProblem(command, seen);
+        if (problem)
+            return problem;
+    }
+    return null;
+};
+// What reading the kit-shaped block as data can tell; the kit's own schema checks the rest.
+export const kitShapeProblem = (agentage) => {
+    const { parts, commands = [] } = agentage;
+    if (!isRecord(parts))
+        return 'agentage.parts must be an object';
+    if (!Array.isArray(commands))
+        return 'agentage.commands must be a list';
+    const problem = commandsProblem(commands);
+    if (problem)
+        return problem;
+    return commands.length > 0 && cliEntryOf(parts) === null
+        ? 'agentage.commands needs parts.cli'
+        : null;
+};

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

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+import { type DiscoveredExtension } from './discover.js';
+import { type LoadedExtension } from './register.js';
+export type KitCheck = (dir: string) => Promise<string | null>;
+export interface LoadOutcome {
+    state: 'ok' | 'failed' | 'blocked';
+    error: string | null;
+}
+export interface LoadSession {
+    outcomes: Map<string, LoadOutcome>;
+    loaded: Map<string, LoadedExtension>;
+    dispose: () => Promise<void>;
+}
+export declare const loadExtensions: (extensions: DiscoveredExtension[], template?: Command, check?: KitCheck) => Promise<LoadSession>;

package/dist/core/loader/load.js

@@ -0,0 +1,78 @@
+import { Command } from 'commander';
+import {} from './discover.js';
+import { disposeAll, holdSignals } from './dispose.js';
+import { loadOrder } from './order.js';
+import { registerExtension, registerTimeoutMs } from './register.js';
+import { writeRunState } from './state.js';
+import { withTimeout } from './timeout.js';
+import { createUse } from './use.js';
+const noKitCheck = async () => 'no kit check in this command';
+const blockedBy = (ext, outcomes) => {
+    const required = ext.peers.filter((peer) => !ext.optionalPeers.includes(peer));
+    const peer = required.find((name) => outcomes.get(name)?.state !== 'ok');
+    return peer === undefined ? null : `peer ${peer} is ${outcomes.get(peer)?.state ?? 'not loaded'}`;
+};
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+// The kit imports the entry, so its top-level code counts toward the same timeout as register.
+const checkKit = async (ext, check) => {
+    if (ext.entry === null)
+        return { state: 'ok', error: null };
+    try {
+        const problem = await withTimeout(check(ext.dir), registerTimeoutMs());
+        return problem === null ? { state: 'ok', error: null } : { state: 'failed', error: problem };
+    }
+    catch (err) {
+        return { state: 'failed', error: messageOf(err) };
+    }
+};
+const attempt = async (ext, session, template, check) => {
+    const blocked = blockedBy(ext, session.outcomes);
+    if (blocked)
+        return { state: 'blocked', error: blocked };
+    if (ext.kind === 'kit')
+        return checkKit(ext, check);
+    const result = await registerExtension(ext, createUse(ext, session.loaded), template);
+    if (!result.ok)
+        return { state: 'failed', error: result.error };
+    session.loaded.set(ext.id ?? '', result.loaded);
+    return { state: 'ok', error: null };
+};
+// What an extension prints while it loads goes to stderr, so stdout stays the command's own.
+const toStderr = async (fn) => {
+    const saved = { log: console.log, info: console.info, debug: console.debug };
+    console.log = console.info = console.debug = console.error;
+    try {
+        await fn();
+    }
+    finally {
+        Object.assign(console, saved);
+    }
+};
+const newSession = () => {
+    const loaded = new Map();
+    let disposed;
+    const disposeOnce = async () => {
+        disposed ??= Promise.all([...loaded.values()].map((l) => disposeAll(l.ext.id ?? '', l.subscriptions)));
+        await disposed;
+    };
+    const release = holdSignals(disposeOnce);
+    const dispose = () => {
+        release();
+        return disposeOnce();
+    };
+    return { outcomes: new Map(), loaded, dispose };
+};
+// Loads in peer order; one extension failing never stops the others, only what depends on it.
+export const loadExtensions = async (extensions, template = new Command('agentage'), check = noKitCheck) => {
+    // Not a sandbox, but the token never reaches extension code through the environment.
+    delete process.env['AGENTAGE_TOKEN'];
+    const session = newSession();
+    await toStderr(async () => {
+        for (const ext of loadOrder(extensions)) {
+            const outcome = await attempt(ext, session, template, check);
+            session.outcomes.set(ext.pkg, outcome);
+            writeRunState(ext.id ?? '', { ...outcome, version: ext.version });
+        }
+    });
+    return session;
+};

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

@@ -0,0 +1,3 @@
+import { type ExtensionLog } from '../../extension.js';
+export declare const LOG_CAP_BYTES: number;
+export declare const extensionLog: (id: string) => ExtensionLog;

package/dist/core/loader/log.js

@@ -0,0 +1,23 @@
+import { appendFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import {} from '../../extension.js';
+import { writeTextAtomic } from '../../lib/fs/json-file.js';
+import { logsDir } from '../paths.js';
+export const LOG_CAP_BYTES = 1024 * 1024;
+// Past the cap, keep the newest half from its first whole line, so the file stays small.
+const trim = (path) => {
+    if (statSync(path).size <= LOG_CAP_BYTES)
+        return;
+    const tail = readFileSync(path)
+        .subarray(-LOG_CAP_BYTES / 2)
+        .toString('utf-8');
+    writeTextAtomic(path, tail.slice(tail.indexOf('\n') + 1));
+};
+// The extension's own log; the core never reads it, its run state lives in state/<id>.json.
+export const extensionLog = (id) => (message, fields = {}) => {
+    const path = join(logsDir(), `${id}.log`);
+    mkdirSync(logsDir(), { recursive: true, mode: 0o700 });
+    const line = JSON.stringify({ at: new Date().toISOString(), message, ...fields });
+    appendFileSync(path, `${line}\n`, { mode: 0o600 });
+    trim(path);
+};

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

@@ -1,7 +1,9 @@
+import { type KitCommand } from './kit-manifest.js';
 export declare const ID_PATTERN: RegExp;
-export declare const DEFAULT_ENGINE = "^1";
-export declare const RESERVED_IDS: ReadonlySet<string>;
+export declare const CORE_COMMANDS: string[];
+export type ManifestKind = 'api' | 'kit';
 export interface ManifestInfo {
+    kind: ManifestKind;
     name: string | null;
     version: string | null;
     id: string | null;
@@ -10,7 +12,9 @@ export interface ManifestInfo {
     commands: string[];
     peers: string[];
     optionalPeers: string[];
+    configuration: Record<string, unknown>;
+    kitCommands: KitCommand[];
+    shape: string | null;
 }
-export declare const entryOf: (pkg: Record<string, unknown>) => string | null;
 export declare const manifestInfo: (pkg: Record<string, unknown>) => ManifestInfo;
-export declare const manifestProblem: (pkg: string, info: ManifestInfo, api?: string) => string | null;
+export declare const manifestProblem: (pkg: string, info: ManifestInfo, api?: string, kit?: string) => string | null;

package/dist/core/loader/manifest.js

@@ -1,11 +1,14 @@
 import { isRecord } from '../../lib/fs/json-file.js';
-import { PLUGIN_API_VERSION } from '../../plugin.js';
+import { EXTENSION_API_VERSION } from '../../extension.js';
+import { kitVersion } from '../kit-version.js';
 import { isRange, satisfies } from '../semver-range.js';
+import { cliEntryOf, isKitShaped, kitCommandsOf, kitShapeProblem, } from './kit-manifest.js';
 export const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
-export const DEFAULT_ENGINE = '^1';
-const CORE_COMMANDS = ['setup', 'status', 'update', 'add', 'remove', 'help'];
+const DEFAULT_ENGINE = '^1';
+export const CORE_COMMANDS = ['setup', 'status', 'update', 'extension', 'add', 'remove', 'help'];
 const DEVICE_NAMES = ['con', 'prn', 'aux', 'nul'].concat(...Array.from({ length: 10 }, (_, n) => [`com${n}`, `lpt${n}`]));
-export const RESERVED_IDS = new Set([...CORE_COMMANDS, ...DEVICE_NAMES]);
+const RESERVED_IDS = new Set([...CORE_COMMANDS, ...DEVICE_NAMES]);
+const SUBCOMMAND = /^[a-z0-9][a-z0-9-]*$/;
 const str = (value) => (typeof value === 'string' ? value : null);
 const record = (value) => (isRecord(value) ? value : {});
 const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
@@ -17,7 +20,7 @@ const fromConditions = (value, depth = 0) => {
     return fromConditions(value['import'], depth + 1) ?? fromConditions(value['default'], depth + 1);
 };
 // Node semantics: a present `exports` field is authoritative, `main` only applies without it.
-export const entryOf = (pkg) => {
+const entryOf = (pkg) => {
     const exp = pkg['exports'];
     if (exp === undefined)
         return str(pkg['main']);
@@ -29,17 +32,40 @@ export const entryOf = (pkg) => {
 const optionalPeersOf = (meta) => Object.entries(meta)
     .filter(([, m]) => isRecord(m) && m['optional'] === true)
     .map(([name]) => name);
+const kitInfo = (pkg, agentage) => {
+    const kitCommands = kitCommandsOf(agentage['commands']);
+    return {
+        kind: 'kit',
+        name: str(pkg['name']),
+        version: str(pkg['version']),
+        id: str(agentage['id']),
+        engine: str(record(pkg['engines'])['agentage']) ?? '',
+        entry: cliEntryOf(agentage['parts']),
+        commands: kitCommands.map((command) => command.name),
+        peers: [],
+        optionalPeers: [],
+        configuration: {},
+        kitCommands,
+        shape: kitShapeProblem(agentage),
+    };
+};
 export const manifestInfo = (pkg) => {
     const agentage = record(pkg['agentage']);
+    if (isKitShaped(agentage))
+        return kitInfo(pkg, agentage);
     return {
+        kind: 'api',
         name: str(pkg['name']),
         version: str(pkg['version']),
         id: str(agentage['id']),
         engine: str(record(pkg['engines'])['agentage']) ?? DEFAULT_ENGINE,
         entry: entryOf(pkg),
-        commands: strings(record(agentage['contributes'])['commands']),
+        commands: [...new Set(strings(record(agentage['contributes'])['commands']))],
         peers: Object.keys(record(pkg['peerDependencies'])),
         optionalPeers: optionalPeersOf(record(pkg['peerDependenciesMeta'])),
+        configuration: record(agentage['configuration']),
+        kitCommands: [],
+        shape: null,
     };
 };
 const idProblem = (id) => {
@@ -49,18 +75,34 @@ const idProblem = (id) => {
         return `agentage.id "${id}" must match [a-z][a-z0-9-]*`;
     return RESERVED_IDS.has(id) ? `agentage.id "${id}" is reserved` : null;
 };
-const engineProblem = (engine, api) => {
+// `against` names what the range must match: the extension API, or the kit.
+const engineProblem = (engine, version, against) => {
     if (!isRange(engine))
         return `engines.agentage "${engine}" is not a supported range`;
-    if (satisfies(api, engine))
+    if (satisfies(version, engine))
+        return null;
+    return `engines.agentage "${engine}" does not match ${against} ${version}`;
+};
+// A kit-shaped range is over the kit's version; it has no default.
+const kitProblem = (info, kit) => idProblem(info.id) ??
+    info.shape ??
+    (info.engine === '' ? 'engines.agentage is missing' : engineProblem(info.engine, kit, 'kit'));
+// Commands are named after the id, so no two extensions, nor the core, can claim one.
+const commandsProblem = (id, commands) => {
+    const ownSub = (name) => name.startsWith(`${id}:`) && SUBCOMMAND.test(name.slice(id.length + 1));
+    const bad = commands.find((name) => name !== id && !ownSub(name));
+    if (bad === undefined)
         return null;
-    return `engines.agentage "${engine}" does not match plugin API ${api}`;
+    return `agentage.contributes.commands: "${bad}" must be "${id}" or "${id}:<name>"`;
 };
 // Static checks only: the manifest is read as data and the entry is never imported.
-export const manifestProblem = (pkg, info, api = PLUGIN_API_VERSION) => {
+export const manifestProblem = (pkg, info, api = EXTENSION_API_VERSION, kit = kitVersion()) => {
     if (info.name !== pkg)
         return `package.json name ${JSON.stringify(info.name)} is not ${pkg}`;
+    if (info.kind === 'kit')
+        return kitProblem(info, kit);
     return (idProblem(info.id) ??
-        engineProblem(info.engine, api) ??
-        (info.entry === null ? 'no entry point (exports or main)' : null));
+        engineProblem(info.engine, api, 'extension API') ??
+        (info.entry === null ? 'no entry point (exports or main)' : null) ??
+        commandsProblem(info.id ?? '', info.commands));
 };

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

@@ -0,0 +1,2 @@
+import { type DiscoveredExtension } from './discover.js';
+export declare const loadOrder: (roots: DiscoveredExtension[], all?: DiscoveredExtension[]) => DiscoveredExtension[];

package/dist/core/loader/order.js

@@ -0,0 +1,20 @@
+import {} from './discover.js';
+// Peers first, from `roots` through `all`; cycles are invalid already, `seen` ends the walk anyway.
+export const loadOrder = (roots, all = roots) => {
+    const byPkg = new Map(all.map((ext) => [ext.pkg, ext]));
+    const seen = new Set();
+    const ordered = [];
+    const visit = (ext) => {
+        if (seen.has(ext.pkg))
+            return;
+        seen.add(ext.pkg);
+        for (const peer of [...ext.peers, ...ext.optionalPeers]) {
+            const found = byPkg.get(peer);
+            if (found)
+                visit(found);
+        }
+        ordered.push(ext);
+    };
+    roots.forEach(visit);
+    return ordered;
+};

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

@@ -0,0 +1,19 @@
+import { type Command } from 'commander';
+import { type Disposable, type ExtensionApi, type ExtensionUse } from '../../extension.js';
+import { type DiscoveredExtension } from './discover.js';
+export declare const DEFAULT_REGISTER_TIMEOUT_MS = 10000;
+export interface LoadedExtension {
+    ext: DiscoveredExtension;
+    program: Command;
+    subscriptions: Disposable[];
+    facade: ExtensionApi;
+}
+export type Attempt = {
+    ok: true;
+    loaded: LoadedExtension;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const registerTimeoutMs: () => number;
+export declare const registerExtension: (ext: DiscoveredExtension, use: ExtensionUse, template: Command) => Promise<Attempt>;

package/dist/core/loader/register.js

@@ -0,0 +1,39 @@
+import { pathToFileURL } from 'node:url';
+import {} from 'commander';
+import {} from '../../extension.js';
+import { isRecord } from '../../lib/fs/json-file.js';
+import { createContext } from './ctx.js';
+import {} from './discover.js';
+import { disposeAll } from './dispose.js';
+import { withTimeout } from './timeout.js';
+import { facadeOf } from './use.js';
+export const DEFAULT_REGISTER_TIMEOUT_MS = 10_000;
+// Tests shorten the wait; anything but a positive integer keeps the default.
+export const registerTimeoutMs = () => {
+    const raw = process.env['AGENTAGE_REGISTER_TIMEOUT_MS'] ?? '';
+    return /^[1-9]\d{0,8}$/.test(raw) ? Number(raw) : DEFAULT_REGISTER_TIMEOUT_MS;
+};
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+const isRegister = (value) => typeof value === 'function';
+const importAndRegister = async (entry, ctx) => {
+    const exported = await import(pathToFileURL(entry).href);
+    const register = isRecord(exported) ? exported['register'] : undefined;
+    if (!isRegister(register))
+        throw new Error('the entry exports no register function');
+    return register(ctx);
+};
+// The import counts toward the timeout too: a top-level await can hang like register can.
+export const registerExtension = async (ext, use, template) => {
+    const staged = createContext({ ext, use, template });
+    try {
+        const api = await withTimeout(importAndRegister(ext.entry ?? '', staged.ctx), registerTimeoutMs());
+        staged.close();
+        const { program, subscriptions } = staged;
+        return { ok: true, loaded: { ext, program, subscriptions, facade: facadeOf(api) } };
+    }
+    catch (err) {
+        staged.revoke();
+        await disposeAll(ext.id ?? '', staged.subscriptions);
+        return { ok: false, error: messageOf(err) };
+    }
+};

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

@@ -0,0 +1,18 @@
+import { type Plan } from '../installer/plan.js';
+import { type MachineFile } from '../profile/machine.js';
+import { type Effective } from '../profile/merge.js';
+import { type ProfileParse } from '../profile/schema.js';
+import { type DiscoveredExtension, type Discovery } from './discover.js';
+import { type StaticResult } from './states.js';
+export interface Scan {
+    machine: MachineFile;
+    parsed: ProfileParse | null;
+    eff: Effective;
+    found: Discovery;
+    states: Map<string, StaticResult>;
+    plan: Plan;
+    removed: DiscoveredExtension[];
+    drift: string[];
+}
+export declare const scan: (machine: MachineFile, tree?: string) => Scan;
+export declare const loadSet: (found: Scan) => DiscoveredExtension[];

package/dist/core/loader/scan.js

@@ -0,0 +1,34 @@
+import { currentDependencies, lockDrift, planChanges } from '../installer/plan.js';
+import {} from '../profile/machine.js';
+import { effective } from '../profile/merge.js';
+import { readProfile } from '../profile/profile.js';
+import {} from '../profile/schema.js';
+import { extensionsDir } from '../paths.js';
+import { discover } from './discover.js';
+import { staticStates } from './states.js';
+// A tree extension whose bytes the two locks disagree on is never trusted, so never imported.
+const withDrift = (found, drift) => ({
+    ...found,
+    extensions: found.extensions.map((p) => {
+        const key = `${p.pkg}@${p.version}`;
+        const drifted = p.source === 'tree' && p.problem === null && drift.includes(key);
+        return drifted ? { ...p, problem: `integrity drift: ${key}` } : p;
+    }),
+});
+// Everything known about this machine's extensions without running any of them; `tree` reads
+// that tree instead of the current one.
+export const scan = (machine, tree) => {
+    const parsed = readProfile();
+    const eff = effective(parsed?.ok ? parsed.profile : null, machine);
+    const dir = extensionsDir();
+    const drift = lockDrift(dir).integrity;
+    const input = { extensionsDir: dir, dev: eff.dev, config: eff.config, tree };
+    const found = withDrift(discover({ ...input, names: Object.keys(eff.install) }), drift);
+    const plan = planChanges(eff, currentDependencies(dir));
+    const gone = plan.extensions.filter((e) => e.verb === 'remove' && !(e.name in eff.dev));
+    const removed = discover({ ...input, dev: {}, names: gone.map((e) => e.name) }).extensions;
+    const states = staticStates(found.extensions, eff.off);
+    return { machine, parsed, eff, found, states, plan, removed, drift };
+};
+// What can load: a valid manifest, installed, not off here, and peers that can load too.
+export const loadSet = (found) => found.found.extensions.filter((ext) => found.states.get(ext.pkg)?.state === 'installed');