@xingular/harness 2.0.0 → 2.0.1-unstable

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

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

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

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

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

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

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

@@ -0,0 +1,278 @@
+import { fuzzyFilter, matchesKey, parseColor, 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().reduce((height, entry) => height + (entry.row?.subtitle === undefined ? 1 : 2), 0);
+    }
+    /** 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)); }
+    rowGap() {
+        const gap = this.options.rowGap ?? 0;
+        return Number.isFinite(gap) ? Math.max(0, Math.floor(gap)) : 0;
+    }
+    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.subtitle ?? ''} ${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;
+        const gap = this.rowGap();
+        for (const [index, row] of this.visible.entries()) {
+            if (!this.query && row.group && row.group !== last)
+                entries.push({ heading: row.group });
+            last = row.group;
+            entries.push({ row });
+            if (index < this.visible.length - 1) {
+                for (let line = 0; line < gap; line += 1)
+                    entries.push({ spacer: true });
+            }
+        }
+        return entries;
+    }
+    lines(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 prefix = selected ? '❯ ' : '  ';
+        const labelText = selected || row.disabled || !row.labelParts?.length ? label : this.labelParts(row.labelParts, label, theme);
+        const main = prefix + label;
+        const primary = selected
+            ? selectedRow(selectionText(theme, main) + gap + (showDetail ? selectionMuted(theme, detail) : ''), width, theme)
+            : (row.disabled ? theme.fg('dim', main) : prefix + labelText) + gap + (showDetail ? tone(detail) : '');
+        if (row.subtitle === undefined)
+            return [primary];
+        const subtitle = truncateToWidth(`  ${safeText(row.subtitle)}`, width, '…');
+        const secondary = selected
+            ? selectedRow(selectionMuted(theme, subtitle), width, theme)
+            : theme.fg(row.disabled ? 'dim' : 'muted', subtitle);
+        return [primary, secondary];
+    }
+    labelParts(parts, visibleLabel, theme) {
+        const source = parts.map(part => safeText(part.text)).join('');
+        const truncated = visibleWidth(source) > visibleWidth(visibleLabel);
+        let remaining = Math.max(0, visibleWidth(visibleLabel) - (truncated ? 1 : 0));
+        const output = [];
+        for (const part of parts) {
+            if (remaining <= 0)
+                break;
+            const text = safeText(part.text);
+            const fitted = truncateToWidth(text, remaining, '');
+            if (fitted) {
+                output.push(part.color ? theme.style(fitted, { fg: parseColor(part.color) }) : part.tone ? theme.fg(part.tone, fitted) : fitted);
+            }
+            remaining -= visibleWidth(fitted);
+            if (visibleWidth(fitted) < visibleWidth(text))
+                break;
+        }
+        if (truncated)
+            output.push('…');
+        return output.join('');
+    }
+    /** `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));
+        let start = at;
+        let end = at + 1;
+        let used = entries[at]?.row?.subtitle === undefined ? 1 : 2;
+        let preferBefore = true;
+        while (start > 0 || end < entries.length) {
+            const before = entries[start - 1];
+            const after = entries[end];
+            const beforeHeight = before ? (before.row?.subtitle === undefined ? 1 : 2) : Number.POSITIVE_INFINITY;
+            const afterHeight = after ? (after.row?.subtitle === undefined ? 1 : 2) : Number.POSITIVE_INFINITY;
+            if (preferBefore && before && used + beforeHeight <= budget) {
+                start -= 1;
+                used += beforeHeight;
+            }
+            else if (after && used + afterHeight <= budget) {
+                end += 1;
+                used += afterHeight;
+            }
+            else if (before && used + beforeHeight <= budget) {
+                start -= 1;
+                used += beforeHeight;
+            }
+            else
+                break;
+            preferBefore = !preferBefore;
+        }
+        if (entries[start]?.spacer)
+            start += 1;
+        if (entries[end - 1]?.spacer)
+            end -= 1;
+        for (const entry of entries.slice(start, end)) {
+            if (entry.row) {
+                const rendered = this.lines(entry.row, width);
+                lines.push(...rendered);
+                this.renderedRows.push(...rendered.map(() => entry.row));
+            }
+            else if (entry.spacer) {
+                lines.push('');
+                this.renderedRows.push(undefined);
+            }
+            else {
+                lines.push(theme.fg('dim', safeText(entry.heading ?? '')));
+                this.renderedRows.push(undefined);
+            }
+        }
+        this.renderedRows = this.renderedRows.slice(0, rowBudget);
+        return lines.slice(0, rowBudget).map(line => truncateToWidth(line, width, ''));
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type MarkdownTheme } from '@earendil-works/pi-tui';
+/** The Harness markdown colours, mapped onto the component's callbacks. */
+export declare function markdownTheme(theme: Theme): MarkdownTheme;
+/** Model output as markdown source: terminal control sequences never reach the renderer. */
+export declare function markdownSource(text: string): string;
+/**
+ * One surface's Markdown component. It re-renders only when the streamed text, the width or the
+ * theme changes, and drops trailing blank rows so the caller frames the block itself.
+ */
+export declare class MarkdownBlock {
+    private component;
+    private theme;
+    private text;
+    lines(text: string, width: number, theme: Theme): string[];
+}

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

