@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,40 @@
+import type { SessionInfo, Theme } from '@earendil-works/pi-coding-agent';
+import { type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TerminalPage } from "./page.js";
+import type { TerminalMouseInput } from "./mouse.js";
+export declare function formatSessionRelativeTime(value: Date, now?: number): string;
+export declare function formatSessionSize(bytes: number | undefined): string;
+export interface ResumeSessionsPageOptions {
+    theme: () => Theme;
+    cwd(): string;
+    branch(): string | null;
+    listSessions(signal: AbortSignal): Promise<SessionInfo[]>;
+    select(path: string): void;
+    cancel(): void;
+    changed(): void;
+}
+export declare class ResumeSessionsPage implements TerminalPage {
+    private readonly options;
+    readonly presentation: "fullscreen";
+    private readonly list;
+    private loading;
+    private loaded;
+    private disposed;
+    private error;
+    private abort?;
+    constructor(options: ResumeSessionsPageOptions);
+    get focused(): boolean;
+    set focused(value: boolean);
+    tabs(): {
+        id: string;
+        title: string;
+    }[];
+    activeTab(): string;
+    hint(): string;
+    activate(): void;
+    dispose(): void;
+    private load;
+    handleInput(data: string): boolean;
+    handleMouse(event: TerminalMouseInput): TuiMouseEventResult | undefined;
+    render(width: number, rows: number): string[];
+}

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

