@agentage/cli 0.39.0 → 0.41.0

package/README.md

@@ -2,18 +2,19 @@
 
 ![Connect this machine to agentage from the terminal](https://github.com/agentage/cli/raw/master/docs/banner.svg)
 
-Connect this machine to your [agentage](https://agentage.io) account from the terminal. One
-command signs you in through your browser, and from then on the machine is known to your account.
+Connect this machine to your [agentage](https://agentage.io) account from the terminal, and
+install the extensions your account's profile names. One command signs you in through your
+browser; the same profile then gives you the same extensions on every machine you set up.
 
 ## What is this?
 
-agentage gives your AI tools a shared, account-backed home. Every machine you use needs to be
-connected to that account once: this package does that connection. It keeps your sign-in on
-the machine (OAuth 2.1 with PKCE, nothing typed into the terminal), tells you whether the
-machine is connected, and keeps itself up to date.
+agentage gives your AI tools a shared, account-backed home. Every machine you use is connected
+to that account once, by this package. It keeps your sign-in on the machine (OAuth 2.1 with
+PKCE, nothing typed into the terminal), tells you whether the machine is connected, and keeps
+itself up to date.
 
-It is intentionally **small**: sign-in, status and update. Everything else arrives as plugins
-that the CLI installs for you.
+The CLI itself stays **small**: sign-in, status, update, and an extension manager. Everything
+else, memory included, arrives as an extension the CLI installs for you.
 
 ## Get started
 
@@ -33,7 +34,7 @@ agentage status
 ### On a server or in CI (no browser)
 
 ```bash
-agentage setup --no-browser        # prints the sign-in URL to open elsewhere
+agentage setup --no-browser              # prints the sign-in URL to open elsewhere
 AGENTAGE_TOKEN=aga_... agentage status   # or use a personal access token
 ```
 
@@ -44,34 +45,131 @@ AGENTAGE_TOKEN=aga_... agentage status   # or use a personal access token
 
 ## Commands
 
-| Command                       | What it does                                                            |
-| ----------------------------- | ----------------------------------------------------------------------- |
-| `agentage setup`              | Sign in through your browser, then show status                          |
-| `agentage setup --no-browser` | Print the sign-in URL instead of opening a browser                      |
-| `agentage setup --reauth`     | Force a fresh sign-in                                                   |
-| `agentage setup --disconnect` | Sign out and remove local credentials                                   |
-| `agentage status`             | Version, update, target, sign-in state, endpoint (`--json` for scripts) |
-| `agentage update`             | Install the latest published version (`--check` only reports)           |
+| Command                       | What it does                                                                  |
+| ----------------------------- | ----------------------------------------------------------------------------- |
+| `agentage setup`              | Sign in through your browser, install your account's profile, show status     |
+| `agentage setup --no-browser` | Print the sign-in URL instead of opening a browser                            |
+| `agentage setup --reauth`     | Force a fresh sign-in                                                         |
+| `agentage setup --disconnect` | Sign out and remove local credentials                                         |
+| `agentage status`             | Version, update, target, sign-in, endpoint, then machine, profile, extensions |
+| `agentage update`             | Install the latest published version (`--check` only reports)                 |
+
+For extensions (see below):
+
+| Command                                      | What it does                                                     |
+| -------------------------------------------- | ---------------------------------------------------------------- |
+| `agentage setup --profile <file>`            | Install and load the extensions a profile file names, no sign-in |
+| `agentage setup --profile <file> --dry-run`  | Show what would be installed, write nothing                      |
+| `agentage setup --latest`                    | Update each extension to the newest version its range allows     |
+| `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 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).
 
+## Extensions
+
+An extension is an npm package that adds to the CLI: commands today, more later. Extensions are
+on by default. A machine whose profile names no extensions has none, and `setup`, `status` and
+`update` work as described above, with three more `status` lines: `machine`, `profile` and
+`extensions`.
+
+The model is simple. A **profile** says what this account wants: which extensions, at which
+version ranges, and which ones are switched off on which machine. The CLI brings the machine
+to that state: `setup` installs what the profile names, loads each extension once and prints
+whether it loaded (`ok`) or why not. `extension install` and `extension remove` edit the
+profile and then do the same. Nothing installs itself on a timer; the state only changes when
+you run a command.
+
+Once you are signed in, `setup` reads the profile your account holds, when it has one, so every
+machine you set up gets the same extensions, and `extension install` and `extension remove` save
+the change there. When your account has no profile to give, `setup` says so on one line and
+carries on. Each machine you run `setup` on appears in your account as one of its machines.
+
+```bash
+agentage setup --profile ./profile.json            # install and load the extensions a profile names
+agentage setup --profile ./profile.json --dry-run  # show the plan, write nothing
+agentage setup --check                             # exit 1 when this machine differs from its profile
+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`
+shows it per extension and `status` sums it up, for example `extensions 2 (1 to add)`.
+
+`setup --latest` moves each extension to the newest version its range allows and prints one line
+per change, such as `~ update @agentage/example 1.0.0 -> 1.0.1`. The new versions take over only
+after every extension loaded from them cleanly; until then the installed ones stay. A version
+that needs a newer extension API than this CLI has is skipped, here and by `extension install`.
+
+A profile is a JSON file that maps package names to version ranges. `registries` is optional
+and routes a scope to another npm-compatible registry; everything else comes from npm's public
+registry.
+
+```json
+{
+  "version": 1,
+  "extensions": { "@agentage/example": "^1.0.0" },
+  "registries": { "@acme": "https://npm.acme.example" }
+}
+```
+
+Extensions run in the CLI process with your privileges, so install only extensions you trust.
+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/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).
+
 ## How it works
 
 This is the **terminal client for an agentage account**. `setup` registers a one-off OAuth
 client, opens the authorization page in your browser and waits on a localhost callback; the
 tokens land in `~/.agentage/auth.json` with owner-only permissions and are refreshed
 automatically. `status` validates the session against the account's introspection endpoint
-and reports version, update, target host and connectivity. Nothing runs in the background and
-nothing is installed beyond this package.
+and reports version, update, target host and connectivity. Nothing runs in the background, and
+nothing is installed beyond this package unless your profile names extensions.
 
 ## Configuration
 
-| Env                   | Default       | Purpose                                            |
-| --------------------- | ------------- | -------------------------------------------------- |
-| `AGENTAGE_SITE_FQDN`  | `agentage.io` | Target host                                        |
-| `AGENTAGE_CONFIG_DIR` | `~/.agentage` | Config and credentials directory                   |
-| `AGENTAGE_TOKEN`      | -             | Personal access token for CI and headless machines |
-| `NO_COLOR`            | -             | Disable colored output                             |
+| Env                       | Default               | Purpose                                            |
+| ------------------------- | --------------------- | -------------------------------------------------- |
+| `AGENTAGE_SITE_FQDN`      | `agentage.io`         | Target host                                        |
+| `AGENTAGE_CONFIG_DIR`     | `~/.agentage`         | Config and credentials directory                   |
+| `AGENTAGE_TOKEN`          | -                     | Personal access token for CI and headless machines |
+| `AGENTAGE_EXTENSIONS_DIR` | `<config>/extensions` | Where extensions are installed                     |
+| `NO_COLOR`                | -                     | Disable colored output                             |
 
 ## Develop
 
@@ -81,6 +179,9 @@ npm run verify
 npm run build && npm run test:e2e -- --grep @offline
 ```
 
+The e2e specs under `e2e/core/` read as scenarios: each title names the command and what must
+hold. They run against a loopback registry that serves the extensions under `fixtures/`.
+
 ## Release
 
 Releases publish to npm via GitHub Actions when a `chore(release): X.Y.Z` commit that touches

package/dist/commands/auth/setup.d.ts

@@ -2,11 +2,17 @@ import { type Command } from 'commander';
 import { type SignInOptions, type SignInResult } from '../../lib/auth/sign-in.js';
 export interface SetupOptions extends SignInOptions {
     disconnect?: boolean;
+    profile?: string;
+    dryRun?: boolean;
+    check?: boolean;
+    latest?: boolean;
+    json?: boolean;
 }
 export interface SetupDeps {
     ensureSignedIn: (opts: SignInOptions) => Promise<SignInResult>;
     signOut: () => Promise<void>;
-    printStatus: () => Promise<void>;
+    printStatus: (opts?: {
+        token?: string;
+    }) => Promise<void>;
 }
-export declare const runSetup: (opts: SetupOptions, deps: SetupDeps) => Promise<void>;
 export declare const registerSetup: (program: Command, action: (opts: SetupOptions) => Promise<void>) => void;

package/dist/commands/auth/setup.js

@@ -1,11 +1,36 @@
-import {} from 'commander';
+import { Option } from 'commander';
 import {} from '../../lib/auth/sign-in.js';
-export const runSetup = async (opts, deps) => {
-    if (opts.disconnect)
-        return deps.signOut();
-    await deps.ensureSignedIn({ reauth: opts.reauth, browser: opts.browser });
-    await deps.printStatus();
-};
+const EXTENSIONS_HELP = `
+Extensions: --profile <file> validates a profile (schema v1), saves it as profile.json and
+installs its extensions with npm, without signing in. --dry-run prints the plan, what setup
+would change (+ add, ~ update, - remove, o off, then one summary line), and writes nothing;
+--check prints the plan and exits 1 when anything would change, the lock in the extensions
+directory does not match the installed tree, or machine.json is missing; it writes nothing.
+Neither signs in. Plain setup signs in, then pulls the profile from your account (creating it
+from this machine's profile.json, or the default, when the account has none), registers this
+machine in the account and installs; it never pushes a change. When the account cannot be
+reached it installs from the local profile.json, or, with none, installs nothing and says so on
+one line. A profile from --profile stays local: setup neither pulls nor pushes it. Each package
+comes from the registry the profile's registries map names for its scope (default
+https://registry.npmjs.org) into AGENTAGE_EXTENSIONS_DIR (default ~/.agentage/extensions). After
+installing, setup lists the secrets extensions declare and this machine has not set (asking for
+them on a terminal), then loads every extension once and prints ok or failed for each; it exits
+1 when any failed. Signed in to another account than the one this machine is connected to, setup
+exits 1; run setup --disconnect first, which also marks this machine disconnected in your
+account.
+
+--latest runs npm update in a staged copy of the installed tree: each extension moves to the
+newest version its range allows, unless that version needs another extension API (then it is
+kept, saying so). It prints one line per changed extension and a summary, loads the new tree and
+makes it current only when every extension loaded clean, then pushes the profile with the new
+lock to your account when the profile comes from it. With nothing newer it only prints
+"latest: nothing to update". It never signs in.`;
+const latestOption = () => new Option('--latest', 'update extensions to the newest versions their ranges allow').conflicts([
+    'profile',
+    'dryRun',
+    'check',
+    'disconnect',
+]);
 export const registerSetup = (program, action) => {
     program
         .command('setup')
@@ -13,5 +38,11 @@ export const registerSetup = (program, action) => {
         .option('--disconnect', 'sign out and remove local credentials')
         .option('--reauth', 'force a fresh sign-in')
         .option('--no-browser', 'print the sign-in URL instead of opening a browser')
+        .option('--profile <file>', 'install the extensions a profile file names; never signs in')
+        .option('--dry-run', 'print what setup would change and write nothing')
+        .option('--check', 'exit 1 when setup would change anything; write nothing')
+        .addOption(latestOption())
+        .option('--json', 'with --dry-run or --check: the plan as JSON')
+        .addHelpText('after', EXTENSIONS_HELP)
         .action(action);
 };

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

@@ -0,0 +1,5 @@
+import { type Account } from '../../core/profile/cloud.js';
+export type AccountOf = (opts?: {
+    token?: string;
+}) => Account | null;
+export declare const signedInAccount: AccountOf;

package/dist/commands/extension/account.js

@@ -0,0 +1,18 @@
+import {} from '../../core/profile/cloud.js';
+import { authedFetch } from '../../lib/auth/api.js';
+import { resolveAuth } from '../../lib/auth/credentials.js';
+import { detectEnvMismatch } from '../../lib/auth/env-match.js';
+import { introspectToken } from '../../lib/auth/introspect.js';
+import { apiOrigin, links, siteFqdn } from '../../lib/net/origins.js';
+const CLIENT = { 'x-client-type': 'cli' };
+// Read before any extension loads: the token is captured here, the fetch at CLI start.
+export const signedInAccount = (opts = {}) => {
+    const auth = resolveAuth(opts);
+    const fqdn = siteFqdn();
+    if (auth === null || detectEnvMismatch(auth, fqdn) !== null)
+        return null;
+    const target = links(fqdn);
+    const fetch = (path, { headers, timeoutMs, ...init } = {}) => authedFetch(auth, target, `${apiOrigin(fqdn)}${path}`, { ...init, headers: { ...CLIENT, ...headers } }, { timeoutMs });
+    const id = () => introspectToken(auth, target).then((s) => s.userId ?? null, () => null);
+    return { fetch, id };
+};

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

@@ -0,0 +1,6 @@
+import { type Command } from 'commander';
+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

@@ -0,0 +1,57 @@
+import {} from 'commander';
+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 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);
+        if (!loaded)
+            throw new Error(`extension ${ext.id} ${run?.state}: ${run?.error}`);
+        if (!loaded.program.commands.some((command) => command.name() === name))
+            throw new Error(`extension ${ext.id} did not add the command ${name}`);
+        await loaded.program.parseAsync(argv);
+    }
+    finally {
+        await session.dispose();
+    }
+};
+// Usage, exit 2: the core commands, then one line per extension with what it contributes.
+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}: ${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, tool = loadKitTool) => {
+    const core = program.commands.map((command) => command.name());
+    const extensions = loadSet(scan(readMachine() ?? NO_MACHINE));
+    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/doctor.js

@@ -0,0 +1,44 @@
+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; 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, undefined, kitCheck(tool));
+    await session.dispose();
+    return gatherFrom(found, session.outcomes);
+};
+export const failedError = (rows) => {
+    const failed = rows.filter((row) => row.state === 'failed').map((row) => row.id ?? row.package);
+    if (failed.length === 0)
+        return null;
+    const count = `${failed.length} extension${failed.length === 1 ? '' : 's'}`;
+    return new Error(`${count} failed to load: ${failed.join(', ')}`);
+};
+// 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 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.d.ts

