@kinqs/brainrouter-cli 0.3.6 → 0.3.8

package/dist/cli/slashSuggest.d.ts

@@ -0,0 +1,32 @@
+import type readline from 'node:readline';
+import { type Theme } from './theme.js';
+export interface SlashCommand {
+    /** "/help", "/config", etc. — the literal token the user types. */
+    cmd: string;
+    /** One-line description shown after the em-dash. */
+    description: string;
+}
+export interface SlashSuggestController {
+    /** Call after every readline keypress to refresh the popup. */
+    onKey(): void;
+    /** Force-hide the popup (called on submit / cancel). */
+    hide(): void;
+    /** Returns true while the popup is visible. */
+    isVisible(): boolean;
+}
+export interface SlashSuggestOpts {
+    rl: readline.Interface;
+    commands: SlashCommand[];
+    theme?: Theme;
+}
+/**
+ * Two-tier rank for a single command against a query. Lower wins.
+ *
+ *   0  command starts with query (after the leading /)
+ *   1  command contains query
+ *   2  description contains query
+ *   3  no match
+ */
+export declare function scoreSlashCommand(cmd: SlashCommand, query: string): number;
+export declare function filterAndSort(commands: SlashCommand[], query: string): SlashCommand[];
+export declare function createSlashSuggest(opts: SlashSuggestOpts): SlashSuggestController;

package/dist/cli/slashSuggest.js

@@ -0,0 +1,146 @@
+import { buildTheme } from './theme.js';
+/**
+ * 0.3.7 — slash-command autosuggest popup.
+ *
+ * Renders a filtered list of slash commands BELOW the prompt as the
+ * user types. Hides automatically when the input no longer starts
+ * with `/`. Updates on every keystroke.
+ *
+ * Pattern lineage:
+ *   - Two-tier ranking (exact → prefix → includes, lower wins, stable
+ *     secondary sort by original index) lifted from
+ *     `openSrc/grok-cli/src/ui/slash-menu.ts:44-64`.
+ *   - Popup height cap (max ~6 visible) from
+ *     `openSrc/codex/codex-rs/tui/src/bottom_pane/popup_consts.rs`
+ *     and the Claude Code CHANGELOG note (line 378) explicitly
+ *     capping the popup at "3-5 visible commands instead of scaling
+ *     with terminal height."
+ *
+ * Render strategy (kept simple — no scroll-region tricks needed):
+ *
+ *   - On every keystroke we check `rl.line`. If it starts with `/`,
+ *     compute the filtered list and (re)render the popup BELOW the
+ *     current prompt line. The cursor is saved before the popup
+ *     write and restored after — readline's prompt position stays
+ *     untouched.
+ *   - If the popup was previously visible AND should now be hidden
+ *     (input no longer starts with `/`, or no matches), erase the
+ *     popup region with `\x1b[J` from the position one line below
+ *     the prompt.
+ *
+ * The function returns a controller you can wire into the REPL —
+ * call `controller.onKey()` after each readline keypress to refresh.
+ * Call `controller.hide()` on submit / cancel.
+ */
+const MAX_VISIBLE = 6;
+/**
+ * Two-tier rank for a single command against a query. Lower wins.
+ *
+ *   0  command starts with query (after the leading /)
+ *   1  command contains query
+ *   2  description contains query
+ *   3  no match
+ */
+export function scoreSlashCommand(cmd, query) {
+    if (!query)
+        return 0;
+    const q = query.toLowerCase();
+    const cmdBody = cmd.cmd.slice(1).toLowerCase(); // skip the leading /
+    if (cmdBody.startsWith(q))
+        return 0;
+    if (cmdBody.includes(q))
+        return 1;
+    if (cmd.description.toLowerCase().includes(q))
+        return 2;
+    return 3;
+}
+export function filterAndSort(commands, query) {
+    if (!query)
+        return commands.slice(0, MAX_VISIBLE);
+    const scored = commands
+        .map((c, i) => ({ c, i, s: scoreSlashCommand(c, query) }))
+        .filter((x) => x.s < 3);
+    scored.sort((a, b) => (a.s - b.s) || (a.i - b.i)); // stable by original index
+    return scored.slice(0, MAX_VISIBLE).map((x) => x.c);
+}
+export function createSlashSuggest(opts) {
+    const theme = opts.theme ?? buildTheme('dark');
+    const stdout = process.stdout;
+    let lastVisible = false;
+    let lastHeight = 0;
+    let lastQuery = '';
+    const readLine = () => {
+        const rl = opts.rl;
+        return rl.line ?? '';
+    };
+    const erase = () => {
+        if (!lastVisible)
+            return;
+        // Save cursor → move to col 0 of next line → erase from cursor to
+        // end of screen → restore cursor. `\x1b[s` and `\x1b[u` are the
+        // SCO sequences; widely supported.
+        stdout.write('\x1b7'); // DECSC — save cursor + attrs (more reliable than \x1b[s in xterm)
+        stdout.write('\n'); // move down one
+        stdout.write('\r'); // col 0
+        stdout.write('\x1b[J'); // erase from here to end of screen
+        stdout.write('\x1b8'); // DECRC — restore cursor
+        lastVisible = false;
+        lastHeight = 0;
+    };
+    const render = (matches) => {
+        // Pad command column for alignment.
+        const cmdWidth = Math.max(...matches.map((m) => m.cmd.length));
+        const lines = matches.map((m, idx) => {
+            const cmdPart = theme.heading(m.cmd.padEnd(cmdWidth, ' '));
+            const arrow = theme.dim('—');
+            const desc = theme.muted(m.description);
+            // First match gets a `›` marker; others a space.
+            const marker = idx === 0 ? theme.primary('›') : ' ';
+            return `  ${marker} ${cmdPart}  ${arrow}  ${desc}`;
+        });
+        // Hint line under the suggestions.
+        lines.push(theme.dim('    Tab to autocomplete  ·  Enter to submit  ·  type to filter'));
+        // First, erase any previous popup.
+        if (lastVisible) {
+            stdout.write('\x1b7');
+            stdout.write('\n\r\x1b[J');
+            stdout.write('\x1b8');
+        }
+        // Now draw the new popup below the prompt:
+        stdout.write('\x1b7');
+        stdout.write('\n'); // step down to a new line
+        stdout.write('\r');
+        for (let i = 0; i < lines.length; i++) {
+            stdout.write(lines[i]);
+            if (i < lines.length - 1)
+                stdout.write('\n\r');
+        }
+        stdout.write('\x1b8'); // restore cursor to the prompt input position
+        lastVisible = true;
+        lastHeight = lines.length;
+    };
+    return {
+        onKey: () => {
+            const line = readLine();
+            if (!line.startsWith('/')) {
+                if (lastVisible)
+                    erase();
+                lastQuery = '';
+                return;
+            }
+            const query = line.slice(1);
+            if (query === lastQuery && lastVisible)
+                return; // no-op
+            lastQuery = query;
+            const matches = filterAndSort(opts.commands, query);
+            if (matches.length === 0) {
+                if (lastVisible)
+                    erase();
+                return;
+            }
+            render(matches);
+        },
+        hide: () => { erase(); lastQuery = ''; },
+        isVisible: () => lastVisible,
+    };
+}