@@ -0,0 +1,141 @@
+import { stat } from 'node:fs/promises';
+import { stripTerminalSequences } from '@earendil-works/pi-tui';
+import { displayProjectName, singleLine } from "./status.js";
+import { FilterList } from "./list.js";
+const RELATIVE_TIME = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
+const TIME_UNITS = [
+    [365 * 24 * 60 * 60 * 1000, 'year'],
+    [30 * 24 * 60 * 60 * 1000, 'month'],
+    [7 * 24 * 60 * 60 * 1000, 'week'],
+    [24 * 60 * 60 * 1000, 'day'],
+    [60 * 60 * 1000, 'hour'],
+    [60 * 1000, 'minute'],
+    [1000, 'second']
+];
+export function formatSessionRelativeTime(value, now = Date.now()) {
+    const delta = value.getTime() - now;
+    if (!Number.isFinite(delta))
+        return 'unknown time';
+    const absolute = Math.abs(delta);
+    const unit = TIME_UNITS.find(([size]) => absolute >= size);
+    return unit ? RELATIVE_TIME.format(Math.round(delta / unit[0]), unit[1]) : RELATIVE_TIME.format(0, 'second');
+}
+export function formatSessionSize(bytes) {
+    if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0)
+        return '—';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? Math.round(size) : size.toFixed(1)}${units[unit]}`;
+}
+function safe(value) {
+    return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ');
+}
+export class ResumeSessionsPage {
+    options;
+    presentation = 'fullscreen';
+    list;
+    loading = false;
+    loaded = false;
+    disposed = false;
+    error;
+    abort;
+    constructor(options) {
+        this.options = options;
+        this.list = new FilterList({
+            theme: options.theme,
+            search: 'always',
+            rowGap: 1,
+            noun: ['session', 'sessions'],
+            empty: 'No saved sessions in this project',
+            onCancel: options.cancel,
+            onActivate: row => { if (row.data)
+                options.select(row.data); }
+        });
+    }
+    get focused() { return this.list.focused; }
+    set focused(value) { this.list.focused = value; }
+    tabs() { return [{ id: 'sessions', title: 'Resume session' }]; }
+    activeTab() { return 'sessions'; }
+    hint() { return '↑/↓ select · type to search · Enter resume'; }
+    activate() {
+        if (this.loaded || this.loading || this.disposed)
+            return;
+        this.abort = new AbortController();
+        void this.load(this.abort.signal);
+    }
+    dispose() {
+        this.disposed = true;
+        this.abort?.abort();
+    }
+    async load(signal) {
+        this.loading = true;
+        this.options.changed();
+        try {
+            const sessions = await this.options.listSessions(signal);
+            const branch = singleLine(this.options.branch() ?? '') || '—';
+            const rows = await Promise.all(sessions.map(async (session) => {
+                let bytes;
+                try {
+                    bytes = (await stat(session.path)).size;
+                }
+                catch { /* A removed or unreadable file remains selectable and shows an unknown size. */ }
+                const title = session.name?.trim() || session.firstMessage.trim() || session.id;
+                const project = displayProjectName(session.cwd || this.options.cwd());
+                const modified = formatSessionRelativeTime(session.modified);
+                const subtitle = `${modified} · ${project}:${branch} · ${formatSessionSize(bytes)}`;
+                return {
+                    id: session.path,
+                    label: singleLine(title),
+                    subtitle,
+                    searchText: `${title} ${session.firstMessage} ${session.id} ${subtitle}`,
+                    data: session.path
+                };
+            }));
+            if (this.disposed || signal.aborted)
+                return;
+            this.list.setRows(rows);
+            this.error = undefined;
+        }
+        catch (error) {
+            if (!this.disposed && !signal.aborted)
+                this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.loaded = true;
+            this.loading = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    handleInput(data) {
+        if (!this.list.handleInput(data))
+            return false;
+        this.options.changed();
+        return true;
+    }
+    handleMouse(event) {
+        if (event.type === 'move')
+            return { handled: true, render: false };
+        if (event.type === 'wheel')
+            return undefined;
+        const result = this.list.handleMouse(event);
+        if (result?.render)
+            this.options.changed();
+        return result;
+    }
+    render(width, rows) {
+        if (width < 1 || rows < 1)
+            return [];
+        const theme = this.options.theme();
+        if (this.error)
+            return [theme.fg('error', `Could not read saved sessions: ${safe(this.error)}`)];
+        if (this.loading || !this.loaded)
+            return [theme.fg('dim', 'Loading saved sessions…')];
+        return this.list.render(width, rows);
+    }
+}

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,14 @@
+import type { AgentSession, ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import type { TerminalSettingItem } from "./pages/settingsPage.js";
+export interface SettingsModelHost {
+    session(): AgentSession;
+    ui: ExtensionUIContext;
+    control<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    hotkeys?(): string;
+    refresh(): void;
+}
+export declare function createSettingsModel(host: SettingsModelHost): {
+    items: () => TerminalSettingItem[];
+    apply: (id: string) => Promise<void>;
+    load: () => Promise<void>;
+};

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

@@ -0,0 +1,195 @@
+const BROWSER_BACKEND_ID = 'browser.backend';
+const BROWSER_CONNECTION_ID = 'browser.connection';
+const PRIVATE_ACCESS_ID = 'browser.allowPrivate';
+const GROUP_ORDER = ['Theme', 'Display', 'Images', 'Thinking', 'Recovery', 'Editor', 'Queues', 'Commands', 'Terminal', 'Keyboard', 'Compaction', 'Connection', 'Network'];
+export function createSettingsModel(host) {
+    let browserSettings = null;
+    let extensionSettings = null;
+    let pairingCode = null;
+    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] };
+        });
+        if (browserSettings) {
+            result.push({
+                id: BROWSER_BACKEND_ID,
+                tab: 'Browser',
+                group: 'Connection',
+                label: 'Browser backend',
+                value: browserSettings.backend === 'brave' ? 'Brave profile' : 'Isolated browser',
+                description: 'Choose the browser the agent controls. Brave uses your existing signed-in profile and only sites you allow in the extension; Incognito is excluded. The extension does not request history or cookie permissions or export cookies. A disconnect never switches to the other backend.'
+            });
+            result.push({
+                id: BROWSER_CONNECTION_ID,
+                tab: 'Browser',
+                group: 'Connection',
+                label: 'Brave extension',
+                value: extensionSettings?.state ?? 'Checking',
+                description: pairingCode
+                    ? `Enter pairing code ${pairingCode} in the extension popup. It expires in five minutes.`
+                    : extensionSettings?.state === 'connected'
+                        ? 'Connected to Brave. Use the in-page badge to pause or stop control.'
+                        : extensionSettings?.paired
+                            ? 'The extension is paired and waiting. Open its toolbar popup to reconnect, or select this row to reset pairing.'
+                            : 'Select this row to start the loopback bridge and get a one-time pairing code.'
+            });
+            result.push({
+                id: PRIVATE_ACCESS_ID,
+                tab: 'Browser',
+                group: 'Network',
+                label: 'Private address access',
+                value: browserSettings.allowPrivate ? 'On' : 'Off',
+                description: 'This device-wide setting lets agent browsing and annotation capture reach localhost and private networks.'
+            });
+        }
+        return result.sort((a, b) => GROUP_ORDER.indexOf(a.group) - GROUP_ORDER.indexOf(b.group));
+    }
+    async function load() {
+        const [config, extension] = await Promise.all([
+            host.control('terminal.browser.config'),
+            host.control('terminal.browser.extension.status')
+        ]);
+        if (!config || typeof config.allowPrivate !== 'boolean' || !['isolated', 'brave'].includes(config.backend))
+            throw new Error('The Harness returned invalid browser settings.');
+        if (!extension || typeof extension.connected !== 'boolean' || typeof extension.paired !== 'boolean' || !['stopped', 'pairing', 'waiting', 'connected', 'paused'].includes(extension.state))
+            throw new Error('The Harness returned invalid Brave extension status.');
+        browserSettings = { backend: config.backend, allowPrivate: config.allowPrivate };
+        extensionSettings = extension;
+        if (extension.paired)
+            pairingCode = null;
+    }
+    async function apply(id) {
+        if (id === BROWSER_BACKEND_ID) {
+            if (!browserSettings)
+                return;
+            const selected = await host.ui.select('Browser backend', ['Isolated browser', 'Brave profile']);
+            const backend = selected === 'Brave profile' ? 'brave' : selected === 'Isolated browser' ? 'isolated' : null;
+            if (!backend || backend === browserSettings.backend)
+                return;
+            if (backend === 'brave' && !await host.ui.confirm('Use your Brave profile?', 'The agent can see and control normal tabs on sites you explicitly allow in the extension. Your signed-in pages may contain private information. The extension requires Brave’s debugger permission but does not request history or cookie permissions or export cookies. Incognito is never available, and a disconnect will not switch browsers automatically.'))
+                return;
+            const saved = await host.control('terminal.browser.configure', { backend });
+            if (!saved || saved.backend !== backend)
+                throw new Error('The Harness did not save the browser backend.');
+            browserSettings = { ...browserSettings, backend: saved.backend };
+            extensionSettings = await host.control('terminal.browser.extension.status');
+            host.refresh();
+            return;
+        }
+        if (id === BROWSER_CONNECTION_ID) {
+            if (!extensionSettings)
+                return;
+            let start = false;
+            if (extensionSettings.paired) {
+                const action = await host.ui.select('Brave extension', ['Keep waiting', 'Stop and pair again']);
+                if (action === 'Stop and pair again') {
+                    await host.control('terminal.browser.extension.stop');
+                    extensionSettings = await host.control('terminal.browser.extension.status');
+                    start = true;
+                }
+                else if (action === 'Keep waiting') {
+                    const result = await host.control('terminal.browser.extension.start');
+                    extensionSettings = result.status;
+                    pairingCode = result.pairingCode ?? null;
+                }
+            }
+            else
+                start = true;
+            if (start) {
+                const result = await host.control('terminal.browser.extension.start');
+                extensionSettings = result.status;
+                pairingCode = result.pairingCode ?? null;
+                if (pairingCode)
+                    host.ui.notify(`Pair the Brave extension with code ${pairingCode}.`, 'info');
+            }
+            host.refresh();
+            return;
+        }
+        if (id === PRIVATE_ACCESS_ID) {
+            if (!browserSettings)
+                return;
+            const allowPrivate = !browserSettings.allowPrivate;
+            if (allowPrivate && !await host.ui.confirm('Allow private network addresses?', 'This device-wide setting lets pages opened by agent browsing and annotation capture reach localhost and private networks.'))
+                return;
+            const saved = await host.control('terminal.browser.configure', { allowPrivate });
+            if (!saved || typeof saved.allowPrivate !== 'boolean')
+                throw new Error('The Harness returned invalid browser settings.');
+            browserSettings = { ...browserSettings, allowPrivate: saved.allowPrivate };
+            host.refresh();
+            return;
+        }
+        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, load };
+}

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

@@ -0,0 +1,57 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type Component } from '@earendil-works/pi-tui';
+import type { SideQuestionContext, SideQuestionRead } from "../../sessions/sideQuestions.js";
+export type SideState = 'thinking' | 'answered' | 'failed';
+type SideQuestionStart = {
+    runId: string;
+    sessionId: string;
+    nativeSessionId: string | null;
+};
+/** Visible native history and tool activity, with hidden reasoning and image bytes omitted. */
+export declare function sideQuestionSnapshot(messages: readonly unknown[], running: boolean): string;
+export interface SideQuestionOptions {
+    context(): SideQuestionContext;
+    start(question: string, context: SideQuestionContext): Promise<SideQuestionStart>;
+    read(runId: string, afterSequence: number): Promise<SideQuestionRead>;
+    interrupt(runId: string): Promise<unknown>;
+    copyText(text: string): Promise<void>;
+    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 runId;
+    private generation;
+    private pollTimer;
+    private question;
+    private answerText;
+    private error;
+    private current;
+    private startedAt;
+    private afterSequence;
+    private answerOffset;
+    /** The answer is taller than the dock, so PageUp/PageDown browse it instead of the transcript. */
+    private overflowing;
+    private readonly answerMarkdown;
+    private readonly dock;
+    constructor(options: SideQuestionOptions);
+    get visible(): boolean;
+    get state(): SideState | undefined;
+    get answer(): string;
+    get scrollable(): boolean;
+    /** Asks one question, replacing any earlier one. Empty text dismisses. */
+    ask(question: string): Promise<void>;
+    /** Scrolls the answer while it is longer than the dock. */
+    scroll(direction: 'up' | 'down'): void;
+    /** Copies the whole side answer, including any lines outside the dock. */
+    copyAnswer(): Promise<void>;
+    /** Interrupts a running side question and removes the dock. */
+    dismiss(): Promise<void>;
+    private poll;
+    private release;
+    /** The dock: question, a scrollable answer window, and a hint for browsing or copying. */
+    private render;
+}
+export {};