@xingular/harness 0.1.6 → 1.0.0

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

@@ -0,0 +1,363 @@
+import { Editor, Input, matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { CENTER_DIALOG_PAD, CHROME_ROWS, blockFrame, centerDialogChromeRows, centerDialogContentWidth, centerDialogFrame, centerDialogVerticalPad, contentWidth, pageFrame, safeText, selectionText } from "./chrome.js";
+import { centeredDialogHost, dialogFits, pageOverlayOptions, pageRows } from "./dialogGeometry.js";
+import { FilterList } from "./list.js";
+import { searchFieldRowsFor } from "./search.js";
+export function selectTheme(theme) {
+    return {
+        selectedPrefix: text => selectionText(theme, text), selectedText: text => selectionText(theme, text.replace(/^→/, '❯')),
+        description: text => theme.fg('muted', text), scrollInfo: text => theme.fg('dim', text),
+        noMatch: text => theme.fg('warning', text.replace('commands', 'options'))
+    };
+}
+/** Input keeps the original value; only its rendered cells are masked. */
+export class SecretInput extends Input {
+    render(width) {
+        const lines = super.render(width);
+        if (!this.getValue())
+            return lines;
+        const segments = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+        return lines.map(line => line.split(/(\x1b(?:\[[0-9;?]*[ -/]*[@-~]|_[^\x07]*\x07))/g).map((part, index) => index % 2
+            ? part
+            : [...segments.segment(part)].map(item => '•'.repeat(visibleWidth(item.segment))).join('')).join(''));
+    }
+}
+const safe = safeText;
+/** Choices as a `FilterList`, with the standard search field visible for every list. */
+export class SearchableSelect {
+    tui;
+    select;
+    cancel;
+    list;
+    labels;
+    focusedValue = false;
+    constructor(options, tui, theme, select, cancel, search = 'always') {
+        this.tui = tui;
+        this.select = select;
+        this.cancel = cancel;
+        this.labels = options.map(safe);
+        this.list = new FilterList({
+            theme, search,
+            rows: this.labels.map((label, index) => ({ id: String(index), label, data: index })),
+            limit: () => this.windowRows(),
+            noun: ['option', 'options'],
+            onActivate: row => this.select(row.data ?? 0),
+            onCancel: cancel
+        });
+    }
+    get focused() { return this.focusedValue; }
+    set focused(value) { this.focusedValue = value; this.list.focused = value; }
+    get pinnedRows() { return this.list.pinnedRows; }
+    contentRows() {
+        const centered = centeredDialogHost(this.tui);
+        const maxRows = centered ? pageRows(this.tui) : Math.max(3, Math.floor(this.tui.terminal.rows * 0.8));
+        const chromeRows = centered ? centerDialogChromeRows(maxRows) : CHROME_ROWS;
+        return Math.max(1, maxRows - chromeRows);
+    }
+    searchRows() { return searchFieldRowsFor(this.contentRows()); }
+    windowRows() {
+        return Math.min(12, Math.max(1, this.contentRows() - this.searchRows()));
+    }
+    invalidate() { this.list.invalidate(); }
+    handleMouse(event) {
+        return this.list.handleMouse(event);
+    }
+    handleInput(data) {
+        if (matchesKey(data, 'ctrl+c')) {
+            this.cancel();
+            return;
+        }
+        if (!this.list.query && /^[1-9]$/.test(data)) {
+            const index = this.labels.findIndex(label => label.startsWith(`${data}. `));
+            if (index >= 0) {
+                this.select(index);
+                return;
+            }
+        }
+        if (this.list.handleInput(data))
+            return;
+        if (!this.list.query && this.list.pinnedRows === 0 && (data === 'j' || data === 'k'))
+            this.list.handleInput(data === 'j' ? '\x1b[B' : '\x1b[A');
+    }
+    render(width) {
+        return this.list.render(Math.max(4, width), this.windowRows() + this.searchRows()).map(line => truncateToWidth(line, width, ''));
+    }
+}
+/** An overlay owns focus; its input emits the cursor marker through this delegate. */
+export class DialogPanel {
+    title;
+    content;
+    theme;
+    hint;
+    message;
+    variant;
+    deadline;
+    maxRows;
+    centered = false;
+    focusedValue = false;
+    detailOffset = 0;
+    detailRows = 0;
+    detailTotal = 0;
+    mouseBodyStart = 0;
+    mouseContentRows = [];
+    constructor(title, content, theme, hint, message, variant = 'block') {
+        this.title = title;
+        this.content = content;
+        this.theme = theme;
+        this.hint = hint;
+        this.message = message;
+        this.variant = variant;
+    }
+    get focused() { return this.focusedValue; }
+    set focused(value) {
+        this.focusedValue = value;
+        if ('focused' in this.content)
+            this.content.focused = value;
+    }
+    invalidate() { this.content.invalidate(); }
+    handleMouse(event) {
+        if (event.type === 'wheel') {
+            const key = event.wheelDelta !== undefined && event.wheelDelta < 0 ? '\x1b[5~' : '\x1b[6~';
+            this.handleInput(key);
+            return { handled: true, render: true };
+        }
+        if (event.type !== 'move' && event.type !== 'click')
+            return undefined;
+        if (event.type === 'click' && event.button !== 'left')
+            return undefined;
+        const row = this.mouseContentRows[event.y - this.mouseBodyStart];
+        if (row === undefined)
+            return undefined;
+        const mouseAware = this.content;
+        return mouseAware.handleMouse?.({ ...event, y: row });
+    }
+    handleInput(data) {
+        if (this.detailTotal > this.detailRows && (matchesKey(data, 'pageUp') || matchesKey(data, 'pageDown'))) {
+            const delta = matchesKey(data, 'pageUp') ? -1 : 1;
+            this.detailOffset = Math.max(0, Math.min(this.detailTotal - this.detailRows, this.detailOffset + delta * Math.max(1, this.detailRows)));
+            return;
+        }
+        this.content.handleInput?.(data);
+    }
+    render(width) {
+        if (width < 1)
+            return [];
+        const theme = this.theme();
+        const inner = this.centered ? centerDialogContentWidth(width) : contentWidth(width);
+        const details = this.message
+            ? wrapTextWithAnsi(stripTerminalSequences(this.message).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '').replace(/\t/g, '    '), inner)
+            : [];
+        const content = this.content.render(inner);
+        const frameRows = this.centered ? CENTER_DIALOG_PAD * 2 + 2 : CHROME_ROWS;
+        const maxHeight = this.maxRows ? Math.max(3, Math.floor(this.maxRows())) : details.length + content.length + frameRows;
+        const chromeRows = this.centered ? centerDialogChromeRows(maxHeight) : CHROME_ROWS;
+        const budget = Math.max(0, maxHeight - chromeRows);
+        // Keep choices mounted even when an approval contains a large command or path.
+        const minContent = Math.min(content.length, Math.min(2, budget));
+        const detailBudget = Math.min(details.length, Math.max(0, budget - Math.max(minContent, Math.min(content.length, budget))));
+        this.detailRows = detailBudget;
+        this.detailTotal = details.length;
+        this.detailOffset = Math.max(0, Math.min(this.detailOffset, details.length - detailBudget));
+        const body = details.slice(this.detailOffset, this.detailOffset + detailBudget).map(line => theme.fg('muted', line));
+        this.mouseContentRows = body.map(() => undefined);
+        const available = Math.max(0, budget - body.length);
+        // A search row stays on top when a tall list has to be cut.
+        const pinned = Math.min(Math.max(0, 'pinnedRows' in this.content ? Number(this.content.pinnedRows) || 0 : 0), content.length, available);
+        const scrolling = content.slice(pinned);
+        const room = available - pinned;
+        const cursor = scrolling.findIndex(line => line.includes('\x1b_pi:c\x07') || stripTerminalSequences(line).startsWith('❯'));
+        const first = scrolling.length <= room ? 0 : Math.max(0, Math.min(scrolling.length - room, cursor - Math.floor(room / 2)));
+        body.push(...content.slice(0, pinned), ...scrolling.slice(first, first + room));
+        this.mouseContentRows.push(...Array.from({ length: pinned }, (_, index) => index));
+        this.mouseContentRows.push(...Array.from({ length: Math.min(room, scrolling.length - first) }, (_, index) => pinned + first + index));
+        const height = this.centered ? body.length + centerDialogChromeRows(body.length + chromeRows) : maxHeight;
+        this.mouseBodyStart = this.centered ? centerDialogVerticalPad(height) + 2 : 2;
+        const seconds = this.deadline === undefined ? undefined : `${Math.max(0, Math.ceil((this.deadline - Date.now()) / 1000))}s`;
+        let footer = this.hint;
+        if (details.length > detailBudget) {
+            footer = `PgUp/PgDn details ${this.detailOffset + 1}-${this.detailOffset + detailBudget}/${details.length} · ${footer}`;
+            if (visibleWidth(footer) > inner)
+                footer = 'PgUp/PgDn details · Enter · Esc';
+        }
+        const frame = { title: this.title, meta: seconds, body, footer, width, theme };
+        if (this.centered)
+            return centerDialogFrame({ title: this.title, body, width, rows: height, theme });
+        return (this.variant === 'page' && this.maxRows ? pageFrame({ ...frame, rows: height }) : blockFrame(frame)).slice(0, height);
+    }
+}
+export class TerminalDialogs {
+    tui;
+    theme;
+    keybindings;
+    changed;
+    pending = new Set();
+    disposed = false;
+    constructor(tui, theme, keybindings, changed) {
+        this.tui = tui;
+        this.theme = theme;
+        this.keybindings = keybindings;
+        this.changed = changed;
+    }
+    show(build, options) {
+        if (this.disposed || options?.signal?.aborted)
+            return Promise.resolve(undefined);
+        return new Promise((resolve, reject) => {
+            let handle;
+            let timer;
+            let countdown;
+            let settled = false;
+            let panel;
+            const finish = (value, error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                clearInterval(countdown);
+                options?.signal?.removeEventListener('abort', cancel);
+                this.pending.delete(cancel);
+                handle?.hide();
+                const content = panel?.content;
+                try {
+                    content?.dispose?.();
+                }
+                catch { /* The dialog must still release focus and settle. */ }
+                this.changed();
+                if (error !== undefined)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const done = (value) => finish(value);
+            const cancel = () => done(undefined);
+            this.pending.add(cancel);
+            options?.signal?.addEventListener('abort', cancel, { once: true });
+            try {
+                panel = build(done);
+                const page = panel.variant === 'page';
+                const centered = centeredDialogHost(this.tui);
+                panel.centered = centered && (!page || dialogFits(this.tui.terminal.columns, this.tui.terminal.rows));
+                // A centered host caps every dialog at the rows its overlay shows, so a long list is not cut at the bottom.
+                panel.maxRows = () => centered ? pageRows(this.tui) : page ? Math.max(3, Math.floor(this.tui.terminal.rows)) : Math.max(3, Math.floor(this.tui.terminal.rows * 0.8));
+                if (options?.timeout !== undefined) {
+                    panel.deadline = Date.now() + Math.max(0, options.timeout);
+                    timer = setTimeout(cancel, Math.max(0, options.timeout));
+                    countdown = setInterval(this.changed, 250);
+                    countdown.unref?.();
+                }
+                // Every dialog on a centered host is the same flat panel on the scrim that the page commands use.
+                handle = this.tui.showOverlay(panel, centered
+                    ? pageOverlayOptions()
+                    : page
+                        ? { anchor: 'top-left', width: '100%', maxHeight: '100%' }
+                        : { anchor: 'bottom-center', width: '100%', maxHeight: '80%' });
+                if (settled)
+                    handle.hide();
+                this.changed();
+            }
+            catch (error) {
+                finish(undefined, error);
+            }
+        });
+    }
+    select(title, options, opts) {
+        return this.show(done => {
+            const list = new SearchableSelect(options, this.tui, this.theme, index => done(options[index]), () => done(undefined));
+            return new DialogPanel(title, list, this.theme, '↑/↓ select · Enter confirm · Esc cancel', undefined, opts?.page ? 'page' : 'block');
+        }, opts);
+    }
+    async confirm(title, message, opts) {
+        return (await this.show(done => {
+            const list = new SearchableSelect(['Yes', 'No'], this.tui, this.theme, index => done(index === 0), () => done(undefined), 'never');
+            return new DialogPanel(title, list, this.theme, '↑/↓ select · Enter confirm · Esc cancel', message);
+        }, opts)) ?? false;
+    }
+    input(title, placeholder, opts, secret = false) {
+        return this.show(done => {
+            const InputType = secret ? SecretInput : Input;
+            const input = new InputType({ prompt: secret ? '' : '> ', placeholder, placeholderStyle: text => this.theme().fg('dim', text) });
+            input.onSubmit = done;
+            input.onEscape = () => done(undefined);
+            return new DialogPanel(title, input, this.theme, 'Enter submit · Esc cancel');
+        }, opts);
+    }
+    editor(title, prefill) {
+        return this.show(done => {
+            const editor = new Editor(this.tui, { borderColor: text => this.theme().fg('border', text), selectList: selectTheme(this.theme()) });
+            editor.setText(prefill ?? '');
+            editor.onSubmit = done;
+            const content = {
+                get focused() { return editor.focused; }, set focused(value) { editor.focused = value; },
+                invalidate: () => editor.invalidate(), render: width => editor.render(Math.max(4, width)).map(line => truncateToWidth(line, width, '')),
+                handleInput: data => {
+                    if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c'))
+                        done(undefined);
+                    else
+                        editor.handleInput(data);
+                }
+            };
+            return new DialogPanel(title, content, this.theme, 'Enter submit · Shift+Enter newline · Esc cancel');
+        });
+    }
+    custom(factory, options) {
+        if (this.disposed)
+            return Promise.resolve(undefined);
+        return new Promise((resolve, reject) => {
+            let handle;
+            let component;
+            let settled = false;
+            const done = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.pending.delete(cancel);
+                handle?.hide();
+                try {
+                    component?.dispose?.();
+                }
+                catch { /* Cleanup cannot prevent completion. */ }
+                this.changed();
+                resolve(value);
+            };
+            const cancel = () => done(undefined);
+            this.pending.add(cancel);
+            Promise.resolve().then(() => factory(this.tui, this.theme(), this.keybindings, done)).then(value => {
+                component = value;
+                if (settled) {
+                    try {
+                        component.dispose?.();
+                    }
+                    catch { /* It never mounted. */ }
+                    return;
+                }
+                const defaults = { anchor: 'bottom-center', width: '100%', maxHeight: '90%' };
+                const source = options?.overlayOptions;
+                const overlayOptions = typeof source === 'function'
+                    ? new Proxy(defaults, { get: (target, key) => source()[key] ?? target[key] })
+                    : { ...defaults, ...source };
+                handle = this.tui.showOverlay(component, overlayOptions);
+                options?.onHandle?.(handle);
+                this.changed();
+            }).catch(error => {
+                if (!settled) {
+                    settled = true;
+                    this.pending.delete(cancel);
+                    handle?.hide();
+                    try {
+                        component?.dispose?.();
+                    }
+                    catch { /* Cleanup cannot prevent completion. */ }
+                    this.changed();
+                    reject(error);
+                }
+            });
+        });
+    }
+    reset() {
+        for (const cancel of [...this.pending])
+            cancel();
+    }
+    dispose() {
+        this.disposed = true;
+        this.reset();
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { KeybindingsManager as PiKeybindingsManager } from '@earendil-works/pi-coding-agent';
+import { type KeybindingDefinitions } from '@earendil-works/pi-tui';
+declare module '@earendil-works/pi-tui' {
+    interface Keybindings {
+        'app.thinking.increase': true;
+        'app.thinking.decrease': true;
+        'app.message.steer': true;
+    }
+}
+export declare const HARNESS_KEYBINDINGS: KeybindingDefinitions;
+export declare function terminalKeybindings(agentDir: string): PiKeybindingsManager;

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

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { KeybindingsManager, TUI_KEYBINDINGS } from '@earendil-works/pi-tui';
+// Harness owns application actions. Editing and selection retain Pi's reusable bindings.
+const actions = {
+    'app.commands': 'ctrl+k',
+    'app.interrupt': 'escape', 'app.clear': 'ctrl+c', 'app.exit': 'ctrl+d',
+    'app.suspend': process.platform === 'win32' ? [] : 'ctrl+z',
+    'app.thinking.cycle': [], 'app.thinking.save': 'ctrl+s',
+    'app.thinking.increase': 'shift+up', 'app.thinking.decrease': 'shift+down',
+    'app.model.cycleForward': 'ctrl+p', 'app.model.cycleBackward': 'alt+p',
+    'app.model.select': 'ctrl+l', 'app.tools.expand': 'ctrl+o', 'app.thinking.toggle': 'ctrl+t',
+    'app.editor.external': 'ctrl+g', 'app.message.copy': 'ctrl+x',
+    'app.message.steer': ['super+enter', 'alt+enter'], 'app.message.dequeue': 'alt+up',
+    'app.clipboard.pasteImage': process.platform === 'darwin' ? ['ctrl+v', 'alt+v'] : 'ctrl+v',
+    'app.session.toggleNamedFilter': 'ctrl+n', 'app.session.togglePath': 'ctrl+p',
+    'app.session.toggleSort': 'ctrl+s', 'app.session.rename': 'ctrl+r',
+    'app.session.delete': 'ctrl+d', 'app.session.deleteNoninvasive': 'ctrl+backspace',
+    'app.tree.foldOrUp': ['alt+left', 'ctrl+left'], 'app.tree.unfoldOrDown': ['alt+right', 'ctrl+right'],
+    'app.tree.editLabel': 'ctrl+e', 'app.tree.toggleLabelTimestamp': 'ctrl+y',
+    'app.tree.filter.default': 'ctrl+d', 'app.tree.filter.noTools': 'ctrl+t',
+    'app.tree.filter.userOnly': 'ctrl+u', 'app.tree.filter.labeledOnly': 'ctrl+l',
+    'app.tree.filter.all': 'ctrl+a', 'app.tree.filter.cycleForward': 'ctrl+o',
+    'app.tree.filter.cycleBackward': 'ctrl+shift+o', 'app.models.save': 'ctrl+s',
+    'app.models.enableAll': 'ctrl+a', 'app.models.clearAll': 'ctrl+x',
+    'app.models.toggleProvider': 'ctrl+p', 'app.models.reorderUp': 'alt+up', 'app.models.reorderDown': 'alt+down',
+    'app.session.new': [], 'app.session.tree': [], 'app.session.fork': [], 'app.session.resume': []
+};
+export const HARNESS_KEYBINDINGS = {
+    ...TUI_KEYBINDINGS,
+    ...Object.fromEntries(Object.entries(actions).map(([name, keys]) => [name, { defaultKeys: keys, description: name.replace(/^app\./, '').replaceAll('.', ' ') }]))
+};
+function readBindings(agentDir) {
+    let bindings = {};
+    try {
+        const source = JSON.parse(readFileSync(join(agentDir, 'keybindings.json'), 'utf8'));
+        if (source && typeof source === 'object' && !Array.isArray(source)) {
+            bindings = Object.fromEntries(Object.entries(source).filter(([, value]) => typeof value === 'string' || Array.isArray(value) && value.every(key => typeof key === 'string')));
+        }
+    }
+    catch { /* A missing keybindings file uses the application defaults. */ }
+    return bindings;
+}
+export function terminalKeybindings(agentDir) {
+    const manager = new KeybindingsManager(HARNESS_KEYBINDINGS, readBindings(agentDir));
+    // CustomEditor and selector factories type their manager as Pi's private subclass.
+    // They consume the public base plus getEffectiveConfig; Harness owns the definitions.
+    return Object.assign(manager, { getEffectiveConfig: () => manager.getResolvedBindings(), reload() { manager.setUserBindings(readBindings(agentDir)); } });
+}

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

@@ -0,0 +1,73 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type Component, type Focusable, type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import { type TerminalMouseInput } from "./mouse.js";
+export type RowTone = 'success' | 'warning' | 'error' | 'muted' | 'dim' | 'accent';
+export interface ListRow<T = unknown> {
+    id: string;
+    label: string;
+    /** Shown at the right edge, in `tone`. */
+    detail?: string;
+    tone?: RowTone;
+    /** Rows with the same consecutive group share a heading (not shown while searching). */
+    group?: string;
+    searchText?: string;
+    /** Shown dim, skipped by the arrow keys, never activated. */
+    disabled?: boolean;
+    data?: T;
+}
+export interface FilterListOptions<T> {
+    theme: () => Theme;
+    rows?: readonly ListRow<T>[];
+    /** Search is visible by default; use `never` only for a fixed, non-searchable choice list. */
+    search?: 'always' | 'never';
+    /** Rows the list may use; the search field is part of it. Defaults to what `render` is given. */
+    limit?: () => number;
+    empty?: string;
+    noun?: readonly [string, string];
+    /** Short context included in the search row while a query is active. */
+    searchContext?: (query: string) => string | undefined;
+    onActivate?: (row: ListRow<T>) => void;
+    /** Space, while the search is empty. */
+    onToggle?: (row: ListRow<T>) => void;
+    onCancel?: () => void;
+}
+export declare class FilterList<T = unknown> implements Component, Focusable {
+    private readonly options;
+    private rows;
+    private visible;
+    private selectedId;
+    private focusedValue;
+    private renderedSearchRows;
+    private renderedRows;
+    private readonly search;
+    constructor(options: FilterListOptions<T>);
+    get focused(): boolean;
+    set focused(value: boolean);
+    get query(): string;
+    get selected(): ListRow<T> | undefined;
+    get total(): number;
+    get shown(): number;
+    /** Rows the list would use if nothing cut it: the search field, headings and rows. */
+    get height(): number;
+    /** Rows at the top of `render` that a frame must keep when it has to cut the list. */
+    get pinnedRows(): number;
+    setRows(rows: readonly ListRow<T>[]): void;
+    /** Searches for `text` as if it had been typed. */
+    setQuery(text: string): void;
+    select(id: string): void;
+    /** Selects the row at a rendered line, and activates it on a primary click. */
+    handleMouse(event: TerminalMouseInput): TuiMouseEventResult | undefined;
+    invalidate(): void;
+    private limit;
+    private mode;
+    private canSearch;
+    private searchVisible;
+    private firstSelectable;
+    private refilter;
+    private move;
+    handleInput(data: string): boolean;
+    private entries;
+    private line;
+    /** `rows` is the most the list may use, the search row included. */
+    render(width: number, rows?: number): string[];
+}