@@ -0,0 +1,55 @@
+import { Markdown, stripTerminalSequences } from '@earendil-works/pi-tui';
+/** The Harness markdown colours, mapped onto the component's callbacks. */
+export function markdownTheme(theme) {
+    return {
+        heading: text => theme.fg('mdHeading', text),
+        link: text => theme.fg('mdLink', text),
+        linkUrl: text => theme.fg('mdLinkUrl', text),
+        code: text => theme.fg('mdCode', text),
+        codeBlock: text => theme.fg('mdCodeBlock', text),
+        codeBlockBorder: text => theme.fg('mdCodeBlockBorder', text),
+        quote: text => theme.fg('mdQuote', text),
+        quoteBorder: text => theme.fg('mdQuoteBorder', text),
+        hr: text => theme.fg('mdHr', text),
+        listBullet: text => theme.fg('mdListBullet', text),
+        bold: text => theme.bold(text),
+        italic: text => theme.italic(text),
+        underline: text => theme.underline(text),
+        strikethrough: text => theme.strikethrough(text),
+        // A block surface has no syntax highlighter; its code keeps the theme's code colour.
+        highlightCode: code => code.split('\n').map(line => theme.fg('mdCodeBlock', line))
+    };
+}
+/** Model output as markdown source: terminal control sequences never reach the renderer. */
+export function markdownSource(text) {
+    return stripTerminalSequences(text)
+        .replace(/\r\n?/gu, '\n')
+        .replace(/[\x00-\x08\x0b-\x1f\x7f]/gu, ' ');
+}
+/**
+ * One surface's Markdown component. It re-renders only when the streamed text, the width or the
+ * theme changes, and drops trailing blank rows so the caller frames the block itself.
+ */
+export class MarkdownBlock {
+    component;
+    theme;
+    text = '';
+    lines(text, width, theme) {
+        if (width < 1 || !text.trim())
+            return [];
+        if (!this.component || this.theme !== theme) {
+            this.component = new Markdown('', 0, 0, markdownTheme(theme));
+            this.theme = theme;
+            this.text = '';
+        }
+        if (this.text !== text) {
+            this.component.setText(text);
+            this.text = text;
+        }
+        const lines = this.component.render(width);
+        let end = lines.length;
+        while (end > 0 && !stripTerminalSequences(lines[end - 1]).trim())
+            end -= 1;
+        return lines.slice(0, end);
+    }
+}

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

@@ -0,0 +1,61 @@
+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;
+}
+/** The model the terminal resolved for a saved reference, when the account can use it. */
+export type UsableModel = (reference: string) => Promise<ChoiceModel | undefined>;
+/** What a fallback put in place, for the notice that explains it. */
+export interface AppliedChoice {
+    reference: string;
+    effort?: Effort;
+}
+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;
+    };
+    /** The selection a conversation falls back to when the account cannot use the model in its history. */
+    start(mode: ComposerMode): {
+        model?: string;
+        effort?: Effort;
+    };
+    /**
+     * Starts a conversation this account cannot continue on the model in its own history, on the
+     * newest selection the person made on this account. Each model is tried in order, so a choice the
+     * account cannot use is skipped; the change stays a change the terminal made itself.
+     */
+    useFallback(session: ChoiceSession, mode: ComposerMode, usable: UsableModel, fallback: AgentSession['thinkingLevel']): Promise<AppliedChoice | null>;
+    /** 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. A mode with no effort of its own
+     * returns to `fallback`, so a level chosen in another mode does not stay with this one.
+     */
+    apply(session: ChoiceSession, mode: ComposerMode, modelFor: (reference: string) => ChoiceModel | undefined, fallback: AgentSession['thinkingLevel']): 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,95 @@
+import { resolveChoice, startChoice, startModels } 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);
+    }
+    /** The selection a conversation falls back to when the account cannot use the model in its history. */
+    start(mode) {
+        return startChoice(this.modes, mode);
+    }
+    /**
+     * Starts a conversation this account cannot continue on the model in its own history, on the
+     * newest selection the person made on this account. Each model is tried in order, so a choice the
+     * account cannot use is skipped; the change stays a change the terminal made itself.
+     */
+    async useFallback(session, mode, usable, fallback) {
+        const effort = this.start(mode).effort;
+        for (const reference of startModels(this.modes, mode)) {
+            const model = await usable(reference);
+            if (!model)
+                continue;
+            if (session.model && session.model.provider === model.provider && session.model.id === model.id)
+                return null;
+            await this.quietly(async () => {
+                await session.setModel(model, { persist: false });
+                session.setThinkingLevel((effort ?? fallback), { persist: false });
+            });
+            return { reference: `${model.provider}/${model.id}`, ...(effort ? { effort } : {}) };
+        }
+        return null;
+    }
+    /** 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. A mode with no effort of its own
+     * returns to `fallback`, so a level chosen in another mode does not stay with this one.
+     */
+    async apply(session, mode, modelFor, fallback) {
+        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.
+                }
+            }
+            session.setThinkingLevel((choice.effort ?? fallback), { 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.
+        }
+    }
+}