@aragon-agent/cli 0.5.12 → 0.6.1

package/dist/cli.js

@@ -32,6 +32,13 @@ import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
 import { runHeadless } from './agent/headless.js';
+// The four `register*Command` entry points of cli-integration-surface §3.1. The
+// declarations live in those modules rather than here; see the header of
+// `exec/cli-commands.ts` for why this new code departs from the `logs` /
+// `history` / `skills` convention.
+import { registerExecCommand } from './exec/cli-commands.js';
+import { registerSessionsCommand } from './session/cli-commands.js';
+import { registerDoctorCommand, registerInfoCommand } from './diagnostics/cli-commands.js';
 import { App } from './ui/App.js';
 import { decideRenderMode } from './ui/layout/frame.js';
 import { createFrameDiffer } from './ui/frame-differ.js';
@@ -39,6 +46,7 @@ import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
 import { setFrameStatsProvider } from './commands/perf.js';
 import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
+import { supportsWindowsVtInput } from './ui/win-vt-input.js';
 import { readExitSnapshot } from './ui/exit-snapshot.js';
 import { renderTranscriptText } from './ui/transcript-text.js';
 import { detectCapabilities } from './ui/capabilities.js';
@@ -234,9 +242,35 @@ function makeController(flags, opts = { interactive: true }) {
                     : Promise.resolve(null),
             }
             : DENY_ALL_HUMAN_INPUT,
+        ...(opts.permission ? { permission: opts.permission } : {}),
+        ...(opts.appendSystemPrompt ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
     });
     return { controller, confirmBridge, humanInputBridge };
 }
+/**
+ * The controller factory `aragon exec` runs on.
+ *
+ * IT REPRODUCES `runOneShot`'s SETUP EXACTLY, and that is the whole reason it
+ * lives here rather than inside `exec/`: the deny-all approval gate, the
+ * deny-all human-input channel, the two log attachments and the untrusted-skill
+ * notices are decisions `makeController`'s own comment says must have ONE
+ * definition. `exec/index.ts` receives this as a parameter, which also keeps
+ * `cli.tsx -> exec/cli-commands.ts -> exec/index.ts` acyclic.
+ */
+function makeExecController(flags, deps) {
+    const { controller } = makeController(flags, { interactive: false, ...deps });
+    const logger = getLogger();
+    logger.info('cli', 'run_exec', {});
+    logger.onFailure((reason) => process.stderr.write(`[log] ${reason}\n`));
+    attachAgentEvents(logger, controller);
+    attachTeamEvents(logger, controller);
+    for (const dir of controller.getSkillService().untrustedDirs()) {
+        // STDERR, NEVER STDOUT. In `json` / `stream-json` mode stdout carries
+        // nothing but the schema, and a notice on it would corrupt every consumer.
+        process.stderr.write(`[skills] project skills in ${dir} skipped (untrusted). Run: aragon skills trust ${dir}\n`);
+    }
+    return controller;
+}
 /**
  * Raised once per session, on the 0->1 edge of the writer's `fallbacks` counter
  * (tui-input-flicker-fix §5.6 / AC-15).
@@ -294,7 +328,23 @@ function runInteractive(flags, extras = {}) {
     // reaches `runInteractive` without the stdin check the default action makes)
     // would wrap a stream no report can ever arrive on and ask the terminal to
     // start reporting anyway. §4.2's "non-TTY ⇒ no filter" covers both ends.
-    const wantMouse = mode === 'fullscreen' && config.mouse && !!process.stdout.isTTY && !!process.stdin.isTTY;
+    //
+    // R-1 IS DECIDED HERE, AND ONLY HERE (shift-tab-and-mouse-wheel-dead-on-some-
+    // terminals, F1'). On a Windows console whose Node never sets
+    // `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv drops every non-KEY_EVENT record
+    // before it reaches this process, so `\x1b[?1000h` is a pure no-op and the
+    // filter has nothing to filter. Gating `wantMouse` — rather than the three
+    // things downstream of it — is what keeps the three in agreement: the
+    // `?1000h` write (`enterAltScreen(..., { mouse: filter !== null })`), the
+    // filter itself, and the `mouseSource` prop that decides whether the user is
+    // advised about a mode that is not running. Wiring any of them separately
+    // re-opens the gap where the app claims a capability it does not have.
+    const vtInputSupported = supportsWindowsVtInput(process.platform, process.versions.node);
+    const wantMouse = mode === 'fullscreen' &&
+        config.mouse &&
+        !!process.stdout.isTTY &&
+        !!process.stdin.isTTY &&
+        vtInputSupported;
     const mouseFilter = wantMouse
         ? tryCreateMouseFilter(process.stdin, (reason) => logger.warn('cli', 'mouse_filter_failed', { reason }))
         : null;
@@ -400,7 +450,13 @@ function runInteractive(flags, extras = {}) {
         !!process.stdin.isTTY &&
         !process.env.CI &&
         config.update.mode !== 'off';
-    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source, updateBridge: updateEligible ? updateBridge : undefined }), 
+    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source, 
+        // Present ONLY when this console swallows `CSI Z` and mouse reports.
+        // Passed in rather than probed inside `App` so that every test renders
+        // the same tree on every machine — reading `process.versions.node` from
+        // a component would make the notice appear or vanish according to which
+        // Node the developer happened to have installed.
+        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined }), 
     // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
     // straight to stdout and permanently shifts the fixed frame's accounting.
     {
@@ -1266,6 +1322,19 @@ function buildProgram() {
         const provider = opts.provider ?? program.opts().provider;
         await runModels(toFlags(program.opts()), provider);
     });
+    // --- The machine-facing face (cli-integration-surface §3.1). --------------
+    //
+    // FOUR CALL SITES, ~10 LINES. Each module owns its own `.command()` and
+    // `.option()` declarations, because this file is already 60% over the
+    // repository's 1000-line guideline and twenty more declarations would make
+    // that worse for the audience `aragon --help` exists for.
+    registerExecCommand(program, toFlags, {
+        version: VERSION,
+        makeController: makeExecController,
+    });
+    registerSessionsCommand(program);
+    registerInfoCommand(program, toFlags, VERSION);
+    registerDoctorCommand(program, toFlags);
     return program;
 }
 async function main() {

package/dist/config/ui-state.d.ts

@@ -34,6 +34,22 @@ export interface UiState {
     submitCount: number;
     /** Whether the one-shot "hold Shift to select text" notice has been shown. */
     mouseNoticeSeen: boolean;
