@xingular/harness 0.1.7 → 1.0.0

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

@@ -0,0 +1,60 @@
+import { Input, matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+export const SEARCH_GLYPH = '⌕';
+export const SEARCH_PLACEHOLDER = 'Type to search';
+export const SEARCH_FIELD_ROWS = 5;
+export function searchFieldRowsFor(availableRows) {
+    const fieldRoom = Math.max(0, Math.floor(availableRows) - 1);
+    if (fieldRoom >= SEARCH_FIELD_ROWS)
+        return SEARCH_FIELD_ROWS;
+    return fieldRoom >= 3 ? 3 : 1;
+}
+const SCREEN_KEYS = ['left', 'right', 'up', 'down', 'enter', 'tab', 'shift+tab', 'escape', 'pageUp', 'pageDown', 'home', 'end'];
+export class SearchField {
+    theme;
+    input;
+    constructor(theme, placeholder = SEARCH_PLACEHOLDER) {
+        this.theme = theme;
+        this.input = new Input({ prompt: '', placeholder, placeholderStyle: text => this.theme().fg('dim', text) });
+    }
+    get value() { return this.input.getValue(); }
+    set focused(value) { this.input.focused = value; }
+    /** Presets the text, for a command that was given something to search for. */
+    setValue(text) { this.input.setValue(text); }
+    /** Empties the field; says whether there was anything to empty. */
+    clear() {
+        if (!this.value)
+            return false;
+        this.input.setValue('');
+        return true;
+    }
+    /** Takes typed text, paste, Backspace and Ctrl+U. Says whether the text changed. */
+    handleInput(data) {
+        if (SCREEN_KEYS.some(key => matchesKey(data, key)))
+            return false;
+        const before = this.value;
+        this.input.handleInput(data);
+        return this.value !== before;
+    }
+    invalidate() { this.input.invalidate(); }
+    /** One row, `width` cells: the glyph, the text or placeholder, and `note` at the right edge. */
+    render(width, note = '') {
+        if (width < 1)
+            return '';
+        const theme = this.theme();
+        const glyph = theme.fg('text', `${SEARCH_GLYPH} `);
+        const room = Math.max(0, width - visibleWidth(glyph));
+        const shownNote = note && room > visibleWidth(note) + 8 ? note : '';
+        const field = this.input.render(Math.max(1, room - (shownNote ? visibleWidth(shownNote) + 1 : 0)))[0] ?? '';
+        return truncateToWidth(glyph + field + (shownNote ? ' ' + theme.fg('muted', shownNote) : ''), width, '');
+    }
+    renderLines(width, note = '', rows = SEARCH_FIELD_ROWS) {
+        if (width < 1)
+            return [];
+        if (rows < 3)
+            return [this.render(width, note)];
+        const rule = this.theme().fg('border', '─'.repeat(width));
+        return rows >= SEARCH_FIELD_ROWS
+            ? ['', rule, this.render(width, note), rule, '']
+            : [rule, this.render(width, note), rule];
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * One selection palette for every terminal surface. A selected row is a muted blue field with
+ * explicit near-white text, so the accent colour never sits on the selection background.
+ */
+export declare const SELECTION_COLORS: {
+    readonly dark: {
+        readonly background: "#1b314d";
+        readonly text: "#f4f8ff";
+        readonly muted: "#c4d3e6";
+    };
+    readonly light: {
+        readonly background: "#dbe8fa";
+        readonly text: "#10233a";
+        readonly muted: "#455a72";
+    };
+};

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

@@ -0,0 +1,16 @@
+/**
+ * One selection palette for every terminal surface. A selected row is a muted blue field with
+ * explicit near-white text, so the accent colour never sits on the selection background.
+ */
+export const SELECTION_COLORS = {
+    dark: {
+        background: '#1b314d',
+        text: '#f4f8ff',
+        muted: '#c4d3e6'
+    },
+    light: {
+        background: '#dbe8fa',
+        text: '#10233a',
+        muted: '#455a72'
+    }
+};

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

@@ -0,0 +1,3 @@
+import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+/** Retained UI methods belong to the resource generation that received them. */
+export declare function sessionUiContext(ui: ExtensionUIContext, current: () => boolean): ExtensionUIContext;

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

@@ -0,0 +1,30 @@
+const dialogs = new Set(['select', 'input', 'editor', 'custom']);
+/** Retained UI methods belong to the resource generation that received them. */
+export function sessionUiContext(ui, current) {
+    return new Proxy(ui, {
+        get(target, key, receiver) {
+            const value = Reflect.get(target, key, receiver);
+            if (typeof value !== 'function')
+                return value;
+            return (...args) => {
+                if (current())
+                    return Reflect.apply(value, target, args);
+                if (key === 'confirm')
+                    return Promise.resolve(false);
+                if (dialogs.has(String(key)))
+                    return Promise.resolve(undefined);
+                if (key === 'onTerminalInput')
+                    return () => { };
+                if (key === 'setTheme')
+                    return { success: false, error: 'This terminal session has ended.' };
+                if (key === 'getEditorText')
+                    return '';
+                if (key === 'getToolsExpanded')
+                    return false;
+                if (key === 'getAllThemes')
+                    return [];
+                return undefined;
+            };
+        }
+    });
+}

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

@@ -0,0 +1,12 @@
+import type { AgentSession, ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import type { TerminalSettingItem } from "./pages/settingsPage.js";
+export interface SettingsModelHost {
+    session(): AgentSession;
+    ui: ExtensionUIContext;
+    hotkeys?(): string;
+    refresh(): void;
+}
+export declare function createSettingsModel(host: SettingsModelHost): {
+    items: () => TerminalSettingItem[];
+    apply: (id: string) => Promise<void>;
+};

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

@@ -0,0 +1,84 @@
+const GROUP_ORDER = ['Theme', 'Display', 'Images', 'Thinking', 'Recovery', 'Editor', 'Queues', 'Commands', 'Terminal', 'Keyboard', 'Compaction'];
+export function createSettingsModel(host) {
+    const booleans = (session) => {
+        const settings = session.settingsManager;
+        return [
+            ['Auto compaction', () => session.autoCompactionEnabled, (value) => session.setAutoCompactionEnabled(value)],
+            ['Auto retry', () => session.autoRetryEnabled, (value) => session.setAutoRetryEnabled(value)],
+            ['Show images', () => settings.getShowImages(), (value) => settings.setShowImages(value)],
+            ['Resize images', () => settings.getImageAutoResize(), (value) => settings.setImageAutoResize(value)],
+            ['Block images', () => settings.getBlockImages(), (value) => settings.setBlockImages(value)],
+            ['Skill commands', () => settings.getEnableSkillCommands(), (value) => settings.setEnableSkillCommands(value)],
+            ['Hide thinking', () => settings.getHideThinkingBlock(), (value) => settings.setHideThinkingBlock(value)],
+            ['Hardware cursor', () => settings.getShowHardwareCursor(), (value) => settings.setShowHardwareCursor(value)],
+            ['Terminal progress', () => settings.getShowTerminalProgress(), (value) => settings.setShowTerminalProgress(value)]
+        ];
+    };
+    const locations = [
+        ['Context', 'Compaction'], ['Model', 'Recovery'], ['Appearance', 'Images'], ['Appearance', 'Images'],
+        ['Context', 'Images'], ['Interaction', 'Commands'], ['Appearance', 'Display'], ['Interaction', 'Editor'],
+        ['Interaction', 'Terminal'], ['Model', 'Thinking'], ['Interaction', 'Queues'], ['Interaction', 'Queues'],
+        ['Appearance', 'Theme'], ['Interaction', 'Keyboard']
+    ];
+    const descriptions = [
+        'Compact the context automatically when the session approaches its limit.', 'Retry eligible provider failures automatically.',
+        'Display actual image content returned by tools.', 'Resize image attachments before provider requests.',
+        'Block image attachments in provider requests.', 'Expose commands for the skills loaded in this session.',
+        'Collapse assistant thinking blocks in the transcript.', 'Display the terminal hardware cursor for editing and input methods.',
+        'Report active work through supported terminal progress controls.', 'Reasoning effort for the current model.',
+        'Delivery mode for messages that steer an active run.', 'Delivery mode for messages queued after a run.',
+        'Theme loaded from the trusted resource catalog.', 'View the current application keyboard bindings.'
+    ];
+    /** One line per setting, `Label: value`; its position is the setting's id. */
+    const options = (session) => [
+        ...booleans(session).map(([label, get]) => `${label}: ${get() ? 'on' : 'off'}`),
+        `Thinking: ${session.thinkingLevel}`, `Steering: ${session.steeringMode}`, `Follow-up: ${session.followUpMode}`,
+        `Theme: ${host.ui.theme.name}`, 'Keyboard controls'
+    ];
+    function items() {
+        const result = options(host.session()).map((option, index) => {
+            const split = option.indexOf(':');
+            return { id: String(index), tab: locations[index][0], group: locations[index][1], label: split < 0 ? option : option.slice(0, split), value: split < 0 ? '' : option.slice(split + 1).trim(), description: descriptions[index] };
+        });
+        return result.sort((a, b) => GROUP_ORDER.indexOf(a.group) - GROUP_ORDER.indexOf(b.group));
+    }
+    async function apply(id) {
+        const session = host.session();
+        const index = Number(id);
+        const switches = booleans(session);
+        const selected = options(session)[index];
+        if (selected === undefined)
+            return;
+        if (index < switches.length) {
+            const [, get, set] = switches[index];
+            set(!get());
+        }
+        else if (selected.startsWith('Thinking:')) {
+            const level = await host.ui.select('Thinking effort', session.getAvailableThinkingLevels());
+            if (level)
+                session.setThinkingLevel(level, { persist: true });
+        }
+        else if (selected.startsWith('Steering:') || selected.startsWith('Follow-up:')) {
+            const mode = await host.ui.select('Queue delivery', ['all', 'one-at-a-time']);
+            if (mode === 'all' || mode === 'one-at-a-time') {
+                if (selected.startsWith('Steering:'))
+                    session.setSteeringMode(mode);
+                else
+                    session.setFollowUpMode(mode);
+            }
+        }
+        else if (selected.startsWith('Theme:')) {
+            const theme = await host.ui.select('Theme', host.ui.getAllThemes().map(item => item.name));
+            if (theme) {
+                const result = host.ui.setTheme(theme);
+                if (!result.success)
+                    throw new Error(result.error);
+                session.settingsManager.setTheme(theme);
+            }
+        }
+        else
+            host.ui.notify(host.hotkeys?.() ?? 'Use /help for commands. Keyboard bindings are managed by the terminal application.', 'info');
+        host.refresh();
+    }
+    return { items, apply };
+}

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

@@ -0,0 +1,53 @@
+import { type AgentSession, type AgentSessionServices, type Theme } from '@earendil-works/pi-coding-agent';
+import { type Component } from '@earendil-works/pi-tui';
+export declare const SIDE_PROMPT: string;
+export declare const ANSWER_ROWS = 8;
+/**
+ * A bounded plain-text excerpt of the main conversation: the last few user and assistant turns, the
+ * tools an assistant turn called by name, and whether the reply is still running. Hidden reasoning,
+ * tool inputs and results, and images are left out.
+ */
+export declare function sideQuestionSnapshot(messages: readonly unknown[], running: boolean): string;
+/** What the controller needs from a session; a Pi `AgentSession` satisfies it through `createSideSession`. */
+export interface SideSession {
+    prompt(text: string): Promise<void>;
+    abort(): Promise<void>;
+    subscribe(listener: () => void): () => void;
+    answer(): string;
+    /** Why the provider ended the turn in error, if it did. */
+    failure(): string | undefined;
+    dispose(): void;
+}
+/** A separate in-memory session on the same account and model, with no tools, extensions, skills or project files. */
+export declare function createSideSession(services: AgentSessionServices, main: AgentSession): Promise<SideSession>;
+export type SideState = 'thinking' | 'answered' | 'failed';
+export interface SideQuestionOptions {
+    create(): Promise<SideSession>;
+    snapshot(): string;
+    theme(): Theme;
+    /** Puts the dock above the composer, or takes it away. */
+    mount(dock: Component | undefined): void;
+    changed(): void;
+}
+export declare class SideQuestion {
+    private readonly options;
+    private session;
+    private unsubscribe;
+    private generation;
+    private question;
+    private answerText;
+    private error;
+    private current;
+    private startedAt;
+    private readonly dock;
+    constructor(options: SideQuestionOptions);
+    get visible(): boolean;
+    get state(): SideState | undefined;
+    /** Asks one question, replacing any earlier one. Empty text dismisses. */
+    ask(question: string): Promise<void>;
+    /** Interrupts a running side question and removes the dock. */
+    dismiss(): Promise<void>;
+    private release;
+    /** The dock: a neutral rule, the inline question, its answer, and a hint, separated by blank rows. */
+    private render;
+}

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

@@ -0,0 +1,197 @@
+// `/btw <question>`: a side question answered by a separate, tool-free session while the main
+// conversation carries on. It lives in a dock above the composer, never enters the transcript, the
+// queue or the run history, and is gone on dismiss, on a session change, or when a new one replaces it.
+import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { contentWidth, footerRow, neutralRule, padded, safeText } from "./chrome.js";
+import { getWorkingSpinnerFrames, SPINNER_INTERVAL_MS, spinnerFrameAt } from "./workingStatus.js";
+export const SIDE_PROMPT = [
+    'You answer one short side question from a person whose main task is still running in another session.',
+    'You have no tools: you cannot read or change files, run commands, browse, or call anything, and you must not say you did.',
+    'Use the conversation excerpt for context and do not invent what it does not show. Answer briefly and plainly.'
+].join(' ');
+const TURNS = 6;
+const TURN_CHARS = 1_200;
+const TOTAL_CHARS = 6_000;
+const QUESTION_ROWS = 2;
+export const ANSWER_ROWS = 8;
+function blocks(content) {
+    if (typeof content === 'string')
+        return [{ type: 'text', text: content }];
+    return Array.isArray(content) ? content.filter((block) => typeof block === 'object' && block !== null) : [];
+}
+const clip = (text, limit) => text.length > limit ? `${text.slice(0, limit)}…` : text;
+/**
+ * A bounded plain-text excerpt of the main conversation: the last few user and assistant turns, the
+ * tools an assistant turn called by name, and whether the reply is still running. Hidden reasoning,
+ * tool inputs and results, and images are left out.
+ */
+export function sideQuestionSnapshot(messages, running) {
+    const turns = [];
+    for (const message of messages) {
+        const { role, content } = (message ?? {});
+        if (role !== 'user' && role !== 'assistant')
+            continue;
+        const parts = blocks(content);
+        const text = parts.filter(block => block.type === 'text' && typeof block.text === 'string').map(block => String(block.text)).join('\n').trim();
+        const tools = [...new Set(parts.filter(block => block.type === 'toolCall' && typeof block.name === 'string').map(block => String(block.name)))];
+        if (!text && !tools.length)
+            continue;
+        turns.push(`${role === 'user' ? 'User' : 'Assistant'}: ${clip(safeText(text).replace(/\s+/g, ' ').trim(), TURN_CHARS)}${tools.length ? ` [used tools: ${tools.join(', ')}]` : ''}`);
+    }
+    let recent = turns.slice(-TURNS);
+    while (recent.length > 1 && recent.join('\n').length > TOTAL_CHARS)
+        recent = recent.slice(1);
+    const lines = ['Conversation excerpt, oldest first:', ...(recent.length ? recent : ['(nothing yet)'])];
+    if (running)
+        lines.push('', 'The main reply is still running; its latest turn above may be unfinished.');
+    return lines.join('\n');
+}
+/** A separate in-memory session on the same account and model, with no tools, extensions, skills or project files. */
+export async function createSideSession(services, main) {
+    const model = main.model;
+    if (!model || model.id === 'unknown')
+        throw new Error('Choose a model before asking a side question.');
+    const settingsManager = SettingsManager.inMemory({});
+    const resourceLoader = new DefaultResourceLoader({
+        cwd: services.cwd, agentDir: services.agentDir, settingsManager,
+        noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true, systemPrompt: SIDE_PROMPT
+    });
+    await resourceLoader.reload();
+    const { session } = await createAgentSession({
+        cwd: services.cwd, agentDir: services.agentDir, modelRuntime: services.modelRuntime, settingsManager, resourceLoader,
+        sessionManager: SessionManager.inMemory(services.cwd), model, thinkingLevel: 'off', noTools: 'all'
+    });
+    return {
+        prompt: text => session.prompt(text),
+        abort: () => session.abort(),
+        subscribe: listener => session.subscribe(() => listener()),
+        answer: () => session.getLastAssistantText() ?? '',
+        failure: () => {
+            const last = session.messages.at(-1);
+            return last?.role === 'assistant' && last.stopReason === 'error' ? last.errorMessage ?? 'The provider returned an error.' : undefined;
+        },
+        dispose: () => session.dispose()
+    };
+}
+export class SideQuestion {
+    options;
+    session;
+    unsubscribe;
+    generation = 0;
+    question = '';
+    answerText = '';
+    error;
+    current;
+    startedAt = 0;
+    dock;
+    constructor(options) {
+        this.options = options;
+        this.dock = { invalidate: () => { }, render: width => this.render(width) };
+    }
+    get visible() { return this.current !== undefined; }
+    get state() { return this.current; }
+    /** Asks one question, replacing any earlier one. Empty text dismisses. */
+    async ask(question) {
+        const text = question.trim();
+        if (!text) {
+            await this.dismiss();
+            return;
+        }
+        await this.release();
+        const generation = ++this.generation;
+        this.question = text;
+        this.startedAt = Date.now();
+        this.answerText = '';
+        this.error = undefined;
+        this.current = 'thinking';
+        this.options.mount(this.dock);
+        this.options.changed();
+        try {
+            const session = await this.options.create();
+            if (generation !== this.generation) {
+                session.dispose();
+                return;
+            }
+            this.session = session;
+            this.unsubscribe = session.subscribe(() => {
+                if (generation !== this.generation)
+                    return;
+                this.answerText = session.answer();
+                this.options.changed();
+            });
+            await session.prompt(`${this.options.snapshot()}\n\nSide question: ${text}`);
+            if (generation !== this.generation)
+                return;
+            this.answerText = session.answer();
+            const failure = session.failure();
+            if (failure) {
+                this.current = 'failed';
+                this.error = failure;
+            }
+            else
+                this.current = 'answered';
+        }
+        catch (error) {
+            if (generation !== this.generation)
+                return;
+            this.current = 'failed';
+            this.error = error instanceof Error ? error.message : String(error);
+        }
+        this.options.changed();
+    }
+    /** Interrupts a running side question and removes the dock. */
+    async dismiss() {
+        this.generation++;
+        this.current = undefined;
+        await this.release();
+        this.options.mount(undefined);
+        this.options.changed();
+    }
+    async release() {
+        const session = this.session;
+        this.session = undefined;
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        if (!session)
+            return;
+        try {
+            await session.abort();
+        }
+        catch { /* A side run that cannot be stopped is still dropped. */ }
+        try {
+            session.dispose();
+        }
+        catch { /* Cleanup cannot keep the dock open. */ }
+    }
+    /** The dock: a neutral rule, the inline question, its answer, and a hint, separated by blank rows. */
+    render(width) {
+        if (width < 1 || !this.current)
+            return [];
+        const theme = this.options.theme();
+        const inner = contentWidth(width);
+        const spinner = this.current === 'thinking'
+            ? spinnerFrameAt(Date.now() - this.startedAt, getWorkingSpinnerFrames(process.env.TERM), SPINNER_INTERVAL_MS)
+            : '';
+        const marker = `${spinner ? `${spinner} ` : ''}/btw`;
+        const markerWidth = visibleWidth(marker) + 1;
+        const asked = wrapTextWithAnsi(safeText(this.question), Math.max(1, inner - markerWidth));
+        const question = asked.slice(0, QUESTION_ROWS).map((line, index) => {
+            const prefix = index === 0 ? `${theme.bold(theme.fg('accent', marker))} ` : ' '.repeat(markerWidth);
+            return prefix + theme.fg('muted', line);
+        });
+        if (asked.length > QUESTION_ROWS)
+            question[QUESTION_ROWS - 1] = truncateToWidth(question[QUESTION_ROWS - 1], inner - 1, '') + theme.fg('muted', '…');
+        const text = this.current === 'failed' ? `${this.answerText ? `${this.answerText}\n` : ''}${this.error ?? 'The side question failed.'}` : this.answerText;
+        const wrapped = text ? text.split('\n').flatMap(line => line ? wrapTextWithAnsi(safeText(line), inner) : ['']) : [];
+        const shown = wrapped.slice(0, ANSWER_ROWS).map(line => this.current === 'failed' ? theme.fg('error', line) : line);
+        const more = wrapped.length - shown.length;
+        return [
+            neutralRule(width, theme),
+            ...question.map(line => padded(line, width)),
+            ...(shown.length ? ['', ...shown.map(line => padded(line, width))] : []),
+            '',
+            footerRow(`${more > 0 ? `+${more} more lines · ` : ''}/btw or Esc to dismiss`, width, theme)
+        ].map(line => truncateToWidth(line, width, ''));
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { AutocompleteProvider } from '@earendil-works/pi-tui';
+export interface SkillEntry {
+    name: string;
+    description: string;
+}
+/** Rewrites a leading `$name` of a loaded skill into `/skill:name`. Anything else passes through, so `$5` stays text. */
+export declare function expandSkillInvocation(text: string, skills: ReadonlySet<string>): string;
+/** Offers the loaded skills at a `$` that starts a word. Every other completion is `base`'s. */
+export declare function skillCompletions(base: AutocompleteProvider, skills: () => readonly SkillEntry[]): AutocompleteProvider;

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

@@ -0,0 +1,43 @@
+/** Rewrites a leading `$name` of a loaded skill into `/skill:name`. Anything else passes through, so `$5` stays text. */
+export function expandSkillInvocation(text, skills) {
+    const trimmed = text.trimStart();
+    const match = /^\$(\S+)(?=\s|$)/.exec(trimmed);
+    if (!match || !skills.has(match[1]))
+        return text;
+    return `/skill:${match[1]}${trimmed.slice(match[0].length)}`;
+}
+/** A `$` that starts a word, and the partial name after it, at the cursor. */
+const SKILL_TOKEN = /(?:^|\s)\$([^\s$]*)$/;
+/** A line whose first word is a skill invocation. */
+const SKILL_LINE = /^\s*\$\S/;
+/** Offers the loaded skills at a `$` that starts a word. Every other completion is `base`'s. */
+export function skillCompletions(base, skills) {
+    return {
+        triggerCharacters: [...(base.triggerCharacters ?? []), '$'],
+        async getSuggestions(lines, cursorLine, cursorCol, options) {
+            const line = lines[cursorLine] ?? '';
+            const token = SKILL_TOKEN.exec(line.slice(0, cursorCol));
+            if (token) {
+                const partial = token[1];
+                const items = skills()
+                    .filter((skill) => skill.name.startsWith(partial))
+                    .map((skill) => ({ value: skill.name, label: `$${skill.name}`, description: skill.description }));
+                return items.length ? { items, prefix: `$${partial}` } : null;
+            }
+            // The arguments of a line that starts with a skill invocation are free text, not file paths.
+            if (SKILL_LINE.test(line))
+                return null;
+            return base.getSuggestions(lines, cursorLine, cursorCol, options);
+        },
+        applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+            if (!prefix.startsWith('$'))
+                return base.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+            const line = lines[cursorLine] ?? '';
+            const start = cursorCol - prefix.length;
+            const inserted = `$${item.value} `;
+            const newLines = [...lines];
+            newLines[cursorLine] = `${line.slice(0, start)}${inserted}${line.slice(cursorCol)}`;
+            return { lines: newLines, cursorLine, cursorCol: start + inserted.length };
+        }
+    };
+}

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

@@ -0,0 +1,18 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+export interface BandState {
+    cwd: string;
+    model?: {
+        name: string;
+        reasoning: boolean;
+        contextWindow: number;
+    };
+    thinkingLevel: string;
+    branch: string | null;
+    account?: string;
+    inputTokens: number;
+    outputTokens: number;
+}
+export declare function singleLine(text: string): string;
+export declare function displayProjectName(cwd: string): string;
+export declare function formatTokenCount(value: number): string;
+export declare function renderStatusBand(state: BandState, width: number, theme: Theme): string;

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

@@ -0,0 +1,67 @@
+// Presentation adapted from Oh My Pi 18.11.3's status line; it sits in the footer below the prompt frame.
+// Upstream MIT license and evidence are recorded in NOTICE.md and docs/terminal-tui.md.
+import { basename, sep } from 'node:path';
+import { parseColor, stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { TITANIUM } from "./theme.js";
+// OMP's shipped light theme supplies status colors separately from transcript colors.
+const LIGHT_STATUS = {
+    ...TITANIUM, darkTitanium: '#e0e0e0', electricBlue: '#875f87', subtleGray: '#808080',
+    brightAluminum: '#005f87', readoutGreen: '#005f00', titaniumGold: '#005f5f'
+};
+const palette = (theme) => theme.appearance === 'light' ? LIGHT_STATUS : TITANIUM;
+export function singleLine(text) {
+    return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f-\x9f]/g, ' ').replace(/ +/g, ' ').trim();
+}
+export function displayProjectName(cwd) {
+    return singleLine(basename(cwd) || cwd || sep);
+}
+export function formatTokenCount(value) {
+    const count = Math.max(0, Number.isFinite(value) ? Math.floor(value) : 0);
+    if (count >= 1_000_000_000)
+        return `${Math.floor(count / 1_000_000_000)}B`;
+    if (count >= 1_000_000)
+        return `${Math.floor(count / 1_000_000)}M`;
+    if (count >= 1_000)
+        return `${Math.floor(count / 1_000)}K`;
+    return count.toLocaleString('en-US');
+}
+function fitParts(parts, width) {
+    const fitted = parts.map(part => ({ ...part }));
+    const separator = ' | ';
+    const plain = () => fitted.map(part => part.text).join(separator);
+    while (fitted.length > 1 && visibleWidth(plain()) > width) {
+        const last = fitted[fitted.length - 1];
+        const otherWidth = visibleWidth(plain()) - visibleWidth(separator) - visibleWidth(last.text);
+        const available = width - otherWidth - visibleWidth(separator);
+        if (available > 0 && available < visibleWidth(last.text)) {
+            last.text = truncateToWidth(last.text, available, '', false);
+            if (visibleWidth(plain()) <= width)
+                return fitted;
+        }
+        fitted.pop();
+    }
+    if (fitted.length && visibleWidth(plain()) > width) {
+        fitted[0].text = truncateToWidth(fitted[0].text, width, '', false);
+    }
+    return fitted;
+}
+function color(theme, hex, text) {
+    return theme.style(text, { fg: parseColor(hex) });
+}
+export function renderStatusBand(state, width, theme) {
+    const size = Math.max(0, Math.floor(width));
+    if (!size)
+        return '';
+    const colors = palette(theme);
+    const model = state.model ? singleLine(state.model.name).replace(/^Claude /, '') || 'no-model' : 'no-model';
+    const account = singleLine(state.account ?? '') || 'account unknown';
+    const effort = singleLine(state.thinkingLevel) || 'off';
+    const parts = fitParts([
+        { text: displayProjectName(state.cwd), color: colors.brightAluminum },
+        { text: singleLine(state.branch ?? '') || '—', color: colors.readoutGreen },
+        { text: `${account} · ${model} · ${effort}`, color: colors.electricBlue },
+        { text: `↑ ${formatTokenCount(state.inputTokens)} ↓ ${formatTokenCount(state.outputTokens)}`, color: colors.titaniumGold }
+    ], size);
+    const separator = color(theme, colors.subtleGray, ' | ');
+    return parts.map(part => color(theme, part.color, part.text)).join(separator);
+}