ai-runtime-engine 1.2.0 → 2.7.0

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>;

package/dist/cli/commands/inspect.js

@@ -3,7 +3,18 @@
  * All go through the key-free facade views and redacted output.
  */
 import { loadAI } from '../context.js';
-import { print } from '../render.js';
+import { withRuntime } from '../runtimeSession.js';
+import { print, displaySafe } from '../render.js';
+import { loadModelProfile } from '../../runtime/models/modelProfile.js';
+import { candidatesFrom, deriveCapabilitiesOffline } from '../../runtime/planning/deriveCapabilities.js';
+/** Render one models.md directive compactly. */
+function describeDirective(d) {
+    if (d.kind === 'strategy')
+        return `strategy: ${d.strategy}`;
+    if (d.kind === 'pin')
+        return `pin: ${d.provider ?? ''}${d.model ? ':' + d.model : ''}`;
+    return `prefer: ${[...new Set([...d.models, ...d.providers])].join(', ')}`;
+}
 export async function providersCommand(opts) {
     const { ai, hasProviders } = loadAI(opts.config);
     if (!hasProviders)
@@ -20,6 +31,30 @@ export async function providersCommand(opts) {
     }
 }
 export async function modelsCommand(opts) {
+    // `--profile` prints the loaded models.md routing profile (per-mode / per-task directives) instead.
+    if (opts.profile) {
+        const profile = loadModelProfile(process.cwd());
+        if (!profile)
+            return print('No models.md found (workspace root or .ai-runtime/models.md).');
+        if (opts.json)
+            return print(JSON.stringify(profile, null, 2));
+        print('Model routing (models.md):');
+        const byMode = Object.entries(profile.byMode);
+        const byTask = Object.entries(profile.byTask);
+        if (byMode.length) {
+            print('  By mode:');
+            for (const [k, d] of byMode)
+                print(`    ${k.padEnd(12)} ${describeDirective(d)}`);
+        }
+        if (byTask.length) {
+            print('  By task:');
+            for (const [k, d] of byTask)
+                print(`    ${k.padEnd(28)} ${describeDirective(d)}`);
+        }
+        if (!byMode.length && !byTask.length)
+            print('  (empty)');
+        return;
+    }
     const { ai, hasProviders } = loadAI(opts.config);
     if (!hasProviders)
         return print('No providers configured.');
@@ -36,7 +71,126 @@ export async function modelsCommand(opts) {
     }
 }
 const GROUPS = ['input', 'output', 'intelligence', 'agent'];
-export async 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 function actionCapabilityRows(rt) {
+    const reg = rt.capabilities();
+    const rows = [];
+    for (const cap of reg.list()) {
+        for (const p of reg.providersOf(cap.id)) {
+            rows.push({ id: cap.id, provider: p.providerId, source: p.source, effects: p.effects.join('/'), availability: p.availability, evidence: p.verification, description: cap.description });
+        }
+    }
+    return rows;
+}
+export async function gatherActionCapabilities(config) {
+    return withRuntime({ ...(config ? { config } : {}) }, async (rt) => {
+        // This command's whole purpose is an accurate picture of what the runtime can do, so it DOES connect
+        // (the lazy rule is per command class): reporting a cache-seeded MCP tool's fail-closed placeholders
+        // as if they were the server's real annotations would be the wrong kind of honest.
+        if (rt.hasMcpServers())
+            await rt.connectMcp();
+        return actionCapabilityRows(rt);
+    });
+}
+/** Render the action-capability table as aligned text (shared by the CLI and the REPL). */
+export function renderActionCapabilities(rows) {
+    if (rows.length === 0)
+        return ['No action capabilities registered.'];
+    const lines = ['Action capabilities (what this runtime can DO, and who provides it):'];
+    for (const r of rows)
+        lines.push(`  ${r.id.padEnd(22)} ${r.provider.padEnd(26)} ${r.source.padEnd(8)} ${r.effects.padEnd(10)} ${r.availability.padEnd(12)} ${r.evidence}`);
+    return lines;
+}
+/** One-line gloss per gap reason (exhaustive over CapabilityGapReason). */
+export const GAP_REASON_GLOSS = {
+    unknown: 'nothing registered provides it',
+    unavailable: 'its provider is not usable right now',
+    disabled: 'its provider is turned off',
+    permission: 'the runtime is not allowed to do this',
+};
+/** One actionable line per GapSuggestion (exhaustive over all four arms). */
+export function renderGapSuggestion(s) {
+    switch (s.kind) {
+        case 'grant-permission':
+            return `grant ${displaySafe(s.policyKey, 60)} in .ai-runtime/config.yaml`;
+        case 'enable-server':
+            return `enable the MCP server '${displaySafe(s.serverId, 40)}' (ai-runtime mcp enable ${displaySafe(s.serverId, 40)}) and grant permissions.mcp.servers.${displaySafe(s.serverId, 40)}`;
+        case 'register':
+            return displaySafe(s.hint, 160);
+        case 'install-skill':
+            return displaySafe(s.hint, 160);
+    }
+}
+/**
+ * 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 function renderCapabilityGaps(report) {
+    if (report.required.length === 0)
+        return [];
+    // "appears to need": derivation is a lexical inference over capability descriptions, and a plan step's
+    // provider can do more than the step will. The rows are advice, and the wording says so.
+    const lines = ['', 'Capabilities this goal appears to need:'];
+    for (const r of report.required) {
+        const gloss = r.status === 'available' ? displaySafe(r.providers.join(', '), 60) : GAP_REASON_GLOSS[r.status];
+        lines.push(`  ${r.status === 'available' ? '✓' : '✗'} ${displaySafe(r.capabilityId, 30).padEnd(30)} ${r.status.padEnd(12)} ${gloss}`);
+    }
+    if (!report.gaps.length)
+        return lines;
+    const fixes = report.suggestions.map(renderGapSuggestion);
+    // A gap with an EMPTY suggestions array is reachable (every provider disabled, none MCP-sourced), so a
+    // gap is never printed without a remedy line.
+    for (const g of report.gaps) {
+        if (!g.suggestions.length)
+            fixes.push(`no automatic remedy for '${displaySafe(g.capabilityId, 30)}' — see \`ai-runtime capabilities --actions\``);
+    }
+    lines.push('To fix:', ...fixes.map((f) => `  • ${f}`));
+    return lines;
+}
+/**
+ * `capabilities --actions <goal>` — a free, OFFLINE "can you do this?" pre-flight. No model call and no
+ * provider needed: derivation is pure BM25 over the registry and resolution is pure, so this answers
+ * correctly with `providers: []` and no network.
+ */
+async function actionsForGoal(goal, opts) {
+    return withRuntime({ ...(opts.config ? { config: opts.config } : {}) }, async (rt) => {
+        if (rt.hasMcpServers())
+            await rt.connectMcp();
+        const required = deriveCapabilitiesOffline(goal, candidatesFrom(rt.capabilities().list()));
+        if (!required.length) {
+            // `--json` must stay machine-readable on EVERY path — a consumer that asked for JSON and got prose
+            // has to special-case it.
+            if (opts.json)
+                return print(JSON.stringify({ goal: displaySafe(goal, 200), required: [], gaps: [], suggestions: [] }, null, 2));
+            return print(`No action capability matched ${JSON.stringify(displaySafe(goal, 80))} — run \`ai-runtime capabilities --actions\` to see everything this runtime can do.`);
+        }
+        const report = rt.capabilityReport(required);
+        if (opts.json)
+            return print(JSON.stringify(report, null, 2));
+        for (const line of renderCapabilityGaps(report))
+            print(line);
+    });
+}
+export async function capabilitiesCommand(goal, opts) {
+    // `--actions` shows ACTION capabilities (Phase 3.1); the default stays the MODEL capability matrix.
+    // With a goal, `--actions` answers "what does THIS need, and what is missing?" — offline (Phase 3.3).
+    // A goal only means anything for action capabilities (the model matrix takes no goal), so a goal
+    // IMPLIES --actions rather than being silently discarded.
+    if (goal)
+        return actionsForGoal(goal, opts);
+    if (opts.actions) {
+        const rows = await gatherActionCapabilities(opts.config);
+        if (opts.json)
+            return print(JSON.stringify(rows, null, 2));
+        for (const line of renderActionCapabilities(rows))
+            print(line);
+        return;
+    }
     const { ai, hasProviders } = loadAI(opts.config);
     if (!hasProviders)
         return print('No providers configured.');
@@ -57,4 +211,5 @@ export async function capabilitiesCommand(opts) {
             print(`    context       ${ctx.value} (${ctx.evidence})`);
         }
     }