package/dist/cli/wizard/modelsApi.d.ts

@@ -0,0 +1,72 @@
+import type { Theme } from '../theme.js';
+import type { ProviderEntry } from './providers.js';
+/**
+ * Fetch the live model list from an OpenAI-compatible `/v1/models`
+ * endpoint and return them as a sorted, deduped string array.
+ *
+ * Every OpenAI-compatible server we ship a provider entry for honours
+ * `GET <endpoint>/models` (OpenAI, DeepSeek, OpenRouter, LM Studio,
+ * Ollama, vLLM, gateway proxies like LiteLLM). The response shape is
+ * `{ object: 'list', data: [{ id: string, owned_by?: string, ... }] }`.
+ *
+ * We derive the `/models` URL from the provider's chat endpoint by
+ * stripping the trailing `/chat/completions` path segment. That works
+ * for every endpoint shape we care about:
+ *
+ *   https://api.openai.com/v1/chat/completions    → /v1/models
+ *   http://localhost:1234/v1/chat/completions     → /v1/models
+ *   https://openrouter.ai/api/v1/chat/completions → /api/v1/models
+ *
+ * 5-second timeout — if the call hangs or fails, the wizard falls
+ * back to the provider's curated static catalog so users on a slow
+ * link / behind a captive portal aren't blocked.
+ */
+export declare function fetchOpenAiCompatibleModels(provider: ProviderEntry, apiKey: string, endpointOverride?: string): Promise<{
+    ok: true;
+    models: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function deriveModelsUrl(chatEndpoint: string): string;
+/**
+ * Open the model picker — live `/v1/models` fetch with the provider's
+ * static catalog as the offline fallback. Returns the selected model id,
+ * or `undefined` when the user cancels.
+ *
+ * Used by both the onboarding wizard's Model step
+ * (`cli/wizard/runner.ts → runModelStep`) and the in-REPL `/model`
+ * quick-swap command (`cli/commands/ui.ts → /model`). Keeping a single
+ * implementation means a future enrichment (recently-used badge,
+ * cost-per-token hint, model-size group headers) lights up everywhere
+ * at once.
+ *
+ * `currentModel` (when supplied) defaults the picker cursor onto the
+ * currently active row — important for `/model` where the user almost
+ * always wants to confirm what's currently selected before changing.
+ */
+export interface SelectModelOptions {
+    theme: Theme;
+    provider: ProviderEntry;
+    apiKey: string;
+    /** Override the provider's default chat endpoint (custom-endpoint flow). */
+    endpointOverride?: string;
+    /** Active model id — cursor opens on this row when present. */
+    currentModel?: string;
+    /** Picker title (default: "Model"). */
+    title?: string;
+    /** Optional badge rendered next to the title. */
+    badge?: string;
+    /** Erase the picker frame after a selection (true for wizard, false for in-REPL). */
+    eraseOnClose?: boolean;
+}
+export interface SelectModelResult {
+    model: string;
+    /** Where the picker got its list from — surfaces in the success message. */
+    source: 'live' | 'static' | 'fallback';
+    /** Number of models the live call returned (0 when source !== 'live'). */
+    liveCount: number;
+    /** Live-call error message when source !== 'live' (omitted on live success). */
+    liveError?: string;
+}
+export declare function selectModel(opts: SelectModelOptions): Promise<SelectModelResult | undefined>;

package/dist/cli/wizard/modelsApi.js

@@ -0,0 +1,166 @@
+import { runPicker } from '../ink/runPicker.js';
+/**
+ * Fetch the live model list from an OpenAI-compatible `/v1/models`
+ * endpoint and return them as a sorted, deduped string array.
+ *
+ * Every OpenAI-compatible server we ship a provider entry for honours
+ * `GET <endpoint>/models` (OpenAI, DeepSeek, OpenRouter, LM Studio,
+ * Ollama, vLLM, gateway proxies like LiteLLM). The response shape is
+ * `{ object: 'list', data: [{ id: string, owned_by?: string, ... }] }`.
+ *
+ * We derive the `/models` URL from the provider's chat endpoint by
+ * stripping the trailing `/chat/completions` path segment. That works
+ * for every endpoint shape we care about:
+ *
+ *   https://api.openai.com/v1/chat/completions    → /v1/models
+ *   http://localhost:1234/v1/chat/completions     → /v1/models
+ *   https://openrouter.ai/api/v1/chat/completions → /api/v1/models
+ *
+ * 5-second timeout — if the call hangs or fails, the wizard falls
+ * back to the provider's curated static catalog so users on a slow
+ * link / behind a captive portal aren't blocked.
+ */
+export async function fetchOpenAiCompatibleModels(provider, apiKey, endpointOverride) {
+    const chatEndpoint = endpointOverride ?? provider.endpoint;
+    const modelsUrl = deriveModelsUrl(chatEndpoint);
+    const headers = { 'Content-Type': 'application/json' };
+    // Cloud providers always want a Bearer header. Local endpoints (LM
+    // Studio, Ollama) accept anything OR nothing, but sending the key
+    // through doesn't hurt — they ignore it.
+    if (apiKey.trim().length > 0) {
+        headers['Authorization'] = `Bearer ${apiKey.trim()}`;
+    }
+    else if (provider.local) {
+        // Some local servers reject requests with NO Authorization header
+        // even though they don't validate the value. A literal "local"
+        // bearer is the convention for LM Studio / Ollama config snippets.
+        headers['Authorization'] = 'Bearer local';
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5_000);
+    try {
+        const res = await fetch(modelsUrl, {
+            method: 'GET',
+            headers,
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            return { ok: false, error: `HTTP ${res.status} ${res.statusText} — ${text.slice(0, 200)}` };
+        }
+        const data = await res.json();
+        const list = Array.isArray(data?.data) ? data.data : [];
+        const ids = list
+            .map((m) => (typeof m?.id === 'string' ? m.id : null))
+            .filter((s) => !!s);
+        if (ids.length === 0) {
+            return { ok: false, error: 'endpoint returned an empty model list' };
+        }
+        return { ok: true, models: dedupeAndSort(ids) };
+    }
+    catch (err) {
+        if (err?.name === 'AbortError') {
+            return { ok: false, error: 'timed out after 5s' };
+        }
+        return { ok: false, error: String(err?.message ?? err) };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export function deriveModelsUrl(chatEndpoint) {
+    // Replace a trailing `/chat/completions` (with optional trailing
+    // slash) with `/models`. If the endpoint doesn't end in
+    // `/chat/completions` (already a base URL, custom path), append
+    // `/models` directly.
+    const trimmed = chatEndpoint.replace(/\/+$/, '');
+    if (trimmed.endsWith('/chat/completions')) {
+        return trimmed.slice(0, -'/chat/completions'.length) + '/models';
+    }
+    return trimmed + '/models';
+}
+function dedupeAndSort(ids) {
+    return Array.from(new Set(ids)).sort((a, b) => a.localeCompare(b));
+}
+export async function selectModel(opts) {
+    const { provider, apiKey, endpointOverride, currentModel, theme } = opts;
+    let modelsList = provider.models;
+    let source = 'static';
+    let liveCount = 0;
+    let liveError;
+    let subtitleHint = `Pick the chat model for ${provider.label}.`;
+    // Live fetch is gated on either having a key (cloud) or running local.
+    // Skipping the fetch entirely when neither is true avoids a guaranteed
+    // 401 / network error on the loading frame.
+    if (apiKey.trim().length > 0 || provider.local) {
+        const fetched = await fetchOpenAiCompatibleModels(provider, apiKey, endpointOverride);
+        if (fetched.ok) {
+            const live = fetched.models;
+            // Default model floats to the top so "(default)" stays in the
+            // natural-first position the user expects. Then the currently-
+            // active model floats next (cursor lands here below).
+            const reordered = floatToTop(live, [provider.defaultModel]);
+            modelsList = reordered;
+            source = 'live';
+            liveCount = live.length;
+            subtitleHint = `Pick a model — ${live.length} returned by ${provider.label}'s /v1/models endpoint. Use "Other" to type any name.`;
+        }
+        else {
+            source = 'fallback';
+            liveError = fetched.error;
+            subtitleHint = `Pick a model. (Live list unavailable — ${fetched.error}. Showing curated short-list.) Use "Other" to type any name.`;
+        }
+    }
+    const finalList = modelsList.length > 0 ? modelsList : [provider.defaultModel];
+    const rows = finalList.map((m) => ({
+        id: m,
+        label: m,
+        value: m === currentModel ? 'current' :
+            m === provider.defaultModel ? 'default' : '',
+    }));
+    // Cursor priority: currently-active model > provider default > top.
+    let initialCursor = 0;
+    if (currentModel) {
+        const idx = finalList.indexOf(currentModel);
+        if (idx >= 0)
+            initialCursor = idx;
+    }
+    if (initialCursor === 0 && !currentModel) {
+        const idx = finalList.indexOf(provider.defaultModel);
+        if (idx >= 0)
+            initialCursor = idx;
+    }
+    const result = await runPicker({
+        theme,
+        title: opts.title ?? 'Model',
+        subtitle: subtitleHint,
+        badge: opts.badge,
+        rows,
+        initialCursor,
+        allowOther: true,
+        otherLabel: 'Other model',
+        otherDescription: 'Type any model name supported by this endpoint',
+        eraseOnClose: opts.eraseOnClose ?? false,
+    });
+    if (result.kind === 'cancelled')
+        return undefined;
+    const model = (result.kind === 'other' ? result.text.trim() : result.id) || provider.defaultModel;
+    return { model, source, liveCount, liveError };
+}
+function floatToTop(list, priority) {
+    const seen = new Set();
+    const front = [];
+    for (const p of priority) {
+        if (list.includes(p) && !seen.has(p)) {
+            front.push(p);
+            seen.add(p);
+        }
+    }
+    for (const m of list) {
+        if (!seen.has(m)) {
+            front.push(m);
+            seen.add(m);
+        }
+    }
+    return front;
+}

package/dist/cli/wizard/picker.d.ts

@@ -0,0 +1,202 @@
+import { type Theme } from '../theme.js';
+/**
+ * Internal picker primitive — purpose-built for the wizard / `/config` /
+ * `/login` flows.
+ *
+ * Distinct from `cliPrompt.ts:askChoice` (which backs the LLM-callable
+ * `ask_user_choice` tool and is intentionally constrained: 2–4 options,
+ * always-on synthetic "Other" row, error envelopes for the agent). This
+ * picker has no LLM-tool constraints — N options, optional "Other" row,
+ * optional free-text input, optional live-preview callback that returns
+ * preview ROWS (rendered INSIDE the picker's frame) instead of writing
+ * to stdout.
+ *
+ * Render contract (atomic frame):
+ *
+ *   1. Caller passes ALL chrome (title, subtitle, options, footer hint)
+ *      as fields on `PickerView`. The picker computes the full frame
+ *      string in one pass and writes it with one `stdout.write`.
+ *   2. The picker owns its rendered region for its lifetime. NO call
+ *      site may write to stdout while the picker is active — preview
+ *      lines are returned from `onCursorChange` as a string[] that the
+ *      picker splices into its own frame. (Pattern lifted from
+ *      `openSrc/codex/codex-rs/tui/src/theme_picker.rs` — preview never
+ *      writes; the redraw owns the change.)
+ *   3. Redraw uses `\x1b[<N>F` (cursor up + col 0) + `\x1b[J` (erase to
+ *      end of screen) to nuke the previous frame, then writes the new
+ *      one. No `text + '\n'` off-by-one because we count the actual
+ *      lines we'll write.
+ *
+ * Why a separate file (not just an extension of `cliPrompt.ts`)? The
+ * LLM-tool contract for `ask_user_choice` is explicit ("2-4 options
+ * with mutually exclusive labels, always an Other fallback"), and
+ * widening it would weaken the constraint the system prompt teaches
+ * the model to follow. Internal CLI flows have different requirements
+ * (7 providers in a list, no "Other" for theme picker, free-text-only
+ * for API-key entry). Keep them in separate primitives.
+ */
+export interface PickerRow {
+    /** Stable id used in the resolved result. */
+    id: string;
+    /** Human-readable left-aligned label. */
+    label: string;
+    /** Right-aligned value column (current setting, hint text, status). Optional. */
+    value?: string;
+    /** Sub-line shown muted under the label. Optional. */
+    description?: string;
+    /** When true, the row is shown but not selectable (separator-like). */
+    disabled?: boolean;
+}
+export interface PickFromListOptions {
+    /** Bold title rendered at the top of the frame (e.g. "Theme"). */
+    title: string;
+    /** Muted subtitle under the title (e.g. "Pick a color palette."). Optional. */
+    subtitle?: string;
+    /** Right-side chip in the title bar (e.g. "Step 1 of 6"). Optional. */
+    badge?: string;
+    /** Footer hint line (e.g. "↑/↓ navigate · ENTER confirm · q to cancel"). Defaults are sensible. */
+    footer?: string;
+    /** Picker rows. No upper limit; height clamps automatically. */
+    rows: PickerRow[];
+    /** Initial cursor index. Clamped to [0, rows.length - 1]. */
+    initialCursor?: number;
+    /** When true, an "Other" row is appended that drops to free-text entry. */
+    allowOther?: boolean;
+    /** Label for the appended Other row (default: "Other"). */
+    otherLabel?: string;
+    /** Description for the Other row. */
+    otherDescription?: string;
+    /** Pre-fill the Other free-text buffer. Used by env-var-derived defaults. */
+    prefilledOther?: string;
+    /**
+     * Live-preview hook. Fires after a real cursor move only. Returns an
+     * array of preview lines to render INSIDE the picker frame (above the
+     * footer). Returning `undefined` or `[]` means "no preview".
+     *
+     * The picker takes care of the redraw — the callback must NOT write
+     * to stdout. Mirrors `openSrc/codex/codex-rs/tui/src/theme_picker.rs`
+     * (preview returns a row spec, never `stdout.write`).
+     */
+    onCursorChange?: (cursorId: string, cursorIndex: number) => string[] | undefined;
+    /** Theme for chrome coloring; defaults to `dark`. */
+    theme?: Theme;
+    /**
+     * When true, the frame is erased on close so the next picker (or
+     * print) lands at the same screen position. Wizard sets this so
+     * each step REPLACES the previous frame instead of stacking
+     * downward on screen.
+     */
+    eraseOnClose?: boolean;
+}
+export type PickFromListResult = {
+    kind: 'pick';
+    id: string;
+} | {
+    kind: 'other';
+    text: string;
+} | {
+    kind: 'cancelled';
+};
+/**
+ * Free-text-only entry. Used by the wizard's API-key step.
+ *
+ * Renders a single masked input row inside a framed panel. Same redraw
+ * contract as `pickFromList` — atomic frames, owns its region.
+ */
+export interface PromptTextOptions {
+    title: string;
+    subtitle?: string;
+    badge?: string;
+    /** Right-side chip in the title bar (e.g. "openai · cloud"). */
+    /** Pre-filled buffer (e.g. value from env). ENTER accepts as-is. */
+    prefilled?: string;
+    /** When true, render input as `·······abcd` (mask all but last 4). */
+    mask?: boolean;
+    /** Placeholder shown muted when the input is empty. */
+    placeholder?: string;
+    /** Footer hint. */
+    footer?: string;
+    /** Optional validator. Return undefined to accept; return string to show as an inline error. */
+    validate?: (raw: string) => string | undefined;
+    /** Theme for chrome coloring. */
+    theme?: Theme;
+    /** See PickFromListOptions.eraseOnClose. */
+    eraseOnClose?: boolean;
+}
+export type PromptTextResult = {
+    kind: 'accept';
+    text: string;
+} | {
+    kind: 'cancelled';
+};
+export declare function isInternalPickerActive(): boolean;
+interface FrameInputs {
+    theme: Theme;
+    title: string;
+    subtitle?: string;
+    badge?: string;
+    bodyLines: string[];
+    previewLines?: string[];
+    footer: string;
+    width: number;
+}
+/**
+ * Compute the full picker frame as a single string. Pure function so
+ * tests can assert on the exact output without driving a TTY.
+ *
+ * Layout (single column for now — wide-terminal two-column comes in a
+ * follow-up):
+ *
+ *   ┌─ <title> ─────────────────────── <badge> ─┐
+ *   │ <subtitle>                                │
+ *   │                                           │
+ *   │ <body line 1>                             │
+ *   │ <body line 2>                             │
+ *   │ ...                                       │
+ *   │                                           │  (preview block if present)
+ *   │ <preview line 1>                          │
+ *   │ <preview line 2>                          │
+ *   │                                           │
+ *   │ <footer>                                  │
+ *   └───────────────────────────────────────────┘
+ */
+export declare function renderFrame(f: FrameInputs): string;
+/** ANSI-aware right-pad. Strips ANSI sequences when counting width. */
+declare function padRightVisible(s: string, w: number): string;
+declare function visibleLength(s: string): number;
+declare function stripAnsi(s: string): string;
+/** Simple word-wrap; doesn't try to be ANSI-aware (subtitle takes plain text). */
+declare function wrap(s: string, w: number): string[];
+declare function formatBodyRow(t: Theme, row: PickerRow, isSelected: boolean, valueColWidth: number, inner: number): string[];
+export declare function pickFromList(opts: PickFromListOptions): Promise<PickFromListResult>;
+declare function computeValueColumn(rows: PickerRow[]): number;
+declare function defaultFooter(phase: 'pick' | 'other', allowOther: boolean): string;
+export declare function promptText(opts: PromptTextOptions): Promise<PromptTextResult>;
+export interface FramedInputOptions {
+    /**
+     * When true (default), the frame is **erased** when the picker
+     * closes — the cursor ends up where the frame started, so the next
+     * print overwrites the same screen region. Every caller in the
+     * wizard / `/config` / `/login` flows wants this behaviour:
+     * pickers are modal, not transcript-y.
+     *
+     * Set to false explicitly to leave the frame on screen as
+     * scrollback after close (the cursor lands one line below).
+     * No current callers use this; reserved for future surfaces
+     * (e.g. an `/agents` picker where the user wants the list to
+     * stay visible).
+     */
+    eraseOnClose?: boolean;
+}
+/** Pure helpers exposed for unit tests. */
+export declare const __test: {
+    renderFrame: typeof renderFrame;
+    formatBodyRow: typeof formatBodyRow;
+    visibleLength: typeof visibleLength;
+    stripAnsi: typeof stripAnsi;
+    wrap: typeof wrap;
+    padRightVisible: typeof padRightVisible;
+    computeValueColumn: typeof computeValueColumn;
+    defaultFooter: typeof defaultFooter;
+};
+export {};