+    /**
+     * Whether the one-shot "this Windows console cannot deliver Shift+Tab or the
+     * wheel" notice has been shown.
+     *
+     * A SEPARATE KEY FROM `mouseNoticeSeen`, AND THAT IS THE WHOLE POINT. The
+     * people this notice exists for are precisely the ones who have already
+     * started aragon, already been shown the mouse notice that does not apply to
+     * them, and therefore already have `mouseNoticeSeen: true` on disk. Folding
+     * the two would make the fix inert for its entire audience, in silence.
+     *
+     * NOT ADDED TO `UI_STATE_SCHEMA`: bumping the schema makes `readFromDisk`
+     * discard the whole object, which would reset everyone's submit counter and
+     * re-show the mouse notice. A new field simply reads as its default on an
+     * older file, which is the behaviour wanted here anyway.
+     */
+    vtInputNoticeSeen: boolean;
 }
 /** Read the state, caching it for the life of the process. Never throws. */
 export declare function loadUiState(): UiState;
@@ -42,6 +58,8 @@ export declare function readSubmitCount(): number;
 export declare function bumpSubmitCount(): number;
 export declare function getMouseNoticeSeen(): boolean;
 export declare function setMouseNoticeSeen(seen: boolean): void;
+export declare function getVtInputNoticeSeen(): boolean;
+export declare function setVtInputNoticeSeen(seen: boolean): void;
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/config/ui-state.js

