ai-runtime-engine 1.3.0 → 2.8.0

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

package/dist/cli/commands/mcp.js

@@ -0,0 +1,148 @@
+/**
+ * `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 { withRuntime } from '../runtimeSession.js';
+import { print, printError } from '../render.js';
+import { KEY_LIKE } from '../../config/schema.js';
+function grantOf(grants, id) {
+    // Own-property checked, not `grants[id] ?? 'off'`. The resolved map is null-prototype, but a caller may
+    // hand us a plain object (doctor JSON-serializes it with a spread), and a server id like `constructor`
+    // is legal under the id regex — a prototype lookup would then answer with a function, which is both
+    // wrong on screen and a hole in deny-by-default.
+    return Object.prototype.hasOwnProperty.call(grants, id) ? String(grants[id]) : 'off';
+}
+export function mcpRow(grants, s) {
+    const tools = s.toolCount + (s.truncated ? '+' : '');
+    const notes = [s.rejectedTools ? `${s.rejectedTools} rejected` : '', s.tokenSet ? `token ${s.tokenEnv}` : ''].filter(Boolean).join(', ');
+    return `  ${s.id.padEnd(16)} ${s.state.padEnd(12)} ${s.transport.padEnd(6)} tools ${String(tools).padEnd(5)} grant ${grantOf(grants, s.id).padEnd(5)} ${s.origin === 'dynamic' ? '(added)' : ''}${notes ? `  ${notes}` : ''}`;
+}
+export function renderMcpList(grants, list) {
+    if (!list.length) {
+        return ['No MCP servers configured.', '', 'Add one:  ai-runtime mcp add <id> --command "npx -y some-mcp-server"', '          ai-runtime mcp add <id> --url https://example.com/mcp --token-env MY_TOKEN'];
+    }
+    const lines = ['MCP servers:', ...list.map((s) => mcpRow(grants, s))];
+    const ungranted = list.filter((s) => grantOf(grants, s.id) === 'off');
+    if (ungranted.length) {
+        lines.push('', `Not permitted to execute: ${ungranted.map((s) => s.id).join(', ')}`, '  Grant in .ai-runtime/config.yaml:  permissions.mcp.servers.<id>: read   (or full)');
+    }
+    return lines;
+}
+export function renderMcpDetail(grants, s, diagnostics, tools) {
+    const lines = [
+        `MCP server '${s.id}'`,
+        `  state        ${s.state}${s.lastError ? ` — ${s.lastError}` : ''}`,
+        `  transport    ${s.transport}${s.endpoint ? `  ${s.endpoint}` : ''}`,
+        `  origin       ${s.origin === 'dynamic' ? 'added (store)' : 'config'}`,
+        `  enabled      ${s.enabled}`,
+        `  credential   ${s.tokenSet ? `set via ${s.tokenEnv}` : s.tokenEnv ? `${s.tokenEnv} (NOT set)` : 'none'}`,
+        `  grant        ${grantOf(grants, s.id)}`,
+        `  protocol     ${s.protocolVersion ?? '(not negotiated)'}${s.serverName ? `  server: ${s.serverName}` : ''}`,
+        `  tools        ${s.toolCount}${s.truncated ? ' (truncated — the server offers more than we accept)' : ''}${s.rejectedTools ? `, ${s.rejectedTools} rejected as unsafe` : ''}`,
+    ];
+    if (tools.length) {
+        lines.push('', '  Tools:');
+        for (const t of tools)
+            lines.push(`    ${t.name.padEnd(28)} ${t.readOnly ? 'read ' : 'write'}${t.destructive ? ' destructive' : ''}  ${t.description}`);
+    }
+    if (diagnostics.length) {
+        lines.push('', '  Recent diagnostics (redacted):');
+        for (const d of diagnostics)
+            lines.push(`    ${d}`);
+    }
+    return lines;
+}
+export async function mcpCommand(id, opts) {
+    await withRuntime(opts, async (rt) => {
+        if (!rt.hasMcpServers()) {
+            if (opts.json)
+                return print(JSON.stringify({ servers: [] }, null, 2));
+            return print(renderMcpList(rt.permissions().mcp.servers, []).join('\n'));
+        }
+        await rt.connectMcp();
+        if (!id) {
+            const list = rt.mcp().list();
+            if (opts.json)
+                return print(JSON.stringify({ servers: list, warnings: rt.mcpWarningsList() }, null, 2));
+            const lines = renderMcpList(rt.permissions().mcp.servers, list);
+            const warnings = rt.mcpWarningsList();
+            if (warnings.length)
+                lines.push('', 'Warnings:', ...warnings.map((w) => `  ! ${w}`));
+            return print(lines.join('\n'));
+        }
+        const status = rt.mcp().status(id);
+        if (!status)
+            return printError(`no MCP server '${id}' — run 'ai-runtime mcp' to list them`);
+        const tools = rt.mcp().tools(id);
+        if (opts.json)
+            return print(JSON.stringify({ server: status, tools, diagnostics: rt.mcp().diagnostics(id) }, null, 2));
+        print(renderMcpDetail(rt.permissions().mcp.servers, status, rt.mcp().diagnostics(id), tools).join('\n'));
+    });
+}
+export async function mcpAddCommand(id, opts) {
+    await withRuntime(opts, async (rt) => {
+        if (!opts.command && !opts.url)
+            return printError('specify either --command "<argv>" (stdio) or --url <endpoint> (http)');
+        if (opts.command && opts.url)
+            return printError('a server is either stdio (--command) or http (--url), not both');
+        // --token-env takes a NAME. Refuse a value here, before it would be written to the store in plain
+        // text and echoed back to the terminal (the manager refuses too; this is the friendly message).
+        if (opts.tokenEnv && KEY_LIKE.test(opts.tokenEnv)) {
+            return printError('--token-env takes the NAME of an environment variable, not the token itself (e.g. --token-env GITHUB_MCP_TOKEN)');
+        }
+        const argv = (opts.command ?? '').trim().split(/\s+/).filter(Boolean);
+        const cfg = opts.url
+            ? { transport: 'http', url: opts.url, ...(opts.tokenEnv ? { tokenEnv: opts.tokenEnv } : {}), ...(opts.timeout ? { timeoutMs: Number(opts.timeout) } : {}) }
+            : { transport: 'stdio', command: argv[0], ...(argv.length > 1 ? { args: argv.slice(1) } : {}), ...(opts.tokenEnv ? { tokenEnv: opts.tokenEnv } : {}), ...(opts.timeout ? { timeoutMs: Number(opts.timeout) } : {}) };
+        try {
+            const status = await rt.mcp().addServer(id, cfg);
+            if (opts.json)
+                return print(JSON.stringify({ ok: true, server: status }, null, 2));
+            print(renderMcpDetail(rt.permissions().mcp.servers, status, rt.mcp().diagnostics(id), rt.mcp().tools(id)).join('\n'));
+            print(`\nAdded '${id}' (stored locally — your config file was not modified).`);
+            print(`It can execute nothing yet. Grant it in .ai-runtime/config.yaml:\n  permissions:\n    mcp:\n      servers:\n        ${id}: read   # or full`);
+        }
+        catch (e) {
+            printError(e instanceof Error ? e.message : String(e));
+        }
+    });
+}
+export async function mcpRemoveCommand(id, opts) {
+    await withRuntime(opts, async (rt) => {
+        const res = rt.mcp().removeServer(id);
+        if (!res.ok)
+            return printError(res.reason ?? `could not remove '${id}'`);
+        print(`Removed MCP server '${id}'.`);
+    });
+}
+export async function mcpEnableCommand(id, enabled, opts) {
+    await withRuntime(opts, async (rt) => {
+        const res = rt.mcp().setEnabled(id, enabled);
+        if (!res.ok)
+            return printError(res.reason ?? `no MCP server '${id}'`);
+        print(`MCP server '${id}' is now ${enabled ? 'enabled' : 'disabled'}.`);
+    });
+}
+export async function mcpTestCommand(id, opts) {
+    await withRuntime(opts, async (rt) => {
+        if (!rt.mcp().status(id))
+            return printError(`no MCP server '${id}' — run 'ai-runtime mcp' to list them`);
+        const res = await rt.mcp().test(id);
+        if (opts.json)
+            return print(JSON.stringify(res, null, 2));
+        const lines = renderMcpDetail(rt.permissions().mcp.servers, res, rt.mcp().diagnostics(id), rt.mcp().tools(id));
+        if (res.pingMs !== undefined)
+            lines.push(`  ping         ${res.pingMs}ms`);
+        print(lines.join('\n'));
+    });
+}

package/dist/cli/commands/route.js

@@ -6,6 +6,7 @@
 import { buildDemoAI } from '../../providers/mock/demo.js';
 import { loadAI } from '../context.js';
 import { print } from '../render.js';
+import { loadModelProfile, resolveModelDirective, directiveToOverrides } from '../../runtime/models/modelProfile.js';
 export async function routeCommand(task, options) {
     const loaded = loadAI(options.config);
     const ai = loaded.hasProviders ? loaded.ai : buildDemoAI();
@@ -18,6 +19,26 @@ export async function routeCommand(task, options) {
         request.provider = options.provider;
     if (options.model)
         request.model = options.model;
+    // models.md (Phase 23): a `## By task` entry for this router task steers routing — a strategy, a soft
+    // prefer (merged into request.routing), or a hard pin — but only where the caller passed no explicit
+    // flag (explicit -s/-p/-m win). This is where per-TASK routing applies (the Runtime handles per-MODE).
+    const profile = loadModelProfile(process.cwd());
+    const directive = profile ? resolveModelDirective(profile, { task }) : undefined;
+    if (directive) {
+        const o = directiveToOverrides(directive);
+        if (o.strategy && request.strategy === undefined)
+            request.strategy = o.strategy;
+        if (o.routing)
+            request.routing = { ...o.routing, ...request.routing };
+        // A pin is atomic (provider+model together) — apply it only when the caller pinned NEITHER, so an
+        // explicit -p/-m is never combined with the profile's pin into an impossible provider/model pair.
+        if ((o.provider || o.model) && request.provider === undefined && request.model === undefined) {
+            if (o.provider)
+                request.provider = o.provider;
+            if (o.model)
+                request.model = o.model;
+        }
+    }
     const result = await ai.run(request);
     if (options.json) {
         print(JSON.stringify(result, null, 2));

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

@@ -8,5 +8,6 @@ export interface RunOptions {
     json?: boolean;
     dryRun?: boolean;
     stream?: boolean;
+    partial?: boolean;
 }
 export declare function runCommand(input: string, options: RunOptions): Promise<void>;

package/dist/cli/commands/run.js

@@ -2,14 +2,27 @@
  * `ai-runtime run "<input>"` — one-shot Runtime invocation for CI/scripts. Shares the exact Runtime
  * the interactive REPL uses. Prints the response (or a structured result with --json).
  */
