@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/terminal/tui/pages/trajectoryPage.js

@@ -0,0 +1,377 @@
+import { matchesKey, stripTerminalSequences, truncateToWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { selectedRow, selectionText } from "../chrome.js";
+import { FilterList } from "../list.js";
+import { isPrimaryClick } from "../mouse.js";
+const ACTIVE = new Set(['queued', 'running', 'waiting_for_approval', 'waiting_for_input']);
+const payloadOf = (event) => event.payload && typeof event.payload === 'object' ? event.payload : {};
+const stringOf = (value) => typeof value === 'string' ? value : undefined;
+const numberOf = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+function safe(value) {
+    return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ');
+}
+function timeOf(value) {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toLocaleTimeString() : value;
+}
+function eventDescription(event) {
+    const payload = payloadOf(event);
+    switch (event.type) {
+        case 'message.completed':
+        case 'message.delta':
+            return `${stringOf(payload.role) ?? 'message'}: ${stringOf(payload.text)?.replace(/\s+/g, ' ').slice(0, 90) ?? ''}`;
+        case 'tool.started':
+        case 'tool.completed':
+            return `${stringOf(payload.name) ?? 'tool'}${stringOf(payload.summary) ? ` · ${stringOf(payload.summary)}` : ''}`;
+        case 'usage.updated': {
+            const request = payload.request && typeof payload.request === 'object' ? payload.request : {};
+            return `${stringOf(request.model) ?? stringOf(payload.model) ?? 'model'} · request ${numberOf(request.index) ?? numberOf(payload.requests) ?? '?'} · ${numberOf(request.durationMs) ?? 0} ms`;
+        }
+        case 'status.changed':
+            return stringOf(payload.status) ?? 'status update';
+        case 'retry.started':
+        case 'retry.ended':
+            return `attempt ${numberOf(payload.attempt) ?? 1}${stringOf(payload.error) ? ` · ${stringOf(payload.error)}` : ''}`;
+        case 'compaction.started':
+        case 'compaction.ended':
+            return stringOf(payload.reason) ?? 'context compaction';
+        case 'extension.notice':
+            return stringOf(payload.text) ?? 'extension notice';
+        case 'context.snapshot':
+            return 'Recorded prompt and tool definitions';
+        case 'failed':
+            return stringOf(payload.message) ?? stringOf(payload.code) ?? 'run failed';
+        default:
+            return stringOf(payload.text) ?? stringOf(payload.name) ?? '';
+    }
+}
+function usageLine(events) {
+    const event = [...events].reverse().find(item => item.type === 'usage.updated');
+    if (!event)
+        return 'Usage not recorded';
+    const payload = payloadOf(event);
+    const tokens = (name) => numberOf(payload[name])?.toLocaleString() ?? '—';
+    const cost = numberOf(payload.costUsd);
+    const requests = numberOf(payload.requests);
+    return `Input ${tokens('inputTokens')} · Output ${tokens('outputTokens')} · Cache read ${tokens('cacheReadTokens')} · ${requests ?? 0} requests · ${cost === undefined ? 'cost —' : `$${cost.toFixed(4)}`}`;
+}
+function durationLine(run) {
+    const start = Date.parse(run.startedAt);
+    const end = run.endedAt ? Date.parse(run.endedAt) : Date.now();
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return run.startedAt;
+    return `${((Math.max(0, end - start)) / 1000).toFixed(1)} s · ${timeOf(run.startedAt)}`;
+}
+const bySequence = (left, right) => left.sequence - right.sequence;
+const SECTIONS = [
+    { id: 'runs', title: 'Runs' },
+    { id: 'events', title: 'Events' }
+];
+export class TrajectoryPage {
+    options;
+    runs = [];
+    section = 'runs';
+    runList;
+    runIndex = 0;
+    run;
+    events = [];
+    selected = 0;
+    detailOffset = 0;
+    eventRowsStart = -1;
+    eventRowsFirst = 0;
+    eventRowsCount = 0;
+    loading = false;
+    loaded = false;
+    disposed = false;
+    timer;
+    error;
+    constructor(options) {
+        this.options = options;
+        this.runList = new FilterList({
+            theme: options.theme, search: 'never', noun: ['run', 'runs'], empty: 'No runs recorded for this native session yet',
+            onActivate: row => { if (row.data)
+                void this.selectRun(row.data); }
+        });
+    }
+    get selectedRunId() { return this.run?.id; }
+    get selectedEvent() { return this.events[this.selected]; }
+    get focused() { return this.runList.focused; }
+    set focused(value) { this.runList.focused = value; }
+    tabs() { return SECTIONS; }
+    activeTab() { return this.section; }
+    activate() {
+        if (this.disposed)
+            return;
+        if (!this.loaded)
+            void this.load();
+        this.timer ??= setInterval(() => { void this.refresh(); }, 2_000);
+        this.timer.unref?.();
+    }
+    deactivate() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    dispose() {
+        this.disposed = true;
+        this.deactivate();
+    }
+    async load() {
+        this.loading = true;
+        this.options.changed();
+        try {
+            this.runs = await this.options.runs();
+            this.runList.setRows(this.runRows());
+            const at = this.options.initialRunId ? this.runs.findIndex(run => run.id === this.options.initialRunId) : 0;
+            if (this.options.initialRunId && at < 0)
+                throw new Error('Run not found in this native session');
+            this.runIndex = Math.max(0, at);
+            const selected = this.runs[this.runIndex];
+            if (selected) {
+                this.runList.select(selected.id);
+                await this.open(selected);
+                if (this.options.initialRunId)
+                    this.section = 'events';
+            }
+            this.error = undefined;
+        }
+        catch (error) {
+            if (!this.disposed) {
+                this.error = error instanceof Error ? error.message : String(error);
+                if (this.options.initialRunId)
+                    this.section = 'events';
+            }
+        }
+        finally {
+            this.loaded = true;
+            this.loading = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    async open(run) {
+        const snapshot = await this.options.read(run.id);
+        if (this.disposed || this.runs[this.runIndex]?.id !== run.id)
+            return;
+        this.run = snapshot.run;
+        this.events = snapshot.events.slice().sort(bySequence);
+        this.runList.select(run.id);
+        this.selected = Math.max(0, this.events.length - 1);
+        this.detailOffset = 0;
+    }
+    async refresh() {
+        if (this.disposed || this.loading || !this.run || !ACTIVE.has(this.run.status))
+            return;
+        this.loading = true;
+        const lastSequence = this.events.at(-1)?.sequence;
+        const followedLatest = this.selected === this.events.length - 1;
+        try {
+            const snapshot = await this.options.read(this.run.id, lastSequence);
+            if (this.disposed)
+                return;
+            this.run = snapshot.run;
+            this.runs = this.runs.map(run => run.id === snapshot.run.id ? snapshot.run : run);
+            this.runList.setRows(this.runRows());
+            if (lastSequence === undefined)
+                this.events = snapshot.events.slice().sort(bySequence);
+            else {
+                const existing = new Set(this.events.map(event => event.sequence));
+                this.events = [...this.events, ...snapshot.events.filter(event => !existing.has(event.sequence))].sort(bySequence);
+            }
+            if (followedLatest && this.events.length)
+                this.selected = this.events.length - 1;
+            this.error = undefined;
+        }
+        catch (error) {
+            if (!this.disposed)
+                this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.loading = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    /** `[` is the older run, `]` the newer one. */
+    runRows() {
+        return this.runs.map(run => ({
+            id: run.id,
+            label: run.id,
+            detail: run.status + ' · ' + timeOf(run.startedAt),
+            group: run.mode,
+            searchText: run.id + ' ' + run.status + ' ' + (run.goal ?? ''),
+            data: run
+        }));
+    }
+    async selectRun(run) {
+        const at = this.runs.findIndex(candidate => candidate.id === run.id);
+        if (at < 0 || this.loading)
+            return;
+        this.runIndex = at;
+        this.runList.select(run.id);
+        this.run = run;
+        this.events = [];
+        this.selected = 0;
+        this.detailOffset = 0;
+        this.error = undefined;
+        this.loading = true;
+        this.options.changed();
+        try {
+            await this.open(run);
+            this.section = 'events';
+        }
+        catch (error) {
+            if (!this.disposed)
+                this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.loading = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    async changeRun(direction) {
+        const next = this.runIndex + direction;
+        if (next < 0 || next >= this.runs.length || this.loading)
+            return;
+        this.runIndex = next;
+        this.run = this.runs[next];
+        this.runList.select(this.run.id);
+        this.events = [];
+        this.selected = 0;
+        this.detailOffset = 0;
+        this.error = undefined;
+        this.loading = true;
+        this.options.changed();
+        try {
+            await this.open(this.runs[next]);
+        }
+        catch (error) {
+            if (!this.disposed)
+                this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.loading = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    hint() {
+        return this.section === 'runs' ? '↑/↓ runs · Enter inspect' : '[ ] runs · ↑/↓ events · PgUp/PgDn details · c copy';
+    }
+    handleMouse(event) {
+        if (event.type === 'click' && event.button !== 'left')
+            return undefined;
+        if (this.section === 'runs')
+            return this.runList.handleMouse({ ...event, y: event.y - 1 });
+        const offset = event.y - this.eventRowsStart;
+        if (this.eventRowsStart < 0 || offset < 0 || offset >= this.eventRowsCount)
+            return undefined;
+        const next = this.eventRowsFirst + offset;
+        const changed = this.selected !== next;
+        this.selected = next;
+        this.detailOffset = 0;
+        return { handled: true, render: changed || isPrimaryClick(event) };
+    }
+    handleInput(data) {
+        if (matchesKey(data, 'tab') || matchesKey(data, 'shift+tab')) {
+            const at = SECTIONS.findIndex(section => section.id === this.section);
+            const delta = matchesKey(data, 'shift+tab') ? -1 : 1;
+            this.section = SECTIONS[(at + delta + SECTIONS.length) % SECTIONS.length].id;
+            return true;
+        }
+        if (this.section === 'runs')
+            return this.runList.handleInput(data);
+        if (data === '[') {
+            void this.changeRun(1);
+            return true;
+        }
+        if (data === ']') {
+            void this.changeRun(-1);
+            return true;
+        }
+        if (matchesKey(data, 'up')) {
+            this.selected = Math.max(0, this.selected - 1);
+            this.detailOffset = 0;
+            return true;
+        }
+        if (matchesKey(data, 'down')) {
+            this.selected = this.events.length ? Math.min(this.events.length - 1, this.selected + 1) : 0;
+            this.detailOffset = 0;
+            return true;
+        }
+        if (matchesKey(data, 'pageUp')) {
+            this.detailOffset = Math.max(0, this.detailOffset - 8);
+            return true;
+        }
+        if (matchesKey(data, 'pageDown')) {
+            this.detailOffset += 8;
+            return true;
+        }
+        if (data.toLowerCase() === 'c' && this.selectedEvent) {
+            const text = JSON.stringify(this.selectedEvent, null, 2);
+            void this.options.copy(text).then(() => this.options.notify('Copied selected trajectory event')).catch(error => this.options.notify(String(error), 'error'));
+            return true;
+        }
+        return false;
+    }
+    render(width, rows) {
+        const theme = this.options.theme();
+        if (width < 1 || rows < 1)
+            return [];
+        if (this.section === 'runs') {
+            this.eventRowsStart = -1;
+            this.eventRowsCount = 0;
+            if (this.error && !this.runs.length)
+                return [theme.fg('error', 'Read error: ' + this.error)];
+            const lines = [theme.fg('dim', !this.loaded ? 'Loading recorded runs…' : this.runs.length + ' recorded runs')];
+            lines.push(...this.runList.render(width, Math.max(0, rows - lines.length)));
+            return lines.slice(0, rows).map(line => truncateToWidth(line, width, ''));
+        }
+        if (!this.run) {
+            this.eventRowsStart = -1;
+            this.eventRowsCount = 0;
+            if (this.error)
+                return [theme.fg('error', 'Read error: ' + this.error)];
+            return [theme.fg('dim', this.loading || !this.loaded ? 'Loading recorded runs…' : 'No run selected. Choose a run in the Runs tab.')];
+        }
+        const runPosition = (this.runIndex + 1) + '/' + this.runs.length;
+        const modelEvent = [...this.events].reverse().find(event => event.type === 'usage.updated');
+        const usage = modelEvent ? payloadOf(modelEvent) : {};
+        const model = stringOf(usage.model) ?? 'model unavailable';
+        const lines = [theme.bold(theme.fg('accent', 'Run ' + runPosition + ' · ' + this.run.id + ' · ' + this.run.status + (this.loading ? ' · loading' : '')))];
+        if (rows >= 9) {
+            lines.push(theme.fg('muted', model + ' · ' + durationLine(this.run) + ' · ' + this.run.mode));
+            lines.push(theme.fg('muted', usageLine(this.events)));
+            lines.push(this.run.goal ? theme.fg('dim', 'Prompt: ' + this.run.goal.replace(/\s+/g, ' ').slice(0, 140)) : theme.fg('dim', 'Prompt text unavailable'));
+        }
+        else if (rows >= 6) {
+            lines.push(theme.fg('muted', model + ' · ' + durationLine(this.run)));
+        }
+        lines.push(theme.bold('Events'));
+        if (this.error)
+            lines.push(theme.fg('error', 'Read error: ' + this.error));
+        if (!this.events.length)
+            lines.push(theme.fg('dim', this.loading ? 'Loading recorded events…' : 'No recorded events'));
+        const available = Math.max(0, rows - lines.length - 1);
+        const ledgerBudget = this.events.length ? Math.min(this.events.length, Math.max(1, Math.floor(available * 0.4))) : 0;
+        const detailBudget = Math.max(0, available - ledgerBudget);
+        const firstEvent = Math.max(0, Math.min(this.events.length - ledgerBudget, this.selected - Math.floor(ledgerBudget / 2)));
+        this.eventRowsStart = lines.length;
+        this.eventRowsFirst = firstEvent;
+        this.eventRowsCount = ledgerBudget;
+        for (let offset = 0; offset < ledgerBudget; offset++) {
+            const index = firstEvent + offset;
+            const event = this.events[index];
+            const prefix = index === this.selected ? '❯' : ' ';
+            const label = truncateToWidth(prefix + ' ' + timeOf(event.timestamp) + '  ' + event.type + '  ' + eventDescription(event), width, '');
+            lines.push(index === this.selected ? selectedRow(selectionText(theme, label), width, theme) : theme.fg('muted', label));
+        }
+        const selected = this.selectedEvent;
+        lines.push(theme.bold(selected ? 'Selected event · ' + selected.type + ' · #' + selected.sequence : 'Selected event'));
+        if (selected) {
+            const details = wrapTextWithAnsi(safe(JSON.stringify({ payload: selected.payload, type: selected.type, sequence: selected.sequence, timestamp: selected.timestamp }, null, 2)), width);
+            this.detailOffset = Math.min(this.detailOffset, Math.max(0, details.length - detailBudget));
+            lines.push(...details.slice(this.detailOffset, this.detailOffset + detailBudget).map(line => theme.fg('dim', line)));
+        }
+        return lines.slice(0, rows).map(line => truncateToWidth(line, width, ''));
+    }
+}

package/dist/sdk/terminal/tui/piAdapter.d.ts

@@ -0,0 +1,18 @@
+import type { InlineExtension, Theme, ToolRenderers } from '@earendil-works/pi-coding-agent';
+export interface PiAdapter {
+    builtins: InlineExtension[];
+    setTheme(theme: Theme): void;
+    withBuiltInRenderers(toolName: string, definition: ToolRenderers | undefined): ToolRenderers | undefined;
+    readClipboardText(): Promise<string | null>;
+    readClipboardFilePaths(): Promise<string[] | null>;
+    readClipboardImage(): Promise<{
+        bytes: Uint8Array;
+        mimeType: string;
+    } | null>;
+    extensionForImageMimeType(mimeType: string): string | null;
+}
+export declare function assertPiAdapterVersion(version: string): void;
+export declare function loadPiAdapter(): Promise<PiAdapter>;
+/** Initialize once with loadPiAdapter() before rendering native rich tool components. */
+export declare function setPiTheme(theme: Theme): void;
+export declare function withBuiltInRenderers(toolName: string, definition: ToolRenderers | undefined): ToolRenderers | undefined;

package/dist/sdk/terminal/tui/piAdapter.js

@@ -0,0 +1,48 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadPi, PINNED_PI_VERSION } from "../../pi/runtime.js";
+let adapter;
+let loading;
+export function assertPiAdapterVersion(version) {
+    if (version !== PINNED_PI_VERSION)
+        throw new Error(`The Harness terminal adapter requires Pi ${PINNED_PI_VERSION}; found ${version}. Install the Harness package's pinned dependencies.`);
+}
+export function loadPiAdapter() {
+    loading ??= (async () => {
+        const pi = await loadPi();
+        assertPiAdapterVersion(pi.VERSION);
+        const root = pi.getPackageDir();
+        const [extensions, theme, renderers, clipboard, images] = await Promise.all([
+            import(pathToFileURL(join(root, 'dist/extensions/index.js')).href),
+            import(pathToFileURL(join(root, 'dist/modes/interactive/theme/theme.js')).href),
+            import(pathToFileURL(join(root, 'dist/core/tools/renderers/index.js')).href),
+            import(pathToFileURL(join(root, 'dist/utils/clipboard.js')).href),
+            import(pathToFileURL(join(root, 'dist/utils/clipboard-image.js')).href)
+        ]);
+        if (!Array.isArray(extensions.builtInExtensions) || typeof theme.setThemeInstance !== 'function' || typeof renderers.withBuiltInRenderers !== 'function' || typeof clipboard.readClipboardText !== 'function' || typeof clipboard.readClipboardFilePaths !== 'function' || typeof images.readClipboardImage !== 'function' || typeof images.extensionForImageMimeType !== 'function') {
+            throw new Error('The pinned Pi terminal adapter no longer exposes its required builtin or theme hooks.');
+        }
+        adapter = {
+            builtins: extensions.builtInExtensions,
+            setTheme: theme.setThemeInstance,
+            withBuiltInRenderers: renderers.withBuiltInRenderers,
+            readClipboardText: clipboard.readClipboardText,
+            readClipboardFilePaths: clipboard.readClipboardFilePaths,
+            readClipboardImage: images.readClipboardImage,
+            extensionForImageMimeType: images.extensionForImageMimeType
+        };
+        return adapter;
+    })();
+    return loading;
+}
+/** Initialize once with loadPiAdapter() before rendering native rich tool components. */
+export function setPiTheme(theme) {
+    if (!adapter)
+        throw new Error('Initialize the Pi terminal adapter before setting its theme.');
+    adapter.setTheme(theme);
+}
+export function withBuiltInRenderers(toolName, definition) {
+    if (!adapter)
+        throw new Error('Initialize the Pi terminal adapter before resolving builtin renderers.');
+    return adapter.withBuiltInRenderers(toolName, definition);
+}

package/dist/sdk/terminal/tui/planMode.d.ts

@@ -0,0 +1,2 @@
+export { parseProposedPlan, planModeTools } from "../../sessions/planMode.js";
+export type { ProposedPlan } from "../../sessions/planMode.js";

package/dist/sdk/terminal/tui/planMode.js

@@ -0,0 +1,2 @@
+// The terminal's plan mode uses the session's read-only tool set.
+export { parseProposedPlan, planModeTools } from "../../sessions/planMode.js";

package/dist/sdk/terminal/tui/questionPicker.d.ts

@@ -0,0 +1,20 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type TUI } from '@earendil-works/pi-tui';
+import type { QuestionOption } from "../../sessions/contracts.js";
+import { DialogPanel } from "./dialogs.js";
+type DisplayOption = {
+    option: QuestionOption;
+    index: number;
+};
+export type QuestionPickerResult = {
+    type: 'answer';
+    selected: string[];
+} | {
+    type: 'text';
+    selected: string[];
+} | {
+    type: 'cancel';
+};
+export declare function questionOptionsInDisplayOrder(options: readonly QuestionOption[]): DisplayOption[];
+export declare function createQuestionPicker(tui: TUI, theme: Theme, title: string, question: string | undefined, options: readonly QuestionOption[], multiSelect: boolean, allowText: boolean, selected: readonly string[], done: (result: QuestionPickerResult) => void): DialogPanel;
+export {};

package/dist/sdk/terminal/tui/questionPicker.js

@@ -0,0 +1,150 @@
+import { SelectList, stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { selectedRow, selectionText } from "./chrome.js";
+import { centeredDialogHost, dialogFits } from "./dialogGeometry.js";
+import { DialogPanel } from "./dialogs.js";
+const RECOMMENDED = '(Recommended)';
+export function questionOptionsInDisplayOrder(options) {
+    const indexed = options.map((option, index) => ({ option, index }));
+    return [...indexed.filter(({ option }) => option.recommended), ...indexed.filter(({ option }) => !option.recommended)];
+}
+function recommendedSelectTheme(theme) {
+    return {
+        selectedPrefix: text => selectionText(theme, text),
+        selectedText: text => {
+            const marker = text.lastIndexOf(RECOMMENDED);
+            if (marker < 0)
+                return selectionText(theme, text.replace(/^→/, '❯'));
+            const afterMarker = marker + RECOMMENDED.length;
+            return selectionText(theme, text.slice(0, marker).replace(/^→/, '❯')) + theme.fg('warning', RECOMMENDED) + selectionText(theme, text.slice(afterMarker));
+        },
+        description: text => theme.fg('muted', text),
+        scrollInfo: text => theme.fg('dim', text),
+        noMatch: text => theme.fg('warning', text.replace('commands', 'options'))
+    };
+}
+class QuestionPickerContent {
+    tui;
+    theme;
+    options;
+    multiSelect;
+    allowText;
+    done;
+    list;
+    selectedIndexes;
+    focusedValue = false;
+    displayOptions;
+    constructor(tui, theme, options, multiSelect, allowText, selected, done) {
+        this.tui = tui;
+        this.theme = theme;
+        this.options = options;
+        this.multiSelect = multiSelect;
+        this.allowText = allowText;
+        this.done = done;
+        this.displayOptions = questionOptionsInDisplayOrder(options);
+        this.selectedIndexes = [];
+        const remaining = [...selected];
+        options.forEach((option, index) => {
+            const selectedIndex = remaining.indexOf(option.label);
+            if (selectedIndex >= 0) {
+                this.selectedIndexes.push(index);
+                remaining.splice(selectedIndex, 1);
+            }
+        });
+        this.rebuild();
+    }
+    get focused() { return this.focusedValue; }
+    set focused(value) { this.focusedValue = value; }
+    labels() {
+        return this.selectedIndexes.map(index => this.options[index].label);
+    }
+    rebuild() {
+        const selectedValue = this.list?.getSelectedItem()?.value;
+        const items = this.displayOptions.map(({ option }, displayIndex) => ({
+            value: `option:${displayIndex}`,
+            label: `${displayIndex + 1}. ${this.selectedIndexes.includes(this.displayOptions[displayIndex].index) ? '✓ ' : ''}${option.label}${option.recommended ? ` ${RECOMMENDED}` : ''}`,
+            description: option.description
+        }));
+        if (this.allowText)
+            items.push({ value: 'write', label: 'Write an answer', description: undefined });
+        if (this.multiSelect)
+            items.push({ value: 'submit', label: 'Submit choices', description: undefined });
+        const maxVisible = Math.min(12, Math.max(1, Math.floor(this.tui.terminal.rows * 0.6) - 5));
+        const theme = recommendedSelectTheme(this.theme);
+        this.list = new SelectList(items, maxVisible, theme, {
+            minPrimaryColumnWidth: 1,
+            maxPrimaryColumnWidth: 60,
+            truncatePrimary: ({ text, maxWidth, isSelected }) => {
+                const marker = text.lastIndexOf(RECOMMENDED);
+                if (marker < 0)
+                    return truncateToWidth(text, maxWidth, '');
+                const label = text.slice(0, marker).trimEnd();
+                const suffix = text.slice(marker);
+                const suffixWidth = visibleWidth(suffix);
+                const shortened = suffixWidth >= maxWidth ? truncateToWidth(suffix, maxWidth, '') : `${truncateToWidth(label, Math.max(1, maxWidth - suffixWidth), '…')} ${suffix}`;
+                if (isSelected)
+                    return shortened;
+                const shortenedMarker = shortened.lastIndexOf(RECOMMENDED);
+                return shortenedMarker < 0
+                    ? shortened
+                    : shortened.slice(0, shortenedMarker) + this.theme.fg('warning', shortened.slice(shortenedMarker));
+            }
+        });
+        if (selectedValue) {
+            const index = items.findIndex(item => item.value === selectedValue);
+            if (index >= 0)
+                this.list.setSelectedIndex(index);
+        }
+        this.list.onSelect = item => {
+            if (item.value === 'write') {
+                this.done({ type: 'text', selected: this.labels() });
+                return;
+            }
+            if (item.value === 'submit') {
+                this.done({ type: 'answer', selected: this.labels() });
+                return;
+            }
+            const displayIndex = Number(item.value.slice('option:'.length));
+            const originalIndex = this.displayOptions[displayIndex]?.index;
+            if (originalIndex === undefined)
+                return;
+            if (!this.multiSelect) {
+                this.done({ type: 'answer', selected: [this.options[originalIndex].label] });
+                return;
+            }
+            const selectedIndex = this.selectedIndexes.indexOf(originalIndex);
+            if (selectedIndex >= 0)
+                this.selectedIndexes.splice(selectedIndex, 1);
+            else
+                this.selectedIndexes.push(originalIndex);
+            this.rebuild();
+            this.tui.requestRender();
+        };
+        this.list.onCancel = () => this.done({ type: 'cancel' });
+    }
+    invalidate() { this.list.invalidate(); }
+    handleInput(data) {
+        if (/^[1-9]$/.test(data)) {
+            const index = Number(data) - 1;
+            if (index >= 0 && index < this.displayOptions.length) {
+                this.list.setSelectedIndex(index);
+                this.list.handleInput('\r');
+                return;
+            }
+        }
+        this.list.handleInput(data === 'j' ? '\x1b[B' : data === 'k' ? '\x1b[A' : data);
+    }
+    render(width) {
+        return this.list.render(width).map(line => {
+            const bounded = truncateToWidth(line, width, '');
+            return stripTerminalSequences(line).startsWith('❯') ? selectedRow(bounded, width, this.theme) : bounded;
+        });
+    }
+}
+export function createQuestionPicker(tui, theme, title, question, options, multiSelect, allowText, selected, done) {
+    const content = new QuestionPickerContent(tui, theme, options, multiSelect, allowText, selected, done);
+    const hint = multiSelect ? '↑/↓ select · Enter toggle · Submit choices · Esc cancel' : '↑/↓ select · Enter choose · Esc cancel';
+    const panel = new DialogPanel(title, content, () => theme, hint, question);
+    panel.centered = centeredDialogHost(tui) && dialogFits(tui.terminal.columns, tui.terminal.rows);
+    panel.maxRows = () => Math.max(3, Math.floor(tui.terminal.rows * 0.8));
+    return panel;
+}

package/dist/sdk/terminal/tui/questions.d.ts

@@ -0,0 +1,19 @@
+import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import type { QuestionAnswer } from "../../sessions/registry.js";
+export interface TerminalQuestion {
+    requestId: string;
+    question?: string;
+    summary?: string;
+    options: {
+        label: string;
+        description?: string;
+        recommended?: boolean;
+    }[];
+    multiSelect?: boolean;
+    allowText?: boolean;
+    batchId?: string;
+    batchIndex?: number;
+    batchCount?: number;
+}
+/** Answers stay local until the complete group can be submitted to the registry. */
+export declare function answerTerminalQuestion(ui: ExtensionUIContext, request: TerminalQuestion, signal: AbortSignal): Promise<QuestionAnswer | undefined>;