+    print('\n(model capabilities — use `--actions` for action capabilities: read_file, run_tests, …)');
 }

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

@@ -0,0 +1,45 @@
+/**
+ * `ai-runtime mcp` — inspect and manage MCP servers (Phase 3.2).
+ *
+ *   mcp                       list every configured server with its state, tool count, and grant
+ *   mcp <id>                  one server in detail, including redacted diagnostics
+ *   mcp add <id> …            add a server — persisted to the STORE, never to config.yaml
+ *   mcp remove <id>           remove a store-added server (a config-declared one is the operator's file)
+ *   mcp enable|disable <id>   flip a server without editing anything
+ *   mcp test <id>             connect, handshake, list tools, ping — and report honestly
+ *
+ * Credentials are named, never valued: `--token-env NAME` records an env-var NAME, and nothing here ever
+ * prints a token value. Every server-supplied string reaching this output has already passed the
+ * discovery-time normalization gate, so a server cannot forge a row.
+ */
+import type { McpServerStatus } from '../../mcp/manager.js';
+/**
+ * The per-server grant map (`permissions.mcp.servers`), passed to the renderers instead of a Runtime so
+ * they stay Runtime-free — `mcp`, the REPL `/mcp`, and `doctor` therefore share ONE formatter and can
+ * never disagree. The map is null-prototype (src/tools/permissions.ts), so `?? 'off'` is correct for
+ * every key, configured or not.
+ */
+export type McpGrants = Record<string, string>;
+export declare function mcpRow(grants: McpGrants, s: McpServerStatus): string;
+export declare function renderMcpList(grants: McpGrants, list: McpServerStatus[]): string[];
+export declare function renderMcpDetail(grants: McpGrants, s: McpServerStatus, diagnostics: string[], tools: Array<{
+    name: string;
+    description: string;
+    readOnly: boolean;
+    destructive: boolean;
+}>): string[];
+export interface McpCommandOptions {
+    config?: string;
+    json?: boolean;
+    /** add: */
+    command?: string;
+    args?: string;
+    url?: string;
+    tokenEnv?: string;
+    timeout?: string;
+}
+export declare function mcpCommand(id: string | undefined, opts: McpCommandOptions): Promise<void>;
+export declare function mcpAddCommand(id: string, opts: McpCommandOptions): Promise<void>;
+export declare function mcpRemoveCommand(id: string, opts: McpCommandOptions): Promise<void>;
+export declare function mcpEnableCommand(id: string, enabled: boolean, opts: McpCommandOptions): Promise<void>;
+export declare function mcpTestCommand(id: string, opts: McpCommandOptions): Promise<void>;