ai-runtime-engine 1.3.0 → 2.8.0

package/dist/cli/cli.js

@@ -17,10 +17,11 @@ import { setupCommand } from './commands/setup.js';
 import { infoCommand } from './commands/info.js';
 import { cleanupCommand } from './commands/cleanup.js';
 import { skillsCommand } from './commands/skills.js';
+import { mcpCommand, mcpAddCommand, mcpRemoveCommand, mcpEnableCommand, mcpTestCommand } from './commands/mcp.js';
 import { startRepl } from './interactive/repl.js';
 import { printError } from './render.js';
 const program = new Command();
-program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('1.3.0');
+program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('2.8.0');
 const configOpt = ['-c, --config <path>', 'path to an ai-runtime config file'];
 // Bare `ai-runtime` (no subcommand) opens the interactive terminal. `allowExcessArguments(false)` keeps
 // a mistyped subcommand (e.g. `ai-runtime porviders`) failing fast instead of silently opening the REPL.
@@ -36,6 +37,7 @@ program
     .option('--json', 'print the full RuntimeResult as JSON')
     .option('--dry-run', 'plan and report what would happen without making any changes')
     .option('--stream', 'stream the answer token-by-token (text output only)')
+    .option('--partial', 'if over the call budget, run the phases that fit and pause (vs. notify-and-wait)')
     .action((input, o) => runCommand(input, o));
 program
     .command('executions')
@@ -60,11 +62,57 @@ program
     .action((o) => setupCommand(o));
 program
     .command('skills')
-    .description('List available skills; --discover scans the workspace for more (reported, not loaded)')
+    .description('List available skills; --discover scans the workspace for more; --scaffold drafts a new one')
     .option(...configOpt)
     .option('--discover', 'scan the workspace for skill files elsewhere and report them')
+    .option('--scaffold <goal>', 'draft a *.skill.yaml manifest for a goal (asks before saving)')
+    .option('-y, --yes', 'with --scaffold, save the drafted skill without prompting')
     .option('--json', 'print as JSON')
     .action((o) => skillsCommand(o));
+// `mcp` — MCP servers. A subcommand-bearing group whose bare form lists, and `mcp <id>` details one.
+// Every path releases stdio children on completion (Runtime.close), so a one-shot command never orphans.
+const mcp = program.command('mcp').description('Inspect and manage MCP servers (tools from external servers)');
+mcp
+    .argument('[id]', 'a server id to show in detail')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((id, o) => mcpCommand(id, o));
+mcp
+    .command('add')
+    .argument('<id>', 'a short id for the server (lowercase, kebab/snake)')
+    .description('Add a server (stored locally — your config file is never modified)')
+    .option('--command <argv>', 'stdio server command line, e.g. "npx -y some-mcp-server"')
+    .option('--url <url>', 'streamable-HTTP endpoint')
+    .option('--token-env <NAME>', 'env-var NAME holding the credential (never the value itself)')
+    .option('--timeout <ms>', 'per-call timeout override')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((id, o) => mcpAddCommand(id, o));
+mcp
+    .command('remove')
+    .argument('<id>', 'server id')
+    .description('Remove a server that was added with `mcp add`')
+    .option(...configOpt)
+    .action((id, o) => mcpRemoveCommand(id, o));
+mcp
+    .command('enable')
+    .argument('<id>', 'server id')
+    .description('Enable a disabled server')
+    .option(...configOpt)
+    .action((id, o) => mcpEnableCommand(id, true, o));
+mcp
+    .command('disable')
+    .argument('<id>', 'server id')
+    .description('Disable a server without removing it')
+    .option(...configOpt)
+    .action((id, o) => mcpEnableCommand(id, false, o));
+mcp
+    .command('test')
+    .argument('<id>', 'server id')
+    .description('Connect, handshake, list tools, and ping — reporting exactly what happened')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((id, o) => mcpTestCommand(id, o));
 program
     .command('info')
     .description('Summarize the runtime: workspace, providers, skills, tools, memory, learning, storage')
@@ -90,13 +138,16 @@ program
     .description('List known models across providers')
     .option(...configOpt)
     .option('--json', 'print as JSON')
+    .option('--profile', 'show the models.md per-mode/per-task routing profile instead')
     .action((o) => modelsCommand(o));
 program
     .command('capabilities')
