ai-runtime-engine 1.3.0 → 2.8.0

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

@@ -0,0 +1,69 @@
+/**
+ * Multi-lane agent display (Phase 3.6) — concurrent agent steps as live rows in the REPL.
+ *
+ * PURE BY CONSTRUCTION. Nothing here reads `process.stdout`, a clock, or an environment variable: the
+ * terminal width, whether colour is on, and every value rendered are parameters. That is what makes a
+ * terminal feature testable offline and deterministically, and it is the rule to keep — the moment this
+ * module reads the real terminal, its tests start describing the machine they ran on.
+ *
+ * WRAPPING IS MADE IMPOSSIBLE RATHER THAN HANDLED. In-place rewriting works by moving the cursor up N
+ * rows, which is only correct while one logical line occupies exactly one physical row. So every line is
+ * clamped to `cols - 1`: no line ever reaches the final column, nothing wraps, and the arithmetic is
+ * exact. Lines are built as plain text, clamped, and styled last, so the clamp never has to count
+ * invisible escape bytes.
+ */
+import type { RuntimeEvent } from '../../runtime/events.js';
+export interface AgentLane {
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    /** `running` covers started + progress; the terminal states come from the completion event. */
+    state: 'running' | 'completed' | 'failed' | 'cancelled' | 'waiting';
+    succeeded: number;
+    total: number;
+    callsUsed: number;
+    findings: number;
+}
+/** Display width in terminal columns, not code units. */
+export declare function displayWidth(text: string): number;
+/** Truncate to `cols` display columns, never splitting a surrogate pair or half a wide glyph. */
+export declare function sliceColumns(text: string, cols: number): string;
+/**
+ * Accumulates agent lanes from the event stream. Insertion-ordered, so lanes do not jump around between
+ * frames — a display that reorders itself is unreadable even when every value in it is right.
+ */
+export declare class LaneSet {
+    private readonly lanes;
+    /**
+     * Fold one event in. Returns the lane it touched, or `undefined` for an event that is not an agent
+     * event — a lane rather than a boolean, so the caller neither re-narrows the event nor looks the lane
+     * up a second time.
+     */
+    observe(event: RuntimeEvent): AgentLane | undefined;
+    list(): AgentLane[];
+    /** True once at least one lane exists and none is still in flight. */
+    settled(): boolean;
+    clear(): void;
+}
+/**
+ * Render the lanes as one line each. `tick` animates the running marker; it is a parameter rather than a
+ * timer so a test can render frame 3 without waiting for it.
+ */
+export declare function laneLines(lanes: AgentLane[], opts: {
+    cols: number;
+    colors: boolean;
+    tick: number;
+}): string[];
+/**
+ * Rewrite an owned region of the terminal in place, returning the bytes to write.
+ *
+ * `prevRows === 0` opens the region at the cursor's current line. Otherwise the cursor is assumed to be
+ * on the region's LAST row (which is where this function always leaves it) and walks up from there.
+ *
+ * The cursor never ends on a fresh line below the frame: a trailing newline on the terminal's last row
+ * scrolls the viewport, and the next frame's `cursorUp` would then land one row high and duplicate the
+ * region on every tick, forever.
+ */
+export declare function frameDiff(prevRows: number, lines: string[], enabled: boolean): string;
+/** How many rows `frameDiff` will have left behind — the `prevRows` for the next call. */
+export declare function frameRows(lines: string[]): number;

package/dist/cli/interactive/lanes.js

