ai-runtime-engine 1.3.0 → 2.7.0

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);
+}

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;