@xingular/harness 0.1.6 → 1.0.0

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

@@ -0,0 +1,196 @@
+import { fuzzyFilter, matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { safeText, selectedRow, selectionMuted, selectionText } from "./chrome.js";
+import { SEARCH_FIELD_ROWS, SearchField, searchFieldRowsFor } from "./search.js";
+import { isPrimaryClick } from "./mouse.js";
+export class FilterList {
+    options;
+    rows;
+    visible;
+    selectedId;
+    focusedValue = false;
+    renderedSearchRows = SEARCH_FIELD_ROWS;
+    renderedRows = [];
+    search;
+    constructor(options) {
+        this.options = options;
+        this.search = new SearchField(options.theme);
+        this.rows = [...(options.rows ?? [])];
+        this.visible = this.rows;
+        this.selectedId = this.firstSelectable()?.id;
+    }
+    get focused() { return this.focusedValue; }
+    set focused(value) { this.focusedValue = value; }
+    get query() { return this.search.value; }
+    get selected() { return this.visible.find(row => row.id === this.selectedId); }
+    get total() { return this.rows.length; }
+    get shown() { return this.visible.length; }
+    /** Rows the list would use if nothing cut it: the search field, headings and rows. */
+    get height() { return (this.searchVisible() ? this.renderedSearchRows : 0) + this.entries().length; }
+    /** Rows at the top of `render` that a frame must keep when it has to cut the list. */
+    get pinnedRows() { return this.searchVisible() ? this.renderedSearchRows : 0; }
+    setRows(rows) {
+        this.rows = [...rows];
+        this.refilter();
+    }
+    /** Searches for `text` as if it had been typed. */
+    setQuery(text) {
+        this.search.setValue(text);
+        this.refilter();
+    }
+    select(id) {
+        if (this.visible.some(row => row.id === id))
+            this.selectedId = id;
+    }
+    /** Selects the row at a rendered line, and activates it on a primary click. */
+    handleMouse(event) {
+        if (!Number.isInteger(event.y) || event.y < 0)
+            return undefined;
+        const row = this.renderedRows[event.y];
+        if (!row || row.disabled)
+            return undefined;
+        const changed = this.selectedId !== row.id;
+        this.selectedId = row.id;
+        const activate = isPrimaryClick(event);
+        if (activate) {
+            if (this.options.onActivate)
+                this.options.onActivate(row);
+            else
+                this.options.onToggle?.(row);
+        }
+        return { handled: true, render: changed || activate };
+    }
+    invalidate() { this.search.invalidate(); }
+    limit() { return Math.max(1, Math.floor(this.options.limit?.() ?? Number.POSITIVE_INFINITY)); }
+    mode() { return this.options.search ?? 'always'; }
+    canSearch() { return this.mode() === 'always'; }
+    searchVisible() { return this.canSearch() || this.query.length > 0; }
+    firstSelectable() { return this.visible.find(row => !row.disabled); }
+    refilter() {
+        const query = this.query.trim();
+        this.visible = query
+            ? fuzzyFilter(this.rows, query, row => row.searchText ?? `${row.label} ${row.detail ?? ''} ${row.group ?? ''}`)
+            : this.rows;
+        if (!this.visible.some(row => row.id === this.selectedId && !row.disabled))
+            this.selectedId = this.firstSelectable()?.id;
+    }
+    move(delta) {
+        const selectable = this.visible.filter(row => !row.disabled);
+        if (!selectable.length)
+            return;
+        const at = Math.max(0, selectable.findIndex(row => row.id === this.selectedId));
+        this.selectedId = selectable[Math.max(0, Math.min(selectable.length - 1, at + delta))].id;
+    }
+    handleInput(data) {
+        if (matchesKey(data, 'escape')) {
+            if (this.search.clear()) {
+                this.refilter();
+                return true;
+            }
+            this.options.onCancel?.();
+            return Boolean(this.options.onCancel);
+        }
+        if (matchesKey(data, 'up')) {
+            this.move(-1);
+            return true;
+        }
+        if (matchesKey(data, 'down')) {
+            this.move(1);
+            return true;
+        }
+        if (matchesKey(data, 'pageUp')) {
+            this.move(-Math.max(1, this.limit() - 1));
+            return true;
+        }
+        if (matchesKey(data, 'pageDown')) {
+            this.move(Math.max(1, this.limit() - 1));
+            return true;
+        }
+        if (matchesKey(data, 'home')) {
+            this.move(-this.visible.length);
+            return true;
+        }
+        if (matchesKey(data, 'end')) {
+            this.move(this.visible.length);
+            return true;
+        }
+        if (matchesKey(data, 'enter')) {
+            const row = this.selected;
+            if (row && !row.disabled)
+                this.options.onActivate?.(row);
+            return true;
+        }
+        if (data === ' ' && !this.query && this.options.onToggle) {
+            const row = this.selected;
+            if (row && !row.disabled)
+                this.options.onToggle(row);
+            return true;
+        }
+        if (!this.canSearch() && !this.query)
+            return false;
+        if (this.search.handleInput(data)) {
+            this.refilter();
+            return true;
+        }
+        return false;
+    }
+    entries() {
+        const entries = [];
+        let last;
+        for (const row of this.visible) {
+            if (!this.query && row.group && row.group !== last)
+                entries.push({ heading: row.group });
+            last = row.group;
+            entries.push({ row });
+        }
+        return entries;
+    }
+    line(row, width) {
+        const theme = this.options.theme();
+        const selected = row.id === this.selectedId;
+        const detail = row.detail ? safeText(row.detail) : '';
+        const room = width - 2;
+        const showDetail = detail && room >= visibleWidth(detail) + 6;
+        const label = truncateToWidth(safeText(row.label), Math.max(0, room - (showDetail ? visibleWidth(detail) + 2 : 0)), '…');
+        const gap = ' '.repeat(Math.max(0, room - visibleWidth(label) - (showDetail ? visibleWidth(detail) : 0)));
+        const tone = (text) => theme.fg(row.tone ?? 'muted', text);
+        const main = (selected ? '❯ ' : '  ') + label;
+        if (selected)
+            return selectedRow(selectionText(theme, main) + gap + (showDetail ? selectionMuted(theme, detail) : ''), width, theme);
+        return (row.disabled ? theme.fg('dim', main) : main) + gap + (showDetail ? tone(detail) : '');
+    }
+    /** `rows` is the most the list may use, the search row included. */
+    render(width, rows) {
+        this.renderedRows = [];
+        if (width < 1)
+            return [];
+        const theme = this.options.theme();
+        const searching = this.searchVisible();
+        const rowBudget = Math.floor(rows ?? this.limit());
+        this.renderedSearchRows = searching ? searchFieldRowsFor(rowBudget) : 0;
+        this.search.focused = this.focusedValue && searching;
+        const lines = [];
+        if (searching) {
+            const [one, many] = this.options.noun ?? ['option', 'options'];
+            const count = this.query ? `${this.shown} of ${this.total}` : `${this.total} ${this.total === 1 ? one : many}`;
+            const context = this.query ? this.options.searchContext?.(this.query.trim()) : undefined;
+            const note = context ? `${count} · ${context}` : count;
+            const searchLines = this.search.renderLines(width, note, this.renderedSearchRows);
+            lines.push(...searchLines);
+            this.renderedRows.push(...searchLines.map(() => undefined));
+        }
+        const budget = Math.max(1, rowBudget - lines.length);
+        const entries = this.entries();
+        if (!entries.length) {
+            lines.push(theme.fg('dim', this.query ? 'No matches' : this.options.empty ?? 'Nothing to show'));
+            this.renderedRows.push(undefined);
+            return lines.map(line => truncateToWidth(line, width, ''));
+        }
+        const at = Math.max(0, entries.findIndex(entry => entry.row?.id === this.selectedId));
+        const start = Math.max(0, Math.min(Math.max(0, entries.length - budget), at - Math.floor(budget / 2)));
+        for (const entry of entries.slice(start, start + budget)) {
+            lines.push(entry.row ? this.line(entry.row, width) : theme.fg('dim', safeText(entry.heading ?? '')));
+            this.renderedRows.push(entry.row);
+        }
+        return lines.map(line => truncateToWidth(line, width, ''));
+    }
+}

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

@@ -0,0 +1,42 @@
+import type { AgentSession } from '@earendil-works/pi-coding-agent';
+import { type ChoicePatch, type ModeChoice } from "../../accounts/choices.js";
+import type { Effort } from "../../core/effort.js";
+export type ComposerMode = 'normal' | 'plan';
+export type ChoiceModel = Parameters<AgentSession['setModel']>[0];
+/** The part of the account store a terminal can reach: its own account, through the session socket. */
+export interface ChoiceStore {
+    read(): Promise<Record<string, ModeChoice>>;
+    write(mode: ComposerMode, patch: ChoicePatch): Promise<unknown>;
+}
+/** The part of a native session a choice touches. */
+export interface ChoiceSession {
+    readonly model?: ChoiceModel;
+    setModel(model: ChoiceModel, options: {
+        persist: boolean;
+    }): Promise<void>;
+    setThinkingLevel(level: AgentSession['thinkingLevel'], options: {
+        persist: boolean;
+    }): void;
+}
+export declare class ModeChoices {
+    private readonly store;
+    private modes;
+    private quiet;
+    constructor(store: ChoiceStore);
+    /** Reads the account's choices. A failed read keeps what is already known, so a session still starts. */
+    load(): Promise<void>;
+    /** The model and effort a mode starts from: its own, else normal's, field by field. */
+    resolve(mode: ComposerMode): {
+        model?: string;
+        effort?: Effort;
+    };
+    /** Runs `action` as the terminal's own change. Nothing it causes is recorded as a person's selection. */
+    quietly<T>(action: () => T | Promise<T>): Promise<T>;
+    /**
+     * Applies a mode's saved model and effort to the session. A model the account cannot use is
+     * skipped, and Pi clamps an effort the model does not support.
+     */
+    apply(session: ChoiceSession, mode: ComposerMode, modelFor: (reference: string) => ChoiceModel | undefined): Promise<void>;
+    /** Records a selection the person made in `mode`. Skipped while the terminal is making its own change. */
+    record(mode: ComposerMode, patch: ChoicePatch): Promise<void>;
+}

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

@@ -0,0 +1,70 @@
+import { resolveChoice } from "../../accounts/choices.js";
+export class ModeChoices {
+    store;
+    modes = {};
+    quiet = 0;
+    constructor(store) {
+        this.store = store;
+    }
+    /** Reads the account's choices. A failed read keeps what is already known, so a session still starts. */
+    async load() {
+        try {
+            this.modes = await this.store.read();
+        }
+        catch {
+            // Keep the choices already known; the terminal starts on Pi's own default when there are none.
+        }
+    }
+    /** The model and effort a mode starts from: its own, else normal's, field by field. */
+    resolve(mode) {
+        return resolveChoice(this.modes, mode);
+    }
+    /** Runs `action` as the terminal's own change. Nothing it causes is recorded as a person's selection. */
+    async quietly(action) {
+        this.quiet += 1;
+        try {
+            return await action();
+        }
+        finally {
+            this.quiet -= 1;
+        }
+    }
+    /**
+     * Applies a mode's saved model and effort to the session. A model the account cannot use is
+     * skipped, and Pi clamps an effort the model does not support.
+     */
+    async apply(session, mode, modelFor) {
+        const choice = this.resolve(mode);
+        await this.quietly(async () => {
+            const model = choice.model ? modelFor(choice.model) : undefined;
+            if (model && !(session.model && session.model.provider === model.provider && session.model.id === model.id)) {
+                try {
+                    await session.setModel(model, { persist: false });
+                }
+                catch {
+                    // Not usable on this account (no key, or no longer offered): keep the session's model.
+                }
+            }
+            if (choice.effort)
+                session.setThinkingLevel(choice.effort, { persist: false });
+        });
+    }
+    /** Records a selection the person made in `mode`. Skipped while the terminal is making its own change. */
+    async record(mode, patch) {
+        if (this.quiet > 0)
+            return;
+        const current = this.modes[mode];
+        this.modes[mode] = {
+            ...current,
+            ...(patch.model !== undefined ? { model: patch.model } : {}),
+            ...(patch.effort !== undefined ? { effort: patch.effort } : {}),
+            updatedAt: new Date().toISOString()
+        };
+        try {
+            await this.store.write(mode, patch);
+        }
+        catch {
+            // Best effort: the selection still applies to this session, and the next one is recorded again.
+        }
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * The `/model` picker: every model the account can use, searched in the standard place, with the
+ * current model marked, the default noted, and Tab to move between all models and the scoped set.
+ * Enter uses a model for this session; Ctrl+S also saves it as the default.
+ */
+import type { AgentSession, Theme } from '@earendil-works/pi-coding-agent';
+import { type Component, type Focusable, type TUI } from '@earendil-works/pi-tui';
+type PiModel = NonNullable<AgentSession['model']>;
+type ModelCatalog = Pick<AgentSession['modelRuntime'], 'getAvailableSnapshot' | 'getModel' | 'getError' | 'refresh'>;
+export interface ModelPickerOptions {
+    theme: () => Theme;
+    tui: TUI;
+    runtime: ModelCatalog;
+    current: PiModel | undefined;
+    /** The models Ctrl+P cycles through, when any are chosen. */
+    scoped: ReadonlyArray<{
+        model: PiModel;
+    }>;
+    defaultModel?: {
+        provider: string;
+        id: string;
+    };
+    initialSearch?: string;
+    select(model: PiModel, persist: boolean): void;
+    cancel(): void;
+    changed(): void;
+}
+export declare class ModelPicker implements Component, Focusable {
+    private readonly options;
+    private scope;
+    private all;
+    private scoped;
+    private status;
+    private error;
+    private closed;
+    private readonly abort;
+    private readonly timer;
+    private readonly list;
+    constructor(options: ModelPickerOptions);
+    get focused(): boolean;
+    set focused(value: boolean);
+    private isCurrent;
+    private isDefault;
+    private load;
+    /** The current model first, the default second, then by provider. */
+    private fill;
+    private refresh;
+    private finish;
+    private cancel;
+    dispose(): void;
+    invalidate(): void;
+    handleInput(data: string): void;
+    render(width: number): string[];
+}
+export {};

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

@@ -0,0 +1,155 @@
+import { matchesKey, truncateToWidth } from '@earendil-works/pi-tui';
+import { centerDialogChromeRows, centerDialogContentWidth, centerDialogFrame, contentWidth, pageFrame, safeText, tabStrip } from "./chrome.js";
+import { centeredDialogHost, dialogFits, pageRows } from "./dialogGeometry.js";
+import { FilterList } from "./list.js";
+const REFRESH_TIMEOUT_MS = 15_000;
+const SCOPES = [{ id: 'all', title: 'All models' }, { id: 'scoped', title: 'Scoped models' }];
+const keyOf = (model) => `${model.provider}\u0000${model.id}`;
+export class ModelPicker {
+    options;
+    scope;
+    all = [];
+    scoped;
+    status = 'Refreshing model catalogs…';
+    error;
+    closed = false;
+    abort = new AbortController();
+    timer;
+    list;
+    constructor(options) {
+        this.options = options;
+        this.scoped = options.scoped.map(item => options.runtime.getModel(item.model.provider, item.model.id) ?? item.model);
+        this.scope = this.scoped.length ? 'scoped' : 'all';
+        this.list = new FilterList({
+            theme: options.theme, search: 'always', noun: ['model', 'models'], empty: 'No models are available for this account.',
+            searchContext: () => this.scope === 'all' ? 'all models' : 'scoped models',
+            onActivate: row => { if (row.data)
+                this.finish(row.data, false); },
+            onCancel: () => this.cancel()
+        });
+        this.load();
+        if (options.initialSearch)
+            this.list.setQuery(options.initialSearch);
+        this.timer = setTimeout(() => this.abort.abort(), REFRESH_TIMEOUT_MS);
+        void this.refresh();
+    }
+    get focused() { return this.list.focused; }
+    set focused(value) { this.list.focused = value; }
+    isCurrent(model) { return this.options.current ? keyOf(this.options.current) === keyOf(model) : false; }
+    isDefault(model) { return this.options.defaultModel ? keyOf(this.options.defaultModel) === keyOf(model) : false; }
+    load() {
+        this.all = [...this.options.runtime.getAvailableSnapshot()];
+        this.fill();
+    }
+    /** The current model first, the default second, then by provider. */
+    fill() {
+        const source = this.scope === 'scoped' ? this.scoped : this.all;
+        const ordered = [...source].sort((left, right) => Number(this.isCurrent(right)) - Number(this.isCurrent(left)) || Number(this.isDefault(right)) - Number(this.isDefault(left)) || left.provider.localeCompare(right.provider));
+        const rows = ordered.map(model => ({
+            id: keyOf(model), data: model,
+            label: `${this.isCurrent(model) ? '✓' : ' '} ${safeText(model.id)}`,
+            detail: `${safeText(model.provider)}${this.isDefault(model) ? ' · default' : ''}`,
+            tone: 'muted',
+            searchText: `${model.provider} ${model.provider}/${model.id} ${model.id} ${model.name ?? ''}${this.isDefault(model) ? ' default' : ''}`
+        }));
+        this.list.setRows(rows);
+        const current = ordered.find(model => this.isCurrent(model));
+        if (current)
+            this.list.select(keyOf(current));
+    }
+    async refresh() {
+        try {
+            const result = await this.options.runtime.refresh({ allowNetwork: true, signal: this.abort.signal });
+            if (this.closed)
+                return;
+            this.status = '';
+            if (result.aborted)
+                this.error = 'Model refresh timed out; showing cached models.';
+            else if (result.errors.size)
+                this.error = `Could not refresh ${[...result.errors.keys()].join(', ')}; showing cached models.`;
+            else {
+                this.error = this.options.runtime.getError();
+                if (!this.error)
+                    this.status = 'Model catalogs refreshed.';
+            }
+            this.load();
+        }
+        catch (error) {
+            if (this.closed)
+                return;
+            this.status = '';
+            this.error = `Could not refresh model catalogs: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        finally {
+            clearTimeout(this.timer);
+            if (!this.closed)
+                this.options.changed();
+        }
+    }
+    finish(model, persist) {
+        this.dispose();
+        this.options.select(model, persist);
+    }
+    cancel() {
+        this.dispose();
+        this.options.cancel();
+    }
+    dispose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        clearTimeout(this.timer);
+        this.abort.abort();
+    }
+    invalidate() { this.list.invalidate(); }
+    handleInput(data) {
+        if (matchesKey(data, 'ctrl+c')) {
+            this.cancel();
+            return;
+        }
+        const centered = centeredDialogHost(this.options.tui) && dialogFits(this.options.tui.terminal.columns, this.options.tui.terminal.rows);
+        const scopeForward = matchesKey(data, 'tab') || (centered && matchesKey(data, 'right'));
+        const scopeBackward = matchesKey(data, 'shift+tab') || (centered && matchesKey(data, 'left'));
+        if (scopeForward || scopeBackward) {
+            if (this.scoped.length && !this.list.query) {
+                this.scope = this.scope === 'all' ? 'scoped' : 'all';
+                this.fill();
+            }
+            return;
+        }
+        if (matchesKey(data, 'ctrl+s')) {
+            const model = this.list.selected?.data;
+            if (model)
+                this.finish(model, true);
+            return;
+        }
+        const before = this.list.query;
+        this.list.handleInput(data);
+        if (this.list.query !== before)
+            this.options.changed();
+    }
+    render(width) {
+        const rows = pageRows(this.options.tui);
+        const theme = this.options.theme();
+        if (width < 1 || rows < 1)
+            return [];
+        const centered = centeredDialogHost(this.options.tui) && dialogFits(this.options.tui.terminal.columns, this.options.tui.terminal.rows);
+        const inner = centered ? centerDialogContentWidth(width) : contentWidth(width);
+        const selected = this.list.selected?.data;
+        const notes = [
+            this.status ? theme.fg('muted', this.status) : '',
+            selected ? theme.fg('muted', `Model name: ${safeText(selected.name ?? selected.id)}`) : '',
+            this.error ? theme.fg('error', this.error) : ''
+        ].filter(Boolean);
+        const chromeRows = centered ? centerDialogChromeRows(rows) : 4;
+        const lines = this.list.render(inner, Math.max(2, rows - chromeRows - 1 - (notes.length ? notes.length + 1 : 0)));
+        if (this.scoped.length)
+            lines.splice(this.list.pinnedRows, 0, tabStrip(SCOPES, this.scope, inner, theme, 'sub'));
+        if (notes.length)
+            lines.push('', ...notes);
+        const hint = `Enter use · Ctrl+S set as default${this.scoped.length ? ' · Tab scope' : ''} · Esc cancel`;
+        if (centered)
+            return centerDialogFrame({ title: 'Model', body: lines.map(line => truncateToWidth(line, inner, '')), width, rows, theme });
+        return pageFrame({ title: 'Model', meta: this.status || undefined, body: lines.map(line => truncateToWidth(line, inner, '')), footer: hint, width, rows, theme });
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { TuiMouseEvent } from '@earendil-works/pi-tui';
+export type TerminalMouseInput = TuiMouseEvent;
+export declare function isPrimaryClick(event: TerminalMouseInput): boolean;

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

@@ -0,0 +1,3 @@
+export function isPrimaryClick(event) {
+    return event.type === 'click' && event.button === 'left';
+}

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

@@ -0,0 +1,14 @@
+import type { TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TabInfo } from "./chrome.js";
+import type { TerminalMouseInput } from "./mouse.js";
+export interface TerminalPage {
+    tabs(): readonly TabInfo[];
+    activeTab(): string;
+    render(width: number, rows: number): string[];
+    handleInput(data: string): boolean;
+    handleMouse?(event: TerminalMouseInput): TuiMouseEventResult | undefined;
+    hint(): string;
+    focused?: boolean;
+    activate?(): void;
+    dispose?(): void;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,27 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type Component, type Focusable, type TUI, type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TerminalMouseInput } from "./mouse.js";
+import type { TerminalPage } from "./page.js";
+export interface PageOverlayOptions {
+    page: TerminalPage;
+    tui: TUI;
+    theme: () => Theme;
+    close(): void;
+    changed(): void;
+}
+export declare class PageOverlay implements Component, Focusable {
+    readonly options: PageOverlayOptions;
+    private focusedValue;
+    private disposed;
+    private pointerLayout?;
+    private hoveredTab?;
+    constructor(options: PageOverlayOptions);
+    get page(): TerminalPage;
+    get focused(): boolean;
+    set focused(value: boolean);
+    invalidate(): void;
+    handleMouse(event: TerminalMouseInput): TuiMouseEventResult | undefined;
+    handleInput(data: string): void;
+    render(width: number): string[];
+    dispose(): void;
+}