@@ -0,0 +1,7 @@
+import { type InstallSet } from '../../core/installer/installer.js';
+import { type Npm } from '../../core/installer/npm.js';
+import { type DiscoveredExtension } from '../../core/loader/discover.js';
+export declare const line: (label: string, value: string) => string;
+export declare const counted: (n: number) => string;
+export declare const listSecrets: (extensions: DiscoveredExtension[]) => Promise<void>;
+export declare const installAndLoad: (set: InstallSet, npm: () => Promise<Npm>, installed?: () => Promise<unknown>) => Promise<void>;

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

@@ -0,0 +1,42 @@
+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 { 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';
+export const line = (label, value) => `${label.padEnd(10)} ${value}`;
+export const counted = (n) => n === 0 ? 'no extensions' : `${n} extension${n === 1 ? '' : 's'}`;
+const installLine = (result) => {
+    const how = result.reused ? 'reused' : result.npm ? `npm ${result.npm}` : 'npm skipped';
+    return line('install', `${counted(result.count)} in tree ${result.tree} (${how})`);
+};
+// 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 }));
+    if (outcome.result)
+        console.log(installLine(outcome.result));
+    if (outcome.result)
+        await installed();
+    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;
+    const failed = failedError(gathered.status.extensions);
+    if (failed)
+        throw failed;
+};

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

