@xingular/harness 0.1.7 → 1.1.1

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

@@ -0,0 +1,114 @@
+import { type AgentSession, type AgentSessionEventListener, type AgentSessionRuntime, type AgentSessionServices, type ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import type { SessionAccount } from "../accountsMenu.js";
+import type { QuestionAnswer } from "../../sessions/registry.js";
+import type { TerminalQuestion } from "./questions.js";
+import { type ComposerMode } from "./modeChoices.js";
+export interface TerminalArguments {
+    appendSystemPrompt: string[];
+    extensions: string[];
+    skills: string[];
+    prompts: string[];
+    themes: string[];
+    sessionDir: string;
+    session?: string;
+    model?: string;
+}
+/** The launch specification comes from Terminals.prepare(), never from Pi's own discovery. */
+export declare function parseTerminalArguments(args: string[]): TerminalArguments;
+export interface TerminalRuntimeHost {
+    ui: ExtensionUIContext;
+    shutdown(): void;
+    notify(message: string): void;
+    changed(): void;
+    resources?(services: AgentSessionServices): void;
+}
+type SessionChangeListener = (session: AgentSession) => void | Promise<void>;
+type NewOptions = Parameters<AgentSessionRuntime['newSession']>[0];
+type SwitchOptions = Parameters<AgentSessionRuntime['switchSession']>[1];
+type ForkOptions = Parameters<AgentSessionRuntime['fork']>[1];
+type TreeOptions = Parameters<AgentSession['navigateTree']>[1];
+export interface TerminalSnapshot {
+    readonly sessionId: string;
+    readonly sessionFile?: string;
+    readonly name?: string;
+    readonly cwd: string;
+    readonly account: Readonly<SessionAccount> | null;
+    readonly model?: Readonly<{
+        id: string;
+        provider: string;
+        name: string;
+        reasoning: boolean;
+        contextWindow: number;
+    }>;
+    readonly thinkingLevel: AgentSession['thinkingLevel'];
+    readonly isStreaming: boolean;
+    readonly idle: boolean;
+    readonly hasUserMessages: boolean;
+    readonly hideThinking: boolean;
+    readonly context: Readonly<{
+        percent: number | null;
+        window: number;
+    }>;
+    readonly costUsd: number;
+    readonly subscription: boolean;
+    readonly queue: Readonly<{
+        steering: readonly string[];
+        followUp: readonly string[];
+    }>;
+}
+export interface TerminalDecision extends TerminalQuestion {
+    type: 'approval' | 'question';
+    target?: string;
+    action?: string;
+    rememberable?: boolean;
+}
+export interface TerminalPermissionState {
+    readonly full: boolean;
+    readonly globalTools: readonly string[];
+}
+/** An image the user attached to a prompt, as Pi sends it to the model. */
+export interface TerminalImage {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+export interface TerminalRuntime {
+    pending(): Promise<TerminalDecision[]>;
+    approve(requestId: string, decision: 'approved' | 'denied', alwaysAllowTool?: boolean): Promise<void>;
+    permissions(): Promise<TerminalPermissionState>;
+    setFullPermission(enabled: boolean): Promise<void>;
+    setGlobalTool(tool: string, allowed: boolean): Promise<void>;
+    answer(requestId: string, answer: QuestionAnswer): Promise<void>;
+    answerBatch(batchId: string, answers: Array<{
+        questionId: string;
+        answer: QuestionAnswer;
+    }>): Promise<void>;
+    snapshot(): TerminalSnapshot;
+    /** Images go to the model in the same user message as `text`. */
+    submit(text: string, followUp?: boolean, images?: TerminalImage[]): Promise<void>;
+    submitPlan(text: string, images?: TerminalImage[]): Promise<void>;
+    /** The composer's mode. Its saved model and effort apply now, or when a running turn settles. */
+    setMode(mode: ComposerMode): Promise<void>;
+    readonly session: AgentSession;
+    readonly services: AgentSessionServices;
+    readonly cwd: string;
+    readonly sessionDirectory: string;
+    subscribe(listener: AgentSessionEventListener): () => void;
+    onSessionChange(listener: SessionChangeListener): () => void;
+    onBeforeSessionChange(listener: () => void): () => void;
+    newSession(options?: NewOptions): ReturnType<AgentSessionRuntime['newSession']>;
+    switchSession(path: string, options?: SwitchOptions): ReturnType<AgentSessionRuntime['switchSession']>;
+    fork(entryId: string, options?: ForkOptions): ReturnType<AgentSessionRuntime['fork']>;
+    navigateTree(targetId: string, options?: TreeOptions): ReturnType<AgentSession['navigateTree']>;
+    importFromJsonl(path: string, cwdOverride?: string): ReturnType<AgentSessionRuntime['importFromJsonl']>;
+    installationDeviceId(): Promise<string>;
+    reload(): Promise<void>;
+    interrupt(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Saved native history stays in the prepared project folder, including symlink targets. */
+export declare function assertTerminalHistoryPath(path: string, sessionDirectory: string): void;
+/** Inspect the header before any native switch/import can invalidate a session or copy a file. */
+export declare function assertTerminalSessionScope(path: string, cwd: string, cwdOverride?: string): void;
+export declare function createTerminalRuntime(args: string[], host: TerminalRuntimeHost): Promise<TerminalRuntime>;
+export {};

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

@@ -0,0 +1,443 @@
+import { createAgentSession, createAgentSessionRuntime, DefaultResourceLoader, ModelRuntime, resolveCliModel, SessionManager, SettingsManager } from '@earendil-works/pi-coding-agent';
+import { closeSync, existsSync, openSync, readSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import terminalExtension from "../piExtension.js";
+import { normalModeTools, planModeTools, QUESTION_TOOL_NAMES } from "./planMode.js";
+import { claimTerminalControl, controlCall } from "../control.js";
+import { loadPiAdapter } from "./piAdapter.js";
+import { loadPi } from "../../pi/runtime.js";
+import { sessionUiContext } from "./sessionUi.js";
+import { ModeChoices } from "./modeChoices.js";
+/** The launch specification comes from Terminals.prepare(), never from Pi's own discovery. */
+export function parseTerminalArguments(args) {
+    const result = { appendSystemPrompt: [], extensions: [], skills: [], prompts: [], themes: [], sessionDir: '' };
+    const lists = {
+        '--append-system-prompt': result.appendSystemPrompt, '--extension': result.extensions,
+        '--skill': result.skills, '--prompt-template': result.prompts, '--theme': result.themes
+    };
+    const flags = new Set(['--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes']);
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (flags.has(argument))
+            continue;
+        if (!(argument in lists) && !['--session-dir', '--session', '--model'].includes(argument)) {
+            throw new Error(`Unsupported prepared terminal argument: ${argument}`);
+        }
+        const value = args[++index];
+        if (!value || value.startsWith('--'))
+            throw new Error(`${argument} needs a value.`);
+        if (argument in lists)
+            lists[argument].push(value);
+        else if (argument === '--session-dir')
+            result.sessionDir = value;
+        else if (argument === '--session')
+            result.session = value;
+        else
+            result.model = value;
+    }
+    if (!result.sessionDir)
+        throw new Error('The Harness terminal requires its prepared --session-dir.');
+    if (!result.extensions.length)
+        throw new Error('The Harness terminal requires its prepared bridge extension.');
+    return result;
+}
+/** Saved native history stays in the prepared project folder, including symlink targets. */
+export function assertTerminalHistoryPath(path, sessionDirectory) {
+    const within = relative(realpathSync(sessionDirectory), realpathSync(path));
+    if (!within || within === '..' || within.startsWith(`..${sep}`) || isAbsolute(within)) {
+        throw new Error('Resume only from this terminal history folder. Use /import for another native session file in this working folder.');
+    }
+}
+/** Inspect the header before any native switch/import can invalidate a session or copy a file. */
+export function assertTerminalSessionScope(path, cwd, cwdOverride) {
+    if (cwdOverride !== undefined && realpathSync(resolve(cwdOverride)) !== realpathSync(cwd)) {
+        throw new Error('Resume this conversation in a terminal opened for its own working folder.');
+    }
+    const descriptor = openSync(path, 'r');
+    let first;
+    try {
+        const buffer = Buffer.alloc(65_536);
+        const size = readSync(descriptor, buffer, 0, buffer.length, 0);
+        const text = buffer.subarray(0, size).toString('utf8').replace(/^\uFEFF/, '');
+        const newline = text.indexOf('\n');
+        if (newline === -1 && size === buffer.length)
+            throw new Error('The native session header is too large.');
+        first = newline === -1 ? text : text.slice(0, newline);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    let header;
+    try {
+        header = JSON.parse(first);
+    }
+    catch {
+        throw new Error('This file does not have a readable native session header.');
+    }
+    if (header.type !== 'session' || !header.cwd || !isAbsolute(header.cwd)) {
+        throw new Error('The native session must record its original absolute working folder.');
+    }
+    if (realpathSync(header.cwd) !== realpathSync(cwd)) {
+        throw new Error('This conversation belongs to another working folder. Open its terminal to keep project permissions and context isolated.');
+    }
+}
+export async function createTerminalRuntime(args, host) {
+    const prepared = parseTerminalArguments(args);
+    const cwd = realpathSync(process.cwd());
+    const agentDirValue = process.env.PI_CODING_AGENT_DIR;
+    if (!agentDirValue || !isAbsolute(agentDirValue))
+        throw new Error('The Harness terminal requires its isolated account directory.');
+    const agentDir = realpathSync(agentDirValue);
+    const sessionDirectory = realpathSync(resolve(cwd, prepared.sessionDir));
+    // Pi writes a session file only after its first message, so a restart before that has nothing to resume.
+    const resume = prepared.session && existsSync(resolve(cwd, prepared.session)) ? resolve(cwd, prepared.session) : null;
+    if (resume) {
+        assertTerminalHistoryPath(resume, sessionDirectory);
+        assertTerminalSessionScope(resume, cwd);
+    }
+    await loadPi();
+    // Claim before loading any plugin code and retain it in the trusted process across reloads.
+    await claimTerminalControl();
+    const identity = await controlCall('accounts.session').catch(() => null);
+    const account = identity && typeof identity.accountId === 'string' && typeof identity.label === 'string'
+        ? Object.freeze({ accountId: identity.accountId, label: identity.label }) : null;
+    const adapter = await loadPiAdapter();
+    const modelRuntime = await ModelRuntime.create({ authPath: join(agentDir, 'auth.json'), modelsPath: join(agentDir, 'models.json') });
+    const listeners = new Set();
+    const changes = new Set();
+    const beforeChanges = new Set();
+    let unsubscribe;
+    let changing = false;
+    let disposed = false;
+    let uiGeneration = 0;
+    let deviceIdPromise = null;
+    const installationDeviceId = () => {
+        if (!deviceIdPromise) {
+            deviceIdPromise = controlCall('accounts.deviceId').catch((error) => {
+                deviceIdPromise = null;
+                throw error;
+            });
+        }
+        return deviceIdPromise;
+    };
+    const currentUi = () => {
+        const generation = uiGeneration;
+        return sessionUiContext(host.ui, () => !disposed && generation === uiGeneration);
+    };
+    const planRun = { active: false, allowedTools: new Set() };
+    let currentMode = 'normal';
+    let pendingApply = false;
+    const choiceStore = {
+        read: () => controlCall('accounts.choices.get'),
+        write: (mode, patch) => controlCall('accounts.choices.set', { mode, ...patch })
+    };
+    const modeChoices = new ModeChoices(choiceStore);
+    // A selection is recorded against the mode it was made in; a one-shot plan run is always plan.
+    const recordingMode = () => (planRun.active ? 'plan' : currentMode);
+    const modelFor = (reference) => resolveCliModel({ cliModel: reference, modelRuntime }).model;
+    const applyMode = () => modeChoices.apply(native.session, currentMode, modelFor);
+    const restoreChoice = async (session, previous) => {
+        if (previous.model && (session.model?.provider !== previous.model.provider || session.model?.id !== previous.model.id)) {
+            await session.setModel(previous.model, { persist: false }).catch(() => undefined);
+        }
+        session.setThinkingLevel(previous.effort, { persist: false });
+    };
+    let native;
+    const factory = async ({ cwd: targetCwd, sessionManager, sessionStartEvent }) => {
+        if (realpathSync(targetCwd) !== cwd)
+            throw new Error('A native session cannot change this terminal working folder.');
+        const settingsManager = SettingsManager.create(cwd, agentDir);
+        const resourceLoader = new DefaultResourceLoader({
+            cwd, agentDir,
+            // The real settings still control models and tools; empty discovery settings prevent a
+            // second resource decision outside the Harness's trusted prepare() result.
+            settingsManager: SettingsManager.inMemory({}),
+            noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true,
+            additionalExtensionPaths: prepared.extensions.slice(0, -1),
+            additionalSkillPaths: prepared.skills, additionalPromptTemplatePaths: prepared.prompts,
+            additionalThemePaths: prepared.themes,
+            extensionFactories: [
+                ...adapter.builtins,
+                { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun, () => native.session), hidden: true },
+                // A model picked in the terminal reaches Pi as this event. A restore is not a pick.
+                { name: 'harness-mode-choices', factory: pi => { pi.on('model_select', event => { if (event.source !== 'restore')
+                        void modeChoices.record(recordingMode(), { model: `${event.model.provider}/${event.model.id}` }); }); }, hidden: true }
+            ],
+            appendSystemPromptOverride: (base) => [...base, ...prepared.appendSystemPrompt]
+        });
+        const reloadResources = resourceLoader.reload.bind(resourceLoader);
+        resourceLoader.reload = async (options) => {
+            // Recheck the host's exact package trust and attachment identities before every load,
+            // including the reload performed internally by AgentSession.reload().
+            await controlCall('terminal.resources', {}, 30_000);
+            await reloadResources(options);
+        };
+        await resourceLoader.reload();
+        const errors = resourceLoader.getExtensions().errors;
+        if (errors.length)
+            throw new Error(errors.map((error) => `${error.path}: ${error.error}`).join('\n'));
+        let selected;
+        if (prepared.model && sessionStartEvent?.reason === 'startup') {
+            selected = resolveCliModel({ cliModel: prepared.model, modelRuntime });
+            if (selected.error || !selected.model)
+                throw new Error(selected.error ?? `Model ${prepared.model} is unavailable.`);
+        }
+        // A fresh conversation starts on this account's latest normal-mode choice. A resumed one keeps its history,
+        // and an explicit --model wins. A saved model the account cannot use is skipped.
+        const fresh = !prepared.model && (sessionStartEvent?.reason === 'new' || (sessionStartEvent?.reason === 'startup' && !resume));
+        const saved = fresh ? modeChoices.resolve('normal') : {};
+        if (fresh && saved.model) {
+            const chosen = resolveCliModel({ cliModel: saved.model, modelRuntime });
+            if (chosen.model && !chosen.error && await modelRuntime.checkAuth(chosen.model.provider))
+                selected = chosen;
+        }
+        const thinkingLevel = selected?.thinkingLevel ?? (fresh ? saved.effort : undefined);
+        const created = await createAgentSession({
+            cwd, agentDir, modelRuntime, settingsManager, resourceLoader, sessionManager, sessionStartEvent,
+            ...(selected?.model ? { model: selected.model } : {}),
+            ...(thinkingLevel ? { thinkingLevel } : {})
+        });
+        created.session.setActiveToolsByName(normalModeTools(created.session.getActiveToolNames()));
+        const services = { cwd, agentDir, modelRuntime, settingsManager, resourceLoader, diagnostics: [] };
+        host.resources?.(services);
+        return { ...created, services, diagnostics: services.diagnostics };
+    };
+    await modeChoices.load();
+    native = await createAgentSessionRuntime(factory, {
+        cwd, agentDir,
+        sessionManager: resume ? SessionManager.open(resume, sessionDirectory) : SessionManager.create(cwd, sessionDirectory),
+        sessionStartEvent: { type: 'session_start', reason: 'startup' }
+    });
+    const before = () => {
+        uiGeneration += 1;
+        unsubscribe?.();
+        unsubscribe = undefined;
+        for (const listener of beforeChanges)
+            listener();
+    };
+    const announce = async () => {
+        for (const listener of changes)
+            await listener(native.session);
+        host.changed();
+    };
+    const exclusive = async (action) => {
+        if (disposed)
+            throw new Error('The terminal runtime has closed.');
+        if (changing)
+            throw new Error('A native session change is already in progress.');
+        if (!native.session.isIdle)
+            throw new Error('Stop the current response before changing or reloading this session.');
+        changing = true;
+        try {
+            await controlCall('terminal.resources', {}, 30_000);
+            // A model or effort a switch restores belongs to the session's history, not to a choice the person made.
+            return await modeChoices.quietly(action);
+        }
+        finally {
+            changing = false;
+        }
+    };
+    const decide = async (call, params) => {
+        if (disposed)
+            throw new Error('The terminal runtime has closed.');
+        await controlCall(call, params);
+    };
+    const runtime = {
+        async pending() {
+            if (disposed)
+                return [];
+            return (await controlCall('terminal.pending')).requests;
+        },
+        approve: (requestId, decision, alwaysAllowTool = false) => decide('terminal.approve', { requestId, decision, alwaysAllow: alwaysAllowTool }),
+        async permissions() {
+            if (disposed)
+                return { full: false, globalTools: [] };
+            return controlCall('terminal.permissions.get');
+        },
+        setFullPermission: async (enabled) => { await decide('terminal.permissions.setFull', { enabled }); },
+        setGlobalTool: async (tool, allowed) => { await decide('terminal.permissions.setTool', { tool, allowed }); },
+        answer: (requestId, answer) => decide('terminal.answer', { requestId, answer }),
+        answerBatch: (batchId, answers) => decide('terminal.answers', { batchId, answers }),
+        snapshot() {
+            const session = native.session;
+            const usage = session.getContextUsage();
+            const model = session.model?.id === 'unknown' ? undefined : session.model;
+            return Object.freeze({
+                sessionId: session.sessionId, sessionFile: session.sessionFile, name: session.sessionName,
+                cwd, account,
+                model: model ? Object.freeze({ id: model.id, provider: model.provider, name: model.name, reasoning: model.reasoning, contextWindow: model.contextWindow }) : undefined,
+                thinkingLevel: session.thinkingLevel, isStreaming: session.isStreaming, idle: session.isIdle,
+                hasUserMessages: session.state.messages.some(message => message.role === 'user'),
+                hideThinking: session.settingsManager.getHideThinkingBlock(),
+                context: Object.freeze({ percent: usage?.percent ?? null, window: usage?.contextWindow ?? model?.contextWindow ?? 0 }),
+                costUsd: session.getSessionStats().cost,
+                subscription: model ? session.modelRuntime.isUsingSubscription(model.provider) : false,
+                queue: Object.freeze({ steering: Object.freeze([...session.getSteeringMessages()]), followUp: Object.freeze([...session.getFollowUpMessages()]) })
+            });
+        },
+        async submit(text, followUp = false, images) {
+            if (disposed)
+                throw new Error('The terminal runtime has closed.');
+            if (changing)
+                throw new Error('Wait for the native session change to finish before submitting.');
+            const input = text.trimStart().startsWith('/') ? text.trimStart() : text;
+            await native.session.prompt(input, {
+                ...(native.session.isStreaming ? { streamingBehavior: followUp ? 'followUp' : 'steer' } : {}),
+                ...(images?.length ? { images } : {})
+            });
+        },
+        async submitPlan(text, images) {
+            if (disposed)
+                throw new Error('The terminal runtime has closed.');
+            if (changing)
+                throw new Error('Wait for the native session change to finish before submitting.');
+            if (!text.trim())
+                throw new Error('Use /plan <plan brief>.');
+            const session = native.session;
+            if (!session.isIdle)
+                throw new Error('A plan request must wait until the current response settles.');
+            const originalTools = session.getActiveToolNames();
+            const registeredQuestions = session.getAllTools().map(tool => tool.name).filter(name => QUESTION_TOOL_NAMES.has(name));
+            const allowedTools = planModeTools(originalTools, [], registeredQuestions);
+            // The session's own model and effort come back once the plan is done.
+            const previous = { model: session.model, effort: session.thinkingLevel };
+            planRun.allowedTools = new Set(allowedTools);
+            planRun.active = true;
+            try {
+                session.setActiveToolsByName(allowedTools);
+                await modeChoices.apply(session, 'plan', modelFor);
+                await session.prompt(text, { expandPromptTemplates: false, ...(images?.length ? { images } : {}) });
+            }
+            finally {
+                planRun.active = false;
+                planRun.allowedTools = new Set();
+                if (!disposed && native.session === session) {
+                    session.setActiveToolsByName(originalTools);
+                    await modeChoices.quietly(() => restoreChoice(session, previous));
+                    if (pendingApply) {
+                        pendingApply = false;
+                        await applyMode();
+                    }
+                }
+            }
+        },
+        async setMode(mode) {
+            if (disposed)
+                throw new Error('The terminal runtime has closed.');
+            currentMode = mode;
+            // A switch during a running turn waits for it to settle, so the turn keeps the model it started with.
+            if (native.session.isIdle && !planRun.active)
+                await applyMode();
+            else
+                pendingApply = true;
+        },
+        get session() { return native.session; },
+        get services() { return native.services; },
+        cwd, sessionDirectory,
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        onSessionChange(listener) { changes.add(listener); return () => { changes.delete(listener); }; },
+        onBeforeSessionChange(listener) { beforeChanges.add(listener); return () => { beforeChanges.delete(listener); }; },
+        newSession: (options) => exclusive(async () => {
+            // Re-read the choices so a new conversation starts on what was chosen most recently.
+            await modeChoices.load();
+            return native.newSession(options);
+        }),
+        switchSession: (path, options) => exclusive(async () => {
+            const target = resolve(cwd, path);
+            assertTerminalHistoryPath(target, sessionDirectory);
+            assertTerminalSessionScope(target, cwd, options?.cwdOverride);
+            return native.switchSession(target, options);
+        }),
+        fork: (entryId, options) => exclusive(() => native.fork(entryId, options)),
+        navigateTree: (targetId, options) => exclusive(async () => {
+            const result = await native.session.navigateTree(targetId, options);
+            if (!result.cancelled)
+                await announce();
+            return result;
+        }),
+        importFromJsonl: (path, cwdOverride) => exclusive(async () => {
+            const target = resolve(cwd, path);
+            assertTerminalSessionScope(target, cwd, cwdOverride);
+            return native.importFromJsonl(target, cwdOverride);
+        }),
+        installationDeviceId,
+        reload: () => exclusive(async () => {
+            // Refuse a revoked or changed resource set before tearing down the currently usable UI.
+            await controlCall('terminal.resources', {}, 30_000);
+            await runtime.interrupt();
+            before();
+            await native.session.reload({ beforeSessionStart: async () => {
+                    native.session.extensionRunner.setUIContext(currentUi(), 'tui');
+                    observeSession();
+                    await announce();
+                } });
+            host.changed();
+        }),
+        async interrupt() {
+            // Bash executions use their own abort controllers, outside Pi's agent tool loop.
+            native.session.abortBash();
+            // Socket-backed questions and approvals must settle before Pi can finish aborting tools.
+            await controlCall('terminal.interrupt', {}, 15_000).catch(() => { });
+            await native.session.abort();
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            try {
+                await runtime.interrupt();
+                await native.dispose();
+            }
+            finally {
+                unsubscribe?.();
+                listeners.clear();
+                changes.clear();
+                beforeChanges.clear();
+            }
+        }
+    };
+    const observeSession = () => {
+        unsubscribe?.();
+        unsubscribe = native.session.subscribe(event => {
+            if (event.type === 'thinking_level_changed')
+                void modeChoices.record(recordingMode(), { effort: event.level });
+            if (event.type === 'agent_settled' && pendingApply && !planRun.active) {
+                pendingApply = false;
+                void applyMode().catch(() => undefined);
+            }
+            for (const listener of listeners)
+                listener(event);
+            host.changed();
+        });
+    };
+    const bind = async () => {
+        const session = native.session;
+        observeSession();
+        await session.bindExtensions({
+            uiContext: currentUi(), mode: 'tui', shutdownHandler: () => host.shutdown(),
+            abortHandler: () => { void runtime.interrupt().catch((error) => host.notify(error instanceof Error ? error.message : String(error))); },
+            onError: (error) => host.notify(`${error.event}: ${error.error}`),
+            commandContextActions: {
+                waitForIdle: () => native.session.waitForIdle(),
+                newSession: (options) => runtime.newSession(options),
+                switchSession: (path, options) => runtime.switchSession(path, options),
+                fork: (entryId, options) => runtime.fork(entryId, options),
+                navigateTree: (targetId, options) => runtime.navigateTree(targetId, options),
+                reload: () => runtime.reload()
+            }
+        });
+        await announce();
+        if (native.modelFallbackMessage)
+            host.notify(native.modelFallbackMessage);
+    };
+    native.setBeforeSessionInvalidate(before);
+    native.setRebindSession(bind);
+    try {
+        await bind();
+    }
+    catch (error) {
+        await runtime.dispose();
+        throw error;
+    }
+    return runtime;
+}

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

@@ -0,0 +1,22 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+export declare const SEARCH_GLYPH = "\u2315";
+export declare const SEARCH_PLACEHOLDER = "Type to search";
+export declare const SEARCH_FIELD_ROWS = 5;
+export declare function searchFieldRowsFor(availableRows: number): number;
+export declare class SearchField {
+    private readonly theme;
+    private readonly input;
+    constructor(theme: () => Theme, placeholder?: string);
+    get value(): string;
+    set focused(value: boolean);
+    /** Presets the text, for a command that was given something to search for. */
+    setValue(text: string): void;
+    /** Empties the field; says whether there was anything to empty. */
+    clear(): boolean;
+    /** Takes typed text, paste, Backspace and Ctrl+U. Says whether the text changed. */
+    handleInput(data: string): boolean;
+    invalidate(): void;
+    /** One row, `width` cells: the glyph, the text or placeholder, and `note` at the right edge. */
+    render(width: number, note?: string): string;
+    renderLines(width: number, note?: string, rows?: number): string[];
+}

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'
+    }
+};