@agentage/cli 0.40.0 → 0.41.0

package/dist/commands/extension/up.js

@@ -0,0 +1,76 @@
+import { InvalidArgumentError } from 'commander';
+import { loadKitTool } from './kit-tool.js';
+const print = (line) => console.log(line);
+// Each step's line as the kit reports it, the ready line last.
+export const runExtensionUp = async (opts = {}, tool = loadKitTool) => {
+    const { up } = await tool();
+    await up({ ...opts, onLine: print });
+};
+export const runExtensionDown = async (opts = {}, tool = loadKitTool) => {
+    const { down } = await tool();
+    await down({ ...opts, onLine: print });
+};
+// The token alone on stdout, so a script can take it as it is.
+export const runExtensionToken = async (opts, tool = loadKitTool) => {
+    const { token } = await tool();
+    console.log(await token(opts));
+};
+// A usage error (exit 2) before the kit is asked: the issuer is an http: or https: URL.
+export const issuerUrl = (value) => {
+    let protocol;
+    try {
+        protocol = new URL(value).protocol;
+    }
+    catch {
+        throw new InvalidArgumentError('not a URL.');
+    }
+    if (protocol === 'http:' || protocol === 'https:')
+        return value;
+    throw new InvalidArgumentError('not an http: or https: URL.');
+};
+const UP_HELP = `
+Runs the extension package in --dir (default: the current folder) on this machine with Docker
+only, the way a deployment runs it: the part images built with the release recipe, the store
+with its migrations and seeds, a dev token issuer and a local gateway. Prints one line per step
+as the kit reports it, the last one once every part is healthy. Needs docker. Exits 1 when a
+step fails, with the kit's message.`;
+const DOWN_HELP = `
+Removes what agentage extension up started for the package in --dir: its containers, network
+and the store's volume; --keep-data keeps the volume. Exits 1 when that fails.`;
+const TOKEN_HELP = `
+Prints a token from the dev issuer agentage extension up started, alone on stdout, for calling
+/api/v1/ and /mcp by hand or from tests. Only up trusts it. Exits 1 when the issuer refuses.`;
+const DIR = '--dir <path>';
+const DIR_TEXT = 'the extension package folder (default: the current folder)';
+const addUp = (group, up) => {
+    group
+        .command('up')
+        .description('Run the extension package on this machine: images, store, issuer, gateway')
+        .option(DIR, DIR_TEXT)
+        .addHelpText('after', UP_HELP)
+        .action(up);
+};
+const addDown = (group, down) => {
+    group
+        .command('down')
+        .description('Remove what extension up started; --keep-data keeps the store')
+        .option(DIR, DIR_TEXT)
+        .option('--keep-data', "keep the store's volume")
+        .addHelpText('after', DOWN_HELP)
+        .action(down);
+};
+const addToken = (group, token) => {
+    group
+        .command('token')
+        .description('Print a token from the dev issuer extension up started')
+        .requiredOption('--scope <scope>', 'the scope the token carries, e.g. probe:write')
+        .option('--issuer <url>', 'the dev issuer (default: http://localhost:4281)', issuerUrl)
+        .addHelpText('after', TOKEN_HELP)
+        .action(token);
+};
+// up, down and token: thin commands over the kit's tool library, for extension authors.
+export const addKitTools = (group, actions) => {
+    addUp(group, actions.up);
+    addDown(group, actions.down);
+    addToken(group, actions.token);
+};

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

@@ -1,12 +1,20 @@
 export interface Published {
     version: string;
     engine: string;
+    kit?: boolean;
 }
 export interface Compatible {
     version: string | null;
     skipped: Published[];
 }
+export interface Gate {
+    api: string;
+    kit: string;
+}
+export declare const cliGate: () => Gate;
 export declare const fitsApi: (engine: string, api?: string) => boolean;
-export declare const needs: ({ version, engine }: Published) => string;
-export declare const newestCompatible: (published: Published[], api?: string) => Compatible;
+export declare const fits: (p: Omit<Published, "version">, gate?: Gate) => boolean;
+export declare const needsText: ({ engine, kit }: Omit<Published, "version">) => string;
+export declare const needs: (p: Published) => string;
+export declare const newestCompatible: (published: Published[], gate?: Gate) => Compatible;
 export declare const parsePublished: (stdout: string) => Published[] | null;

package/dist/core/installer/compat.js

@@ -1,23 +1,32 @@
 import { EXTENSION_API_VERSION } from '../../extension.js';
 import { isRecord } from '../../lib/fs/json-file.js';
+import { kitVersion } from '../kit-version.js';
 import { manifestInfo } from '../loader/manifest.js';
 import { isRange, newestFirst, satisfies } from '../semver-range.js';
