@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/cli/ink/WizardApp.js

@@ -0,0 +1,422 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useState, useEffect, useCallback, useRef } from 'react';
+import { Box, Text, useApp } from 'ink';
+import Spinner from 'ink-spinner';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Frame } from './Frame.js';
+import { Picker } from './Picker.js';
+import { TextField } from './TextField.js';
+import { PROVIDER_CATALOG, detectProviderFromEnv, validateApiKey, maskApiKey, } from '../wizard/providers.js';
+import { initWizardState, reduceWizard, } from '../wizard/types.js';
+import { fetchOpenAiCompatibleModels } from '../wizard/modelsApi.js';
+import { McpClientWrapper } from '../../runtime/mcpClient.js';
+/**
+ * Ink-based wizard. Replaces the raw-stdout `runWizard` runner
+ * (which had compounding redraw bugs no matter how many off-by-one
+ * fixes we applied — Ink owns the render loop and diffs the cell
+ * grid, so frames never stack or creep).
+ *
+ * Driver pattern:
+ *   - One `<WizardApp>` mounts at the top-level (`render(<WizardApp>)`).
+ *   - It picks ONE child to render based on `state.currentStep`.
+ *   - Each step is its own component (`<WelcomeStep>`, `<ThemeStep>`,
+ *     etc.) that takes a `state` + `onAdvance` / `onBack` /
+ *     `onAbort` / `onWarn` callback.
+ *   - On terminal step (done / abort), the wizard calls
+ *     `useApp().exit()` and `props.onFinish(state)` so the caller
+ *     can persist + unmount.
+ */
+const TOTAL_STEPS = 6;
+function progressBadge(step) {
+    const decisionSteps = ['theme', 'provider', 'apiKey', 'model', 'mcp', 'agentMd'];
+    const idx = decisionSteps.indexOf(step);
+    if (idx < 0)
+        return undefined;
+    return `Step ${idx + 1} of ${TOTAL_STEPS}`;
+}
+const ACCENT = {
+    dark: '#CC9166',
+    light: '#A24E1F',
+    mono: 'white',
+};
+export function WizardApp({ workspaceRoot, onFinish }) {
+    const [state, setState] = useState(() => initWizardState());
+    const { exit } = useApp();
+    // Use refs for the callbacks so child components receive STABLE
+    // references across renders. Otherwise every render gives them a new
+    // function identity, which (a) makes their useEffect dependency
+    // arrays churn (re-firing preview/probe effects) and (b) prevents
+    // React from skipping re-renders. The stable-callback ref pattern is
+    // canonical for React 18/19 component composition.
+    const onFinishRef = useRef(onFinish);
+    useEffect(() => { onFinishRef.current = onFinish; });
+    // Notify the caller + exit Ink when the wizard reaches terminal.
+    // Dep on state.aborted + state.committed only — not on `state` or
+    // `onFinish` — so the effect fires exactly ONCE per terminal
+    // transition. (Earlier code depended on `state` itself, which fired
+    // the effect on every state update; harmless but wasteful.)
+    useEffect(() => {
+        if (state.aborted || state.committed) {
+            onFinishRef.current(state);
+            exit();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [state.aborted, state.committed]);
+    const theme = state.draft.theme ?? 'dark';
+    const accent = ACCENT[theme];
+    const dispatchAdvance = useCallback((patch) => setState((s) => reduceWizard(s, { kind: 'advance', patch })), []);
+    const dispatchWarn = useCallback((message) => setState((s) => reduceWizard(s, { kind: 'warn', message })), []);
+    const dispatchAbort = useCallback(() => setState((s) => reduceWizard(s, { kind: 'abort' })), []);
+    const dispatchCommit = useCallback(() => setState((s) => reduceWizard(s, { kind: 'commit' })), []);
+    switch (state.currentStep) {
+        case 'welcome':
+            return _jsx(WelcomeStep, { accent: accent, onAdvance: () => dispatchAdvance({}), onAbort: dispatchAbort });
+        case 'theme':
+            return (_jsx(ThemeStep, { accent: accent, onPick: (mode) => dispatchAdvance({ theme: mode }), onAbort: dispatchAbort }));
+        case 'provider':
+            return (_jsx(ProviderStep, { accent: accent, onPick: (provider, customEndpoint) => dispatchAdvance({ provider, customEndpoint }), onAbort: dispatchAbort }));
+        case 'apiKey':
+            return (_jsx(ApiKeyStep, { accent: accent, provider: state.draft.provider, onAccept: (apiKey, warning) => {
+                    if (warning)
+                        dispatchWarn(warning);
+                    dispatchAdvance({ apiKey });
+                }, onAbort: dispatchAbort }));
+        case 'model':
+            return (_jsx(ModelStep, { accent: accent, provider: state.draft.provider, apiKey: state.draft.apiKey ?? '', customEndpoint: state.draft.customEndpoint, onPick: (model) => dispatchAdvance({ model }), onAbort: dispatchAbort }));
+        case 'mcp':
+            return (_jsx(McpStep, { accent: accent, draft: state.draft, onAccept: (mcp, warning) => {
+                    if (warning)
+                        dispatchWarn(warning);
+                    dispatchAdvance({ mcp });
+                }, onAbort: dispatchAbort }));
+        case 'agentMd':
+            return (_jsx(AgentMdStep, { accent: accent, workspaceRoot: workspaceRoot, onPick: (writeAgentMd) => dispatchAdvance({ writeAgentMd }), onAbort: dispatchAbort }));
+        case 'done':
+            // Commit immediately on mount; render the summary while the caller
+            // persists.
+            return _jsx(DoneStep, { state: state, accent: accent, onCommit: dispatchCommit });
+    }
+}
+// --- Steps -------------------------------------------------------------
+function WelcomeStep({ accent, onAdvance, onAbort }) {
+    const handleResolve = (r) => {
+        if (r.kind === 'pick' && r.id === 'start')
+            onAdvance();
+        else
+            onAbort();
+    };
+    return (_jsx(Picker, { title: '\uD83E\uDDE0  BrainRouter', subtitle: 'A memory-native coding agent that runs in your terminal. This wizard takes ~60 seconds and writes to ~/.config/brainrouter/config.json plus <workspace>/.brainrouter/cli/preferences.json. Press ENTER to start, q to abort.', badge: 'Welcome', rows: [
+            { id: 'start', label: 'Start setup', description: 'Theme → Provider → API key → Model → MCP → AGENT.md' },
+            { id: 'abort', label: 'Abort', description: 'Exit without saving anything' },
+        ], accentColor: accent, onResolve: handleResolve }));
+}
+function ThemeStep({ accent, onPick, onAbort }) {
+    return (_jsx(Picker, { title: 'Theme', subtitle: 'Pick a color palette.', badge: progressBadge('theme'), rows: [
+            { id: 'dark', label: 'Dark', description: 'Default · saturated accents on a black terminal' },
+            { id: 'light', label: 'Light', description: 'Darker accents for white terminals (solarized-light, GitHub light)' },
+            { id: 'mono', label: 'Mono', description: 'No color · screenshots, CI logs, pipe-to-less' },
+        ], initialCursor: 0, accentColor: accent, onResolve: (r) => {
+            if (r.kind !== 'pick')
+                return onAbort();
+            onPick(r.id);
+        } }));
+}
+function ProviderStep({ accent, onPick, onAbort }) {
+    const detected = detectProviderFromEnv();
+    const rows = PROVIDER_CATALOG.map((p) => {
+        const envHit = !!process.env[p.envKey];
+        const status = envHit ? 'env detected' : p.local ? 'local · key optional' : 'needs API key';
+        return { id: p.id, label: p.label, value: status, description: p.hint };
+    });
+    const initialCursor = detected
+        ? Math.max(0, PROVIDER_CATALOG.findIndex((p) => p.id === detected.id))
+        : 0;
+    return (_jsx(Picker, { title: 'LLM provider', subtitle: detected
+            ? `Detected ${detected.envKey} in your shell — ${detected.label} is pre-selected. Pick "Other" to enter a custom OpenAI-compatible endpoint.`
+            : 'Pick the LLM provider for the chat agent. Pick "Other" to enter a custom OpenAI-compatible endpoint.', badge: progressBadge('provider'), rows: rows, initialCursor: initialCursor, allowOther: true, otherLabel: 'Other endpoint', otherDescription: 'OpenAI-compatible /v1/chat/completions URL', accentColor: accent, onResolve: (r) => {
+            if (r.kind === 'cancelled')
+                return onAbort();
+            if (r.kind === 'other') {
+                const url = r.text;
+                const custom = {
+                    id: 'custom',
+                    label: 'Custom endpoint',
+                    hint: url,
+                    endpoint: url,
+                    envKey: 'BRAINROUTER_LLM_API_KEY',
+                    local: /localhost|127\.0\.0\.1|::1|0\.0\.0\.0/.test(url),
+                    models: [],
+                    defaultModel: 'gpt-4o-mini',
+                };
+                onPick(custom, url);
+                return;
+            }
+            const provider = PROVIDER_CATALOG.find((p) => p.id === r.id);
+            if (provider)
+                onPick(provider);
+        } }));
+}
+function ApiKeyStep({ accent, provider, onAccept, onAbort }) {
+    const envValue = process.env[provider.envKey] ?? '';
+    const subtitle = envValue
+        ? `${provider.envKey} is set in your shell — press ENTER to accept, or type a different key.`
+        : provider.local
+            ? `${provider.label} is local — a blank API key is fine (just press ENTER).`
+            : `Paste your ${provider.label} API key. Stored at ~/.config/brainrouter/config.json.`;
+    return (_jsx(TextField, { title: 'API key', subtitle: subtitle, badge: `${progressBadge('apiKey')} · ${provider.label}`, prefilled: envValue, placeholder: provider.local ? '(blank OK for local endpoints)' : 'paste your API key here', accentColor: accent, validate: (raw) => {
+            const v = validateApiKey(raw, provider);
+            return v.kind === 'reject' ? v.reason : undefined;
+        }, onResolve: (r) => {
+            if (r.kind !== 'accept')
+                return onAbort();
+            const verdict = validateApiKey(r.text, provider);
+            const warning = verdict.kind === 'accept' ? verdict.warning : undefined;
+            onAccept(r.text, warning);
+        } }));
+}
+function ModelStep({ accent, provider, apiKey, customEndpoint, onPick, onAbort }) {
+    const [loading, setLoading] = useState(true);
+    const [modelsList, setModelsList] = useState(provider.models);
+    const [subtitleHint, setSubtitleHint] = useState(`Pick the chat model for ${provider.label}.`);
+    useEffect(() => {
+        let cancelled = false;
+        (async () => {
+            const res = await fetchOpenAiCompatibleModels(provider, apiKey, customEndpoint);
+            if (cancelled)
+                return;
+            if (res.ok) {
+                const withDefault = res.models.includes(provider.defaultModel)
+                    ? [provider.defaultModel, ...res.models.filter((m) => m !== provider.defaultModel)]
+                    : res.models;
+                setModelsList(withDefault);
+                setSubtitleHint(`Pick a model — ${res.models.length} returned by ${provider.label}'s /v1/models endpoint. Use "Other" to type any name.`);
+            }
+            else {
+                setSubtitleHint(`Pick a model. (Live list unavailable — ${res.error}. Showing curated short-list.) Use "Other" to type any name.`);
+            }
+            setLoading(false);
+        })();
+        return () => { cancelled = true; };
+    }, [provider, apiKey, customEndpoint]);
+    if (loading) {
+        return (_jsx(Frame, { title: 'Model', subtitle: `Fetching ${provider.label} models…`, badge: progressBadge('model'), accentColor: accent, children: _jsxs(Box, { children: [_jsx(Text, { color: "green", children: React.createElement(Spinner, { type: 'dots' }) }), _jsxs(Text, { color: "gray", children: ["  loading ", provider.label, " /v1/models"] })] }) }));
+    }
+    const rows = (modelsList.length > 0 ? modelsList : [provider.defaultModel]).map((m) => ({
+        id: m,
+        label: m,
+        value: m === provider.defaultModel ? 'default' : '',
+    }));
+    const initialCursor = Math.max(0, modelsList.indexOf(provider.defaultModel));
+    return (_jsx(Picker, { title: 'Model', subtitle: subtitleHint, badge: progressBadge('model'), rows: rows, initialCursor: initialCursor, allowOther: true, otherLabel: 'Other model', otherDescription: 'Type any model name supported by this endpoint', accentColor: accent, onResolve: (r) => {
+            if (r.kind === 'cancelled')
+                return onAbort();
+            const model = r.kind === 'other' ? r.text.trim() : r.id;
+            onPick(model || provider.defaultModel);
+        } }));
+}
+function McpStep({ accent, draft, onAccept, onAbort }) {
+    // Stages:
+    //   pick       — top-level transport picker
+    //   remote-url — text field for the remote http URL
+    //   mcp-apikey — BrainRouter API key prompt (for local-http + remote-http)
+    //   probing    — spinner while the probe is in flight
+    const [stage, setStage] = useState('pick');
+    const [pendingPick, setPendingPick] = useState(undefined);
+    const [probeMsg, setProbeMsg] = useState('');
+    // 0.3.7 — kick the probe once we have the final pick (with apiKey
+    // already set). Shared between the post-url and post-key transitions
+    // so we don't have two copies of the same Promise+setStage dance.
+    function startProbe(pick) {
+        setPendingPick(pick);
+        setStage('probing');
+        setProbeMsg('contacting server (5s timeout)');
+        (async () => {
+            const probe = await probeMcp(pick, draft, (m) => setProbeMsg(m));
+            onAccept(pick, probe.warning);
+        })();
+    }
+    if (stage === 'probing' && pendingPick) {
+        return (_jsx(Frame, { title: 'MCP probe', subtitle: `Probing ${formatMcpForBadge(pendingPick)}…`, badge: progressBadge('mcp'), accentColor: accent, children: _jsxs(Box, { children: [_jsx(Text, { color: "green", children: React.createElement(Spinner, { type: 'dots' }) }), _jsxs(Text, { color: "gray", children: ["  ", probeMsg || 'connecting…'] })] }) }));
+    }
+    if (stage === 'remote-url') {
+        return (_jsx(TextField, { title: 'Remote MCP URL', subtitle: 'Paste the full URL (e.g. https://brainrouter.example.com/mcp). Press Esc to back out.', badge: progressBadge('mcp'), prefilled: '', placeholder: 'https://...', accentColor: accent, validate: (raw) => {
+                const v = raw.trim();
+                if (!v)
+                    return 'URL is required';
+                try {
+                    new URL(v);
+                }
+                catch {
+                    return 'not a valid URL';
+                }
+                return undefined;
+            }, onResolve: (r) => {
+                if (r.kind !== 'accept')
+                    return setStage('pick');
+                // Carry the URL into the api-key stage; the BrainRouter MCP
+                // server's HTTP transport requires a Bearer token whenever
+                // auth is enabled, so we always offer the input (blank OK
+                // for servers without auth).
+                setPendingPick({ kind: 'remote-http', url: r.text.trim() });
+                setStage('mcp-apikey');
+            } }));
+    }
+    if (stage === 'mcp-apikey' && pendingPick) {
+        // 0.3.7 — added so users can input the BRAINROUTER_API_KEY during
+        // onboarding. Pre-fills from the env var; blank submission is
+        // valid (local servers without auth, dev mode).
+        const envValue = process.env.BRAINROUTER_API_KEY ?? '';
+        const isLocal = pendingPick.kind === 'local-http';
+        return (_jsx(TextField, { title: 'BrainRouter API key', subtitle: envValue
+                ? `BRAINROUTER_API_KEY is set — press ENTER to accept, type to override, or leave blank if the server is unauthenticated.`
+                : isLocal
+                    ? `Optional — leave blank if your local brainrouter-mcp HTTP server runs without auth. Required when BRAINROUTER_API_KEY is set on the server side.`
+                    : `Optional — leave blank if the hosted MCP doesn't require auth. Use the key issued by the BrainRouter dashboard (Users → Profile).`, badge: progressBadge('mcp'), prefilled: envValue, placeholder: '(blank OK)', accentColor: accent, onResolve: (r) => {
+                // Esc cancels the whole step back to the picker so the user
+                // can choose a different transport.
+                if (r.kind !== 'accept')
+                    return setStage('pick');
+                const apiKey = r.text.trim() || undefined;
+                const next = pendingPick.kind === 'local-http'
+                    ? { kind: 'local-http', apiKey }
+                    : pendingPick.kind === 'remote-http'
+                        ? { kind: 'remote-http', url: pendingPick.url, apiKey }
+                        : pendingPick;
+                startProbe(next);
+            } }));
+    }
+    const rows = [
+        { id: 'local-stdio', label: 'Local stdio', value: 'spawn brainrouter-mcp', description: 'No HTTP server needed — the CLI spawns the MCP child', pick: { kind: 'local-stdio' } },
+        { id: 'local-http', label: 'Local HTTP', value: 'http://localhost:3747', description: 'Connect to a brainrouter-mcp HTTP server running locally', pick: { kind: 'local-http' } },
+        { id: 'remote-http', label: 'Remote HTTP', value: 'custom URL', description: 'Connect to a hosted BrainRouter MCP (URL + API key)', pick: { kind: 'remote-http', url: '' } },
+        { id: 'skip', label: 'Skip', value: 'no MCP', description: 'Local tools only · no recall, skills, or capture', pick: { kind: 'skip' } },
+    ];
+    return (_jsx(Picker, { title: 'MCP server', subtitle: "BrainRouter's memory + skills live behind an MCP server. Pick how to reach it.", badge: progressBadge('mcp'), rows: rows, initialCursor: 0, accentColor: accent, onResolve: (r) => {
+            if (r.kind === 'cancelled')
+                return onAbort();
+            if (r.kind !== 'pick')
+                return;
+            const picked = rows.find((row) => row.id === r.id)?.pick;
+            if (!picked)
+                return;
+            if (picked.kind === 'remote-http') {
+                // URL first → then api-key stage → then probe.
+                setStage('remote-url');
+                return;
+            }
+            if (picked.kind === 'local-http') {
+                // Skip the URL prompt (fixed at http://localhost:3747/mcp)
+                // and go straight to the api-key stage.
+                setPendingPick(picked);
+                setStage('mcp-apikey');
+                return;
+            }
+            if (picked.kind === 'skip') {
+                onAccept(picked);
+                return;
+            }
+            // local-stdio — no api key needed (process-local auth).
+            startProbe(picked);
+        } }));
+}
+function formatMcpForBadge(pick) {
+    if (pick.kind === 'local-stdio')
+        return 'local stdio';
+    if (pick.kind === 'local-http')
+        return 'http://localhost:3747/mcp';
+    if (pick.kind === 'remote-http')
+        return pick.url;
+    return 'no MCP';
+}
+async function probeMcp(pick, draft, onStatus) {
+    if (pick.kind === 'skip')
+        return { ok: true };
+    const wrapper = new McpClientWrapper();
+    const llmConfig = draft.provider && draft.model
+        ? { provider: 'openai', apiKey: draft.apiKey ?? '', model: draft.model, endpoint: draft.customEndpoint ?? draft.provider.endpoint }
+        : undefined;
+    const serverConfig = mcpPickToServerConfig(pick);
+    if (!serverConfig)
+        return { ok: false, warning: 'Could not build MCP server config for this pick.' };
+    try {
+        onStatus('connecting…');
+        await Promise.race([
+            wrapper.connect(serverConfig, llmConfig, 'wizard'),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('probe timed out after 5s')), 5_000)),
+        ]);
+        await wrapper.close();
+        return { ok: true };
+    }
+    catch (err) {
+        try {
+            await wrapper.close();
+        }
+        catch { /* ignore */ }
+        return {
+            ok: false,
+            warning: `MCP probe failed (${err?.message ?? err}). Profile saved — start the server and run /mcp reconnect later.`,
+        };
+    }
+}
+function mcpPickToServerConfig(pick) {
+    if (pick.kind === 'local-stdio') {
+        return { type: 'stdio', command: 'brainrouter-mcp', args: [], identity: 'brainrouter' };
+    }
+    if (pick.kind === 'local-http') {
+        return { type: 'http', url: 'http://localhost:3747/mcp', apiKey: pick.apiKey, identity: 'brainrouter' };
+    }
+    if (pick.kind === 'remote-http') {
+        return { type: 'http', url: pick.url, apiKey: pick.apiKey, identity: 'brainrouter' };
+    }
+    return undefined;
+}
+function AgentMdStep({ accent, workspaceRoot, onPick, onAbort }) {
+    const agentMdPath = path.join(workspaceRoot, 'AGENT.md');
+    const claudeMdPath = path.join(workspaceRoot, 'CLAUDE.md');
+    const exists = fs.existsSync(agentMdPath) || fs.existsSync(claudeMdPath);
+    const rows = exists
+        ? [
+            { id: 'skip', label: 'Skip', value: 'keep existing file', description: 'Leave the current AGENT.md / CLAUDE.md alone' },
+            { id: 'overwrite', label: 'Overwrite', value: 'replace contents', description: 'Drop the starter template over the existing file' },
+        ]
+        : [
+            { id: 'write', label: 'Write AGENT.md', value: 'recommended', description: 'Scaffold a starter template in the workspace root' },
+            { id: 'skip', label: 'Skip', value: 'no file', description: 'Write AGENT.md manually later' },
+        ];
+    return (_jsx(Picker, { title: 'AGENT.md', subtitle: exists
+            ? 'Workspace already has AGENT.md / CLAUDE.md — skipping by default. Pick "Overwrite" only if you really want to replace it.'
+            : 'AGENT.md gives every coding agent (Claude Code, Codex, BrainRouter, …) a single hub of repo conventions. Recommended.', badge: progressBadge('agentMd'), rows: rows, initialCursor: 0, accentColor: accent, onResolve: (r) => {
+            if (r.kind === 'cancelled')
+                return onAbort();
+            if (r.kind !== 'pick')
+                return;
+            onPick(r.id === 'write' || r.id === 'overwrite');
+        } }));
+}
+function DoneStep({ state, accent, onCommit }) {
+    useEffect(() => {
+        onCommit();
+    }, [onCommit]);
+    return (_jsx(Frame, { title: '\u2713 Setup complete', badge: 'Done', accentColor: accent, children: _jsxs(Box, { flexDirection: 'column', children: [_jsx(SummaryRow, { label: 'theme', value: state.draft.theme ?? 'dark' }), _jsx(SummaryRow, { label: 'provider', value: state.draft.provider?.label ?? '(unset)' }), _jsx(SummaryRow, { label: 'model', value: state.draft.model ?? '(unset)' }), _jsx(SummaryRow, { label: 'api key', value: maskApiKey(state.draft.apiKey ?? '') }), _jsx(SummaryRow, { label: 'mcp', value: formatMcpSummary(state.draft.mcp) }), _jsx(SummaryRow, { label: 'agent.md', value: state.draft.writeAgentMd ? 'written' : 'skipped' }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", dimColor: true, children: "Config saved to ~/.config/brainrouter/config.json. Re-run any time with /init. Tweak individual knobs with /config." }) }), state.warnings.length > 0 ? (_jsxs(Box, { flexDirection: 'column', marginTop: 1, children: [_jsx(Text, { color: "yellow", children: "Advisories:" }), state.warnings.map((w, i) => (_jsxs(Box, { children: [_jsx(Text, { color: "yellow", children: "  ! " }), _jsx(Text, { children: w.message })] }, i)))] })) : null] }) }));
+}
+function SummaryRow({ label, value }) {
+    return (_jsxs(Box, { children: [_jsx(Box, { width: 10, children: _jsx(Text, { color: "gray", children: label }) }), _jsx(Text, { children: value })] }));
+}
+function formatMcpSummary(pick) {
+    if (!pick)
+        return '(unset)';
+    if (pick.kind === 'local-stdio')
+        return 'local stdio (brainrouter-mcp)';
+    if (pick.kind === 'local-http') {
+        return pick.apiKey
+            ? `local http (http://localhost:3747/mcp) · key ${maskApiKey(pick.apiKey)}`
+            : 'local http (http://localhost:3747/mcp) · no key';
+    }
+    if (pick.kind === 'remote-http') {
+        return pick.apiKey
+            ? `remote · ${pick.url} · key ${maskApiKey(pick.apiKey)}`
+            : `remote · ${pick.url} · no key`;
+    }
+    return 'skipped (offline-only)';
+}

package/dist/cli/ink/ambientChat.d.ts

@@ -0,0 +1,34 @@
+import type { ReactElement } from 'react';
+/**
+ * Process-wide reference to the chat REPL's ChatController, set when
+ * `runChat` mounts and cleared when it unmounts. Lets `runPicker` /
+ * `runTextField` detect "I'm being called from inside the Ink chat
+ * REPL" and route their UI through the chat's overlay slot instead of
+ * mounting a SECOND Ink instance on the same stdin.
+ *
+ * Why a module-level ref rather than React context: the call site is
+ * `cli/commands/config.ts` -> `runHomePanel(ctx)` -> `runPicker(opts)`,
+ * which is a plain async function chain — there's no React tree at the
+ * dispatch entry. The ChatController lives inside the chat React tree
+ * but the slash-command dispatcher is outside it. A module-level
+ * ambient binding bridges the two without forcing every dispatcher to
+ * thread a controller argument through every command handler.
+ *
+ * Mutual exclusion: only ONE chat instance should ever be mounted at a
+ * time, so a single global is sufficient. setAmbientChat(undefined)
+ * MUST be called on unmount, otherwise a later standalone runPicker
+ * call would try to render into a dead controller.
+ */
+export interface AmbientChatController {
+    /**
+     * Render `node` as an overlay above the chat composer. The promise
+     * resolves when `clearOverlay()` is called. Callers typically wire
+     * `<Picker onResolve={...}>` to a callback that resolves the outer
+     * promise and immediately calls clearOverlay().
+     */
+    showOverlay(node: ReactElement): Promise<void>;
+    /** Remove whatever overlay is currently shown; safe to call when none is set. */
+    clearOverlay(): void;
+}
+export declare function setAmbientChat(controller: AmbientChatController | undefined): void;
+export declare function getAmbientChat(): AmbientChatController | undefined;

package/dist/cli/ink/ambientChat.js

@@ -0,0 +1,7 @@
+let ambient;
+export function setAmbientChat(controller) {
+    ambient = controller;
+}
+export function getAmbientChat() {
+    return ambient;
+}

package/dist/cli/ink/consoleCapture.d.ts

@@ -0,0 +1,11 @@
+export interface CapturedConsole<T> {
+    result: T;
+    output: string;
+}
+/**
+ * Legacy slash-command handlers still write through console.log/warn/error.
+ * In the Ink chat shell, letting those writes escape makes Ink promote them
+ * above the live frame, which visually places command output before the
+ * BrainRouter banner. Capture the writes and replay them into scrollback.
+ */
+export declare function captureConsoleOutput<T>(fn: () => Promise<T> | T): Promise<CapturedConsole<T>>;

package/dist/cli/ink/consoleCapture.js

@@ -0,0 +1,33 @@
+import { format } from 'node:util';
+/**
+ * Legacy slash-command handlers still write through console.log/warn/error.
+ * In the Ink chat shell, letting those writes escape makes Ink promote them
+ * above the live frame, which visually places command output before the
+ * BrainRouter banner. Capture the writes and replay them into scrollback.
+ */
+export async function captureConsoleOutput(fn) {
+    const originals = {
+        log: console.log,
+        warn: console.warn,
+        error: console.error,
+        info: console.info,
+    };
+    let output = '';
+    const append = (...args) => {
+        output += format(...args) + '\n';
+    };
+    console.log = append;
+    console.warn = append;
+    console.error = append;
+    console.info = append;
+    try {
+        const result = await fn();
+        return { result, output };
+    }
+    finally {
+        console.log = originals.log;
+        console.warn = originals.warn;
+        console.error = originals.error;
+        console.info = originals.info;
+    }
+}

package/dist/cli/ink/markdownRender.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Render markdown source to ANSI-styled terminal text suitable for an
+ * Ink `<Text>` element. Idempotent across calls (configures `marked`
+ * lazily on the first invocation).
+ *
+ * Empty / non-string input returns the input verbatim.
+ */
+export declare function renderMarkdown(source: string): string;
+/**
+ * Strip a single outer ``` markdown / ``` md fence pair when it wraps the
+ * entire input. Some LLMs (especially when asked to "format your reply
+ * in markdown") emit the whole response inside ``` markdown ... ``` —
+ * which then renders as a single yellow code block instead of formatted
+ * text. Direct port of codex's helper (markdown.rs:86–123).
+ *
+ * Also strips fences around tables — LLMs sometimes wrap tables in ``` md
+ * to "protect" the pipe characters, but marked then renders the table
+ * as code instead of as a native table.
+ *
+ * Exported for tests; the renderMarkdown caller chains this in.
+ */
+export declare function unwrapMarkdownFences(source: string): string;
+/**
+ * Re-scope ANSI styling across newline boundaries so each rendered line
+ * carries its own complete open/close pair.
+ *
+ * Walks the input as a stream of segments — plain text, ANSI SGR
+ * sequences, and `\n` — maintaining a small state machine of active
+ * styles (foreground color, background color, set of attribute flags).
+ * At every `\n`, emit a "close everything currently open" sequence,
+ * then the newline, then a "reopen everything that was open" sequence.
+ *
+ * Edge cases handled:
+ *   - 256-color (38;5;N) and truecolor (38;2;R;G;B) sequences — treated
+ *     as opaque opening codes, replayed verbatim
+ *   - `0` / empty params reset all state
+ *   - already-empty active state at a newline → emit just the newline
+ *
+ * Exported for tests.
+ */
+export declare function preserveAnsiAcrossNewlines(text: string): string;