@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,496 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+import { CORE_COMMANDS, coreCommand } from "../../commands/registry.js";
+import { commandRoutes, promptCommandAvailable } from "../../commands/routes.js";
+import { BUILTIN_PLUGIN_REGISTRY } from "../../plugins/builtin.js";
+import { pluginCommandPrefix } from "../../plugins/commandPrefix.js";
+import { PageOverlay } from "./pageOverlay.js";
+import { ModelPicker } from "./modelPicker.js";
+import { TreePicker } from "./treePicker.js";
+import { createCommandPage } from "./commandPages.js";
+import { pageOverlayOptions } from "./dialogGeometry.js";
+import { ResumeSessionsPage } from "./sessionPicker.js";
+import { groupTerminalCommands } from "../commandHelp.js";
+import { createBuiltinPluginCommandHandlers } from "./pluginCommands.js";
+import { TextPage } from "./pages/textPage.js";
+import { createVariantCommands } from "./variantCommands.js";
+export { parseAnnotate } from "./pluginCommands.js";
+const BUILTINS = CORE_COMMANDS.map((command) => ({
+    name: command.name,
+    ...('aliases' in command ? { aliases: [...command.aliases] } : {}),
+    description: command.description,
+    group: command.group
+}));
+const COMMAND_ALIASES = new Map(BUILTINS.flatMap(command => (command.aliases ?? []).map(alias => [alias, command.name])));
+const CORE_PROMPT_NAMES = new Set([...BUILTINS.map(command => command.name), ...COMMAND_ALIASES.keys()]);
+const LEGACY_BUILTIN_COMMAND_ALIASES = new Map([
+    ['doctor:doctor', 'doctor'], ['plugin:doctor', 'doctor'],
+    ['worktrees:worktree', 'worktree'], ['plugin:worktree', 'worktree'],
+    ['history:trajectory', 'trajectory'], ['plugin:trajectory', 'trajectory'],
+    ['subagents:subagents', 'subagents'], ['plugin:subagents', 'subagents'],
+    ['subagents:agents', 'agents'], ['plugin:agents', 'agents']
+]);
+export function createTerminalCommands(host) {
+    const notify = (text) => host.ui.notify(text, 'info');
+    const choose = async (title, items, label) => {
+        const labels = items.map(label);
+        const selected = await host.ui.select(title, labels);
+        return selected === undefined ? undefined : items[labels.indexOf(selected)];
+    };
+    /** The skills this session may be asked to use, each invoked as `$name`. Off with the "Skill commands" setting. */
+    const skills = () => {
+        const session = host.session();
+        if (!session.settingsManager.getEnableSkillCommands())
+            return [];
+        return session.resourceLoader.getSkills().skills.map((skill) => ({ name: skill.name, description: skill.description }));
+    };
+    async function openPage(id, options = {}) {
+        let close = () => { };
+        const page = createCommandPage(host, id, { ...options, close: () => close(), navigate: (target, runId) => { close(); setTimeout(() => void openPage(target, { runId }), 0); } });
+        await host.ui.custom((tui, _theme, _keys, done) => {
+            close = () => done(undefined);
+            return new PageOverlay({ page, tui, theme: () => host.ui.theme, close, changed: host.changed });
+        }, { overlay: true, overlayOptions: pageOverlayOptions(page.presentation) });
+    }
+    const variantCommands = createVariantCommands({
+        session: () => host.session(),
+        control: host.control,
+        ui: host.ui,
+        shutdown: () => host.shutdown(),
+        showText: async (title, text) => {
+            await host.ui.custom((tui, _theme, _keys, done) => {
+                const page = new TextPage(title, text, host.changed);
+                return new PageOverlay({ page, tui, theme: () => host.ui.theme, close: () => done(undefined), changed: host.changed });
+            }, { overlay: true, overlayOptions: pageOverlayOptions('fullscreen') });
+        }
+    });
+    const pluginHandlers = createBuiltinPluginCommandHandlers(host, openPage);
+    const pluginCommands = BUILTIN_PLUGIN_REGISTRY.commands();
+    const builtinPrefixes = new Map(pluginCommands.map(command => [command.prefix, command.pluginId]));
+    const prefixCache = new WeakMap();
+    const extensionCommands = () => {
+        return commandRoutes(host.session().extensionRunner.getRegisteredCommands().map(command => {
+            const source = command.sourceInfo;
+            let prefix = prefixCache.get(source);
+            if (!prefix) {
+                prefix = pluginCommandPrefix(source);
+                prefixCache.set(source, prefix);
+            }
+            const owner = source.origin === 'package'
+                ? `package:${source.baseDir ?? source.source}`
+                : `extension:${source.path}`;
+            return { ...command, prefix, owner, path: source.path };
+        }));
+    };
+    const coreCommandNames = (session) => new Set([
+        ...BUILTINS.flatMap(command => [command.name, ...(command.aliases ?? [])]),
+        ...session.resourceLoader.getPrompts().prompts.map(prompt => prompt.name)
+    ]);
+    const runBuiltinPluginCommand = async (command, argument) => {
+        try {
+            const handler = pluginHandlers.get(`${command.pluginId}:${command.name}`);
+            if (!handler)
+                throw new Error(`No terminal handler for built-in plugin command ${command.pluginId}:${command.name}.`);
+            await handler(argument);
+            host.refresh();
+        }
+        catch (error) {
+            host.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+        }
+    };
+    const runExtensionCommand = async (registered, argument, route) => {
+        try {
+            const command = host.session().extensionRunner.getCommand(registered.invocationName);
+            if (!command)
+                throw new Error(`Plugin command /${route} is no longer registered. Reload trusted resources.`);
+            await command.handler(argument, host.session().extensionRunner.createCommandContext());
+            host.refresh();
+        }
+        catch (error) {
+            host.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+        }
+    };
+    const runNamespacedCommand = async (typedName, argument) => {
+        const separator = typedName.indexOf(':');
+        if (separator < 1)
+            return false;
+        const prefix = typedName.slice(0, separator);
+        const name = typedName.slice(separator + 1);
+        if (prefix === 'plugin') {
+            host.ui.notify(`Unknown plugin command: /${typedName}. Use its owner-qualified command.`, 'error');
+            return true;
+        }
+        if (host.session().resourceLoader.getPrompts().prompts.some(prompt => prompt.name === typedName))
+            return false;
+        const builtin = name ? BUILTIN_PLUGIN_REGISTRY.command(prefix, name) : BUILTIN_PLUGIN_REGISTRY.defaultCommand(prefix);
+        const extensions = extensionCommands();
+        const isBuiltinPrefix = builtinPrefixes.has(prefix);
+        const isExtensionPrefix = extensions.ownersByPrefix.has(prefix);
+        if (!builtin && !isBuiltinPrefix && !isExtensionPrefix)
+            return false;
+        if (builtin) {
+            const competitors = extensions.routes.get(`${prefix}:${builtin.name}`) ?? [];
+            if (competitors.length) {
+                host.ui.notify(`Extension command /${prefix}:${builtin.name} from ${competitors.map(command => command.sourceInfo.path).join(', ')} is unavailable because the prefix belongs to built-in ${builtin.pluginId}.`, 'error');
+            }
+            await runBuiltinPluginCommand(builtin, argument);
+            return true;
+        }
+        if (extensions.conflictingPrefixes.has(prefix)) {
+            host.ui.notify(`Plugin prefix /${prefix}: is ambiguous or reserved. Owners: ${extensions.conflictingPrefixes.get(prefix).join(', ')}.`, 'error');
+            return true;
+        }
+        if (!name) {
+            host.ui.notify(`Plugin /${prefix}: has no default command. Use /help to list its commands.`, 'error');
+            return true;
+        }
+        const matches = extensions.routes.get(`${prefix}:${name}`) ?? [];
+        if (matches.length > 1) {
+            host.ui.notify(`Plugin command /${prefix}:${name} is ambiguous. Registered by: ${matches.map(command => command.sourceInfo.path).join(', ')}.`, 'error');
+            return true;
+        }
+        if (matches.length === 1) {
+            await runExtensionCommand(matches[0], argument, `${prefix}:${name}`);
+            return true;
+        }
+        host.ui.notify(`Unknown plugin command: /${typedName}. Use /help to list the commands.`, 'error');
+        return true;
+    };
+    const legacyAliases = () => {
+        const session = host.session();
+        const coreNames = coreCommandNames(session);
+        return [...LEGACY_BUILTIN_COMMAND_ALIASES.keys()].filter(name => !name.startsWith('plugin:') && !coreNames.has(name));
+    };
+    const completions = () => {
+        const session = host.session();
+        const prompts = session.resourceLoader.getPrompts().prompts;
+        const commands = new Map(BUILTINS.map(command => [command.name, command]));
+        for (const command of pluginCommands) {
+            if (command.rootOnly)
+                continue;
+            const invocation = `${command.prefix}:${command.name}`;
+            commands.set(invocation, { name: invocation, description: command.description, group: 'Plugins' });
+        }
+        for (const module of BUILTIN_PLUGIN_REGISTRY.modules) {
+            const defaultCommand = module.defaultCommand && BUILTIN_PLUGIN_REGISTRY.defaultCommand(module.commandPrefix ?? module.descriptor.id);
+            if (defaultCommand) {
+                const invocation = `${defaultCommand.prefix}:`;
+                commands.set(invocation, { name: invocation, description: defaultCommand.description, group: 'Plugins' });
+            }
+        }
+        const extensions = extensionCommands();
+        for (const [route, matches] of extensions.routes) {
+            const prefix = route.slice(0, route.indexOf(':'));
+            if (matches.length !== 1 || extensions.conflictingPrefixes.has(prefix))
+                continue;
+            if (BUILTIN_PLUGIN_REGISTRY.command(prefix, matches[0].name))
+                continue;
+            commands.set(route, { name: route, description: matches[0].description, group: 'Plugins' });
+        }
+        const extensionNames = new Set(extensions.byName.keys());
+        for (const prompt of prompts) {
+            if ((prompt.name.includes(':') || promptCommandAvailable(prompt.name, new Set([...commands.keys(), ...COMMAND_ALIASES.keys()]), extensionNames)) && !commands.has(prompt.name))
+                commands.set(prompt.name, { name: prompt.name, description: prompt.description, group: 'Prompts' });
+        }
+        return [...commands.values()];
+    };
+    async function execute(text) {
+        const match = /^\/([^\s]+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+        if (!match)
+            return false;
+        const typedName = match[1];
+        const argument = match[2]?.trim() ?? '';
+        const legacyBuiltin = typedName.startsWith('plugin:') ? undefined : LEGACY_BUILTIN_COMMAND_ALIASES.get(typedName);
+        if (!legacyBuiltin && await runNamespacedCommand(typedName, argument))
+            return true;
+        const session = host.session();
+        const name = coreCommand(legacyBuiltin ?? typedName)?.name ?? legacyBuiltin ?? typedName;
+        const builtin = BUILTINS.find(item => item.name === name);
+        if (!builtin) {
+            // A skill is offered as $name; the typed /skill:name form still reaches the SDK, which expands it.
+            if (skills().some(skill => `skill:${skill.name}` === name))
+                return false;
+            const prompt = session.resourceLoader.getPrompts().prompts.some(item => item.name === name);
+            if (prompt && (name.includes(':') || promptCommandAvailable(name, CORE_PROMPT_NAMES, new Set(extensionCommands().byName.keys()))))
+                return false;
+            host.ui.notify(`Unknown command: /${name}. Use /help to list commands.`, 'error');
+            return true;
+        }
+        try {
+            switch (name) {
+                case 'help':
+                    host.showHelp(groupTerminalCommands(completions()));
+                    break;
+                case 'plan': {
+                    if (!argument || ['on', 'off', 'toggle'].includes(argument.toLowerCase()))
+                        throw new Error('Use /plan <plan brief>.');
+                    host.plan(argument);
+                    break;
+                }
+                case 'goal':
+                    host.ui.notify(await host.goal(argument), 'info');
+                    break;
+                case 'quit':
+                    host.shutdown();
+                    break;
+                case 'btw':
+                    await host.btw(argument);
+                    break;
+                case 'stop': {
+                    if (session.isIdle)
+                        throw new Error('Nothing is running.');
+                    await host.runtime().interrupt();
+                    break;
+                }
+                case 'new':
+                    await host.runtime().newSession();
+                    break;
+                case 'session': {
+                    let path = argument;
+                    if (!path) {
+                        const selected = await host.ui.custom((tui, _theme, _keys, done) => {
+                            const page = new ResumeSessionsPage({
+                                theme: () => host.ui.theme,
+                                cwd: () => host.cwd(),
+                                branch: () => host.branch(),
+                                listSessions: signal => SessionManager.list(host.cwd(), host.sessionDirectory(), undefined, signal),
+                                select: done,
+                                cancel: () => done(undefined),
+                                changed: host.changed
+                            });
+                            return new PageOverlay({ page, tui, theme: () => host.ui.theme, close: () => done(undefined), changed: host.changed });
+                        }, { overlay: true, overlayOptions: pageOverlayOptions('fullscreen') });
+                        if (!selected)
+                            break;
+                        path = selected;
+                    }
+                    // A conversation by its file, or by the session id its runs record (ADR-0083).
+                    const target = sessionFileFor(path, host.cwd(), host.sessionDirectory());
+                    const within = relative(host.sessionDirectory(), target);
+                    if (within === '..' || within.startsWith('../') || within.startsWith('..\\') || isAbsolute(within)) {
+                        throw new Error('Resume sessions from this account history folder.');
+                    }
+                    await host.runtime().switchSession(target);
+                    break;
+                }
+                case 'fork': {
+                    const message = await choose('Fork before message', session.getUserMessagesForForking(), (item, index) => `${index + 1}. ${item.text.replace(/\s+/g, ' ').slice(0, 160)}`);
+                    if (message) {
+                        const result = await host.runtime().fork(message.entryId);
+                        if (!result.cancelled && result.selectedText)
+                            host.setEditorText(result.selectedText);
+                    }
+                    break;
+                }
+                case 'clone': {
+                    const leaf = session.sessionManager.getLeafId();
+                    if (!leaf)
+                        throw new Error('Nothing to clone yet');
+                    const result = await host.runtime().fork(leaf, { position: 'at' });
+                    if (!result.cancelled) {
+                        host.setEditorText('');
+                        notify('Cloned to new session');
+                    }
+                    break;
+                }
+                case 'history': {
+                    const tree = session.sessionManager.getTree();
+                    if (!tree.length)
+                        throw new Error('No entries in this session');
+                    const selected = await host.ui.custom((tui, _theme, keys, done) => new TreePicker({
+                        theme: () => host.ui.theme, tui, matches: (data, action) => keys.matches(data, action),
+                        tree, currentLeafId: session.sessionManager.getLeafId(), initialFilterMode: session.settingsManager.getTreeFilterMode(),
+                        select: done, cancel: () => done(undefined),
+                        copy: text => { void host.copyText(text).catch(error => host.ui.notify(String(error), 'error')); },
+                        editLabel: (_entryId, current) => host.ui.editor('Label (empty to remove)', current),
+                        labelChanged: (entryId, label) => { session.sessionManager.appendLabelChange(entryId, label); },
+                        changed: host.changed
+                    }), { overlay: true, overlayOptions: pageOverlayOptions() });
+                    if (selected && selected !== session.sessionManager.getLeafId()) {
+                        const summarize = await host.ui.confirm('Navigate session', 'Summarize the abandoned branch before navigating?');
+                        const result = await host.runtime().navigateTree(selected, { summarize });
+                        if (!result.cancelled && result.editorText)
+                            host.setEditorText(result.editorText);
+                    }
+                    break;
+                }
+                case 'effort': {
+                    const levels = session.getAvailableThinkingLevels();
+                    const level = argument || await host.ui.select('Thinking effort', levels);
+                    if (!level)
+                        break;
+                    if (!levels.includes(level))
+                        throw new Error(`Available thinking levels: ${levels.join(', ')}`);
+                    session.setThinkingLevel(level, { persist: true });
+                    break;
+                }
+                case 'thinking': {
+                    const settings = session.settingsManager;
+                    const current = settings.getHideThinkingBlock();
+                    const mode = argument.toLowerCase();
+                    if (mode && mode !== 'show' && mode !== 'hide')
+                        throw new Error('Use /thinking, /thinking show, or /thinking hide.');
+                    const hidden = mode ? mode === 'hide' : !current;
+                    if (hidden !== current)
+                        settings.setHideThinkingBlock(hidden);
+                    notify(`Thinking blocks ${hidden ? 'hidden' : 'shown'}.`);
+                    break;
+                }
+                case 'model': {
+                    const provider = session.settingsManager.getDefaultProvider();
+                    const id = session.settingsManager.getDefaultModel();
+                    const selected = await host.ui.custom((tui, _theme, _keys, done) => new ModelPicker({
+                        theme: () => host.ui.theme, tui, runtime: session.modelRuntime, current: session.model, scoped: session.scopedModels,
+                        defaultModel: provider && id ? { provider, id } : undefined, initialSearch: argument || undefined,
+                        select: (model, persist) => done({ model, persist }), cancel: () => done(undefined), changed: host.changed
+                    }), { overlay: true, overlayOptions: pageOverlayOptions() });
+                    if (selected)
+                        await session.setModel(selected.model, { persist: selected.persist });
+                    break;
+                }
+                case 'settings':
+                    await openPage('settings');
+                    break;
+                case 'doctor':
+                    await openPage('doctor');
+                    break;
+                case 'worktree':
+                    await openPage('worktree');
+                    break;
+                case 'follow-up':
+                    await openPage('follow-up');
+                    break;
+                case 'trajectory':
+                    await openPage('trajectory', { runId: argument });
+                    break;
+                case 'todo': {
+                    const items = await host.todo();
+                    if (!items.length)
+                        notify('No todo list in this reply yet. The agent writes one with TodoWrite for multi-step work.');
+                    else
+                        host.showTodo(items);
+                    break;
+                }
+                case 'subagents':
+                    await openPage('subagents');
+                    break;
+                case 'agents':
+                    await openPage('agents');
+                    break;
+                case 'permissions':
+                    await openPage('permissions');
+                    break;
+                case 'accounts':
+                    await openPage('accounts');
+                    break;
+                case 'harness':
+                    await openPage('harness');
+                    break;
+                case 'skills':
+                    await openPage('skills');
+                    break;
+                case 'connections':
+                case 'mcp':
+                    await openPage('connections');
+                    break;
+                case 'tools':
+                    await openPage('tools');
+                    break;
+                case 'plugins':
+                    await openPage('plugins');
+                    break;
+                case 'hub':
+                    await openPage('hub');
+                    break;
+                case 'components':
+                    await openPage('components');
+                    break;
+                case 'variant':
+                    await variantCommands.variant(argument);
+                    break;
+                case 'refine':
+                    await variantCommands.refine(argument);
+                    break;
+                case 'name': {
+                    const name = argument || await host.ui.input('Session name', session.sessionName);
+                    if (name !== undefined)
+                        session.setSessionName(name);
+                    break;
+                }
+                case 'log':
+                    await openPage('log');
+                    break;
+                case 'context':
+                    await openPage('context', { contextTab: argument === 'growth' ? 'growth' : argument === 'request' ? 'request' : 'details' });
+                    break;
+                case 'remote-control': {
+                    const choice = argument.toLowerCase();
+                    if (choice === 'off' || choice === 'stop') {
+                        await host.control('terminal.remoteControl.stop');
+                        notify('Remote control stopped.');
+                        break;
+                    }
+                    if (choice && !['tailscale', 'lan', 'wifi', 'wi-fi'].includes(choice))
+                        throw new Error('Use /remote-control, /remote-control off, /remote-control tailscale or /remote-control lan.');
+                    await host.control('terminal.remoteControl.start', { interface: choice === 'tailscale' ? 'tailscale' : choice ? 'lan' : 'auto' });
+                    host.watchRemoteControl?.();
+                    await openPage('remote-control');
+                    break;
+                }
+                case 'compact':
+                    await session.compact(argument || undefined);
+                    break;
+                case 'reload':
+                    await host.runtime().reload();
+                    notify('Trusted resources reloaded');
+                    break;
+                case 'copy': {
+                    const response = session.getLastAssistantText();
+                    if (!response)
+                        throw new Error('No assistant response to copy yet');
+                    await host.copyText(response);
+                    notify('Copied last assistant response');
+                    break;
+                }
+                case 'export': {
+                    const output = argument || await host.ui.input('Export path (.html or .jsonl)', 'session.html');
+                    if (!output)
+                        break;
+                    const path = resolve(host.cwd(), output);
+                    notify(`Exported to ${path.endsWith('.jsonl') ? session.exportToJsonl(path) : await session.exportToHtml(path, { themeName: host.ui.theme.name })}`);
+                    break;
+                }
+                case 'hotkeys':
+                    notify(host.hotkeys?.() ?? 'Keyboard bindings are managed by the terminal application.');
+                    break;
+            }
+            host.refresh();
+        }
+        catch (error) {
+            host.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+        }
+        return true;
+    }
+    return { execute, completions, skills, legacyAliases };
+}
+/** The history file a `/session` argument names: a path, or the session id in a file's header. */
+export function sessionFileFor(argument, cwd, sessionDirectory) {
+    const named = resolve(cwd, argument);
+    if (existsSync(named) || /[\\/]|\.jsonl$/u.test(argument))
+        return named;
+    try {
+        for (const name of readdirSync(sessionDirectory)) {
+            if (!name.endsWith('.jsonl'))
+                continue;
+            const file = join(sessionDirectory, name);
+            const header = JSON.parse(readFileSync(file, 'utf8').split('\n', 1)[0]);
+            if (header.type === 'session' && header.id === argument)
+                return file;
+        }
+    }
+    catch {
+        // An unreadable folder or header names nothing.
+    }
+    return named;
+}

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

@@ -0,0 +1,27 @@
+import type { OverlayOptions, TUI } from '@earendil-works/pi-tui';
+export declare const DIALOG_MAX_WIDTH = 100;
+export declare const DIALOG_MAX_ROWS = 30;
+/** A page overlay this host may present as a centered dialog. Other hosts ignore the field. */
+export interface HarnessOverlayOptions extends OverlayOptions {
+    dialog?: 'page';
+}
+export interface DialogRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+/** The width of a centered page dialog: 80% of the terminal, never more than 100 columns. */
+export declare function dialogWidth(columns: number): number;
+/** The height of a centered page dialog: 80% of the terminal, never more than 30 rows. */
+export declare function dialogRows(rows: number): number;
+/** Whether the terminal can hold a readable page dialog instead of the full-screen page. */
+export declare function dialogFits(columns: number, rows: number): boolean;
+/** The host that presents page overlays as centered dialogs, rather than full-screen pages. */
+export declare function centeredDialogHost(tui: TUI): boolean;
+/** Rows a page or picker should render for this host: the dialog's rows, or the whole screen. */
+export declare function pageRows(tui: TUI): number;
+/** Centers a rectangle on the screen, clamped so it never starts outside the terminal. */
+export declare function centeredRect(columns: number, rows: number, width: number, height: number): DialogRect;
+/** Page commands declare their presentation; OpenTUI centers only marked dialogs. */
+export declare function pageOverlayOptions(presentation?: 'centered' | 'fullscreen'): HarnessOverlayOptions;

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

@@ -0,0 +1,52 @@
+export const DIALOG_MAX_WIDTH = 100;
+export const DIALOG_MAX_ROWS = 30;
+/** Below this a centered dialog would show too little of the page, so the page keeps the screen. */
+const DIALOG_MIN_WIDTH = 30;
+const DIALOG_MIN_ROWS = 12;
+/** The width of a centered page dialog: 80% of the terminal, never more than 100 columns. */
+export function dialogWidth(columns) {
+    const width = Math.trunc(columns);
+    if (!Number.isFinite(width) || width < 1)
+        return 0;
+    return Math.max(1, Math.min(width, DIALOG_MAX_WIDTH, Math.max(20, Math.floor(width * 0.8))));
+}
+/** The height of a centered page dialog: 80% of the terminal, never more than 30 rows. */
+export function dialogRows(rows) {
+    const height = Math.trunc(rows);
+    if (!Number.isFinite(height) || height < 1)
+        return 0;
+    return Math.max(1, Math.min(height, DIALOG_MAX_ROWS, Math.max(8, Math.floor(height * 0.8))));
+}
+/** Whether the terminal can hold a readable page dialog instead of the full-screen page. */
+export function dialogFits(columns, rows) {
+    return dialogWidth(columns) >= DIALOG_MIN_WIDTH && dialogRows(rows) >= DIALOG_MIN_ROWS;
+}
+/** The host that presents page overlays as centered dialogs, rather than full-screen pages. */
+export function centeredDialogHost(tui) {
+    return tui.centeredDialogs === true;
+}
+/** Rows a page or picker should render for this host: the dialog's rows, or the whole screen. */
+export function pageRows(tui) {
+    const rows = Math.max(0, Math.trunc(tui.terminal.rows));
+    const columns = Math.max(0, Math.trunc(tui.terminal.columns));
+    return centeredDialogHost(tui) && dialogFits(columns, rows) ? dialogRows(rows) : rows;
+}
+/** Centers a rectangle on the screen, clamped so it never starts outside the terminal. */
+export function centeredRect(columns, rows, width, height) {
+    const screenColumns = Math.max(1, Math.trunc(columns));
+    const screenRows = Math.max(1, Math.trunc(rows));
+    const boxWidth = Math.max(1, Math.min(Math.trunc(width), screenColumns));
+    const boxHeight = Math.max(1, Math.min(Math.trunc(height), screenRows));
+    return {
+        top: Math.max(0, Math.floor((screenRows - boxHeight) / 2)),
+        left: Math.max(0, Math.floor((screenColumns - boxWidth) / 2)),
+        width: boxWidth,
+        height: boxHeight
+    };
+}
+/** Page commands declare their presentation; OpenTUI centers only marked dialogs. */
+export function pageOverlayOptions(presentation = 'centered') {
+    if (presentation === 'fullscreen')
+        return { anchor: 'top-left', width: '100%', maxHeight: '100%' };
+    return { anchor: 'top-left', width: '100%', maxHeight: '100%', dialog: 'page' };
+}

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

@@ -0,0 +1,81 @@
+import type { ExtensionUIContext, ExtensionUIDialogOptions, KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent';
+import { type Component, type Focusable, type SelectListTheme, type TUI, type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TerminalMouseInput } from "./mouse.js";
+import { MouseSafeInput } from "./mouseReport.js";
+export interface GroupedSelectOption {
+    label: string;
+    group?: string;
+}
+/** `page` asks for a full-screen dialog; Pi's own dialogs ignore the field. */
+export type TerminalDialogOptions = ExtensionUIDialogOptions & {
+    page?: boolean;
+};
+export type DialogVariant = 'block' | 'page';
+export declare function selectTheme(theme: Theme): SelectListTheme;
+/** Input keeps the original value; only its rendered cells are masked. */
+export declare class SecretInput extends MouseSafeInput {
+    render(width: number): string[];
+}
+/** Choices as a `FilterList`, with the standard search field visible for every list. */
+export declare class SearchableSelect implements Component, Focusable {
+    private readonly tui;
+    private readonly select;
+    private readonly cancel;
+    private readonly list;
+    private readonly labels;
+    private focusedValue;
+    constructor(options: string[], tui: TUI, theme: () => Theme, select: (index: number) => void, cancel: () => void, search?: 'always' | 'never', groups?: readonly (string | undefined)[]);
+    get focused(): boolean;
+    set focused(value: boolean);
+    get pinnedRows(): number;
+    private contentRows;
+    private searchRows;
+    private windowRows;
+    invalidate(): void;
+    handleMouse(event: TerminalMouseInput): TuiMouseEventResult | undefined;
+    handleInput(data: string): void;
+    render(width: number): string[];
+}
+/** An overlay owns focus; its input emits the cursor marker through this delegate. */
+export declare class DialogPanel implements Component, Focusable {
+    readonly title: string;
+    readonly content: Component;
+    private readonly theme;
+    readonly hint: string;
+    private readonly message?;
+    readonly variant: DialogVariant;
+    deadline?: number;
+    maxRows?: () => number;
+    centered: boolean;
+    private focusedValue;
+    private detailOffset;
+    private detailRows;
+    private detailTotal;
+    private mouseBodyStart;
+    private mouseContentRows;
+    constructor(title: string, content: Component, theme: () => Theme, hint: string, message?: string | undefined, variant?: DialogVariant);
+    get focused(): boolean;
+    set focused(value: boolean);
+    invalidate(): void;
+    handleMouse(event: TerminalMouseInput): TuiMouseEventResult | undefined;
+    handleInput(data: string): void;
+    render(width: number): string[];
+}
+export declare class TerminalDialogs {
+    private readonly tui;
+    private readonly theme;
+    private readonly keybindings;
+    private readonly changed;
+    private pending;
+    private disposed;
+    constructor(tui: TUI, theme: () => Theme, keybindings: KeybindingsManager, changed: () => void);
+    private show;
+    select(title: string, options: string[], opts?: TerminalDialogOptions): Promise<string | undefined>;
+    selectGrouped(title: string, options: readonly GroupedSelectOption[], opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+    confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise<boolean>;
+    input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions, secret?: boolean): Promise<string | undefined>;
+    editor(title: string, prefill?: string): Promise<string | undefined>;
+    custom<T>(factory: Parameters<ExtensionUIContext['custom']>[0], options?: Parameters<ExtensionUIContext['custom']>[1]): Promise<T>;
+    reset(): void;
+    dispose(): void;
+}