@@ -35,6 +35,7 @@ const DEFAULT_UI_STATE = {
     schema: UI_STATE_SCHEMA,
     submitCount: 0,
     mouseNoticeSeen: false,
+    vtInputNoticeSeen: false,
 };
 let memory = null;
 function coerceCount(value) {
@@ -64,6 +65,9 @@ function readFromDisk() {
             mouseNoticeSeen: typeof parsed.mouseNoticeSeen === 'boolean'
                 ? parsed.mouseNoticeSeen
                 : DEFAULT_UI_STATE.mouseNoticeSeen,
+            vtInputNoticeSeen: typeof parsed.vtInputNoticeSeen === 'boolean'
+                ? parsed.vtInputNoticeSeen
+                : DEFAULT_UI_STATE.vtInputNoticeSeen,
         };
     }
     catch {
@@ -123,6 +127,12 @@ export function getMouseNoticeSeen() {
 export function setMouseNoticeSeen(seen) {
     update({ mouseNoticeSeen: seen });
 }
+export function getVtInputNoticeSeen() {
+    return loadUiState().vtInputNoticeSeen;
+}
+export function setVtInputNoticeSeen(seen) {
+    update({ vtInputNoticeSeen: seen });
+}
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/diagnostics/cli-commands.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `aragon info` / `aragon doctor` commander wiring
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ */
+import type { Command } from 'commander';
+import type { CliFlags } from '../config/load.js';
+export declare function registerInfoCommand(program: Command, toFlags: (opts: Record<string, unknown>) => CliFlags, version: string): void;
+export declare function registerDoctorCommand(program: Command, toFlags: (opts: Record<string, unknown>) => CliFlags): void;

package/dist/diagnostics/cli-commands.js

@@ -0,0 +1,61 @@
+/**
+ * `aragon info` / `aragon doctor` commander wiring
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ */
+import process from 'node:process';
+import { buildInfo } from './info.js';
+import { runDoctorChecks } from './doctor.js';
+export function registerInfoCommand(program, toFlags, version) {
+    program
+        .command('info')
+        .description('Print what this installation supports (for wrappers and CI)')
+        .option('--json', 'Machine-readable output')
+        .action((opts) => {
+        const info = buildInfo(toFlags(program.opts()), version);
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
+            return;
+        }
+        process.stdout.write([
+            `aragon    ${info.cli} (core ${info.core}, node ${info.node})`,
+            `schema    ${info.schemaVersion}`,
+            `home      ${info.home}`,
+            `config    ${info.configPath}`,
+            `sessions  ${info.sessionsDir}`,
+            `model     ${info.provider}/${info.model}${info.hasApiKey ? '' : '  (no API key)'}`,
+            `formats   out: ${info.outputFormats.join(', ')} | in: ${info.inputFormats.join(', ')}`,
+            `modes     ${info.permissionModes.join(', ')}`,
+            `features  ${info.features.join(', ')}`,
+            '',
+        ].join('\n'));
+    });
+}
+export function registerDoctorCommand(program, toFlags) {
+    program
+        .command('doctor')
+        .description('Check that this machine is configured to run aragon (exit 0 = all clear)')
+        .option('--json', 'Machine-readable output')
+        .option('--probe', 'Also make one minimal API call against the configured provider')
+        .action(async (opts) => {
+        const report = await runDoctorChecks(toFlags(program.opts()), {
+            ...(opts.probe ? { probe: true } : {}),
+        });
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            for (const check of report.checks)
+                process.stdout.write(`${renderCheck(check)}\n`);
+        }
+        // ONLY `fail` MOVES THE EXIT CODE. A `warn` is information; failing on one
+        // would make `aragon doctor` unusable in exactly the CI job it is for.
+        process.exitCode = report.ok ? 0 : 1;
+    });
+}
+function renderCheck(check) {
+    const label = check.verdict.toUpperCase().padEnd(4);
+    const head = `[${label}] ${check.name.padEnd(9)} ${check.detail}`;
+    return check.remedy ? `${head}\n         ${check.remedy}` : head;
+}

