@aragon-agent/cli 0.4.3

package/dist/ui/layout/scroll.js

@@ -0,0 +1,76 @@
+/**
+ * Scroll maths for the self-drawn viewport (spec §4.5). Pure, React-free.
+ *
+ * `offset` counts LINES FROM THE BOTTOM — equivalently, the number of rows
+ * currently hidden BELOW the viewport. `0` means pinned to the newest output;
+ * `overflowLines` means parked at the very top. Counting from the bottom is what
+ * makes auto-follow free: when new content arrives `overflowLines` grows while
+ * `offset` stays 0, so the viewport keeps showing the tail without anyone
+ * calling a "scroll to bottom" routine.
+ *
+ * The rows hidden ABOVE are therefore `overflowLines - offset`. Mixing the two
+ * up inverts both the bottom-snap test and the "N new lines" hint.
+ */
+/**
+ * Rows of context kept across a page turn, and — not a coincidence — the
+ * bottom-snap tolerance. The tolerance must be >= whatever a page turn can
+ * leave behind, or PgDn parks the user in a fake off-bottom state that they
+ * cannot press their way out of.
+ */
+const PAGE_CONTEXT_LINES = 2;
+export const BOTTOM_SNAP_TOLERANCE = PAGE_CONTEXT_LINES;
+export function clampScroll(offset, overflowLines) {
+    const max = Math.max(0, overflowLines);
+    if (!Number.isFinite(offset) || offset < 0)
+        return 0;
+    return Math.min(Math.floor(offset), max);
+}
+export function pageSize(viewportHeight) {
+    return Math.max(1, Math.floor(viewportHeight) - PAGE_CONTEXT_LINES);
+}
+export function isPinnedToBottom(state) {
+    return state.offset === 0;
+}
+/** Intents that move toward the newest output; only these snap to the bottom. */
+function isDownward(intent) {
+    return intent === 'lineDown' || intent === 'pageDown' || intent === 'toBottom';
+}
+export function applyScroll(state, intent, metrics) {
+    const overflowLines = Math.max(0, metrics.content - metrics.viewport);
+    const page = pageSize(metrics.viewport);
+    let next;
+    switch (intent) {
+        case 'lineUp':
+            next = state.offset + 1;
+            break;
+        case 'lineDown':
+            next = state.offset - 1;
+            break;
+        case 'pageUp':
+            next = state.offset + page;
+            break;
+        case 'pageDown':
+            next = state.offset - page;
+            break;
+        case 'toTop':
+            next = overflowLines;
+            break;
+        case 'toBottom':
+            next = 0;
+            break;
+    }
+    const clamped = clampScroll(next, overflowLines);
+    // `offset` IS the number of rows hidden below the viewport, so proximity to
+    // the bottom is `offset <= tolerance` — not `overflowLines - offset`, which
+    // measures the distance to the TOP. Without the snap, a PgDn that lands one
+    // row short parks the user in a fake off-bottom state (a stuck `↑1` and a
+    // permanent "new lines" hint) that no further PgDn can clear, because the
+    // hint row itself shrinks the viewport and keeps re-introducing the residue.
+    //
+    // Downward intents only: with the correct comparison, snapping on the way up
+    // would turn `lineUp` from a pinned viewport into a no-op.
+    if (isDownward(intent) && clamped <= BOTTOM_SNAP_TOLERANCE) {
+        return { offset: 0 };
+    }
+    return { offset: clamped };
+}

package/dist/ui/layout/useTerminalSize.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Terminal size hook (spec §4.11).
+ *
+ * Ink recomputes its own layout on resize, but the React layer needs the new
+ * `rows` to update `height={frameHeight(rows)}`. Without this hook the frame
+ * keeps its old height after the window grows and leaves a dead band at the
+ * bottom of the screen.
+ */
+export interface TerminalSize {
+    rows: number;
+    cols: number;
+}
+export declare function useTerminalSize(): TerminalSize;

package/dist/ui/layout/useTerminalSize.js