-import { Runtime } from '../../runtime/runtime.js';
+import { withRuntime } from '../runtimeSession.js';
 import { print, printChunk } from '../render.js';
+import { renderCapabilityGaps } from './inspect.js';
 import { RUNTIME_MODES } from '../../runtime/types.js';
 export async function runCommand(input, options) {
-    const rt = await Runtime.load({ ...(options.config ? { config: options.config } : {}) });
+    // withRuntime releases MCP stdio children on every path — a one-shot command never orphans a process.
+    return withRuntime(options, (rt) => runWith(rt, input, options));
+}
+async function runWith(rt, input, options) {
+    // Lazy MCP connect, per command class: `run` may plan and execute tools, so its catalog must include
+    // MCP tools. A command that cannot execute tools pays nothing (it never calls this).
+    if (rt.hasMcpServers()) {
+        await rt.connectMcp();
+        for (const w of rt.mcpWarningsList())
+            print(`! ${w}`);
+    }
     const req = { input };
     if (options.dryRun)
         req.dryRun = true;
+    if (options.partial)
+        req.partial = true;
     // --stream renders tokens live (incompatible with --json, which needs the whole object).
     let streamedAny = false;
     if (options.stream && !options.json) {
@@ -45,6 +58,12 @@ export async function runCommand(input, options) {
     if (result.error)
         print(`[${result.error.category}] ${result.error.message}`);
     // Any un-ok result (a router error OR a failed plan/execute/orchestrate) is a non-zero exit for CI.
+    // Phase 3.3: the ONE gap renderer, shared with the REPL and both capabilities surfaces. `--json`
+    // already dumps the whole result, so this is text-mode only. A gap is metadata on an outcome, so
+    // the exit code below is unchanged — it is never a new failure class.
+    if (result.capabilityGaps)
+        for (const l of renderCapabilityGaps(result.capabilityGaps))
+            print(l);
     if (!result.ok)
         process.exitCode = 1;
 }

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

@@ -25,4 +25,6 @@ export declare function skillsCommand(opts: {
     config?: string;
     discover?: boolean;
     json?: boolean;
+    scaffold?: string;
+    yes?: boolean;
 }): Promise<void>;

package/dist/cli/commands/skills.js

@@ -4,8 +4,9 @@
  * them without loading — the user enables one by moving it into `.ai-runtime/skills/` or adding its path to
  * `skills.paths` in config (loading a module runs its code, so it is never implicit).
  */
-import { Runtime } from '../../runtime/runtime.js';
+import { withRuntime } from '../runtimeSession.js';
 import { print } from '../render.js';
+import { confirm } from '../prompt.js';
 export async function gatherSkills(rt, discover) {
     const sources = rt.skillSources();
     const sourceById = new Map();
@@ -39,10 +40,31 @@ function renderSkills(r, discover) {
     return lines;
 }
 export async function skillsCommand(opts) {
-    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
-    const report = await gatherSkills(rt, !!opts.discover);
-    if (opts.json)
-        return print(JSON.stringify(report, null, 2));
-    for (const line of renderSkills(report, !!opts.discover))
-        print(line);
+    // Every Runtime-based command releases its Runtime (MCP children included) on every path.
+    return withRuntime(opts, async (rt) => {
+        // `--scaffold "<goal>"` drafts a *.skill.yaml manifest via the model and offers to save it (never writes
+        // without confirmation; the model emits validated CONFIG, never code).
+        if (opts.scaffold) {
+            const draft = await rt.scaffoldSkill(opts.scaffold);
+            if (!draft.ok || !draft.manifest || !draft.yaml) {
+                if (opts.json)
+                    return print(JSON.stringify({ ok: false, error: draft.error }, null, 2));
+                return print(`Could not scaffold a skill: ${draft.error}`);
+            }
+            if (opts.json)
+                return print(JSON.stringify({ ok: true, manifest: draft.manifest, yaml: draft.yaml }, null, 2));
+            print(`Drafted skill "${draft.manifest.id}":\n`);
+            print(draft.yaml);
+            const proceed = opts.yes || (await confirm(`Save to .ai-runtime/skills/${draft.manifest.id}.skill.yaml?`));
+            if (!proceed)
+                return print('Not saved. (Re-run with --yes to save without prompting.)');
+            const path = rt.saveScaffoldedSkill(draft.manifest);
+            return print(`Saved ${path}`);
+        }
+        const report = await gatherSkills(rt, !!opts.discover);
+        if (opts.json)
+            return print(JSON.stringify(report, null, 2));
+        for (const line of renderSkills(report, !!opts.discover))
+            print(line);
+    });
 }

package/dist/cli/interactive/ansi.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Zero-dependency ANSI helpers for the REPL (Phase 21b). Color/bold are applied ONLY when the output is an
+ * interactive TTY and the environment permits it (`NO_COLOR` unset, `TERM` not "dumb") — so piped/CI output
+ * stays plain and the line-based session tests are unaffected. Every helper is pure and returns a string;
+ * the caller decides where to write it (always through `redactString` at the render layer).
+ */
+export interface ColorOptions {
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/** Whether ANSI color should be emitted: an interactive TTY, `NO_COLOR` unset, and a non-dumb terminal. */
+export declare function colorEnabled(opts?: ColorOptions): boolean;
+declare const CODES: {
+    readonly reset: 0;
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly red: 31;
+    readonly green: 32;
+    readonly yellow: 33;
+    readonly blue: 34;
+    readonly magenta: 35;
+    readonly cyan: 36;
+    readonly gray: 90;
+};
+type CodeName = keyof typeof CODES;
+/** Wrap `text` in the named SGR code when `enabled`; otherwise return it unchanged. */
+export declare function style(text: string, code: CodeName, enabled: boolean): string;
+export declare const bold: (t: string, on: boolean) => string;
+export declare const dim: (t: string, on: boolean) => string;
+export declare const green: (t: string, on: boolean) => string;
+export declare const red: (t: string, on: boolean) => string;
+export declare const yellow: (t: string, on: boolean) => string;
+export declare const cyan: (t: string, on: boolean) => string;
+export declare const gray: (t: string, on: boolean) => string;
+/** Frames for an in-place spinner. */
+export declare const SPINNER_FRAMES: string[];
+/** A carriage-return status line (`\r` + clear-to-EOL + text). Empty string when color/TTY is off. */
+export declare function statusLine(text: string, enabled: boolean): string;
+/** Clear the current line in place (`\r` + clear-to-EOL). Empty string when color/TTY is off. */
+export declare function clearLine(enabled: boolean): string;
+export {};

package/dist/cli/interactive/ansi.js

@@ -0,0 +1,43 @@
+/**
+ * Zero-dependency ANSI helpers for the REPL (Phase 21b). Color/bold are applied ONLY when the output is an
+ * interactive TTY and the environment permits it (`NO_COLOR` unset, `TERM` not "dumb") — so piped/CI output
+ * stays plain and the line-based session tests are unaffected. Every helper is pure and returns a string;
+ * the caller decides where to write it (always through `redactString` at the render layer).
+ */
+/** Whether ANSI color should be emitted: an interactive TTY, `NO_COLOR` unset, and a non-dumb terminal. */
+export function colorEnabled(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (!opts.isTTY)
+        return false;
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return false;
+    if (env.TERM === 'dumb')
+        return false;
+    return true;
+}
+const CODES = { reset: 0, bold: 1, dim: 2, red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, gray: 90 };
+/** Wrap `text` in the named SGR code when `enabled`; otherwise return it unchanged. */
+export function style(text, code, enabled) {
+    if (!enabled)
+        return text;
+    return `[${CODES[code]}m${text}[${CODES.reset}m`;
+}
+export const bold = (t, on) => style(t, 'bold', on);
+export const dim = (t, on) => style(t, 'dim', on);
+export const green = (t, on) => style(t, 'green', on);
+export const red = (t, on) => style(t, 'red', on);
+export const yellow = (t, on) => style(t, 'yellow', on);
+export const cyan = (t, on) => style(t, 'cyan', on);
+export const gray = (t, on) => style(t, 'gray', on);
+/** Frames for an in-place spinner. */
+export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/** A carriage-return status line (`\r` + clear-to-EOL + text). Empty string when color/TTY is off. */
+export function statusLine(text, enabled) {
+    if (!enabled)
+        return '';
+    return `\r${text}`;
+}
+/** Clear the current line in place (`\r` + clear-to-EOL). Empty string when color/TTY is off. */
+export function clearLine(enabled) {
+    return enabled ? '\r' : '';
+}

package/dist/cli/interactive/complete.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Slash-command tab-completion for the REPL (Phase 21b). A pure `node:readline`-shaped completer: given the
+ * current line, return `[matches, lineToComplete]`. It completes ONLY the leading command token of a `/…`
+ * line — never natural-language input and never command arguments — so it can't interfere with typing.
+ */
+/** readline completer contract: `[completions, substringBeingCompleted]`. */
+export type CompleterResult = [string[], string];
+export declare function completeSlash(line: string, commands: readonly string[]): CompleterResult;
+/** Build a `node:readline`-compatible completer bound to a command list. */
+export declare function makeCompleter(commands: readonly string[]): (line: string) => CompleterResult;

package/dist/cli/interactive/complete.js

@@ -0,0 +1,19 @@
+/**
+ * Slash-command tab-completion for the REPL (Phase 21b). A pure `node:readline`-shaped completer: given the
+ * current line, return `[matches, lineToComplete]`. It completes ONLY the leading command token of a `/…`
+ * line — never natural-language input and never command arguments — so it can't interfere with typing.
+ */
+export function completeSlash(line, commands) {
+    const trimmed = line.trimStart();
+    // Only a bare `/command` prefix (no space yet) is completed; args and plain text are left alone.
+    if (!trimmed.startsWith('/') || /\s/.test(trimmed))
+        return [[], line];
+    const prefix = trimmed.slice(1).toLowerCase();
+    const hits = commands.filter((c) => c.startsWith(prefix)).map((c) => `/${c}`);
+    // When there is exactly one full match already typed, offer nothing (avoids a redundant redraw).
+    return [hits, line];
+}
+/** Build a `node:readline`-compatible completer bound to a command list. */
+export function makeCompleter(commands) {
+    return (line) => completeSlash(line, commands);
+}