@@ -0,0 +1,10 @@
+import { type NpmManifest } from '../../core/installer/npm.js';
+import { type EditDeps } from './sync.js';
+export interface ExtensionInstallOptions {
+    name: string;
+    off?: boolean;
+}
+export interface ExtensionInstallDeps extends EditDeps {
+    manifest: () => Promise<NpmManifest>;
+}
+export declare const runExtensionInstall: (opts: ExtensionInstallOptions, deps: ExtensionInstallDeps) => Promise<void>;

package/dist/commands/extension/install.js

@@ -0,0 +1,38 @@
+import { needs } from '../../core/installer/compat.js';
+import {} from '../../core/installer/npm.js';
+import { registryLookup, resolveName } from '../../core/installer/resolve.js';
+import { addExtension } from '../../core/profile/edit.js';
+import { loadMachine, setDev } from '../../core/profile/machine.js';
+import { editableProfile } from '../../core/profile/profile.js';
+import {} from '../../core/profile/schema.js';
+import { installAndLoad, line } from './install-load.js';
+import { finishEdit, pullForEdit } from './sync.js';
+const addPackage = async (target, off, deps) => {
+    for (const newer of target.skipped)
+        console.log(line('skipped', needs(newer)));
+    const synced = await pullForEdit(deps);
+    const { id } = await loadMachine();
+    const note = line('added', `${target.name} ${target.spec}${off ? ' (off on this machine)' : ''}`);
+    const add = (profile) => addExtension(profile, target.name, target.spec, id, off);
+    await finishEdit(synced, add, deps, note);
+};
+// A dev extension is this machine's own: it replaces an installed copy, and never syncs.
+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);
+    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.
+export const runExtensionInstall = async (opts, deps) => {
+    const { registries } = editableProfile();
+    const target = await resolveName(opts.name, registryLookup(deps.manifest, registries));
+    if (target.kind === 'dev')
+        await addDev(target, opts.off === true, deps);
+    else
+        await addPackage(target, opts.off === true, deps);
+};

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}:`);
+    }
+};