@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,372 @@
+import { Editor, 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";
+import { MouseSafeInput } from "./mouseReport.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 MouseSafeInput {
+    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', groups) {
+        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, ...(groups?.[index] ? { group: groups[index] } : {}), 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);
+    }
+    selectGrouped(title, options, opts) {
+        const labels = options.map(option => option.label);
+        return this.show(done => {
+            const list = new SearchableSelect(labels, this.tui, this.theme, index => done(labels[index]), () => done(undefined), 'always', options.map(option => option.group));
+            return new DialogPanel(title, list, this.theme, '↑/↓ select · Enter confirm · Esc cancel');
+        }, 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 : MouseSafeInput;
+            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);
+                component.mounted?.();
+                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/goalCommand.d.ts

@@ -0,0 +1,19 @@
+import { GOAL_CUSTOM_TYPE, type GoalController } from "../../sessions/goal.js";
+export interface GoalCommandDeps {
+    controller: GoalController;
+    /** True when no reply is running. */
+    idle(): boolean;
+    /** Sends a hidden message and starts a reply with it. */
+    start(content: string): Promise<void>;
+    /** Sends a hidden message into the running reply. */
+    steer(content: string): Promise<void>;
+    /** Records a hidden message without starting a reply. */
+    note(content: string): Promise<void>;
+    /** Stops the running reply. */
+    interrupt(): Promise<void>;
+    confirm(title: string, message: string): Promise<boolean>;
+    input(title: string, value: string): Promise<string | undefined>;
+}
+export { GOAL_CUSTOM_TYPE };
+/** Runs one `/goal` and returns the text to show the person. */
+export declare function runGoalCommand(argument: string, deps: GoalCommandDeps): Promise<string>;

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

@@ -0,0 +1,83 @@
+// `/goal` in the terminal (ADR-0072): set, view, edit, pause, resume and clear a goal. Adapted from
+// OpenAI Codex (Apache-2.0; see NOTICE.md): codex-rs/tui/src/chatwidget/slash_dispatch.rs and
+// goal_menu.rs. The model never creates a goal: the person does, here.
+import { GOAL_CUSTOM_TYPE, GoalError, continuationPrompt, goalSummary, objectiveUpdatedPrompt, parseGoalCommand, provenanceText } from "../../sessions/goal.js";
+export { GOAL_CUSTOM_TYPE };
+/** Runs one `/goal` and returns the text to show the person. */
+export async function runGoalCommand(argument, deps) {
+    const { controller } = deps;
+    const command = parseGoalCommand(argument);
+    try {
+        switch (command.kind) {
+            case 'error': return command.message;
+            case 'show': return goalSummary(controller.get());
+            case 'set': {
+                const existing = controller.get();
+                if (existing && existing.status !== 'complete') {
+                    const replace = await deps.confirm('Replace goal?', `The current goal is not finished:\n${existing.objective}\n\nReplace it with the new one and start it now?`);
+                    if (!replace)
+                        return 'Kept the current goal.';
+                }
+                // A reply that is running stops first: the new goal starts from a clean boundary.
+                if (!deps.idle())
+                    await deps.interrupt();
+                const goal = controller.set(command.objective, command.limits);
+                await deps.start(`${provenanceText('set', goal)}\n\n${continuationPrompt(goal)}`);
+                return `Goal active\nObjective: ${goal.objective}`;
+            }
+            case 'edit': {
+                const existing = controller.get();
+                if (!existing)
+                    return 'No goal to edit. Use /goal <objective>.';
+                const objective = command.objective ?? await deps.input('Edit goal', existing.objective);
+                if (!objective?.trim())
+                    return 'Goal unchanged.';
+                const goal = controller.edit(objective);
+                const content = `${provenanceText('edited', goal)}\n\n${objectiveUpdatedPrompt(goal)}`;
+                if (deps.idle())
+                    await deps.start(`${provenanceText('edited', goal)}\n\n${continuationPrompt(goal)}`);
+                else
+                    await deps.steer(content);
+                return `Goal updated\nObjective: ${goal.objective}`;
+            }
+            case 'pause': {
+                const goal = controller.get();
+                if (!goal)
+                    return 'No goal to pause.';
+                if (!deps.idle())
+                    await deps.interrupt();
+                const paused = controller.pause();
+                await deps.note(provenanceText('paused', paused));
+                return `Goal ${paused?.status === 'paused' ? 'paused' : `is ${paused?.status.replace('_', ' ')}`}. Use /goal resume to continue.`;
+            }
+            case 'resume': {
+                const goal = controller.get();
+                if (!goal)
+                    return 'No goal to resume.';
+                if (goal.status === 'complete')
+                    return 'The goal is complete. Set a new one with /goal <objective>.';
+                const resumed = controller.resume();
+                const content = `${provenanceText('resumed', resumed)}\n\n${continuationPrompt(resumed)}`;
+                if (deps.idle())
+                    await deps.start(content);
+                else
+                    await deps.steer(content);
+                return 'Goal active';
+            }
+            case 'clear': {
+                if (!controller.get())
+                    return 'No goal to clear.';
+                if (!deps.idle() && controller.active())
+                    await deps.interrupt();
+                controller.clear();
+                await deps.note(provenanceText('cleared', null));
+                return 'Goal cleared';
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof GoalError)
+            return error.message;
+        throw error;
+    }
+}

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

@@ -0,0 +1,8 @@
+import { type TerminalRuntime, type TerminalRuntimeHost } from "./runtime.js";
+/**
+ * The terminal's runtime (ADR-0083): this client of the harness by default; `inprocess` runs the
+ * previous in-process Pi runtime, which keeps plugins' own terminal components.
+ */
+export declare const HARNESS_RUNTIME_ENV = "XINGULAR_TERMINAL_RUNTIME";
+export declare const harnessRuntimeSelected: (env?: NodeJS.ProcessEnv) => boolean;
+export declare function createHarnessTerminalRuntime(args: string[], host: TerminalRuntimeHost): Promise<TerminalRuntime>;