+export const cliGate = () => ({ api: EXTENSION_API_VERSION, kit: kitVersion() });
 export const fitsApi = (engine, api = EXTENSION_API_VERSION) => isRange(engine) && satisfies(api, engine);
-export const needs = ({ version, engine }) => `${version}: needs extension API ${engine}`;
+// The gate picks the API by manifest shape.
+export const fits = (p, gate = cliGate()) => fitsApi(p.engine, p.kit ? gate.kit : gate.api);
+export const needsText = ({ engine, kit }) => `needs ${kit ? 'kit' : 'extension API'} ${engine}`;
+export const needs = (p) => `${p.version}: ${needsText(p)}`;
 // The resolver's rule: the newest version this CLI can load, instead of whatever `latest` is.
-export const newestCompatible = (published, api = EXTENSION_API_VERSION) => {
+export const newestCompatible = (published, gate = cliGate()) => {
     const sorted = [...published].sort((a, b) => newestFirst(a.version, b.version));
-    const at = sorted.findIndex((p) => fitsApi(p.engine, api));
+    const at = sorted.findIndex((p) => fits(p, gate));
     if (at === -1)
         return { version: null, skipped: sorted };
     return { version: sorted[at]?.version ?? null, skipped: sorted.slice(0, at) };
 };
+// npm view names a nested field by its path: `agentage.parts`.
 const publishedOf = (item) => {
     if (typeof item === 'string')
         return { version: item, engine: manifestInfo({}).engine };
     if (!isRecord(item) || typeof item['version'] !== 'string')
         return null;
-    return { version: item['version'], engine: manifestInfo(item).engine };
+    const parts = item['agentage.parts'];
+    const info = manifestInfo(parts === undefined ? item : { ...item, agentage: { parts } });
+    const kit = info.kind === 'kit' ? { kit: true } : {};
+    return { version: item['version'], engine: info.engine, ...kit };
 };
 // npm view prints one object per version, a lone object for one version, or bare versions.
 export const parsePublished = (stdout) => {

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

@@ -10,6 +10,7 @@ export interface Held {
     version: string;
     newer: string;
     engine: string;
+    kit: boolean;
 }
 export interface LatestResult {
     changes: VersionChange[];

package/dist/core/installer/latest.js

@@ -2,7 +2,7 @@ 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 { fits } from './compat.js';
 import { lockEntries, lockedVersion, parseLock, rootDependencies } from './compare-lock.js';
 import { planInstall, refuseDrift, runNpmInto, } from './installer.js';
 import {} from './npm.js';
@@ -26,14 +26,16 @@ const update = async (plan, npm, packages = []) => {
         throw err;
     }
 };
-const engineIn = (staging, name) => manifestInfo(readJson(join(staging, 'node_modules', name, 'package.json'), isRecord) ?? {})
-    .engine;
+const engineIn = (staging, name) => {
+    const info = manifestInfo(readJson(join(staging, 'node_modules', name, 'package.json'), isRecord) ?? {});
+    return { engine: info.engine, kit: info.kind === 'kit' };
+};
 // 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 range = engineIn(built.staging, name);
+    return fits(range) ? [] : [{ name, version: from, newer: to, ...range }];
 });
 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.

package/dist/core/installer/npm.js