-    .description('Show the capability matrix by model')
+    .argument('[goal]', 'with --actions: which action capabilities this goal needs (offline — no model call)')
+    .description('Show the model capability matrix; --actions shows action capabilities (read_file, run_tests, …)')
     .option(...configOpt)
+    .option('--actions', 'show ACTION capabilities (what the runtime can do) instead of the model matrix')
     .option('--json', 'print as JSON')
-    .action((o) => capabilitiesCommand(o));
+    .action((goal, o) => capabilitiesCommand(goal, o));
 program
     .command('doctor')
     .description('Diagnose the runtime: config, .env, providers, models, store, skills, tools, permissions, git')

package/dist/cli/commands/cleanup.js

@@ -4,9 +4,9 @@
  * Nothing is deleted without confirmation unless `--yes`; `--dry-run` only reports the plan. Integrity
  * issues are reported, never auto-"repaired" destructively.
  */
-import { Runtime } from '../../runtime/runtime.js';
 import { TERMINAL } from '../../executions/execution.js';
 import { confirm } from '../prompt.js';
+import { withRuntime } from '../runtimeSession.js';
 import { print } from '../render.js';
 const DAY_MS = 86_400_000;
 function numEnv(v) {
@@ -67,30 +67,32 @@ function renderPlan(plan) {
     return lines;
 }
 export async function cleanupCommand(opts) {
-    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
-    if (!rt.store.enabled) {
-        print('storage is disabled (stateless mode) — nothing to clean.');
-        return;
-    }
-    const plan = planCleanup(rt, Date.now());
-    if (opts.json)
-        return print(JSON.stringify(plan, null, 2));
-    for (const line of renderPlan(plan))
-        print(line);
-    const removable = toRemove(plan);
-    if (removable === 0) {
-        print('\nNothing to remove.');
-        return;
-    }
-    if (opts.dryRun) {
-        print('\n(dry run — nothing was removed)');
-        return;
-    }
-    const ok = opts.yes || (await confirm(`\nRemove ${removable} item(s)?`));
-    if (!ok) {
-        print('cancelled — nothing was removed.');
-        return;
-    }
-    const done = applyCleanup(rt, plan);
-    print(`\nremoved: ${done.conversations} conversation(s), ${done.executions} execution(s), ${done.artifacts} artifact(s), ${done.cache} cache entr${done.cache === 1 ? 'y' : 'ies'}.`);
+    // Every Runtime-based command releases its Runtime (MCP children included) on every path.
+    return withRuntime(opts, async (rt) => {
+        if (!rt.store.enabled) {
+            print('storage is disabled (stateless mode) — nothing to clean.');
+            return;
+        }
+        const plan = planCleanup(rt, Date.now());
+        if (opts.json)
+            return print(JSON.stringify(plan, null, 2));
+        for (const line of renderPlan(plan))
+            print(line);
+        const removable = toRemove(plan);
+        if (removable === 0) {
+            print('\nNothing to remove.');
+            return;
+        }
+        if (opts.dryRun) {
+            print('\n(dry run — nothing was removed)');
+            return;
+        }
+        const ok = opts.yes || (await confirm(`\nRemove ${removable} item(s)?`));
+        if (!ok) {
+            print('cancelled — nothing was removed.');
+            return;
+        }
+        const done = applyCleanup(rt, plan);
+        print(`\nremoved: ${done.conversations} conversation(s), ${done.executions} execution(s), ${done.artifacts} artifact(s), ${done.cache} cache entr${done.cache === 1 ? 'y' : 'ies'}.`);
+    });
 }

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

@@ -4,6 +4,7 @@
  * Never prints a secret VALUE; all output is redacted. `--json` emits the structured report.
  */
 import { Runtime } from '../../runtime/runtime.js';
+import type { McpServerStatus } from '../../mcp/manager.js';
 import type { IntegrityIssue } from '../../store/area.js';
 export interface DoctorReport {
     configFile?: string;
@@ -36,6 +37,19 @@ export interface DoctorReport {
     };
     skills: string[];
     tools: string[];
+    /**
+     * MCP servers (Phase 3.3). ABSENT when none are configured, so a no-MCP `doctor --json` is unchanged.
+     * `connected: false` always: `doctor` is read-only and never connects (it is also the REPL `/doctor`
+     * path, and `gatherDoctor` is side-effect-free) — so states are as last recorded. `servers` reuses
+     * `McpServerStatus` VERBATIM, which is name-only for credentials (`tokenEnv` + `tokenSet`, never a
+     * value); adding any field beyond it would risk the secret-leak scan that stringifies this report.
+     */
+    mcp?: {
+        connected: boolean;
+        servers: McpServerStatus[];
+        grants: Record<string, string>;
+        warnings: string[];
+    };
     permissions: {
         fsRead: boolean;
         fsWrite: boolean;

package/dist/cli/commands/doctor.js

@@ -3,8 +3,9 @@
  * health, accessible models, the local store (integrity + counts), skills, tools, permissions, and git.
  * Never prints a secret VALUE; all output is redacted. `--json` emits the structured report.
  */
-import { Runtime } from '../../runtime/runtime.js';
+import { mcpRow } from './mcp.js';
 import { loadRuntimeConfig } from '../../runtime/config.js';
+import { withRuntime } from '../runtimeSession.js';
 import { print } from '../render.js';
 /** The credential env-var NAMES ai-runtime knows about (§16). Presence is reported, never the value. */
 const KNOWN_KEY_ENVS = [
@@ -45,6 +46,21 @@ export async function gatherDoctor(rt, configFile, env) {
         },
         skills: rt.skills().map((s) => `${s.id}@${s.version}`),
         tools: rt.tools().map((t) => t.id),
+        // No connectMcp(): doctor stays read-only. `list()` is id-sorted, so rendering is deterministic, and
+        // the spread makes the null-prototype grant map plain JSON.
+        ...(rt.hasMcpServers()
+            ? {
+                mcp: {
+                    // Truthful rather than hardcoded: `doctor` never CONNECTS, but the REPL's `/doctor` runs
+                    // against a session whose servers are already live, and reporting `false` there would be a
+                    // lie. This says whether any server is connected right now, not whether doctor connected it.
+                    connected: rt.mcp().list().some((sv) => sv.state === 'connected' || sv.state === 'degraded'),
+                    servers: rt.mcp().list(),
+                    grants: { ...rt.permissions().mcp.servers },
+                    warnings: rt.mcpWarningsList(),
+                },
+            }
+            : {}),
         permissions: { fsRead: perms.filesystem.read, fsWrite: perms.filesystem.write, shell: perms.shell.enabled, gitCommit: perms.git.commit, gitPush: perms.git.push, network: perms.network.enabled },
         git: { repo: !!ws?.git.isRepo, ...(ws?.git.branch ? { branch: ws.git.branch } : {}) },
     };
@@ -69,6 +85,18 @@ export function renderDoctor(r) {
         lines.push(`  ${r.store.conversations} conversation(s), ${r.store.executions} execution(s), ${r.store.memory} memory record(s), ${r.store.artifacts} artifact(s)`);
         lines.push(`  integrity: ${r.store.integrity.length ? `${r.store.integrity.length} issue(s) — ${r.store.integrity.map((i) => `${i.file} (${i.problem})`).join(', ')}` : 'ok'}`);
     }
+    if (r.mcp) {
+        lines.push('', `MCP servers (${r.mcp.connected ? 'live in this session' : 'as last recorded'} — \`doctor\` does not connect; run \`ai-runtime mcp\` for a live check):`);
+        if (!r.mcp.servers.length)
+            lines.push('  (none)');
+        for (const sv of r.mcp.servers)
+            lines.push(mcpRow(r.mcp.grants, sv));
+        const ungranted = r.mcp.servers.filter((sv) => !Object.prototype.hasOwnProperty.call(r.mcp.grants, sv.id) || r.mcp.grants[sv.id] === 'off').map((sv) => sv.id);
+        if (ungranted.length)
+            lines.push(`  not permitted to execute: ${ungranted.join(', ')} — grant permissions.mcp.servers.<id>: read (or full)`);
+        for (const w of r.mcp.warnings)
+            lines.push(`  ! ${w}`);
+    }
     lines.push('', `Skills:   ${r.skills.length ? r.skills.join(', ') : '(none)'}`);
     lines.push(`Tools:    ${r.tools.join(', ')}`);
     lines.push(`Perms:    fsRead=${r.permissions.fsRead} fsWrite=${r.permissions.fsWrite} shell=${r.permissions.shell} gitCommit=${r.permissions.gitCommit} gitPush=${r.permissions.gitPush} network=${r.permissions.network}`);
@@ -76,11 +104,13 @@ export function renderDoctor(r) {
     return lines;
 }
 export async function doctorCommand(opts) {
-    const loaded = loadRuntimeConfig({ workspaceRoot: process.cwd(), ...(opts.config ? { explicitPath: opts.config } : {}) });
-    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
-    const report = await gatherDoctor(rt, loaded.configFile, process.env);
-    if (opts.json)
-        return print(JSON.stringify(report, null, 2));
-    for (const line of renderDoctor(report))
-        print(line);
+    // Every Runtime-based command releases its Runtime (MCP children included) on every path.
+    return withRuntime(opts, async (rt) => {
+        const loaded = loadRuntimeConfig({ workspaceRoot: process.cwd(), ...(opts.config ? { explicitPath: opts.config } : {}) });
+        const report = await gatherDoctor(rt, loaded.configFile, process.env);
+        if (opts.json)
+            return print(JSON.stringify(report, null, 2));
+        for (const line of renderDoctor(report))
+            print(line);
+    });
 }

package/dist/cli/commands/executions.js

@@ -1,32 +1,41 @@
 /** `ai-runtime executions` (list) and `resume-execution <id>` — inspect and resume persisted work. */
-import { Runtime } from '../../runtime/runtime.js';
 import { print } from '../render.js';
+import { withRuntime } from '../runtimeSession.js';
 export async function executionsCommand(options) {
-    const rt = await Runtime.load({ ...(options.config ? { config: options.config } : {}) });
-    const list = rt.executions();
-    if (options.json)
-        return print(JSON.stringify(list, null, 2));
-    if (!list.length)
-        return print('No executions.');
-    print('Executions:');
-    for (const e of list)
-        print(`  ${e.id}  [${e.status}]  ${e.mode}: ${e.goal.slice(0, 60)}`);
+    return withRuntime(options, async (rt) => {
+        const list = rt.executions();
+        if (options.json)
+            return print(JSON.stringify(list, null, 2));
+        if (!list.length)
+            return print('No executions.');
+        print('Executions:');
+        for (const e of list)
+            print(`  ${e.id}  [${e.status}]  ${e.mode}: ${e.goal.slice(0, 60)}`);
+    });
 }
 export async function resumeExecutionCommand(id, options) {
-    const rt = await Runtime.load({ ...(options.config ? { config: options.config } : {}) });
-    // --approve proceeds past a waiting-for-approval gate; --deny cancels it. Neither → leave the decision.
-    const approve = options.approve ? true : options.deny ? false : undefined;
-    const r = await rt.resumeExecution(id, {
-        ...(options.answer ? { clarificationAnswer: options.answer } : {}),
-        ...(approve !== undefined ? { approve } : {}),
+    return withRuntime(options, async (rt) => {
+        // A resumed plan can execute MCP tool steps, so its servers must be connected — and released on the
+        // way out (withRuntime), or a live stdio child keeps the CLI from ever exiting.
+        if (rt.hasMcpServers()) {
+            await rt.connectMcp();
+            for (const w of rt.mcpWarningsList())
+                print(`! ${w}`);
+        }
+        // --approve proceeds past a waiting-for-approval gate; --deny cancels it. Neither → leave the decision.
+        const approve = options.approve ? true : options.deny ? false : undefined;
+        const r = await rt.resumeExecution(id, {
+            ...(options.answer ? { clarificationAnswer: options.answer } : {}),
+            ...(approve !== undefined ? { approve } : {}),
+        });
+        if (r.response?.text)
+            print(r.response.text);
+        print(`status: ${r.status}`);
+        if (r.status === 'waiting_for_approval')
+            print('(waiting for approval — re-run with --approve to proceed or --deny to cancel)');
+        if (r.clarification)
+            print(`? ${r.clarification.question}`);
+        if (!r.ok)
+            process.exitCode = 1;
     });
-    if (r.response?.text)
-        print(r.response.text);
-    print(`status: ${r.status}`);
-    if (r.status === 'waiting_for_approval')
-        print('(waiting for approval — re-run with --approve to proceed or --deny to cancel)');
-    if (r.clarification)
-        print(`? ${r.clarification.question}`);
-    if (!r.ok)
-        process.exitCode = 1;
 }

package/dist/cli/commands/info.d.ts

@@ -32,6 +32,7 @@ export interface InfoReport {
         home: string;
         project: string;
         enabled: boolean;
+        organization?: string;
     };
 }
 /** Gather the read-only info report from a loaded runtime. Pure aside from reading the local store. */

package/dist/cli/commands/info.js

@@ -3,9 +3,9 @@
  * providers/models, skills, tools, memory + learning stats, and storage paths. Makes NO live calls and
  * mutates nothing. `--json` prints the structured report.
  */
-import { Runtime } from '../../runtime/runtime.js';
 import { resolveContextBudget } from '../../context/budget.js';
 import { summarizeWorkspace } from '../../runtime/workspace/workspace.js';
+import { withRuntime } from '../runtimeSession.js';
 import { print } from '../render.js';
 /** Gather the read-only info report from a loaded runtime. Pure aside from reading the local store. */
 export async function gatherInfo(rt) {
@@ -31,7 +31,7 @@ export async function gatherInfo(rt) {
         tools: rt.tools().map((t) => t.id),
         memory: { enabled: rt.memory.enabled, facts },
         learning: { enabled: rt.learning.enabled, entries: learningSnap.length, preferredProviders: rt.learning.enabled ? rt.learning.preferredProviders() : [] },
-        storage: { home: paths.home, project: paths.project, enabled: rt.store.enabled },
+        storage: { home: paths.home, project: paths.project, enabled: rt.store.enabled, ...(paths.organization ? { organization: paths.organization } : {}) },
     };
 }
 export function renderInfo(r) {
@@ -40,14 +40,16 @@ export function renderInfo(r) {
         lines.push(`workspace:   ${r.workspace.name}${r.workspace.branch ? ` @ ${r.workspace.branch}` : ''}`, `             ${r.workspace.summary}`);
     else
         lines.push('workspace:   (none detected)');
-    lines.push(`mode:        ${r.defaultMode}`, `context:     ${r.contextBudgetTokens} token budget`, `providers:   ${r.providers.total} configured (${r.providers.enabled} enabled), ${r.models} models`, `skills:      ${r.skills.length ? r.skills.join(', ') : '(none — register tools to enable)'}`, `tools:       ${r.tools.join(', ')}`, `memory:      ${r.memory.enabled ? `${r.memory.facts} fact(s)` : 'disabled'}`, `learning:    ${r.learning.enabled ? `${r.learning.entries} record(s)${r.learning.preferredProviders.length ? `, prefers ${r.learning.preferredProviders.join(', ')}` : ''}` : 'disabled'}`, `storage:     ${r.storage.enabled ? r.storage.project : 'disabled (stateless)'}`);
+    lines.push(`mode:        ${r.defaultMode}`, `context:     ${r.contextBudgetTokens} token budget`, `providers:   ${r.providers.total} configured (${r.providers.enabled} enabled), ${r.models} models`, `skills:      ${r.skills.length ? r.skills.join(', ') : '(none — register tools to enable)'}`, `tools:       ${r.tools.join(', ')}`, `memory:      ${r.memory.enabled ? `${r.memory.facts} fact(s)` : 'disabled'}`, `learning:    ${r.learning.enabled ? `${r.learning.entries} record(s)${r.learning.preferredProviders.length ? `, prefers ${r.learning.preferredProviders.join(', ')}` : ''}` : 'disabled'}`, `storage:     ${r.storage.enabled ? r.storage.project : 'disabled (stateless)'}`, ...(r.storage.organization ? [`organization: ${r.storage.organization}`] : []));
     return lines;
 }
 export async function infoCommand(opts) {
-    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
-    const report = await gatherInfo(rt);
-    if (opts.json)
-        return print(JSON.stringify(report, null, 2));
-    for (const line of renderInfo(report))
-        print(line);
+    // Every Runtime-based command releases its Runtime (MCP children included) on every path.
+    return withRuntime(opts, async (rt) => {
+        const report = await gatherInfo(rt);
+        if (opts.json)
+            return print(JSON.stringify(report, null, 2));
+        for (const line of renderInfo(report))
+            print(line);
+    });
 }

package/dist/cli/commands/init.js

@@ -41,6 +41,24 @@ GEMINI_API_KEY=
 GROQ_API_KEY=
 ANTHROPIC_API_KEY=
 `;
+const EXAMPLE_MODELS = `# models.md — optional per-mode / per-task model routing (Phase 23). Uncomment and edit.
+# Each entry is a soft prefer (default), a hard pin (=provider:model), or a strategy keyword
+# (best|fastest|cheapest|highest-quality|local-only|cloud-only|privacy-first|provider-specific|
+# fallback-only, or 'free' → cheapest). Explicit per-run choices always win over this file.
+#
+# What applies where:
+#   - chat mode + '## By task' (router tasks via 'ai-runtime route <task>'): prefer, pin, AND strategy.
+#   - orchestration modes (plan/execute/orchestrate/agent/debug): soft PREFER only — a hard pin or a
+#     strategy is NOT applied there (the planner and skills pick their own models). Use prefer for those.
+#
+# ## By mode
+# - chat:     free                       # chat: cheapest/local models (strategy works here)
+# - plan:     anthropic:claude-sonnet-5  # orchestration: soft prefer a strong planning model
+# - execute:  openai:gpt-5               # orchestration: soft prefer
+#
+# ## By task
+# - generate-playwright-tests: =anthropic:claude-opus-5   # via 'ai-runtime route generate-playwright-tests'
+`;
 const GITIGNORE_ENTRIES = ['.env', '.env.*', '!.env.example', '.ai-runtime/'];
 function writeIfAbsent(file, contents) {
     const full = resolve(process.cwd(), file);
@@ -70,6 +88,7 @@ export function initCommand() {
     // and `setup` scaffold the same file. A root `ai-runtime.yaml` still works as a fallback if present.
     writeIfAbsent('.ai-runtime/config.yaml', EXAMPLE_YAML);
     writeIfAbsent('.env.example', EXAMPLE_ENV);
+    writeIfAbsent('models.md', EXAMPLE_MODELS);
     ensureGitignore();
     print('\nNext steps:');
     print('  1. Copy .env.example to .env and fill in the keys you have');

package/dist/cli/commands/inspect.d.ts

@@ -2,6 +2,8 @@
  * `ai-runtime providers` / `models` / `capabilities` — read-only inspection of the configured fleet.
  * All go through the key-free facade views and redacted output.
  */
+import { Runtime } from '../../runtime/runtime.js';
+import type { CapabilityGapReason, GapSuggestion, MissingCapabilityReport } from '../../capabilities/capability.js';
 export declare function providersCommand(opts: {
     config?: string;
     json?: boolean;
@@ -9,8 +11,45 @@ export declare function providersCommand(opts: {
 export declare function modelsCommand(opts: {
     config?: string;
     json?: boolean;
+    profile?: boolean;
 }): Promise<void>;
-export declare function capabilitiesCommand(opts: {
+/**
+ * Gather the ACTION-capability table (Phase 3.1). Uses a full Runtime (like `doctor`) so autoloaded
+ * skills appear — a listing that omitted them would misreport availability.
+ */
+export declare function actionCapabilityRows(rt: Runtime): Array<{
+    id: string;
+    provider: string;
+    source: string;
+    effects: string;
+    availability: string;
+    evidence: string;
+    description: string;
+}>;
+export declare function gatherActionCapabilities(config?: string): Promise<Array<{
+    id: string;
+    provider: string;
+    source: string;
+    effects: string;
+    availability: string;
+    evidence: string;
+    description: string;
+}>>;
+/** Render the action-capability table as aligned text (shared by the CLI and the REPL). */
+export declare function renderActionCapabilities(rows: Awaited<ReturnType<typeof gatherActionCapabilities>>): string[];
+/** One-line gloss per gap reason (exhaustive over CapabilityGapReason). */
+export declare const GAP_REASON_GLOSS: Record<CapabilityGapReason, string>;
+/** One actionable line per GapSuggestion (exhaustive over all four arms). */
+export declare function renderGapSuggestion(s: GapSuggestion): string;
+/**
+ * Render a MissingCapabilityReport. THE one gap renderer: `run`, the REPL result tail,
+ * `capabilities --actions <goal>` and `/capabilities <goal>` all call this, so they cannot drift.
+ * Every id, hint, and policyKey passes `displaySafe` — a gap's capabilityId originates in the model's
+ * plan JSON, and `sanitizeSegment` restricts its charset but sets no length bound.
+ */
+export declare function renderCapabilityGaps(report: MissingCapabilityReport): string[];
+export declare function capabilitiesCommand(goal: string | undefined, opts: {
     config?: string;
     json?: boolean;
+    actions?: boolean;
 }): Promise<void>;