@@ -0,0 +1,50 @@
+/**
+ * Terminal size hook (spec §4.11).
+ *
+ * Ink recomputes its own layout on resize, but the React layer needs the new
+ * `rows` to update `height={frameHeight(rows)}`. Without this hook the frame
+ * keeps its old height after the window grows and leaves a dead band at the
+ * bottom of the screen.
+ */
+import { useEffect, useState } from 'react';
+import { useStdout } from 'ink';
+import { FALLBACK_COLS, FALLBACK_ROWS } from './frame.js';
+/** Coalesce the burst of resize events a window drag produces. */
+const RESIZE_THROTTLE_MS = 50;
+function readSize(stdout) {
+    const rows = stdout?.rows;
+    const cols = stdout?.columns;
+    return {
+        rows: rows && rows > 0 ? rows : FALLBACK_ROWS,
+        cols: cols && cols > 0 ? cols : FALLBACK_COLS,
+    };
+}
+export function useTerminalSize() {
+    const { stdout } = useStdout();
+    const [size, setSize] = useState(() => readSize(stdout));
+    useEffect(() => {
+        const stream = stdout;
+        if (!stream || typeof stream.on !== 'function')
+            return undefined;
+        let timer = null;
+        const onResize = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                timer = null;
+                const next = readSize(stream);
+                setSize((prev) => (prev.rows === next.rows && prev.cols === next.cols ? prev : next));
+            }, RESIZE_THROTTLE_MS);
+        };
+        stream.on('resize', onResize);
+        return () => {
+            if (timer)
+                clearTimeout(timer);
+            if (typeof stream.off === 'function')
+                stream.off('resize', onResize);
+            else if (typeof stream.removeListener === 'function')
+                stream.removeListener('resize', onResize);
+        };
+    }, [stdout]);
+    return size;
+}

package/dist/ui/markdown-blocks.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Markdown parsing layer (spec §4.7). Pure and React-free so the grammar can be
+ * unit-tested without rendering anything.
+ *
+ * Scope is deliberately small — this is not CommonMark. It covers what a coding
+ * agent's answers actually contain: fenced code, headings, lists, quotes, rules,
+ * tables, and inline emphasis / code / strikethrough.
+ */
+/** Heading levels are rendered with three distinct weights, not one (§4.7). */
+export interface HeadingBlock {
+    kind: 'heading';
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+}
+export interface RuleBlock {
+    kind: 'rule';
+}
+export interface TableBlock {
+    kind: 'table';
+    /** Already column-aligned; render as plain monospace rows. */
+    rows: string[][];
+    align: ('left' | 'right' | 'center')[];
+}
+export declare function parseHeading(line: string): HeadingBlock | null;
+export declare function isRule(line: string): boolean;
+/** Split one `| a | b |` row into trimmed cells. Returns null if not a row. */
+export declare function parseTableRow(line: string): string[] | null;
+/** Is this the `|---|:--:|` divider that makes the preceding row a header? */
+export declare function isTableDivider(line: string): boolean;
+export declare function tableAlignments(dividerLine: string): TableBlock['align'];
+/**
+ * Pad a parsed table into fixed-width columns. Returns one string per row —
+ * no borders, because a bordered table inside an already-indented gutter wraps
+ * on any realistic terminal.
+ */
+export declare function formatTable(rows: string[][], align: TableBlock['align']): string[];
+export type InlineSpan = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'code';
+    text: string;
+} | {
+    kind: 'bold';
+    text: string;
+} | {
+    kind: 'italic';
+    text: string;
+} | {
+    kind: 'strike';
+    text: string;
+};
+/**
+ * Two passes, and that ordering is the fix (§4.7).
+ *
+ * The old single regex alternated `code | bold | italic` at the same level, so
+ * `**bold with `code` inside**` matched neither branch cleanly and rendered as
+ * literal asterisks. Splitting code out FIRST — and never looking for emphasis
+ * inside a code span — resolves both cases: emphasis around code now works, and
+ * asterisks inside code stay literal, which is what a shell snippet needs.
+ */
+export declare function parseInline(text: string): InlineSpan[];

package/dist/ui/markdown-blocks.js

