@agentage/cli 0.40.0 → 0.41.0

package/README.md

@@ -64,8 +64,14 @@ For extensions (see below):
 | `agentage extension install <name> [--off]`  | Add an extension to the profile, install and load it             |
 | `agentage extension remove <name> [--purge]` | Take it out of the profile and reinstall the rest                |
 | `agentage extension list`                    | One row per extension: state, version, commands, last run        |
-| `agentage extension check`                   | Load every extension once and refresh the states                 |
+| `agentage extension doctor`                  | Load every extension once and refresh the states                 |
+| `agentage extension build [--push]`          | Build the part images of an extension package; push with digests |
+| `agentage extension up` / `down`             | Run an extension package on this machine with Docker, then stop  |
+| `agentage extension token --scope <scope>`   | Print a token from the dev issuer `extension up` started         |
 | `agentage <command>`                         | Run a command an installed extension contributes                 |
+| `agentage <id> <command>`                    | The same for an extension built on the kit; always works         |
+
+`agentage extension check` is the old name of `doctor`, kept for 90 days.
 
 Flags, exit codes and token auth are in [`docs/reference.md`](docs/reference.md).
 
@@ -95,11 +101,19 @@ agentage setup --check                             # exit 1 when this machine di
 agentage setup --latest                            # newest versions the ranges allow, diff printed
 agentage extension install @agentage/example       # add one extension, install and load it
 agentage extension install ./my-extension          # a local folder, for development
+agentage extension install .                       # link the working copy you are in
 agentage extension remove @agentage/example        # take it out again
 agentage extension list                            # state per extension, with what setup would change
 agentage hello                                     # a command the hello extension contributes