@@ -0,0 +1,181 @@
+/**
+ * Multi-lane agent display (Phase 3.6) — concurrent agent steps as live rows in the REPL.
+ *
+ * PURE BY CONSTRUCTION. Nothing here reads `process.stdout`, a clock, or an environment variable: the
+ * terminal width, whether colour is on, and every value rendered are parameters. That is what makes a
+ * terminal feature testable offline and deterministically, and it is the rule to keep — the moment this
+ * module reads the real terminal, its tests start describing the machine they ran on.
+ *
+ * WRAPPING IS MADE IMPOSSIBLE RATHER THAN HANDLED. In-place rewriting works by moving the cursor up N
+ * rows, which is only correct while one logical line occupies exactly one physical row. So every line is
+ * clamped to `cols - 1`: no line ever reaches the final column, nothing wraps, and the arithmetic is
+ * exact. Lines are built as plain text, clamped, and styled last, so the clamp never has to count
+ * invisible escape bytes.
+ */
+import { style, SPINNER_FRAMES } from './ansi.js';
+import { flattenClamp } from '../../util/flatten.js';
+const CLEAR_LINE = '\x1b[2K';
+/**
+ * East Asian Wide and Fullwidth code points, which a terminal draws in TWO columns. The no-wrap
+ * invariant is stated in COLUMNS, so counting UTF-16 code units would let a CJK step id — and step ids
+ * are model-authored — produce a line that measures 79 and draws 95, wrapping and breaking every
+ * cursor-up that follows it.
+ */
+function isWide(cp) {
+    return ((cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+        (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals, Kangxi, punctuation
+        (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana .. CJK compatibility
+        (cp >= 0x3400 && cp <= 0x4dbf) ||
+        (cp >= 0x4e00 && cp <= 0x9fff) || // CJK unified ideographs
+        (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+        (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+        (cp >= 0xf900 && cp <= 0xfaff) ||
+        (cp >= 0xfe30 && cp <= 0xfe6f) ||
+        (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
+        (cp >= 0xffe0 && cp <= 0xffe6) ||
+        (cp >= 0x1f300 && cp <= 0x1f64f) || // emoji
+        (cp >= 0x1f900 && cp <= 0x1f9ff) ||
+        (cp >= 0x20000 && cp <= 0x3fffd));
+}
+/** Display width in terminal columns, not code units. */
+export function displayWidth(text) {
+    let n = 0;
+    for (const ch of text)
+        n += isWide(ch.codePointAt(0)) ? 2 : 1;
+    return n;
+}
+/** Truncate to `cols` display columns, never splitting a surrogate pair or half a wide glyph. */
+export function sliceColumns(text, cols) {
+    let out = '';
+    let used = 0;
+    for (const ch of text) {
+        const w = isWide(ch.codePointAt(0)) ? 2 : 1;
+        if (used + w > cols)
+            break;
+        out += ch;
+        used += w;
+    }
+    return out;
+}
+const cursorUp = (n) => (n > 0 ? `\x1b[${n}A` : '');
+/** Which lane state an agent-task state projects onto. Anything unrecognised reads as still running. */
+function laneState(state) {
+    if (state === 'completed' || state === 'failed' || state === 'cancelled')
+        return state;
+    if (state.startsWith('waiting'))
+        return 'waiting';
+    return 'running';
+}
+/**
+ * Accumulates agent lanes from the event stream. Insertion-ordered, so lanes do not jump around between
+ * frames — a display that reorders itself is unreadable even when every value in it is right.
+ */
+export class LaneSet {
+    lanes = new Map();
+    /**
+     * Fold one event in. Returns the lane it touched, or `undefined` for an event that is not an agent
+     * event — a lane rather than a boolean, so the caller neither re-narrows the event nor looks the lane
+     * up a second time.
+     */
+    observe(event) {
+        if (!event.type.startsWith('agent.task.'))
+            return undefined;
+        const e = event;
+        const existing = this.lanes.get(e.agentTaskId);
+        const lane = existing ?? {
+            agentTaskId: e.agentTaskId,
+            agentId: e.agentId,
+            stepId: e.stepId,
+            state: 'running',
+            succeeded: 0,
+            total: 0,
+            callsUsed: 0,
+            findings: 0,
+        };
+        if ('innerSteps' in e) {
+            lane.total = e.innerSteps.total;
+            lane.succeeded = e.innerSteps.succeeded;
+        }
+        if ('callsUsed' in e)
+            lane.callsUsed = e.callsUsed;
+        if ('findings' in e)
+            lane.findings = e.findings;
+        if ('state' in e)
+            lane.state = laneState(e.state);
+        this.lanes.set(e.agentTaskId, lane);
+        return lane;
+    }
+    list() {
+        return [...this.lanes.values()];
+    }
+    /** True once at least one lane exists and none is still in flight. */
+    settled() {
+        const all = this.list();
+        return all.length > 0 && all.every((l) => l.state !== 'running');
+    }
+    clear() {
+        this.lanes.clear();
+    }
+}
+const MARK = { running: '', completed: '✓', failed: '✗', cancelled: '−', waiting: '?' };
+const TINT = {
+    running: 'cyan',
+    completed: 'green',
+    failed: 'red',
+    cancelled: 'gray',
+    waiting: 'yellow',
+};
+/**
+ * Render the lanes as one line each. `tick` animates the running marker; it is a parameter rather than a
+ * timer so a test can render frame 3 without waiting for it.
+ */
+export function laneLines(lanes, opts) {
+    // `|| 80` not `?? 80`: a pty can report ZERO columns, and zero is not nullish. And the floor is 1,
+    // not 20 — raising the width for a narrow terminal MAKES it wrap, which is the failure this clamp
+    // exists to prevent.
+    const width = Math.max(1, (opts.cols || 80) - 1);
+    return lanes.map((l) => {
+        const mark = l.state === 'running' ? SPINNER_FRAMES[opts.tick % SPINNER_FRAMES.length] : MARK[l.state];
+        const progress = l.total > 0 ? `${l.succeeded}/${l.total}` : '…';
+        const found = l.findings > 0 ? `, ${l.findings} finding(s)` : '';
+        // Built plain, clamped, THEN styled — so the clamp never counts escape bytes.
+        const plain = `  ${mark} ${flattenClamp(l.agentId, 24)} @ ${flattenClamp(l.stepId, 16)}  ${progress} step(s), ${l.callsUsed} call(s)${found}`;
+        return style(sliceColumns(plain, width), TINT[l.state], opts.colors);
+    });
+}
+/**
+ * Rewrite an owned region of the terminal in place, returning the bytes to write.
+ *
+ * `prevRows === 0` opens the region at the cursor's current line. Otherwise the cursor is assumed to be
+ * on the region's LAST row (which is where this function always leaves it) and walks up from there.
+ *
+ * The cursor never ends on a fresh line below the frame: a trailing newline on the terminal's last row
+ * scrolls the viewport, and the next frame's `cursorUp` would then land one row high and duplicate the
+ * region on every tick, forever.
+ */
+export function frameDiff(prevRows, lines, enabled) {
+    if (!enabled)
+        return '';
+    const rows = Math.max(prevRows, lines.length);
+    if (rows === 0)
+        return '';
+    let out = '\r';
+    if (prevRows > 0)
+        out += cursorUp(prevRows - 1);
+    for (let i = 0; i < rows; i += 1) {
+        out += CLEAR_LINE + (lines[i] ?? '');
+        if (i < rows - 1)
+            out += '\n';
+    }
+    // Drew fewer rows than last time: the cursor sits on a cleared row below the frame, so walk back up
+    // to the real last line, keeping the "cursor is on the last row" invariant true for the next call.
+    // CLOSING the region (`lines` empty) has no last line, so the target is the region's TOP row — which
+    // is one higher than the shrink case, and the reason this is `max(1, …)` rather than `lines.length`.
+    if (rows > lines.length)
+        out += `\r${cursorUp(rows - Math.max(1, lines.length))}`;
+    return out;
+}
+/** How many rows `frameDiff` will have left behind — the `prevRows` for the next call. */
+export function frameRows(lines) {
+    return lines.length;
+}

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

@@ -1,6 +1,9 @@
 /**
  * The interactive REPL — a thin node:readline wrapper around ReplSession. All output goes through the
  * redacted `print`. Progress is shown by subscribing to the runtime's lifecycle events. Zero new deps.
+ * Phase 21b adds (gated on an interactive TTY): a colored banner/prompt, slash-command tab-completion, a
+ * best-effort persistent history file, and an in-place spinner while a run is in flight. Non-TTY/CI output
+ * stays plain, and `ReplSession.handle` (the tested surface) is untouched.
  */
 /** Start the interactive session. Resolves when the user exits (or stdin closes). */
 export declare function startRepl(configPath?: string): Promise<void>;

package/dist/cli/interactive/repl.js

@@ -1,66 +1,142 @@
 /**
  * The interactive REPL — a thin node:readline wrapper around ReplSession. All output goes through the
  * redacted `print`. Progress is shown by subscribing to the runtime's lifecycle events. Zero new deps.
+ * Phase 21b adds (gated on an interactive TTY): a colored banner/prompt, slash-command tab-completion, a
+ * best-effort persistent history file, and an in-place spinner while a run is in flight. Non-TTY/CI output
+ * stays plain, and `ReplSession.handle` (the tested surface) is untouched.
  */
 import { createInterface } from 'node:readline';
+import { readFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { Runtime } from '../../runtime/runtime.js';
 import { print, printChunk, printError } from '../render.js';
 import { summarizeWorkspace } from '../../runtime/workspace/workspace.js';
-import { ReplSession } from './session.js';
-function banner(rt) {
+import { ReplSession, SLASH_COMMANDS } from './session.js';
+import { makeCompleter } from './complete.js';
+import { colorEnabled, bold, cyan, dim, gray, SPINNER_FRAMES, statusLine, clearLine } from './ansi.js';
+function banner(rt, colors) {
     const ws = rt.workspaceInfo();
-    print('ai-runtime');
+    print(bold('ai-runtime', colors));
     if (ws)
-        print(summarizeWorkspace(ws));
-    print(`mode: auto  ·  ${rt.ai.providers().length} providers  ·  type /help or a request, /exit to quit`);
+        print(dim(summarizeWorkspace(ws), colors));
+    print(gray(`mode: auto  ·  ${rt.ai.providers().length} providers  ·  type /help or a request, /exit to quit`, colors));
     print('');
 }
 /** A concise, redacted progress line for a lifecycle event — the REPL's live feedback during a run. */
-function progressLine(e) {
+function progressLine(e, colors) {
     switch (e.type) {
         case 'mode.selected':
-            return e.source === 'auto' ? `  · mode: ${e.selected} (auto, ${Math.round(e.confidence * 100)}%)` : `  · mode: ${e.selected}`;
+            return dim(e.source === 'auto' ? `  · mode: ${e.selected} (auto, ${Math.round(e.confidence * 100)}%)` : `  · mode: ${e.selected}`, colors);
         case 'provider.selected':
-            return `  · routed → ${e.providerId}/${e.model}`;
+            return dim(`  · routed → ${e.providerId}/${e.model}`, colors);
         case 'provider.failed':
-            return `  · ${e.providerId}/${e.model} failed${e.category ? ` (${e.category})` : ''} — falling back`;
+            return dim(`  · ${e.providerId}/${e.model} failed${e.category ? ` (${e.category})` : ''} — falling back`, colors);
         default:
             return undefined; // runtime.started / clarification.requested / run.completed are covered by the result block
     }
 }
+/** An in-place spinner (TTY only). `stop()` clears the line and is idempotent. */
+function startSpinner(colors) {
+    if (!colors)
+        return { stop: () => { } };
+    let i = 0;
+    const tick = () => {
+        try {
+            process.stdout.write(statusLine(`${cyan(SPINNER_FRAMES[i % SPINNER_FRAMES.length], colors)} working…`, colors));
+        }
+        catch {
+            /* never let a draw break the REPL */
+        }
+        i += 1;
+    };
+    tick();
+    const handle = setInterval(tick, 90);
+    if (typeof handle.unref === 'function')
+        handle.unref();
+    let stopped = false;
+    return {
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(handle);
+            try {
+                process.stdout.write(clearLine(colors));
+            }
+            catch {
+                /* ignore */
+            }
+        },
+    };
+}
 /** Start the interactive session. Resolves when the user exits (or stdin closes). */
 export async function startRepl(configPath) {
     const rt = await Runtime.load({ ...(configPath ? { config: configPath } : {}) });
+    const colors = colorEnabled({ isTTY: !!process.stdout.isTTY, env: process.env });
     const session = new ReplSession(rt, { streaming: true });
-    // Tracks whether the CURRENT line produced any streamed output, so we can close the line cleanly.
+    // Best-effort persistent history under the project store's cache dir.
+    const historyPath = join(rt.store.paths().project, 'cache', 'repl_history');
+    let history = [];
+    try {
+        history = readFileSync(historyPath, 'utf8').split('\n').filter(Boolean).slice(-500).reverse(); // readline wants newest-first
+    }
+    catch {
+        /* no history yet */
+    }
+    const remember = (line) => {
+        if (!line.trim())
+            return;
+        try {
+            mkdirSync(dirname(historyPath), { recursive: true });
+            appendFileSync(historyPath, `${line}\n`);
+        }
+        catch {
+            /* history is a convenience; a write failure must never break the REPL */
+        }
+    };
     let streamedThisRun = false;
+    let spinner;
     // Live progress + token streaming. Events are already redacted; a throwing observer can't break a run.
     rt.on((e) => {
+        spinner?.stop(); // any event means work has started producing output — drop the spinner first
         if (e.type === 'response.delta') {
             printChunk(e.text);
             streamedThisRun = true;
             return;
         }
-        const line = progressLine(e);
+        const line = progressLine(e, colors);
         if (line)
             print(line);
     });
-    banner(rt);
-    const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: '> ' });
+    banner(rt, colors);
+    // The REPL is long-lived and interactive, so MCP connects EAGERLY here (unlike one-shot commands):
+    // the user should see their servers' tools in the very first request, and pay the cost once.
+    if (rt.hasMcpServers()) {
+        const servers = await rt.connectMcp();
+        const up = servers.filter((sv) => sv.state === 'connected' || sv.state === 'degraded').length;
+        print(gray(`mcp: ${up}/${servers.length} server(s) connected`, colors));
+        for (const w of rt.mcpWarningsList())
+            printError(`! ${w}`);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: cyan('> ', colors), completer: makeCompleter(SLASH_COMMANDS), history, historySize: 500 });
     rl.prompt();
     for await (const line of rl) {
+        remember(line);
         let result;
         streamedThisRun = false;
+        spinner = startSpinner(colors);
         try {
             result = await session.handle(line);
         }
         catch (err) {
+            spinner.stop();
             if (streamedThisRun)
                 process.stdout.write('\n');
             printError(`error: ${err instanceof Error ? err.message : String(err)}`);
             rl.prompt();
             continue;
         }
+        spinner.stop();
         if (streamedThisRun)
             process.stdout.write('\n'); // close the streamed line before printing result lines
         if (result.clear)
@@ -69,8 +145,10 @@ export async function startRepl(configPath) {
             print(l);
         if (result.exit) {
             rl.close();
+            await rt.close(); // release MCP stdio children on a clean exit
             return;
         }
         rl.prompt();
     }
+    await rt.close(); // stdin closed (piped input) — same release path
 }

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

@@ -10,6 +10,8 @@ export interface HandleResult {
     exit?: boolean;
     clear?: boolean;
 }
+/** Top-level slash commands, for REPL tab-completion (Phase 21b). Kept in sync with the `handle` dispatch. */
+export declare const SLASH_COMMANDS: readonly ["help", "status", "info", "doctor", "cleanup", "mode", "compare", "models", "config", "providers", "tools", "capabilities", "mcp", "skills", "memory", "conversations", "executions", "resume", "resume-execution", "pause", "cancel", "approve", "deny", "learning", "feedback", "permissions", "budget", "stream", "dry-run", "clear", "exit", "quit"];
 export declare class ReplSession {
     private readonly runtime;
     private mode;
@@ -22,6 +24,12 @@ export declare class ReplSession {
     });
     currentMode(): RuntimeMode;
     private views;
+    /**
+     * MCP servers in the REPL. The session's Runtime is already connected (the REPL connects eagerly at
+     * start), so this NEVER opens a second Runtime — that would spawn duplicate stdio children and give
+     * `close()` the wrong one to tear down. It reuses the exact formatters the `mcp` command prints.
+     */
+    private mcpView;
     handle(raw: string): Promise<HandleResult>;
     private runInput;
     private memory;

package/dist/cli/interactive/session.js

@@ -9,6 +9,16 @@ import { SETUP_CANDIDATES } from '../commands/setup.js';
 import { gatherInfo, renderInfo } from '../commands/info.js';
 import { gatherDoctor, renderDoctor } from '../commands/doctor.js';
 import { planCleanup } from '../commands/cleanup.js';
+import { actionCapabilityRows, renderActionCapabilities, renderCapabilityGaps } from '../commands/inspect.js';
+import { renderMcpList, renderMcpDetail } from '../commands/mcp.js';
+import { candidatesFrom, deriveCapabilitiesOffline } from '../../runtime/planning/deriveCapabilities.js';
+import { displaySafe } from '../render.js';
+/** Top-level slash commands, for REPL tab-completion (Phase 21b). Kept in sync with the `handle` dispatch. */
+export const SLASH_COMMANDS = [
+    'help', 'status', 'info', 'doctor', 'cleanup', 'mode', 'compare', 'models', 'config', 'providers', 'tools', 'capabilities', 'mcp',
+    'skills', 'memory', 'conversations', 'executions', 'resume', 'resume-execution', 'pause', 'cancel', 'approve',
+    'deny', 'learning', 'feedback', 'permissions', 'budget', 'stream', 'dry-run', 'clear', 'exit', 'quit',
+];
 const HELP = [
     'Commands:',
     '  /help                       show this help',
@@ -24,6 +34,10 @@ const HELP = [
     '  /providers/<id> [models|capabilities|health]   inspect one provider',
     '  /models                     list all known models',
     '  /tools                      list registered tools',
+    '  /capabilities               list action capabilities (what the runtime can DO) + providers',
+    '  /capabilities <goal>        which capabilities a goal needs, and what is missing (offline)',
+    '  /mcp                        list MCP servers (state, tools, grant)',
+    '  /mcp/<id>                   inspect one MCP server (protocol, tools, diagnostics)',
     '  /skills [discover]          list available skills; discover scans the workspace',
     '  /permissions                show the current tool permissions',
     '  /feedback <text>            record feedback on the last result (e.g. "that worked")',
@@ -43,6 +57,7 @@ const HELP = [
     '  /config                     show the resolved configuration',
     '  /dry-run                    toggle dry-run (plan only, no changes)',
     '  /stream                     toggle token-by-token streaming of answers',
+    '  /budget                     show the call/cost budget (AI_MAX_CALLS / AI_MAX_COST_USD)',
     '  /clear                      clear the screen',
     '  /exit                       leave the session',
     '',
@@ -67,6 +82,27 @@ export class ReplSession {
             this.viewCache = new ProviderViewCache(this.runtime.ai);
         return this.viewCache;
     }
+    /**
+     * MCP servers in the REPL. The session's Runtime is already connected (the REPL connects eagerly at
+     * start), so this NEVER opens a second Runtime — that would spawn duplicate stdio children and give
+     * `close()` the wrong one to tear down. It reuses the exact formatters the `mcp` command prints.
+     */
+    mcpView(target) {
+        if (!this.runtime.hasMcpServers())
+            return { lines: renderMcpList({}, []) };
+        const grants = this.runtime.permissions().mcp.servers;
+        if (!target) {
+            const lines = renderMcpList(grants, this.runtime.mcp().list());
+            const warnings = this.runtime.mcpWarningsList();
+            if (warnings.length)
+                lines.push('', 'Warnings:', ...warnings.map((w) => `  ! ${w}`));
+            return { lines };
+        }
+        const status = this.runtime.mcp().status(target);
+        if (!status)
+            return { lines: [`no MCP server '${displaySafe(target, 40)}' — /mcp lists them`] };
+        return { lines: renderMcpDetail(grants, status, this.runtime.mcp().diagnostics(target), this.runtime.mcp().tools(target)) };
+    }
     async handle(raw) {
         const line = raw.trim();
         if (!line)
@@ -109,6 +145,24 @@ export class ReplSession {
                 return this.config();
             case 'providers':
                 return this.providers(parts[1], args[0]);
+            case 'capabilities': {
+                // `capabilities --actions` connects (inspect.ts); without this the same question reported
+                // different MCP availability on the two surfaces. connectMcp is idempotent.
+                if (this.runtime.hasMcpServers())
+                    await this.runtime.connectMcp();
+                // Both forms, and never a truncated goal: `/capabilities run the tests` and
+                // `/capabilities/run the tests` must mean the same thing.
+                const goal = [...parts.slice(1), ...args].join(' ').trim();
+                if (!goal)
+                    return { lines: renderActionCapabilities(actionCapabilityRows(this.runtime)) };
+                const required = deriveCapabilitiesOffline(goal, candidatesFrom(this.runtime.capabilities().list()));
+                if (!required.length)
+                    return { lines: [`no action capability matched "${displaySafe(goal, 80)}" — /capabilities lists everything this runtime can do.`] };
+                return { lines: renderCapabilityGaps(this.runtime.capabilityReport(required)) };
+            }
+            case 'mcp':
+                // `/mcp/<id>` and `/mcp <id>` both address one server.
+                return this.mcpView(parts[1] ?? args[0]);
             case 'tools':
                 return { lines: ['Tools:', ...this.runtime.tools().map((t) => `  ${t.id.padEnd(14)} ${t.description}`)] };
             case 'skills': {
@@ -139,6 +193,14 @@ export class ReplSession {
             case 'stream':
                 this.streaming = !this.streaming;
                 return { lines: [`streaming ${this.streaming ? 'ON — answers render token-by-token' : 'OFF'}`] };
+            case 'budget':
+                return {
+                    lines: [
+                        `call budget (AI_MAX_CALLS):    ${process.env.AI_MAX_CALLS ?? '(unset — no limit)'}`,
+                        `cost budget (AI_MAX_COST_USD): ${process.env.AI_MAX_COST_USD ?? '(unset — no limit)'}`,
+                        'over budget: notify-and-wait by default; add --partial (one-shot) to run the phases that fit and pause.',
+                    ],
+                };
             case 'memory':
                 return this.memory(args);
             case 'conversations':
@@ -182,17 +244,25 @@ export class ReplSession {
             const execId = result.execution?.id;
             lines.push(execId ? `(approval required — /approve ${execId} to proceed, or /deny ${execId})` : '(approval required — approve the execution via /executions then /approve <id>)');
         }
+        if (result.status === 'waiting_for_budget') {
+            const execId = result.execution?.id;
+            lines.push(execId ? `(over budget — raise AI_MAX_CALLS and /resume-execution ${execId}, or re-run with more budget)` : '(over budget — raise the call budget and re-run, or add --partial)');
+        }
         if (result.status === 'failed')
             lines.push('(did not complete)');
         if (result.clarification)
             lines.push(`? ${result.clarification.question}`);
         if (result.memory?.captured)
             lines.push('(remembered)');
+        // Phase 3.3: the ONE gap renderer, shared with `ai-runtime run` and both capabilities surfaces.
+        // Appended AFTER the existing advisory tail so every positional assertion above is untouched.
+        if (result.capabilityGaps)
+            lines.push(...renderCapabilityGaps(result.capabilityGaps));
         if (this.conversationId && result.response?.text)
             this.runtime.conversations.append(this.conversationId, 'assistant', result.response.text, result.runId);
         return { lines };
     }
-    memory(args) {
+    async memory(args) {
         if (!this.runtime.memory.enabled)
             return { lines: ['memory is disabled (stateless mode).'] };
         const sub = args[0];
@@ -200,7 +270,8 @@ export class ReplSession {
             const q = args.slice(1).join(' ');
             if (!q)
                 return { lines: ['usage: /memory search <query>'] };
-            const hits = this.runtime.memory.search(q, { limit: 10 });
+            // Semantic ranking when an embedder is configured; degrades to BM25 internally.
+            const hits = await this.runtime.memory.searchSemantic(q, { limit: 10 });
             return { lines: hits.length ? hits.map((r) => `  ${r.id}  [${r.scope}]  ${r.text}`) : ['no matches.'] };
         }
         if (sub === 'delete') {

package/dist/cli/render.d.ts

@@ -11,3 +11,10 @@ export declare function print(line: string): void;
  */
 export declare function printChunk(chunk: string): void;
 export declare function printError(line: string): void;
+/**
+ * Clamp a source- or MODEL-controlled string before it reaches the terminal — the terminal twin of
+ * `promptSafe`. LOAD-BEARING: `print` redacts secrets but strips no control characters and bounds no
+ * length, and a gap's `capabilityId` originates in the model's plan JSON — `sanitizeSegment` restricts
+ * its charset but sets no maximum, and the `register` gap hint interpolates it.
+ */
+export declare function displaySafe(raw: string, max?: number): string;

package/dist/cli/render.js

@@ -4,6 +4,7 @@
  * directly from a command.
  */
 import { redactString } from '../security/redact.js';
+import { flattenClamp } from '../util/flatten.js';
 export function print(line) {
     // eslint-disable-next-line no-console
     console.log(redactString(line));
@@ -20,3 +21,12 @@ export function printError(line) {
     // eslint-disable-next-line no-console
     console.error(redactString(line));
 }
+/**
+ * Clamp a source- or MODEL-controlled string before it reaches the terminal — the terminal twin of
+ * `promptSafe`. LOAD-BEARING: `print` redacts secrets but strips no control characters and bounds no
+ * length, and a gap's `capabilityId` originates in the model's plan JSON — `sanitizeSegment` restricts
+ * its charset but sets no maximum, and the `register` gap hint interpolates it.
+ */
+export function displaySafe(raw, max = 80) {
+    return flattenClamp(raw, max);
+}

package/dist/cli/runtimeSession.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One place where a CLI command borrows a Runtime and gives it back.
+ *
+ * A `Runtime` can own OS resources — today MCP stdio child processes. A one-shot command that returns
+ * without releasing them does not merely leak: a live child keeps the event loop alive, so the CLI never
+ * exits. `withRuntime` guarantees the release on every path, including a thrown error.
+ */
+import { Runtime } from '../runtime/runtime.js';
+export declare function withRuntime<T>(opts: {
+    config?: string;
+}, fn: (rt: Runtime) => Promise<T>): Promise<T>;

package/dist/cli/runtimeSession.js

@@ -0,0 +1,17 @@
+/**
+ * One place where a CLI command borrows a Runtime and gives it back.
+ *
+ * A `Runtime` can own OS resources — today MCP stdio child processes. A one-shot command that returns
+ * without releasing them does not merely leak: a live child keeps the event loop alive, so the CLI never
+ * exits. `withRuntime` guarantees the release on every path, including a thrown error.
+ */
+import { Runtime } from '../runtime/runtime.js';
+export async function withRuntime(opts, fn) {
+    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
+    try {
+        return await fn(rt);
+    }
+    finally {
+        await rt.close();
+    }
+}