@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,544 @@
+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 { withTransientRetry } from "../../pi/retryPolicy.js";
+import { GoalController } from "../../sessions/goal.js";
+import { terminalCredentialStore } from "../credentialStore.js";
+import { normalModeTools, normalToolsForBranch, planModeTools, PLAN_TOOLS_ENTRY, QUESTION_TOOL_NAMES } from "./planMode.js";
+import { claimTerminalControl, controlCall } from "../control.js";
+import { observeProviderResponses } from "../../usage/limits/capture.js";
+import { limitHeaders } from "../../usage/limits/normalize.js";
+import { loadPiAdapter } from "./piAdapter.js";
+import { loadPi } from "../../pi/runtime.js";
+import { wrapPromptLoader } from "../../commands/promptLoader.js";
+import { applyExtensionOwners } from "../../commands/extensionOwners.js";
+import { installPluginCommandRouter } from "../../commands/runtimeRouter.js";
+import { pluginCommandPrefix } from "../../plugins/commandPrefix.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.');
+    }
+}
+/**
+ * The model a conversation's own history names: the last model change, else the model that answered
+ * last. A conversation with no message yet has nothing to continue and names nothing.
+ */
+function recordedModel(branch) {
+    if (!branch.some(entry => entry.type === 'message' && (entry.message.role === 'user' || entry.message.role === 'assistant')))
+        return undefined;
+    for (let index = branch.length - 1; index >= 0; index -= 1) {
+        const entry = branch[index];
+        if (entry.type === 'model_change')
+            return { provider: entry.provider, modelId: entry.modelId };
+        // A routed virtual response names the physical model that answered it, not the selection.
+        if (entry.type === 'message' && entry.message.role === 'assistant' && entry.message.api !== 'pi-virtual') {
+            return { provider: entry.message.provider, modelId: entry.message.model };
+        }
+    }
+    return undefined;
+}
+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);
+    }
+    const pi = 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;
+    await loadPiAdapter();
+    // Credentials live in the host's store, read and refreshed under its lock (`terminalCredentialStore`).
+    const modelRuntime = await ModelRuntime.create({ credentials: terminalCredentialStore(), modelsPath: join(agentDir, 'models.json') });
+    // This process makes the model requests, so it is where response headers are seen. Only the
+    // limit-bearing headers cross the socket, and the parent throttles what it stores.
+    observeProviderResponses(modelRuntime, (provider, response) => {
+        const headers = limitHeaders(response.headers);
+        if (!Object.keys(headers).length)
+            return;
+        void controlCall('terminal.usage.headers', { provider, status: response.status, headers }).catch(() => undefined);
+    });
+    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() };
+    const goal = new GoalController();
+    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;
+    /** A model this account can use: offered by its catalogue and holding credentials. Never a request. */
+    const usableModel = async (reference) => {
+        const model = modelFor(reference);
+        return model && await modelRuntime.checkAuth(model.provider) ? model : undefined;
+    };
+    // The level Pi resolves when no mode has saved an effort: the model's own default, then the account's.
+    const defaultEffort = (session) => {
+        const model = session.model;
+        return ((model ? session.settingsManager.getModelThinkingLevel(model.provider, model.id) : undefined)
+            ?? session.settingsManager.getDefaultThinkingLevel() ?? 'medium');
+    };
+    const applyMode = () => modeChoices.apply(native.session, currentMode, modelFor, defaultEffort(native.session));
+    // Pi rebuilds the active tools from the transcript, where the last recorded set may be a plan's.
+    const restoreNormalTools = (session) => {
+        const recorded = normalToolsForBranch(session.sessionManager.getBranch());
+        session.setActiveToolsByName(normalModeTools(recorded ?? session.getActiveToolNames()));
+    };
+    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 });
+    };
+    // A conversation written on another account can name a model this one cannot use. The account's own
+    // newest choice decides then, and the conversation records it so the next resume is settled. A
+    // fallback never fails the start: whatever is wrong with the choice, Pi's own fallback remains.
+    const recoverModel = async (session) => {
+        // An explicit launch model is the host's decision for this session, and a reading that fails is no reason to change one.
+        if (prepared.model)
+            return null;
+        const recorded = recordedModel(session.sessionManager.getBranch());
+        if (!recorded)
+            return null;
+        const reference = `${recorded.provider}/${recorded.modelId}`;
+        if (await usableModel(reference).catch(() => undefined))
+            return null;
+        const applied = await modeChoices.useFallback(session, currentMode, usableModel, defaultEffort(session)).catch(() => null);
+        return applied ? { recorded: reference, ...applied } : null;
+    };
+    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 = withTransientRetry(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: [
+                { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun, () => native.session, goal), 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 },
+                // The bridge registers parent capabilities when delegation is available. Runs without
+                // delegation still need the same frozen snapshot, after the bridge has begun the run.
+                { name: 'harness-run-capabilities', factory: pi => {
+                        pi.on('before_agent_start', async () => {
+                            if (!pi.getAllTools().some(tool => tool.name === 'spawn_subagent')) {
+                                const snapshot = await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), plan: planRun.active });
+                                if (Array.isArray(snapshot.connectors))
+                                    planRun.connectors = snapshot.connectors;
+                            }
+                        });
+                    }, hidden: true }
+            ],
+            appendSystemPromptOverride: (base) => [...base, ...prepared.appendSystemPrompt]
+        });
+        let resourceOwners = [];
+        const barePrompts = new Set();
+        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().
+            const selected = await controlCall('terminal.resources', {}, 30_000);
+            resourceOwners = selected.resourceOwners ?? [];
+            await reloadResources(options);
+            applyExtensionOwners(resourceLoader, resourceOwners);
+            await wrapPromptLoader(pi, resourceLoader, resourceOwners, prepared.prompts, cwd, agentDir, () => (native?.session?.extensionRunner.getRegisteredCommands() ?? []).map(command => {
+                const source = command.sourceInfo;
+                return { prefix: pluginCommandPrefix(source), name: command.name, owner: source.origin === 'package' ? `package:${source.baseDir ?? source.source}` : `extension:${source.path}`, path: source.path };
+            }), barePrompts);
+        };
+        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 } : {})
+        });
+        installPluginCommandRouter(created.session, resourceOwners, barePrompts);
+        restoreNormalTools(created.session);
+        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.sessionManager.appendCustomEntry(PLAN_TOOLS_ENTRY, { phase: 'begin', normal: originalTools });
+                session.setActiveToolsByName(allowedTools);
+                await modeChoices.apply(session, 'plan', modelFor, defaultEffort(session));
+                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);
+                    session.sessionManager.appendCustomEntry(PLAN_TOOLS_ENTRY, { phase: 'end' });
+                    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 && !planRun.active)
+                restoreNormalTools(native.session);
+            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();
+        }),
+        goal,
+        async interrupt() {
+            // The person stopping a running goal pauses it, as in Codex; /goal resume continues.
+            if (goal.active() && !native.session.isIdle)
+                goal.pause();
+            // 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()
+            }
+        });
+        const recovered = await recoverModel(session);
+        await announce();
+        if (recovered) {
+            const effort = recovered.effort ? ` at ${recovered.effort} effort` : '';
+            host.notify(`This account cannot use ${recovered.recorded}. Started on ${recovered.reference}${effort}, your latest choice on this account.`);
+        }
+        else 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,61 @@
+import { matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { MouseSafeInput } from "./mouseReport.js";
+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 MouseSafeInput({ 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'
+    }
+};