+agentage ping                                      # a command of an extension built on the kit
+agentage probe ping                                # the same, by its extension id
 ```
 
+An extension built on the extension kit lists its commands in its manifest; each runs as
+`agentage <command>` and always as `agentage <id> <command>`. When the name is a core command,
+an extension id or a command an earlier install took, only `agentage <id> <command>` runs it, and
+the install says so.
+
 The plan is what `setup` would change, one line per extension (`+ add`, `~ update`, `- remove`,
 `o off`) and a summary such as `plan: 1 to add, 0 to update, 0 to remove, 0 off, 2 unchanged`.
 `setup --dry-run` prints it, `setup --check` exits 1 when anything would change, `extension list`
@@ -126,13 +140,14 @@ Extensions run in the CLI process with your privileges, so install only extensio
 npm runs with `--ignore-scripts`, and the account token is removed from the environment before
 any extension code loads. Everything lives in the config directory:
 
-| Path                       | What                                                           |
-| -------------------------- | -------------------------------------------------------------- |
-| `~/.agentage/profile.json` | the profile: what this account wants                           |
-| `~/.agentage/machine.json` | this machine's id, name, development extensions and account    |
-| `~/.agentage/extensions/`  | installed extensions; `extensions/current` names the live tree |
-| `~/.agentage/state/`       | the last run of each extension                                 |
-| `~/.agentage/data/<id>/`   | what each extension keeps                                      |
+| Path                        | What                                                           |
+| --------------------------- | -------------------------------------------------------------- |
+| `~/.agentage/profile.json`  | the profile: what this account wants                           |
+| `~/.agentage/machine.json`  | this machine's id, name, development extensions and account    |
+| `~/.agentage/extensions/`   | installed extensions; `extensions/current` names the live tree |
+| `~/.agentage/state/`        | the last run of each extension                                 |
+| `~/.agentage/commands.json` | which extension holds each top-level command                   |
+| `~/.agentage/data/<id>/`    | what each extension keeps                                      |
 
 Every state an extension can be in, and every flag, is in [`docs/reference.md`](docs/reference.md).
 To write an extension, start with [`docs/extensions.md`](docs/extensions.md).

package/dist/commands/extension/build.d.ts

@@ -0,0 +1,10 @@
+import { type Command } from 'commander';
+import { type BuildOptions, type BuildResult } from '@agentage/extension/tool';
+export type ExtensionBuildOptions = Pick<BuildOptions, 'push' | 'dir' | 'registry'>;
+export interface BuildTool {
+    build: (options: BuildOptions) => Promise<BuildResult>;
+    buildLines: (result: BuildResult) => string[];
+}
+export declare const loadBuildTool: () => Promise<BuildTool>;
+export declare const runExtensionBuild: (opts?: ExtensionBuildOptions, tool?: () => Promise<BuildTool>) => Promise<void>;
+export declare const addBuild: (group: Command, build: (opts: ExtensionBuildOptions) => Promise<void>) => void;

package/dist/commands/extension/build.js

@@ -0,0 +1,27 @@
+import {} from 'commander';
+import {} from '@agentage/extension/tool';
+// Imported on use, so every other command starts without loading the kit.
+export const loadBuildTool = () => import('@agentage/extension/tool');
+// One line per image on stdout (part, tag, digest when pushed), then the record path.
+export const runExtensionBuild = async (opts = {}, tool = loadBuildTool) => {
+    const { build, buildLines } = await tool();
+    for (const line of buildLines(await build(opts)))
+        console.log(line);
+};
+const BUILD_HELP = `
+Builds one image per server part of the extension package in --dir (default: the current
+folder): the manifest is checked, the package's own build script runs, then the kit recipe makes
+each image, tagged ghcr.io/agentage/<id>-<part>:<version> with the commit and build time as
+labels. --push pushes them (run docker login first) and writes dist/agentage-extension.json, the
+build record with every image by digest. Needs docker. Exits 1 when the manifest is invalid or a
+build or push fails.`;
+export const addBuild = (group, build) => {
+    group
+        .command('build')
+        .description('Build the part images of an extension package; --push pushes them')
+        .option('--push', 'push the images and write the build record with their digests')
+        .option('--dir <path>', 'the extension package folder (default: the current folder)')
+        .option('--registry <host/owner>', 'image registry and owner (default: ghcr.io/agentage)')
+        .addHelpText('after', BUILD_HELP)
+        .action(build);
+};

package/dist/commands/extension/delegate.d.ts

@@ -1,4 +1,6 @@
 import { type Command } from 'commander';
-type Wrap = (fn: () => Promise<void>) => (opts: unknown) => Promise<void>;
-export declare const registerDelegates: (program: Command, argv: string[], wrap: Wrap) => void;
+import { type LoadKitTool } from './kit-tool.js';
+type Run = (opts: unknown) => Promise<void>;
+type Wrap = (fn: () => Promise<void>) => Run;
+export declare const registerDelegates: (program: Command, argv: string[], wrap: Wrap, tool?: LoadKitTool) => void;
 export {};

package/dist/commands/extension/delegate.js

@@ -3,10 +3,14 @@ import {} from '../../core/loader/discover.js';
 import { loadExtensions } from '../../core/loader/load.js';
 import { loadOrder } from '../../core/loader/order.js';
 import { loadSet, scan } from '../../core/loader/scan.js';
+import { claimVerbs, commandNames, readHeld } from '../../core/loader/verbs.js';
 import { NO_MACHINE, readMachine } from '../../core/profile/machine.js';
+import { registerKit } from './kit-commands.js';
+import { kitCheck, loadKitTool } from './kit-tool.js';
 // Loads the command's extension and its peers only, then hands it the whole command line.
 const runDelegated = async (ext, name, extensions, program, argv) => {
-    const session = await loadExtensions(loadOrder([ext], extensions), program);
+    const order = loadOrder([ext], extensions);
+    const session = await loadExtensions(order, program, kitCheck());
     try {
         const loaded = session.loaded.get(ext.id ?? '');
         const run = session.outcomes.get(ext.pkg);
@@ -21,25 +25,33 @@ const runDelegated = async (ext, name, extensions, program, argv) => {
     }
 };
 // Usage, exit 2: the core commands, then one line per extension with what it contributes.
-const unknownCommand = (program, core, extensions) => (operands) => {
+const unknownCommand = (program, core, extensions, verbs) => (operands) => {
     const lines = [`error: unknown command '${operands[0]}'`, `core: ${core.join(', ')}`];
     for (const ext of extensions.filter((e) => e.commands.length > 0))
-        lines.push(`${ext.id}: ${ext.commands.join(', ')}`);
+        lines.push(`${ext.id}: ${commandNames(ext, verbs).join(', ')}`);
     program.error(lines.join('\n'), { code: 'commander.unknownCommand', exitCode: 2 });
 };
+const registerApi = (program, ext, run) => {
+    for (const name of ext.commands)
+        program
+            .command(name)
+            .description(`from the ${ext.id} extension`)
+            .helpGroup(`${ext.id}:`)
+            .helpOption(false)
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .action(run(name));
+};
 // Manifests only, never code: each stub hands the command line, --help included, to the extension.
-export const registerDelegates = (program, argv, wrap) => {
+export const registerDelegates = (program, argv, wrap, tool = loadKitTool) => {
     const core = program.commands.map((command) => command.name());
     const extensions = loadSet(scan(readMachine() ?? NO_MACHINE));
-    for (const ext of extensions)
-        for (const name of ext.commands)
-            program
-                .command(name)
-                .description(`from the ${ext.id} extension`)
-                .helpGroup(`${ext.id}:`)
-                .helpOption(false)
-                .allowUnknownOption()
-                .allowExcessArguments()
-                .action(wrap(() => runDelegated(ext, name, extensions, program, argv)));
-    program.on('command:*', unknownCommand(program, core, extensions));
+    const verbs = claimVerbs(extensions, readHeld());
+    for (const ext of extensions) {
+        if (ext.kind === 'kit')
+            registerKit(program, ext, verbs, { argv, wrap, tool });
+        else
+            registerApi(program, ext, (name) => wrap(() => runDelegated(ext, name, extensions, program, argv)));
+    }
+    program.on('command:*', unknownCommand(program, core, extensions, verbs));
 };

package/dist/commands/extension/doctor.d.ts

@@ -0,0 +1,13 @@
+import { type DiscoveredExtension } from '../../core/loader/discover.js';
+import { type LoadKitTool } from './kit-tool.js';
+import { type ExtensionRow, type ExtensionsGather } from './rows.js';
+export interface ExtensionDoctorOptions {
+    json?: boolean;
+}
+type BeforeLoad = (extensions: DiscoveredExtension[]) => Promise<void>;
+export declare const loadAndGather: (beforeLoad?: BeforeLoad, tree?: string, tool?: LoadKitTool) => Promise<ExtensionsGather>;
+export declare const failedError: (rows: ExtensionRow[]) => Error | null;
+export declare const runExtensionDoctor: (opts?: ExtensionDoctorOptions, tool?: LoadKitTool) => Promise<void>;
+export declare const CHECK_DEPRECATED: string;
+export declare const deprecatedCheck: (doctor: (opts: ExtensionDoctorOptions) => Promise<void>, writeErr: (text: string) => void) => (opts: ExtensionDoctorOptions) => Promise<void>;
+export {};

package/dist/commands/extension/{check.js → doctor.js}

@@ -1,17 +1,19 @@
+import chalk from 'chalk';
 import { driftLines } from '../../core/installer/plan.js';
 import {} from '../../core/loader/discover.js';
 import { loadExtensions } from '../../core/loader/load.js';
 import { loadSet, scan } from '../../core/loader/scan.js';
 import { loadMachine } from '../../core/profile/machine.js';
+import { kitCheck } from './kit-tool.js';
 import { printReport } from './list.js';
 import { gatherFrom, invalidProfileError, } from './rows.js';
 // Loads what can load, once: state files rewritten, rows carrying this run's ok and failed.
-// `tree` loads that tree instead of the current one.
-export const loadAndGather = async (beforeLoad = async () => undefined, tree) => {
+// `tree` loads that tree instead of the current one; kit-shaped ones are checked by the kit.
+export const loadAndGather = async (beforeLoad = async () => undefined, tree, tool) => {
     const found = scan(await loadMachine(), tree);
     const extensions = loadSet(found);
     await beforeLoad(extensions);
-    const session = await loadExtensions(extensions);
+    const session = await loadExtensions(extensions, undefined, kitCheck(tool));
     await session.dispose();
     return gatherFrom(found, session.outcomes);
 };
@@ -25,11 +27,18 @@ export const failedError = (rows) => {
 // Integrity drift: the extensions it names were not loaded, and setup refuses to build on it.
 const driftError = (drift) => drift.length === 0 ? null : new Error(driftLines(drift).join('\n'));
 // The rows always print; an invalid profile.json, integrity drift or a failed load fails the step.
-export const runExtensionCheck = async (opts = {}) => {
-    const gathered = await loadAndGather();
+export const runExtensionDoctor = async (opts = {}, tool) => {
+    const gathered = await loadAndGather(undefined, undefined, tool);
     printReport(gathered, opts.json);
     const { profile, extensions } = gathered.status;
     const failure = invalidProfileError(profile) ?? driftError(gathered.drift) ?? failedError(extensions);
     if (failure)
         throw failure;
 };
+export const CHECK_DEPRECATED = 'agentage extension check is now agentage extension doctor; ' +
+    'in 90 days check becomes the conformance check';
+// The old name for 90 days: one line on stderr, then doctor, so --json stdout stays the report.
+export const deprecatedCheck = (doctor, writeErr) => async (opts) => {
+    writeErr(`${chalk.yellow(`warning: ${CHECK_DEPRECATED}`)}\n`);
+    await doctor(opts);
+};

package/dist/commands/extension/install-load.js

@@ -2,7 +2,8 @@ import { install } from '../../core/installer/installer.js';
 import {} from '../../core/installer/npm.js';
 import {} from '../../core/loader/discover.js';
 import { missingSecrets } from '../../core/loader/secrets.js';
-import { failedError, loadAndGather } from './check.js';
+import { writeHeld } from '../../core/loader/verbs.js';
+import { failedError, loadAndGather } from './doctor.js';
 import { printWarnings, rowLines } from './row-lines.js';
 import { gatherExtensions } from './rows.js';
 import { askSecrets } from './secrets-prompt.js';
@@ -14,6 +15,12 @@ const installLine = (result) => {
 };
 // Asks for, or lists, the secrets the extensions about to load declare and this machine lacks.
 export const listSecrets = (extensions) => askSecrets(missingSecrets(extensions));
+// Who holds each top-level verb is kept for the next install; one line per namespaced command.
+const settleVerbs = ({ verbs }) => {
+    writeHeld(verbs.top);
+    for (const { id, name, why } of verbs.namespaced)
+        console.log(line('namespaced', `agentage ${id} ${name} (agentage ${name} ${why})`));
+};
 // Rows print either way, only a good install loads; `installed` runs before anything loads.
 export const installAndLoad = async (set, npm, installed = async () => undefined) => {
     const outcome = await install(set, npm).then((result) => ({ result, error: null }), (error) => ({ result: null, error }));
@@ -24,6 +31,8 @@ export const installAndLoad = async (set, npm, installed = async () => undefined
     const gathered = outcome.result ? await loadAndGather(listSecrets) : await gatherExtensions();
     for (const text of rowLines(gathered.status.extensions))
         console.log(text);
+    if (outcome.result)
+        settleVerbs(gathered);
     printWarnings(gathered.warnings);
     if (outcome.error)
         throw outcome.error;

package/dist/commands/extension/install.js

@@ -21,7 +21,10 @@ const addDev = async (target, off, deps) => {
     if (off)
         throw new Error(`--off does not apply to ${target.path}: a dev extension always loads`);
     await setDev(target.name, target.path);
-    console.log(line('dev', `${target.name} ${target.path}`));
+    if (target.kit)
+        console.log(line('linked', `${target.name} (working copy)`));
+    else
+        console.log(line('dev', `${target.name} ${target.path}`));
     await installAndLoad(editableProfile(), deps.npm);
 };
 // Never signs in: the name is looked up in the registries the local profile routes.

package/dist/commands/extension/kit-commands.d.ts

@@ -0,0 +1,13 @@
+import { type Command } from 'commander';
+import { type DiscoveredExtension } from '../../core/loader/discover.js';
+import { type Verbs } from '../../core/loader/verbs.js';
+import { type LoadKitTool } from './kit-tool.js';
+export declare const KIT_EXIT = "agentage.kitExit";
+type Run = (opts: unknown) => Promise<void>;
+export interface KitRegistration {
+    argv: string[];
+    wrap: (fn: () => Promise<void>) => Run;
+    tool: LoadKitTool;
+}
+export declare const registerKit: (program: Command, ext: DiscoveredExtension, verbs: Verbs, { argv, wrap, tool }: KitRegistration) => void;
+export {};

package/dist/commands/extension/kit-commands.js

@@ -0,0 +1,42 @@
+import { CommanderError } from 'commander';
+import {} from '../../core/loader/discover.js';
+import {} from '../../core/loader/verbs.js';
+import {} from './kit-tool.js';
+import { helpOrUnknown } from './list.js';
+// A kit command's own exit code: the program returns it as the CLI's.
+export const KIT_EXIT = 'agentage.kitExit';
+// The kit parses args and owns --json and --help; the token never reaches extension code.
+const runKit = async (tool, dir, command, argv) => {
+    const { runCommand } = await tool();
+    delete process.env['AGENTAGE_TOKEN'];
+    const code = await runCommand({ dir, command, argv });
+    if (code !== 0)
+        throw new CommanderError(code, KIT_EXIT, `${command} exited ${code}`);
+};
+// A stub per command: help from the manifest, everything after its own words to the kit.
+const stub = (parent, name, summary, run) => parent
+    .command(name)
+    .description(summary)
+    .helpOption(false)
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(run);
+// `agentage {id}` alone prints its commands from the manifest; an unknown one is usage.
+const groupOf = (program, id) => program
+    .command(id)
+    .description(`the commands of the ${id} extension`)
+    .helpGroup(`${id}:`)
+    .helpCommand(false)
+    .allowExcessArguments()
+    .action(helpOrUnknown);
+// `agentage {id} {command}` always; `agentage {command}` where the verb is its own.
+export const registerKit = (program, ext, verbs, { argv, wrap, tool }) => {
+    const id = ext.id ?? '';
+    const group = groupOf(program, id);
+    const run = (name, words) => wrap(() => runKit(tool, ext.dir, name, argv.slice(2 + words)));
+    for (const { name, summary } of ext.kitCommands) {
+        stub(group, name, summary, run(name, 2));
+        if (verbs.top.get(name) === ext.pkg)
+            stub(program, name, summary, run(name, 1)).helpGroup(`${id}:`);
+    }
+};

package/dist/commands/extension/kit-tool.d.ts

@@ -0,0 +1,31 @@
+import { type KitCheck } from '../../core/loader/load.js';
+export interface KitRun {
+    dir: string;
+    command: string;
+    argv: string[];
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+}
+export interface KitUp {
+    dir?: string;
+    onLine?: (line: string) => void;
+}
+export interface KitDown extends KitUp {
+    keepData?: boolean;
+}
+export interface KitTool {
+    runCommand: (options: KitRun) => Promise<number>;
+    checkCli: (dir: string) => Promise<string | null>;
+    up: (options: KitUp) => Promise<{
+        parts: number;
+        seconds: number;
+    }>;
+    down: (options: KitDown) => Promise<unknown>;
+    token: (options: {
+        scope: string;
+        issuer?: string;
+    }) => Promise<string>;
+}
+export type LoadKitTool = () => Promise<KitTool>;
+export declare const loadKitTool: LoadKitTool;
+export declare const kitCheck: (tool?: LoadKitTool) => KitCheck;

package/dist/commands/extension/kit-tool.js

@@ -0,0 +1,5 @@
+import {} from '../../core/loader/load.js';
+// Imported on use, so every other command starts without loading the kit.
+export const loadKitTool = () => import('@agentage/extension/tool');
+// doctor and every load check a kit-shaped extension's command entry through the kit.
+export const kitCheck = (tool = loadKitTool) => async (dir) => (await tool()).checkCli(dir);

package/dist/commands/extension/latest.js

@@ -1,9 +1,10 @@
+import { needsText } from '../../core/installer/compat.js';
 import {} from '../../core/installer/installer.js';
 import { updateLatest, } from '../../core/installer/latest.js';
 import {} from '../../core/installer/npm.js';
 import { editableProfile, mutateProfile } from '../../core/profile/profile.js';
 import { pushBody } from '../../core/profile/push.js';
-import { loadAndGather } from './check.js';
+import { loadAndGather } from './doctor.js';
 import { line, listSecrets } from './install-load.js';
 import { printWarnings, rowLines } from './row-lines.js';
 import {} from './rows.js';
@@ -15,7 +16,7 @@ const changeLine = ({ name, from, to }) => {
         return `- remove ${name} ${from}`;
     return `~ update ${name} ${from} -> ${to}`;
 };
-const heldLine = ({ name, version, newer, engine }) => line('kept', `${name} ${version} (${newer} needs extension API ${engine})`);
+const heldLine = ({ name, version, newer, ...range }) => line('kept', `${name} ${version} (${newer} ${needsText(range)})`);
 const printDiff = (result, tree) => {
     for (const held of result.held)
         console.log(heldLine(held));

package/dist/commands/extension/list.d.ts

@@ -1,17 +1,22 @@
 import { type Command } from 'commander';
-import { type ExtensionCheckOptions } from './check.js';
+import { type ExtensionBuildOptions } from './build.js';
+import { type ExtensionDoctorOptions } from './doctor.js';
 import { type ExtensionInstallOptions } from './install.js';
 import { type ExtensionRemoveOptions } from './remove.js';
 import { type ExtensionsGather } from './rows.js';
+import { type KitActions } from './up.js';
 export interface ExtensionListOptions {
     json?: boolean;
 }
 export declare const printReport: ({ status, warnings }: ExtensionsGather, json?: boolean) => void;
 export declare const runExtensionList: (opts?: ExtensionListOptions) => Promise<void>;
-export interface ExtensionActions {
+export declare const helpOrUnknown: (_opts: unknown, group: Command) => void;
+export interface ExtensionActions extends KitActions {
     install: (opts: ExtensionInstallOptions) => Promise<void>;
     remove: (opts: ExtensionRemoveOptions) => Promise<void>;
     list: (opts: ExtensionListOptions) => Promise<void>;
-    check: (opts: ExtensionCheckOptions) => Promise<void>;
+    doctor: (opts: ExtensionDoctorOptions) => Promise<void>;
+    check: (opts: ExtensionDoctorOptions) => Promise<void>;
+    build: (opts: ExtensionBuildOptions) => Promise<void>;
 }
 export declare const registerExtension: (program: Command, actions: ExtensionActions) => void;

package/dist/commands/extension/list.js

@@ -1,9 +1,11 @@
 import {} from 'commander';
-import {} from './check.js';
+import { addBuild } from './build.js';
+import {} from './doctor.js';
 import {} from './install.js';
 import {} from './remove.js';
 import { printWarnings, rowLines } from './row-lines.js';
 import { gatherExtensions, invalidProfileError } from './rows.js';
+import { addKitTools } from './up.js';
 // The rows, or the whole report as JSON, on stdout; warnings on stderr.
 export const printReport = ({ status, warnings }, json) => {
     const rows = status.extensions.length > 0 ? rowLines(status.extensions) : ['no extensions'];
@@ -23,18 +25,21 @@ export const runExtensionList = async (opts = {}) => {
         throw failure;
 };
 const INSTALL_HELP = `
