@xingular/harness 0.1.6 → 1.0.0

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

@@ -0,0 +1,276 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+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 { expandSkillInvocation } from "./skillInvocation.js";
+const BUILTINS = [
+    { name: 'doctor', description: 'Check account, model, tools and runtime readiness' },
+    { name: 'help', description: 'List the commands' },
+    { name: 'plan', description: 'Plan one request, read-only: /plan <brief>' },
+    { name: 'btw', description: 'Ask a side question without interrupting: /btw <question>' },
+    { name: 'new', description: 'Start a new session' },
+    { name: 'stop', description: 'Stop the current reply' },
+    { name: 'resume', description: 'Resume a session in this account and folder' },
+    { name: 'tree', description: 'Navigate the session tree' },
+    { name: 'fork', description: 'Fork from an earlier message' },
+    { name: 'clone', description: 'Clone this branch into a new session' },
+    { name: 'model', description: 'Choose the model' },
+    { name: 'effort', description: 'Choose the thinking effort' },
+    { name: 'thinking', description: 'Toggle transcript thinking visibility: /thinking [show|hide]' },
+    { name: 'name', description: 'Name this session' },
+    { name: 'compact', description: 'Compact the context' },
+    { name: 'copy', description: 'Copy the last reply' },
+    { name: 'export', description: 'Export this branch to HTML or JSONL' },
+    { name: 'reload', description: 'Reload trusted resources and keybindings' },
+    { name: 'accounts', description: 'Sign in, switch, check and remove Pi accounts' },
+    { name: 'permissions', description: 'Full Permission and per-tool approvals' },
+    { name: 'plugins', description: 'Switch plugins on or off and trust their code' },
+    { name: 'hub', description: 'Browse and install reviewed skills, plugins and documents' },
+    { name: 'components', description: 'Browse skills, prompts and rules for this Harness scope' },
+    { name: 'settings', description: 'Session and terminal settings' },
+    { name: 'trajectory', description: 'Inspect the recorded runs of this session' },
+    { name: 'log', description: "Harness diagnostics and this conversation's run events" },
+    { name: 'hotkeys', description: 'Keyboard controls' },
+    { name: 'quit', description: 'Restore the terminal and exit' }
+];
+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)];
+    };
+    const completions = () => {
+        const session = host.session();
+        const commands = new Map(BUILTINS.map(command => [command.name, command]));
+        for (const command of session.extensionRunner.getRegisteredCommands()) {
+            if (!commands.has(command.name))
+                commands.set(command.name, { name: command.name, description: command.description });
+        }
+        for (const prompt of session.resourceLoader.getPrompts().prompts) {
+            if (!commands.has(prompt.name))
+                commands.set(prompt.name, { name: prompt.name, description: prompt.description });
+        }
+        return [...commands.values()];
+    };
+    /** 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 }));
+    };
+    /** The text to send: a leading `$name` of a loaded skill becomes the `/skill:name` form Pi expands. */
+    const expandSkill = (text) => expandSkillInvocation(text, new Set(skills().map((skill) => skill.name)));
+    async function openPage(id, options = {}) {
+        await host.ui.custom((tui, _theme, _keys, done) => new PageOverlay({
+            page: createCommandPage(host, id, options), tui, theme: () => host.ui.theme,
+            close: () => done(undefined), changed: host.changed
+        }), { overlay: true, overlayOptions: pageOverlayOptions() });
+    }
+    async function execute(text) {
+        const match = /^\/([^\s]+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+        if (!match)
+            return false;
+        const name = match[1];
+        const argument = match[2]?.trim() ?? '';
+        if (!BUILTINS.some(item => item.name === name)) {
+            if (completions().some(item => item.name === name))
+                return false;
+            // 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;
+            host.ui.notify(`Unknown command: /${name}. Use /help to list commands.`, 'error');
+            return true;
+        }
+        try {
+            const session = host.session();
+            switch (name) {
+                case 'help':
+                    notify(completions().map(item => `/${item.name}  ${item.description ?? ''}`).join('\n'));
+                    break;
+                case 'plan': {
+                    if (!argument || ['on', 'off', 'toggle'].includes(argument.toLowerCase()))
+                        throw new Error('Use /plan <plan brief>.');
+                    host.plan(argument);
+                    break;
+                }
+                case 'quit':
+                    host.shutdown();
+                    break;
+                case 'btw':
+                    await host.btw(argument);
+                    break;
+                case 'stop': {
+                    if (!session.isStreaming)
+                        throw new Error('Nothing is running.');
+                    await host.runtime().interrupt();
+                    break;
+                }
+                case 'new':
+                    await host.runtime().newSession();
+                    break;
+                case 'resume': {
+                    let path = argument;
+                    if (!path) {
+                        const sessions = await SessionManager.list(host.cwd(), host.sessionDirectory());
+                        const selected = await choose('Resume session', sessions, (item, index) => `${index + 1}. ${item.name ?? item.firstMessage ?? item.id}  ${item.modified.toLocaleString()}`);
+                        if (!selected)
+                            break;
+                        path = selected.path;
+                    }
+                    const target = resolve(host.cwd(), path);
+                    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 'tree': {
+                    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 'doctor':
+                    await openPage('doctor');
+                    break;
+                case 'settings':
+                    await openPage('settings');
+                    break;
+                case 'permissions':
+                    await openPage('permissions');
+                    break;
+                case 'accounts':
+                    await openPage('accounts');
+                    break;
+                case 'plugins':
+                    await openPage('plugins');
+                    break;
+                case 'hub':
+                    await openPage('hub');
+                    break;
+                case 'components':
+                    await openPage('components');
+                    break;
+                case 'name': {
+                    const name = argument || await host.ui.input('Session name', session.sessionName);
+                    if (name !== undefined)
+                        session.setSessionName(name);
+                    break;
+                }
+                case 'trajectory':
+                    await openPage('trajectory', { runId: argument });
+                    break;
+                case 'log':
+                    await openPage('log');
+                    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, expandSkill };
+}

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;
+/** The overlay options every full-screen page command passes; OpenTUI reads the marker. */
+export declare function pageOverlayOptions(): HarnessOverlayOptions;

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

@@ -0,0 +1,50 @@
+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
+    };
+}
+/** The overlay options every full-screen page command passes; OpenTUI reads the marker. */
+export function pageOverlayOptions() {
+    return { anchor: 'top-left', width: '100%', maxHeight: '100%', dialog: 'page' };
+}

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

@@ -0,0 +1,75 @@
+import type { ExtensionUIContext, ExtensionUIDialogOptions, KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent';
+import { Input, type Component, type Focusable, type SelectListTheme, type TUI, type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TerminalMouseInput } from "./mouse.js";
+/** `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 Input {
+    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');
+    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>;
+    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;
+}