@@ -7,7 +7,7 @@ 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'],
+    view: ['name', 'version', 'engines', 'agentage.parts', '--json'],
 };
 // npm reads its env config case-insensitively, so either spelling may carry these paths.
 const npmConfig = (env, key) => {

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

@@ -9,6 +9,7 @@ export type Resolved = {
     kind: 'dev';
     name: string;
     path: string;
+    kit: boolean;
 };
 export interface Found {
     name: string;

package/dist/core/installer/resolve.js

@@ -1,10 +1,10 @@
 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 { cliGate, needs, newestCompatible, parsePublished } from './compat.js';
+import { isKitShaped } from '../loader/kit-manifest.js';
 import { lastLines } from './installer.js';
 import {} from './npm.js';
 // Every release: a range, not `*`, which npm view reads as the `latest` tag alone.
@@ -41,7 +41,7 @@ const devExtension = (input) => {
     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 };
+    return { kind: 'dev', name, path, kit: isKitShaped(agentage) };
 };
 // The first candidate the registry has; a missing one moves on to the next.
 const firstFound = async (specs, input, look) => {
@@ -60,11 +60,12 @@ const fromUrl = async (url, look) => {
     return { kind: 'package', name, spec: url, skipped: [] };
 };
 const pinned = (input, name, published) => {
-    const { version, skipped } = newestCompatible(published);
+    const gate = cliGate();
+    const { version, skipped } = newestCompatible(published, gate);
     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}`;
+    const api = skipped[0]?.kit ? `kit ${gate.kit}` : `extension API ${gate.api}`;
     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.

package/dist/core/kit-version.d.ts

@@ -0,0 +1 @@
+export declare const kitVersion: () => string;

package/dist/core/kit-version.js

@@ -0,0 +1,15 @@
+import { createRequire } from 'node:module';
+import { isRecord, readJson } from '../lib/fs/json-file.js';
+let cached;
+const read = () => {
+    try {
+        const path = createRequire(import.meta.url).resolve('@agentage/extension/package.json');
+        const version = readJson(path, isRecord)?.['version'];
+        return typeof version === 'string' ? version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+// The kit's own version (KIT_VERSION), read as data so startup never loads the kit's code.
+export const kitVersion = () => (cached ??= read());

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

@@ -1,13 +1,17 @@
 import { type ConfigMap } from '../profile/schema.js';
+import { type KitCommand } from './kit-manifest.js';
+import { type ManifestKind } from './manifest.js';
 export type ExtensionSource = 'tree' | 'dev';
 export interface DiscoveredExtension {
     pkg: string;
+    kind: ManifestKind;
     source: ExtensionSource;
     dir: string;
     version: string | null;
     id: string | null;
     entry: string | null;
     commands: string[];
+    kitCommands: KitCommand[];
     peers: string[];
     optionalPeers: string[];
     config: Record<string, unknown>;

package/dist/core/loader/discover.js

@@ -4,6 +4,7 @@ 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 {
@@ -50,12 +51,14 @@ const entryProblem = (info, path) => {
 };
 const blank = (pkg, source, dir) => ({
     pkg,
+    kind: 'api',
     source,
     dir,
     version: null,
     id: null,
     entry: null,
     commands: [],
+    kitCommands: [],
     peers: [],
     optionalPeers: [],
     config: {},
@@ -73,12 +76,13 @@ const inspect = ({ pkg, source, dir }, configs) => {
         return { ...base, missing: true };
     const info = manifestInfo(manifest);
     const entry = info.entry === null ? null : inside(dir, info.entry);
-    const { version, id, commands, peers, optionalPeers } = info;
+    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;
-    return { ...base, version, id, entry, commands, peers, optionalPeers, ...declared, problem };
+    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 = (extensions) => extensions.map((p) => {

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

@@ -1,6 +1,7 @@
 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;
@@ -10,4 +11,4 @@ export interface LoadSession {
     loaded: Map<string, LoadedExtension>;
     dispose: () => Promise<void>;
 }
-export declare const loadExtensions: (extensions: DiscoveredExtension[], template?: Command) => Promise<LoadSession>;
+export declare const loadExtensions: (extensions: DiscoveredExtension[], template?: Command, check?: KitCheck) => Promise<LoadSession>;

package/dist/core/loader/load.js

@@ -2,18 +2,35 @@ import { Command } from 'commander';
 import {} from './discover.js';
 import { disposeAll, holdSignals } from './dispose.js';
 import { loadOrder } from './order.js';
-import { registerExtension } from './register.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 attempt = async (ext, session, template) => {
+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 };
@@ -46,13 +63,13 @@ const newSession = () => {
     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')) => {
+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);
+            const outcome = await attempt(ext, session, template, check);
             session.outcomes.set(ext.pkg, outcome);
             writeRunState(ext.id ?? '', { ...outcome, version: ext.version });
         }

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

@@ -1,5 +1,9 @@
+import { type KitCommand } from './kit-manifest.js';
 export declare const ID_PATTERN: RegExp;
+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;
@@ -9,6 +13,8 @@ export interface ManifestInfo {
     peers: string[];
     optionalPeers: string[];
     configuration: Record<string, unknown>;
+    kitCommands: KitCommand[];
+    shape: 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,9 +1,11 @@
 import { isRecord } from '../../lib/fs/json-file.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-]*$/;
 const DEFAULT_ENGINE = '^1';
-const CORE_COMMANDS = ['setup', 'status', 'update', 'extension', 'add', 'remove', 'help'];
+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}`]));
 const RESERVED_IDS = new Set([...CORE_COMMANDS, ...DEVICE_NAMES]);
 const SUBCOMMAND = /^[a-z0-9][a-z0-9-]*$/;