@@ -0,0 +1,120 @@
+/**
+ * Markdown parsing layer (spec §4.7). Pure and React-free so the grammar can be
+ * unit-tested without rendering anything.
+ *
+ * Scope is deliberately small — this is not CommonMark. It covers what a coding
+ * agent's answers actually contain: fenced code, headings, lists, quotes, rules,
+ * tables, and inline emphasis / code / strikethrough.
+ */
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
+/** `---`, `***` or `___`, three or more, nothing else on the line. */
+const RULE_RE = /^(?:-{3,}|\*{3,}|_{3,})$/;
+const TABLE_ROW_RE = /^\s*\|(.+)\|\s*$/;
+const TABLE_DIVIDER_CELL_RE = /^:?-{1,}:?$/;
+export function parseHeading(line) {
+    const m = HEADING_RE.exec(line);
+    if (!m)
+        return null;
+    return { kind: 'heading', level: m[1].length, text: m[2] ?? '' };
+}
+export function isRule(line) {
+    return RULE_RE.test(line.trim());
+}
+/** Split one `| a | b |` row into trimmed cells. Returns null if not a row. */
+export function parseTableRow(line) {
+    const m = TABLE_ROW_RE.exec(line);
+    if (!m)
+        return null;
+    return m[1].split('|').map((c) => c.trim());
+}
+/** Is this the `|---|:--:|` divider that makes the preceding row a header? */
+export function isTableDivider(line) {
+    const cells = parseTableRow(line);
+    if (!cells || cells.length === 0)
+        return false;
+    return cells.every((c) => TABLE_DIVIDER_CELL_RE.test(c));
+}
+export function tableAlignments(dividerLine) {
+    const cells = parseTableRow(dividerLine) ?? [];
+    return cells.map((c) => {
+        const left = c.startsWith(':');
+        const right = c.endsWith(':');
+        if (left && right)
+            return 'center';
+        if (right)
+            return 'right';
+        return 'left';
+    });
+}
+/**
+ * Pad a parsed table into fixed-width columns. Returns one string per row —
+ * no borders, because a bordered table inside an already-indented gutter wraps
+ * on any realistic terminal.
+ */
+export function formatTable(rows, align) {
+    const colCount = Math.max(...rows.map((r) => r.length), 0);
+    const widths = [];
+    for (let c = 0; c < colCount; c += 1) {
+        widths[c] = Math.max(...rows.map((r) => (r[c] ?? '').length), 0);
+    }
+    return rows.map((row) => row
+        .map((cell, c) => {
+        const w = widths[c] ?? 0;
+        const a = align[c] ?? 'left';
+        if (a === 'right')
+            return cell.padStart(w);
+        if (a === 'center') {
+            const total = w - cell.length;
+            const left = Math.floor(total / 2);
+            return ' '.repeat(left) + cell + ' '.repeat(total - left);
+        }
+        return cell.padEnd(w);
+    })
+        .join('  ')
+        .trimEnd());
+}
+const CODE_RE = /`[^`]+`/g;
+const EMPHASIS_RE = /(\*\*[^*]+\*\*|~~[^~]+~~|\*[^*]+\*)/g;
+/**
+ * Two passes, and that ordering is the fix (§4.7).
+ *
+ * The old single regex alternated `code | bold | italic` at the same level, so
+ * `**bold with `code` inside**` matched neither branch cleanly and rendered as
+ * literal asterisks. Splitting code out FIRST — and never looking for emphasis
+ * inside a code span — resolves both cases: emphasis around code now works, and
+ * asterisks inside code stay literal, which is what a shell snippet needs.
+ */
+export function parseInline(text) {
+    const spans = [];
+    let last = 0;
+    let m;
+    CODE_RE.lastIndex = 0;
+    while ((m = CODE_RE.exec(text)) !== null) {
+        if (m.index > last)
+            pushEmphasis(spans, text.slice(last, m.index));
+        spans.push({ kind: 'code', text: m[0].slice(1, -1) });
+        last = m.index + m[0].length;
+    }
+    if (last < text.length)
+        pushEmphasis(spans, text.slice(last));
+    return spans;
+}
+function pushEmphasis(out, text) {
+    let last = 0;
+    let m;
+    EMPHASIS_RE.lastIndex = 0;
+    while ((m = EMPHASIS_RE.exec(text)) !== null) {
+        if (m.index > last)
+            out.push({ kind: 'text', text: text.slice(last, m.index) });
+        const token = m[0];
+        if (token.startsWith('**'))
+            out.push({ kind: 'bold', text: token.slice(2, -2) });
+        else if (token.startsWith('~~'))
+            out.push({ kind: 'strike', text: token.slice(2, -2) });
+        else
+            out.push({ kind: 'italic', text: token.slice(1, -1) });
+        last = m.index + token.length;
+    }
+    if (last < text.length)
+        out.push({ kind: 'text', text: text.slice(last) });
+}

package/dist/ui/overlays/ConfirmDialog.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Confirm dialog — Yes/No gate for `confirmTools` mode. Resolves the pending
+ * tool-execution promise (spec §3.6). `y` = approve; `n`/Enter/Esc = reject
+ * (Enter follows the safe default shown by the capital N in the "(y/N)" prompt,
+ * since this gates mutating tools like write_file/edit_file/bash).
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+export interface ConfirmState {
+    summary: string;
+    resolve: (approved: boolean) => void;
+}
+interface ConfirmDialogProps {
+    state: ConfirmState;
+    maxRows: number;
+    cols: number;
+    theme: Theme;
+    caps: TermCapabilities;
+    onClose: () => void;
+}
+/**
+ * Self-managed (mode B) and deliberately without a position indicator: five
+ * rows do not need scrolling, and `state.summary` may itself be multi-line, so
+ * element slicing would be meaningless here. The frame is used purely so the
+ * title and border match the other three overlays; the existing `useInput` is
+ * untouched.
+ */
+export declare function ConfirmDialog({ state, maxRows, cols, theme, caps, onClose, }: ConfirmDialogProps): React.ReactElement;
+export {};

package/dist/ui/overlays/ConfirmDialog.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+/**
+ * Self-managed (mode B) and deliberately without a position indicator: five
+ * rows do not need scrolling, and `state.summary` may itself be multi-line, so
+ * element slicing would be meaningless here. The frame is used purely so the
+ * title and border match the other three overlays; the existing `useInput` is
+ * untouched.
+ */
+export function ConfirmDialog({ state, maxRows, cols, theme, caps, onClose, }) {
+    const glyphs = pickGlyphs(caps);
+    useInput((input, key) => {
+        if (input === 'y' || input === 'Y') {
+            state.resolve(true);
+            onClose();
+        }
+        else if (input === 'n' || input === 'N' || key.return || key.escape) {
+            state.resolve(false);
+            onClose();
+        }
+    });
+    return (_jsxs(OverlayFrame, { title: "Confirm action", hint: `y approve ${glyphs.midDot} n / Enter / Esc reject`, maxRows: maxRows, cols: cols, theme: theme, caps: caps, children: [_jsx(Text, { color: theme.assistant, children: state.summary }), _jsx(Text, { color: theme.muted, children: "Proceed? (y/N)" })] }));
+}

package/dist/ui/overlays/HelpOverlay.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Help overlay — keybindings and slash-command reference (spec §5.2 / §5.3).
+ *
+ * Emits a flat array of ONE-ROW elements for `OverlayFrame`'s controlled mode
+ * rather than a nested tree. This content is 29 rows tall against a 15-row
+ * viewport on a 30-row terminal; before v0.4.0 everything past `/clear` was
+ * clipped by `overflow: hidden` with no scrollbar, no indicator, and no way to
+ * reach it. Slicing is done by element, so every row must be exactly one row —
+ * hence the unconditional `wrap="truncate"`: the first keybinding description
+ * alone is 100 characters with its padding and would wrap on any normal
+ * terminal, silently desynchronising the position indicator (R-8).
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+/** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
+export declare function helpRows(theme: Theme, caps: TermCapabilities): React.ReactElement[];

package/dist/ui/overlays/HelpOverlay.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+const KEY_PAD = 24;
+function keyRows(times) {
+    return [
+        ['Enter', 'Submit (idle) / queue steering (running); re-pins to the newest output'],
+        ['Alt+Enter / Shift+Enter', 'Insert newline'],
+        ['Esc', 'Abort run / close overlay'],
+        [`Ctrl+C ${times}2`, 'Exit'],
+        ['Ctrl+L', 'Redraw the frame'],
+        ['Ctrl+T', 'Toggle thinking blocks'],
+        ['PgUp / PgDn', 'Scroll a page (transcript, or this overlay)'],
+        ['Shift+Up / Shift+Down', 'Scroll the transcript a line (full-screen mode)'],
+        ['Up / Down', 'Prompt history (empty input)'],
+    ];
+}
+const COMMANDS = [
+    ['/help', 'Show this help'],
+    ['/model', 'Open the model picker'],
+    ['/settings', 'Open the settings screen'],
+    ['/theme <name>', 'auto | warm | cool | light'],
+    ['/thinking <level>', 'Set thinking level'],
+    ['/tools', 'List active tools'],
+    ['/clear', 'Clear the visible transcript'],
+    ['/reset', 'New conversation'],
+    ['/cwd [dir]', 'Show or change the tool working directory'],
+    ['/save [file]', 'Save the session to JSON'],
+    ['/resume [file]', 'Load a saved session'],
+    ['/copy', 'Copy the last answer to the clipboard'],
+    ['/exit', 'Exit'],
+];
+const SKILL_ROWS = [
+    ['/skills', 'List installed skills'],
+    ['/skills info <name>', 'Show a skill\'s source, files and status'],
+    ['/skills install <src>', 'Install from a dir, git repo, or https URL'],
+    ['/skills enable|disable', 'Turn a skill on or off'],
+    ['/skills policy [mode]', 'Tool ceiling from allowed-tools: off | warn | enforce'],
+    ['/skills unload', 'Drop the tool ceiling (does not reclaim context)'],
+    ['/skills usage [--reset]', 'Show or delete the local skill use counters'],
+    ['/<skill-name> [args]', 'Run a skill directly ($ARGUMENTS / $1..$9)'],
+    ['skill / skill_install', 'Tools the model uses to load and install skills'],
+];
+/** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
+export function helpRows(theme, caps) {
+    const glyphs = pickGlyphs(caps);
+    const rows = [];
+    const section = (title) => (_jsx(Text, { wrap: "truncate", color: theme.accent, bold: true, children: title }, `s-${title}`));
+    const pair = (k, d) => (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: theme.primary, children: k.padEnd(KEY_PAD) }), _jsx(Text, { color: theme.muted, children: d })] }, `r-${k}`));
+    rows.push(section('Keybindings'));
+    for (const [k, d] of keyRows(glyphs.times))
+        rows.push(pair(k, d));
+    rows.push(section('Slash commands'));
+    for (const [c, d] of COMMANDS)
+        rows.push(pair(c, d));
+    rows.push(section('Skills'));
+    for (const [c, d] of SKILL_ROWS)
+        rows.push(pair(c, d));
+    return rows;
+}

package/dist/ui/overlays/ModelPicker.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Model picker overlay. Sources its provider set from the adapter-backed
+ * providers only (R5) so it never offers a model whose provider would fail at
+ * run with `Unknown LLM provider`. Lists each provider's builtin models.
+ *
+ * Uses `OverlayFrame`'s SELF-MANAGED mode (§4.4 / R-12). `ink-select-input`
+ * windows itself via `limit` and registers its own `useInput` with `isFocused`
+ * defaulting to true; Ink delivers every key to every mounted handler, so a
+ * frame that also claimed the arrow keys would move the selection twice per
+ * press. Slicing it by element would be worse still — it is one component, not
+ * a list of rows. So the frame draws chrome only, and `App` registers no arrow
+ * keys while this overlay is open.
+ */
+import React from 'react';
+import type { ModelRegistry } from '@aragon-agent/core';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+interface ModelPickerProps {
+    registry: ModelRegistry;
+    currentProvider: string;
+    currentModel: string;
+    maxRows: number;
+    cols: number;
+    theme: Theme;
+    caps: TermCapabilities;
+    onSelect: (provider: string, model: string) => void;
+}
+export declare function ModelPicker({ registry, currentProvider, currentModel, maxRows, cols, theme, caps, onSelect, }: ModelPickerProps): React.ReactElement;
+export {};

package/dist/ui/overlays/ModelPicker.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import SelectInput from 'ink-select-input';
+import { ADAPTER_PROVIDERS } from '../../config/schema.js';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { overlayListLimit } from '../layout/overlay-window.js';
+export function ModelPicker({ registry, currentProvider, currentModel, maxRows, cols, theme, caps, onSelect, }) {
+    const glyphs = pickGlyphs(caps);
+    const items = [];
+    const seen = new Set();
+    for (const provider of ADAPTER_PROVIDERS) {
+        for (const model of registry.getModels(provider)) {
+            const value = `${provider}:${model.id}`;
+            if (seen.has(value))
+                continue;
+            seen.add(value);
+            const current = provider === currentProvider && model.id === currentModel ? ` ${glyphs.check}` : '';
+            items.push({
+                label: `${provider} ${glyphs.midDot} ${model.name} (${model.id})${current}`,
+                value,
+            });
+        }
+    }
+    const initialIndex = Math.max(0, items.findIndex((it) => it.value === `${currentProvider}:${currentModel}`));
+    return (_jsx(OverlayFrame, { title: "Select a model", hint: `Enter choose ${glyphs.midDot} Esc cancel`, maxRows: maxRows, cols: cols, theme: theme, caps: caps, children: _jsx(SelectInput, { items: items, limit: overlayListLimit(maxRows), initialIndex: initialIndex >= 0 ? initialIndex : 0, onSelect: (item) => {
+                const [provider, ...rest] = item.value.split(':');
+                onSelect(provider, rest.join(':'));
+            } }) }));
+}

package/dist/ui/overlays/SettingsScreen.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Settings screen — edit provider / model / base URL / thinking / max tokens /
+ * API key for the active provider (spec §3.5 / §5.2). Up/Down move between
+ * fields; Left/Right cycle enum fields; typing edits text/secret fields;
+ * Enter saves; Esc (handled by the App) closes without saving.
+ *
+ * The API key is never printed: it renders as dots while editing and masked
+ * otherwise.
+ */
+import React from 'react';
+import type { ThinkingLevel } from '@aragon-agent/core';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+export interface SettingsValues {
+    provider: string;
+    model: string;
+    baseUrl: string;
+    thinkingLevel: ThinkingLevel;
+    maxTokens: string;
+    apiKey: string;
+}
+interface SettingsScreenProps {
+    initial: SettingsValues;
+    /** Resolved keys per provider so switching providers reloads the right key. */
+    apiKeys: Record<string, string | undefined>;
+    maxRows: number;
+    cols: number;
+    /** Owned by `App`, like every other overlay scroll offset. */
+    scrollOffset: number;
+    /** Clamped offset reported back to `App`; see `OverlayFrame`. */
+    onScrollClamp?: (offset: number) => void;
+    theme: Theme;
+    caps: TermCapabilities;
+    onSave: (values: SettingsValues) => void;
+}
+export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }: SettingsScreenProps): React.ReactElement;
+export {};

package/dist/ui/overlays/SettingsScreen.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Settings screen — edit provider / model / base URL / thinking / max tokens /
+ * API key for the active provider (spec §3.5 / §5.2). Up/Down move between
+ * fields; Left/Right cycle enum fields; typing edits text/secret fields;
+ * Enter saves; Esc (handled by the App) closes without saving.
+ *
+ * The API key is never printed: it renders as dots while editing and masked
+ * otherwise.
+ */
+import { useState } from 'react';
+import { Text, useInput } from 'ink';
+import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret } from '../../config/schema.js';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+const FIELDS = [
+    { key: 'provider', label: 'Provider', kind: 'enum', options: ADAPTER_PROVIDERS },
+    { key: 'model', label: 'Model', kind: 'text' },
+    { key: 'baseUrl', label: 'Base URL', kind: 'text' },
+    { key: 'thinkingLevel', label: 'Thinking', kind: 'enum', options: THINKING_LEVELS },
+    { key: 'maxTokens', label: 'Max tokens', kind: 'text' },
+    { key: 'apiKey', label: 'API key', kind: 'secret' },
+];
+export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }) {
+    const [values, setValues] = useState(initial);
+    const [index, setIndex] = useState(0);
+    const glyphs = pickGlyphs(caps);
+    const field = FIELDS[index];
+    const cycle = (dir) => {
+        if (field.kind !== 'enum' || !field.options)
+            return;
+        const opts = field.options;
+        const cur = opts.indexOf(String(values[field.key]));
+        const next = (cur + dir + opts.length) % opts.length;
+        const nextVal = opts[next];
+        setValues((prev) => {
+            const updated = { ...prev, [field.key]: nextVal };
+            // Clear the key editor on provider switch. Never round-trip a resolved
+            // (possibly env-only) key into the editor — saving would then persist a
+            // secret the user never typed into the 0600 config file.
+            if (field.key === 'provider') {
+                updated.apiKey = '';
+            }
+            return updated;
+        });
+    };
+    useInput((input, key) => {
+        if (key.escape)
+            return; // App closes the overlay.
+        if (key.upArrow) {
+            setIndex((i) => (i - 1 + FIELDS.length) % FIELDS.length);
+            return;
+        }
+        if (key.downArrow || key.tab) {
+            setIndex((i) => (i + 1) % FIELDS.length);
+            return;
+        }
+        if (key.return) {
+            onSave(values);
+            return;
+        }
+        if (field.kind === 'enum') {
+            if (key.leftArrow)
+                cycle(-1);
+            if (key.rightArrow)
+                cycle(1);
+            return;
+        }
+        // text / secret editing
+        if (key.backspace || key.delete) {
+            setValues((prev) => ({ ...prev, [field.key]: String(prev[field.key]).slice(0, -1) }));
+            return;
+        }
+        if (input && !key.ctrl && !key.meta) {
+            setValues((prev) => ({ ...prev, [field.key]: String(prev[field.key]) + input }));
+        }
+    });
+    const displayValue = (f, selected) => {
+        const raw = String(values[f.key] ?? '');
+        if (f.kind === 'secret') {
+            // Indicate an already-configured key (env or file) without revealing it or
+            // its length — the editor stays empty until the user types a replacement.
+            const configured = (apiKeys[values.provider] ?? '').length > 0;
+            if (raw.length > 0) {
+                return selected
+                    ? glyphs.maskDot.repeat(Math.min(raw.length, 24))
+                    : maskSecret(raw, { maskChar: glyphs.maskDot, ellipsis: glyphs.ellipsis });
+            }
+            if (configured)
+                return selected ? '(configured - type to replace)' : '(configured)';
+            return selected ? '(type to set)' : '(none)';
+        }
+        if (f.kind === 'enum')
+            return raw;
+        return raw.length > 0 ? raw : selected ? '(type to set)' : '(none)';
+    };
+    // One element per row, each `wrap="truncate"` — the contract for OverlayFrame's
+    // controlled mode. The old title alone was 68 characters and wrapped below 70
+    // columns, adding a row the frame could not account for (P2-9 / R-8).
+    const rows = FIELDS.map((f, i) => {
+        const selected = i === index;
+        return (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: selected ? theme.accent : theme.muted, children: selected ? `${glyphs.caret} ` : '  ' }), _jsx(Text, { color: selected ? theme.assistant : theme.muted, children: (f.key === 'apiKey' ? `API key (${values.provider})` : f.label).padEnd(18) }), _jsx(Text, { color: selected ? theme.primary : theme.muted, children: displayValue(f, selected) }), f.kind === 'enum' && selected && (_jsxs(Text, { color: theme.muted, children: [' (', glyphs.arrowLeft, "/", glyphs.arrowRight, ')'] }))] }, f.key));
+    });
+    rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: "Enter saves. Keys persist to the config file (0600)." }, "__save"));
+    return (_jsx(OverlayFrame, { title: "Settings", hint: `${glyphs.arrowUp}${glyphs.arrowDown} field ${glyphs.midDot} ${glyphs.arrowLeft}${glyphs.arrowRight} change ${glyphs.midDot} Enter save ${glyphs.midDot} Esc close`, maxRows: maxRows, cols: cols, rows: rows, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
+}