package/dist/diagnostics/doctor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `aragon doctor` - "is this machine configured to run me?", in one exit code
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * EVERY CHECK CARRIES A ONE-LINE REMEDY, and only `fail` affects the exit code.
+ * A `warn` that failed the command would make the command useless on the many
+ * machines where something is unusual but working; a `fail` with no remedy makes
+ * the caller guess, which is the state this command exists to end.
+ */
+import { type CliFlags } from '../config/load.js';
+export type CheckVerdict = 'pass' | 'warn' | 'fail';
+export interface DoctorCheck {
+    name: string;
+    verdict: CheckVerdict;
+    detail: string;
+    /** What to do about it. Empty only for a `pass`. */
+    remedy: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+export interface DoctorOptions {
+    /** One minimal API call against the configured provider. */
+    probe?: boolean;
+}
+export declare function runDoctorChecks(flags: CliFlags, opts?: DoctorOptions): Promise<DoctorReport>;

package/dist/diagnostics/doctor.js

@@ -0,0 +1,167 @@
+/**
+ * `aragon doctor` - "is this machine configured to run me?", in one exit code
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * EVERY CHECK CARRIES A ONE-LINE REMEDY, and only `fail` affects the exit code.
+ * A `warn` that failed the command would make the command useless on the many
+ * machines where something is unusual but working; a `fail` with no remedy makes
+ * the caller guess, which is the state this command exists to end.
+ */
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { initProviders, ModelRegistry } from '@aragon-agent/core';
+import { getHomeResolutionWarning, getSessionsDir, getUserDataDir } from '../config/app-paths.js';
+import { readConfigFile } from '../config/store.js';
+import { loadConfig, makeGetApiKey } from '../config/load.js';
+import { isAdapterProvider, toRetryPolicy } from '../config/schema.js';
+const MIN_NODE_MAJOR = 18;
+export async function runDoctorChecks(flags, opts = {}) {
+    const checks = [checkNode(), checkHome(), checkConfigFile()];
+    const config = loadConfig(flags);
+    checks.push(checkProviderKey(config));
+    checks.push(checkModel(config));
+    checks.push(checkSessionsDir());
+    if (opts.probe)
+        checks.push(await probeProvider(config));
+    return { ok: checks.every((c) => c.verdict !== 'fail'), checks };
+}
+function pass(name, detail) {
+    return { name, verdict: 'pass', detail, remedy: '' };
+}
+function checkNode() {
+    const major = Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+    if (major >= MIN_NODE_MAJOR)
+        return pass('node', `v${process.versions.node}`);
+    return {
+        name: 'node',
+        verdict: 'fail',
+        detail: `v${process.versions.node} is below the supported floor`,
+        remedy: `Install Node ${MIN_NODE_MAJOR} or newer.`,
+    };
+}
+function checkHome() {
+    const home = getUserDataDir();
+    const warning = getHomeResolutionWarning();
+    try {
+        if (!existsSync(home))
+            mkdirSync(home, { recursive: true });
+        const probe = join(home, '.doctor-write-probe');
+        writeFileSync(probe, 'ok', 'utf-8');
+        unlinkSync(probe);
+    }
+    catch (err) {
+        return {
+            name: 'home',
+            verdict: 'fail',
+            detail: `${home} is not writable (${err.message})`,
+            remedy: 'Fix the permissions, or point ARAGON_HOME at a directory you own.',
+        };
+    }
+    if (warning) {
+        return {
+            name: 'home',
+            verdict: 'warn',
+            detail: `${home} (${warning})`,
+            remedy: 'Set ARAGON_HOME to an absolute path if this is not where you want state kept.',
+        };
+    }
+    return pass('home', home);
+}
+function checkConfigFile() {
+    const { parseError } = readConfigFile();
+    if (!parseError)
+        return pass('config', 'parses');
+    return {
+        name: 'config',
+        verdict: 'warn',
+        detail: `using defaults, could not parse ${parseError}`,
+        remedy: 'Run `aragon config edit` and fix the JSON, or delete the file to start over.',
+    };
+}
+function checkProviderKey(config) {
+    const key = makeGetApiKey(config)(config.provider);
+    if (key)
+        return pass('api-key', `resolved for ${config.provider}`);
+    return {
+        name: 'api-key',
+        verdict: 'fail',
+        detail: `no API key for provider "${config.provider}"`,
+        remedy: `Run \`aragon config\` and add one, or set the provider's key in the environment.`,
+    };
+}
+function checkModel(config) {
+    if (!isAdapterProvider(config.provider)) {
+        return {
+            name: 'model',
+            verdict: 'fail',
+            detail: `unknown provider "${config.provider}"`,
+            remedy: 'Run `aragon models` to see the providers this build supports.',
+        };
+    }
+    const registry = new ModelRegistry(initProviders({ retryPolicy: toRetryPolicy(config.retry) }));
+    const known = registry.getModels(config.provider).some((m) => m.id === config.model);
+    if (known)
+        return pass('model', `${config.provider}/${config.model}`);
+    // WARN, NOT FAIL. The registry is a builtin list plus whatever an account can
+    // discover, so a model it does not know is frequently one this account has and
+    // the shipped table does not - the cost table is unknown, the run is fine.
+    return {
+        name: 'model',
+        verdict: 'warn',
+        detail: `${config.provider}/${config.model} is not in the builtin registry`,
+        remedy: 'Run `aragon models` to list what this key can reach; cost reporting will be off.',
+    };
+}
+function checkSessionsDir() {
+    const dir = getSessionsDir();
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const probe = join(dir, '.doctor-write-probe');
+        writeFileSync(probe, 'ok', 'utf-8');
+        unlinkSync(probe);
+    }
+    catch (err) {
+        return {
+            name: 'sessions',
+            verdict: 'fail',
+            detail: `${dir} is not writable (${err.message})`,
+            remedy: 'Fix the permissions, or run `aragon exec --no-save-session`.',
+        };
+    }
+    return pass('sessions', dir);
+}
+/**
+ * `--probe`: one minimal API call.
+ *
+ * MODEL DISCOVERY IS THE CHEAPEST HONEST PROBE. It exercises the base URL, the
+ * key and the TLS chain - which is the whole of what "can this machine reach the
+ * provider" means - without spending a single completion token.
+ */
+async function probeProvider(config) {
+    const key = makeGetApiKey(config)(config.provider);
+    if (!key || !isAdapterProvider(config.provider)) {
+        return {
+            name: 'probe',
+            verdict: 'warn',
+            detail: 'skipped: no key or unknown provider',
+            remedy: 'Fix the api-key check above, then run `aragon doctor --probe` again.',
+        };
+    }
+    const registry = new ModelRegistry(initProviders({ retryPolicy: toRetryPolicy(config.retry) }));
+    try {
+        const models = await registry.discoverModels(config.provider, key, config.baseUrl);
+        return pass('probe', `${config.provider} answered with ${models.length} model(s)`);
+    }
+    catch (err) {
+        return {
+            name: 'probe',
+            verdict: 'fail',
+            detail: `${config.provider} did not answer (${err.message})`,
+            remedy: 'Check the key, the base URL and any proxy between this machine and the provider.',
+        };
+    }
+}