-<name> is resolved in this order: a local path (./path or /path) is a dev extension, kept in
-machine.json by its real path and loaded on this machine only, in place of an installed copy of
-the same package; http:, file:, npm: and github: are refused; an https: tarball URL and a
-package name are used as written (a name without @<range> is pinned to ^ its newest version
-whose engines.agentage fits this CLI's extension API, naming each newer version it skipped);
-a short name like memory is @agentage/extension-memory, else agentage-extension-memory. A
-package goes into profile.json (created from the default profile when absent), from the
-registry the profile names for its scope; --off keeps it from loading on this machine. Then
-installs and loads like setup, and exits 1 when an extension failed. Never signs in. On a
-machine whose profile comes from your account, the change applies to the account's newest
-profile and is pushed (with npm's lock) once everything loaded; if another machine pushed in
-between, it is replayed once on that profile.`;
+<name> is resolved in this order: a local path (./path or /path) is a working copy, linked as a
+dev extension: kept in machine.json by its real path and loaded on this machine only, in place
+of an installed copy of the same package; http:, file:, npm: and github: are refused; an https:
+tarball URL and a package name are used as written (a name without @<range> is pinned to ^ its
+newest version whose engines.agentage fits this CLI's extension API, or the kit's version for a
+package built on the extension kit, naming each newer version it skipped); a short name like
+memory is @agentage/extension-memory, else agentage-extension-memory. A package goes into
+profile.json (created from the default profile when absent), from the registry the profile
+names for its scope; --off keeps it from loading on this machine. Then installs and loads like
+setup, and exits 1 when an extension failed. Never signs in. On a machine whose profile comes
+from your account, the change applies to the account's newest profile and is pushed (with npm's
+lock) once everything loaded; if another machine pushed in between, it is replayed once on that
+profile. The commands of a package built on the kit run as agentage <command> and always as
+agentage <id> <command>; one whose name is a core command, an extension id or a command an
+earlier install took runs only as agentage <id> <command>, and one line says so.`;
 const REMOVE_HELP = `
 <name> is a package name, a short name or an extension id. Refused while another extension
 peer-depends on it. Takes it out of profile.json and this machine's off list, or out of
@@ -47,13 +52,15 @@ off, blocked, invalid, missing), what setup would change (add, update, remove; b
 nothing), package, installed version, wanted range, contributed commands, the last run from
 state/<id>.json, and the reason when it cannot load. Extension code is never loaded; the only
 file written is machine.json.`;
-const CHECK_HELP = `
+const DOCTOR_HELP = `
 Loads every extension this machine can run, once, the way setup does: what an extension prints
 while loading goes to stderr, state/<id>.json is rewritten for each, and the rows show ok or
-failed with the reason (a dependent of a failed extension is blocked). Exits 1 when any
-extension failed, or on integrity drift between the lock and the installed tree.`;
+failed with the reason (a dependent of a failed extension is blocked). An extension built on the
+extension kit is ok when its command entry exports create and its handlers are the commands it
+declares. Exits 1 when any extension failed, or on integrity drift between the lock and the
+installed tree. extension check is its old name, kept for 90 days.`;
 // Bare `extension` prints its help (exit 0); an unknown subcommand stays a usage error (exit 2).
-const helpOrUnknown = (_opts, group) => {
+export const helpOrUnknown = (_opts, group) => {
     const name = group.args[0];
     if (name === undefined)
         group.help();
@@ -76,7 +83,7 @@ const addChanges = (group, { install, remove }) => {
         .addHelpText('after', REMOVE_HELP)
         .action((name, opts) => remove({ name, ...opts }));
 };
-const addReports = (group, { list, check }) => {
+const addReports = (group, { list, doctor, check }) => {
     group
         .command('list')
         .description('Show one row per extension: state, versions, commands, last run')
@@ -84,13 +91,18 @@ const addReports = (group, { list, check }) => {
         .addHelpText('after', LIST_HELP)
         .action(list);
     group
-        .command('check')
+        .command('doctor')
         .description('Load every extension once and refresh its state: ok or failed')
         .option('--json', 'machine-readable output')
-        .addHelpText('after', CHECK_HELP)
+        .addHelpText('after', DOCTOR_HELP)
+        .action(doctor);
+    group
+        .command('check', { hidden: true })
+        .description('Deprecated: the old name of doctor')
+        .option('--json', 'machine-readable output')
         .action(check);
 };
-// Help lists the subcommands in this order: install, remove, list, check.
+// Help lists the subcommands in this order: install, remove, list, doctor, build, up, down, token.
 export const registerExtension = (program, actions) => {
     const group = program
         .command('extension')
@@ -99,4 +111,6 @@ export const registerExtension = (program, actions) => {
         .action(helpOrUnknown);
     addChanges(group, actions);
     addReports(group, actions);
+    addBuild(group, actions.build);
+    addKitTools(group, actions);
 };

package/dist/commands/extension/rows.d.ts

@@ -2,6 +2,7 @@ import { type PlanSummary, type PlanVerb } from '../../core/installer/plan.js';
 import { type LoadOutcome } from '../../core/loader/load.js';
 import { type Scan } from '../../core/loader/scan.js';
 import { type StaticState } from '../../core/loader/states.js';
+import { type Verbs } from '../../core/loader/verbs.js';
 import { type ProfileSource } from '../../core/profile/machine.js';
 export type RowState = StaticState | 'ok' | 'failed';
 export interface ExtensionRow {
@@ -50,6 +51,7 @@ export interface ExtensionsGather {
     status: ExtensionsStatus;
     warnings: string[];
     drift: string[];
+    verbs: Verbs;
 }
 export declare const gatherFrom: (found: Scan, runs?: ReadonlyMap<string, LoadOutcome>) => ExtensionsGather;
 export declare const gatherExtensions: () => Promise<ExtensionsGather>;

package/dist/commands/extension/rows.js

@@ -1,9 +1,10 @@
 import {} from '../../core/installer/plan.js';
 import {} from '../../core/loader/discover.js';
 import {} from '../../core/loader/load.js';
-import { scan } from '../../core/loader/scan.js';
+import { loadSet, scan } from '../../core/loader/scan.js';
 import { readRunState } from '../../core/loader/state.js';
 import {} from '../../core/loader/states.js';
+import { claimVerbs, commandNames, readHeld } from '../../core/loader/verbs.js';
 import { loadMachine } from '../../core/profile/machine.js';
 import {} from '../../core/profile/schema.js';
 const profileStatus = (parsed, machine) => {
@@ -21,7 +22,7 @@ const lastRunOf = (p, s) => {
     const run = p.id === null || s.state === 'invalid' ? null : readRunState(p.id);
     return run && { at: run.at, state: run.state, error: run.error };
 };
-const toRow = (p, found, s) => ({
+const toRow = (p, { found, verbs }, s) => ({
     id: p.id,
     package: p.pkg,
     mode: p.source === 'dev' ? 'dev' : 'installed',
@@ -30,7 +31,7 @@ const toRow = (p, found, s) => ({
     state: s.state,
     plan: p.source === 'dev' ? null : verbOf(found, p.pkg),
     error: s.error,
-    commands: p.commands,
+    commands: commandNames(p, verbs),
     lastRun: lastRunOf(p, s),
 });
 const verbOf = (found, pkg) => found.plan.extensions.find((entry) => entry.name === pkg)?.verb ?? null;
@@ -38,12 +39,17 @@ const verbOf = (found, pkg) => found.plan.extensions.find((entry) => entry.name
 const withRun = (row, run) => run ? { ...row, state: run.state, error: run.error, lastRun: null } : row;
 const UNKNOWN = { state: 'invalid', error: null };
 const STILL_INSTALLED = { state: 'installed', error: null };
-export const gatherFrom = (found, runs = new Map()) => {
-    const { machine, parsed, states } = found;
-    const extensions = [
-        ...found.found.extensions.map((p) => withRun(toRow(p, found, states.get(p.pkg) ?? UNKNOWN), runs.get(p.pkg))),
-        ...found.removed.map((p) => toRow(p, found, STILL_INSTALLED)),
+const rowsOf = (seen, runs) => {
+    const { found, states, removed } = seen.found;
+    return [
+        ...found.extensions.map((p) => withRun(toRow(p, seen, states.get(p.pkg) ?? UNKNOWN), runs.get(p.pkg))),
+        ...removed.map((p) => toRow(p, seen, STILL_INSTALLED)),
     ].sort((a, b) => (a.package < b.package ? -1 : 1));
+};
+export const gatherFrom = (found, runs = new Map()) => {
+    const { machine, parsed } = found;
+    const seen = { found, verbs: claimVerbs(loadSet(found), readHeld()) };
+    const extensions = rowsOf(seen, runs);
     const status = {
         machine: { id: machine.id, name: machine.name },
         profile: profileStatus(parsed, machine),
@@ -51,7 +57,7 @@ export const gatherFrom = (found, runs = new Map()) => {
         extensions,
     };
     const warnings = [...(parsed?.ok ? parsed.warnings : []), ...found.found.warnings];
-    return { status, warnings, drift: found.drift };
+    return { status, warnings, drift: found.drift, verbs: seen.verbs };
 };
 // Reads manifests, profile and state files; writes only a missing machine.json.
 export const gatherExtensions = async () => gatherFrom(scan(await loadMachine()));

package/dist/commands/extension/up.d.ts

@@ -0,0 +1,22 @@
+import { type Command } from 'commander';
+import { type LoadKitTool } from './kit-tool.js';
+export interface ExtensionUpOptions {
+    dir?: string;
+}
+export interface ExtensionDownOptions extends ExtensionUpOptions {
+    keepData?: boolean;
+}
+export interface ExtensionTokenOptions {
+    scope: string;
+    issuer?: string;
+}
+export declare const runExtensionUp: (opts?: ExtensionUpOptions, tool?: LoadKitTool) => Promise<void>;
+export declare const runExtensionDown: (opts?: ExtensionDownOptions, tool?: LoadKitTool) => Promise<void>;
+export declare const runExtensionToken: (opts: ExtensionTokenOptions, tool?: LoadKitTool) => Promise<void>;
+export declare const issuerUrl: (value: string) => string;
+export interface KitActions {
+    up: (opts: ExtensionUpOptions) => Promise<void>;
+    down: (opts: ExtensionDownOptions) => Promise<void>;
+    token: (opts: ExtensionTokenOptions) => Promise<void>;
+}
+export declare const addKitTools: (group: Command, actions: KitActions) => void;