@@ -30,9 +32,29 @@ 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']),
@@ -42,6 +64,8 @@ export const manifestInfo = (pkg) => {
         peers: Object.keys(record(pkg['peerDependencies'])),
         optionalPeers: optionalPeersOf(record(pkg['peerDependenciesMeta'])),
         configuration: record(agentage['configuration']),
+        kitCommands: [],
+        shape: null,
     };
 };
 const idProblem = (id) => {
@@ -51,13 +75,18 @@ 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 extension API ${api}`;
+    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));
@@ -67,11 +96,13 @@ const commandsProblem = (id, commands) => {
     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 = EXTENSION_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) ??
+        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/verbs.d.ts

@@ -0,0 +1,15 @@
+import { type DiscoveredExtension } from './discover.js';
+export interface Namespaced {
+    pkg: string;
+    id: string;
+    name: string;
+    why: string;
+}
+export interface Verbs {
+    top: Map<string, string>;
+    namespaced: Namespaced[];
+}
+export declare const readHeld: () => Map<string, string>;
+export declare const writeHeld: (top: Map<string, string>) => void;
+export declare const claimVerbs: (extensions: DiscoveredExtension[], held: Map<string, string>) => Verbs;
+export declare const commandNames: (ext: DiscoveredExtension, verbs: Verbs) => string[];

package/dist/core/loader/verbs.js

@@ -0,0 +1,57 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { isRecord, readJson, writeJsonAtomic } from '../../lib/fs/json-file.js';
+import { commandsPath } from '../paths.js';
+import {} from './discover.js';
+import { CORE_COMMANDS } from './manifest.js';
+const isHeld = (value) => isRecord(value) && Object.values(value).every((pkg) => typeof pkg === 'string');
+// Who held each top-level verb after the last install; absent or unreadable: nobody.
+export const readHeld = () => new Map(Object.entries(readJson(commandsPath(), isHeld) ?? {}));
+// Written only when it changed, so a machine without kit commands never gets the file.
+export const writeHeld = (top) => {
+    const next = Object.fromEntries(top);
+    const current = Object.fromEntries(readHeld());
+    if (isDeepStrictEqual(next, current))
+        return;
+    mkdirSync(dirname(commandsPath()), { recursive: true, mode: 0o700 });
+    writeJsonAtomic(commandsPath(), next);
+};
+// Core commands and every extension id are namespaces; 1.0 commands are named after their id.
+const takenNames = (extensions) => {
+    const taken = new Map(CORE_COMMANDS.map((name) => [name, 'is a core command']));
+    for (const ext of extensions.filter((e) => e.id !== null)) {
+        const why = `is taken by extension ${ext.id}`;
+        taken.set(ext.id ?? '', why);
+        if (ext.kind === 'api')
+            for (const name of ext.commands)
+                taken.set(name, why);
+    }
+    return taken;
+};
+const whyNot = (name, taken, top, ids) => taken.get(name) ?? `is taken by extension ${ids.get(top.get(name) ?? '') ?? '?'}`;
+const namespacedOf = (kit, taken, top) => {
+    const ids = new Map(kit.map((ext) => [ext.pkg, ext.id ?? '']));
+    return kit.flatMap((ext) => ext.commands
+        .filter((name) => top.get(name) !== ext.pkg)
+        .map((name) => ({ pkg: ext.pkg, id: ext.id ?? '', name, why: whyNot(name, taken, top, ids) })));
+};
+// An earlier holder keeps its verb; a later claimant runs only as `agentage {id} {name}`.
+export const claimVerbs = (extensions, held) => {
+    const kit = extensions.filter((ext) => ext.kind === 'kit' && ext.id !== null);
+    const taken = takenNames(extensions);
+    const top = new Map();
+    const claim = (name, pkg) => {
+        if (!taken.has(name) && !top.has(name))
+            top.set(name, pkg);
+    };
+    for (const [name, pkg] of held)
+        if (kit.some((ext) => ext.pkg === pkg && ext.commands.includes(name)))
+            claim(name, pkg);
+    for (const ext of kit)
+        for (const name of ext.commands)
+            claim(name, ext.pkg);
+    return { top, namespaced: namespacedOf(kit, taken, top) };
+};
+// What `extension list` shows: a namespaced command as `{id} {name}`, any other as it is.
+export const commandNames = (ext, verbs) => ext.commands.map((name) => verbs.namespaced.some((n) => n.pkg === ext.pkg && n.name === name) ? `${ext.id} ${name}` : name);

package/dist/core/paths.d.ts

@@ -1,6 +1,7 @@
 export declare const profilePath: () => string;
 export declare const machinePath: () => string;
 export declare const stateDir: () => string;
+export declare const commandsPath: () => string;
 export declare const extensionsDir: () => string;
 export declare const secretsPath: () => string;
 export declare const dataDir: (id: string) => string;

package/dist/core/paths.js

@@ -3,6 +3,7 @@ import { getConfigDir } from '../lib/fs/config.js';
 export const profilePath = () => join(getConfigDir(), 'profile.json');
 export const machinePath = () => join(getConfigDir(), 'machine.json');
 export const stateDir = () => join(getConfigDir(), 'state');
+export const commandsPath = () => join(getConfigDir(), 'commands.json');
 export const extensionsDir = () => process.env['AGENTAGE_EXTENSIONS_DIR'] || join(getConfigDir(), 'extensions');
 export const secretsPath = () => join(getConfigDir(), 'secrets.json');
 export const dataDir = (id) => join(getConfigDir(), 'data', id);