package/dist/diagnostics/info.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `aragon info` - capability discovery (cli-integration-surface section 5.4).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * "INSTALL AND CALL" ACROSS VERSIONS IS ONLY ROBUST IF THE CALLER CAN ASK WHAT
+ * IT JUST INSTALLED (G6). Everything a wrapper might branch on is here, and
+ * `features` is a FLAT STRING LIST on purpose: a wrapper testing
+ * `info.features.includes('sessions')` keeps working across versions that add
+ * capabilities, which a nested shape with renamed keys would not.
+ */
+import { type CliFlags } from '../config/load.js';
+export interface ExecInfo {
+    cli: string;
+    core: string;
+    node: string;
+    schemaVersion: number;
+    home: string;
+    configPath: string;
+    sessionsDir: string;
+    provider: string;
+    model: string;
+    hasApiKey: boolean;
+    tools: string[];
+    outputFormats: string[];
+    inputFormats: string[];
+    permissionModes: string[];
+    features: string[];
+}
+export declare function buildInfo(flags: CliFlags, version: string): ExecInfo;

package/dist/diagnostics/info.js

@@ -0,0 +1,99 @@
+/**
+ * `aragon info` - capability discovery (cli-integration-surface section 5.4).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * "INSTALL AND CALL" ACROSS VERSIONS IS ONLY ROBUST IF THE CALLER CAN ASK WHAT
+ * IT JUST INSTALLED (G6). Everything a wrapper might branch on is here, and
+ * `features` is a FLAT STRING LIST on purpose: a wrapper testing
+ * `info.features.includes('sessions')` keeps working across versions that add
+ * capabilities, which a nested shape with renamed keys would not.
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { getConfigPath, getSessionsDir, getUserDataDir } from '../config/app-paths.js';
+import { loadConfig, makeGetApiKey } from '../config/load.js';
+import { HOST_TOOL_NAMES } from '../tools/index.js';
+import { EXEC_SCHEMA_VERSION } from '../exec/events.js';
+/**
+ * Everything this build can do, as names a wrapper can test for.
+ *
+ * ADD, NEVER RENAME. A removed name is a breaking change for every consumer that
+ * guarded on it, and the whole value of the list is that guarding is cheap.
+ */
+const FEATURES = [
+    'exec',
+    'sessions',
+    'permissions',
+    'budgets',
+    'team',
+    'todo',
+    'skills',
+    'fast',
+];
+export function buildInfo(flags, version) {
+    const config = loadConfig(flags);
+    const getKey = makeGetApiKey(config);
+    return {
+        cli: version,
+        core: readCoreVersion(),
+        node: process.version,
+        schemaVersion: EXEC_SCHEMA_VERSION,
+        home: getUserDataDir(),
+        configPath: getConfigPath(),
+        sessionsDir: getSessionsDir(),
+        provider: config.provider,
+        model: config.model,
+        hasApiKey: Boolean(getKey(config.provider)),
+        // THE SUPERSET, not "what a run would register right now". This answers
+        // "which names can `--allow-tool` take?", which is exactly what
+        // `HOST_TOOL_NAMES` means and exactly what `--allow-tool` validates against.
+        tools: [...HOST_TOOL_NAMES],
+        outputFormats: ['text', 'json', 'stream-json'],
+        inputFormats: ['text', 'stream-json'],
+        permissionModes: ['auto', 'plan', 'strict'],
+        features: [...FEATURES],
+    };
+}
+/**
+ * The installed `@aragon-agent/core` version, or `'unknown'`.
+ *
+ * RESOLVED, NOT READ OFF THE DEPENDENCY RANGE. `"^0.2.12"` in this package's
+ * own `package.json` is what was ASKED FOR; a consumer asking `aragon info`
+ * wants what is actually loaded, and the two differ on every machine that
+ * installed a patch release.
+ *
+ * A DIRECTORY WALK, AND NEITHER `createRequire().resolve()` NOR
+ * `import.meta.resolve()` (implementation finding IF-2). Core's `exports` map
+ * declares only an `import` condition, so `createRequire(...).resolve()` fails
+ * with `ERR_PACKAGE_PATH_NOT_EXPORTED` - and it fails on the DEVELOPER's machine
+ * as readily as on a user's, which is how this was caught. `import.meta.resolve`
+ * is not synchronously available on Node 18, and `engines` says `>=18`.
+ *
+ * The walk covers all three real layouts: the monorepo (a symlink in the root
+ * `node_modules`), a flat npm install (core beside cli under the project's
+ * `node_modules`), and a nested one (core under the cli package's own
+ * `node_modules`).
+ */
+function readCoreVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 10; depth += 1) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, 'node_modules', '@aragon-agent', 'core', 'package.json'), 'utf-8'));
+            if (pkg.version)
+                return pkg.version;
+        }
+        catch {
+            // Not this level. Keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // A bundled or unusual layout. A missing version is worth reporting honestly;
+    // it is not worth failing a discovery command over.
+    return 'unknown';
+}

package/dist/exec/cli-commands.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `aragon exec` commander wiring (cli-integration-surface section 3.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE DECLARATIONS LIVE HERE, NOT IN `cli.tsx`, AND THAT IS A DELIBERATE
+ * DEPARTURE FROM THE EXISTING CONVENTION. `logs` / `history` / `skills` /
+ * `update` declare their options in `cli.tsx` and delegate to a `run*Command`.
+ * `cli.tsx` is already 1600 lines against this repository's 1000-line guideline,
+ * and four new subcommands carrying about twenty declarations between them is
+ * another 120 lines on a file that is 60% over budget. So `cli.tsx` gains four
+ * imports and four `register*Command(...)` call sites instead. This is a rule
+ * for the NEW code, not a refactor of the old (which is out of scope).
+ *
+ * NOT `src/commands/` EITHER: that directory is the SLASH-command tree
+ * (`/help`, `/model`, `/save`, `/resume`), and it already owns the two names
+ * exec's session work sits closest to.
+ */
+import { type Command } from 'commander';
+import type { CliFlags } from '../config/load.js';
+import { type ExecControllerFactory } from './index.js';
+export interface ExecCommandDeps {
+    version: string;
+    /**
+     * Supplied by `cli.tsx`. It cannot be imported: `cli.tsx` imports this module,
+     * so reaching back for `makeController` would be a cycle, and re-deriving it
+     * here would give the headless approval gates a second definition.
+     */
+    makeController: ExecControllerFactory;
+}
+export declare function registerExecCommand(program: Command, toFlags: (opts: Record<string, unknown>) => CliFlags, deps: ExecCommandDeps): void;