@turri-dev/cli 0.1.16 → 0.1.17-next.63f454c

package/dist/ask.d.ts

@@ -46,6 +46,8 @@ export declare const DONE_OPTION = "Done \u2014 that's all of them";
 export declare const TICKED = "\u2611";
 export declare const UNTICKED = "\u2610";
 export declare const DISMISSED = "The user dismissed the question without answering.";
+/** ctrl+c at a question: the person would not answer it - or stopped the turn that asked it. */
+export declare const DECLINED = "The user declined to answer the question.";
 /** How an answer that is no answer starts: the person chose to talk about the question first. */
 export declare const CHAT_PREFIX = "The user has not answered this question yet: they chose to talk about it first.";
 /** What comes back when the person chose "Chat about this": what they said, and what they had picked so far. */

package/dist/ask.js

@@ -13,6 +13,8 @@ export const DONE_OPTION = "Done — that's all of them";
 export const TICKED = "☑";
 export const UNTICKED = "☐";
 export const DISMISSED = "The user dismissed the question without answering.";
+/** ctrl+c at a question: the person would not answer it - or stopped the turn that asked it. */
+export const DECLINED = "The user declined to answer the question.";
 /** How an answer that is no answer starts: the person chose to talk about the question first. */
 export const CHAT_PREFIX = "The user has not answered this question yet: they chose to talk about it first.";
 /** What comes back when the person chose "Chat about this": what they said, and what they had picked so far. */

package/dist/chat-commands.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ChatInfo, type TurriCore } from "./chats.ts";
+/**
+ * The terminal's chats, for the person: `/chat` - new, close, a number, or a pick - its keys, and the strip above the
+ * editor naming each chat with what it is doing.
+ */
+/** A fresh chat. */
+export declare const NEW_CHAT_KEY = "alt+n";
+/** The chat shown, closed. */
+export declare const CLOSE_CHAT_KEY = "alt+w";
+/**
+ * On a Mac, alt is Option, which types ¡ and ñ unless the terminal sends it as Meta: said once a session, as the second
+ * chat opens - when the keys are first worth having.
+ */
+export declare const OPTION_AS_META: string;
+/** Said once a session, as its second chat opens, on a Mac. */
+export declare function tellOfOptionOnce(session: TurriCore, platform?: NodeJS.Platform): void;
+/** What a chat's mark in the strip and the picker says it is doing. */
+export declare function chatMark(chat: ChatInfo, now?: number): string;
+/** The strip: each chat by its number, its title and its mark - the one shown set apart - on one line, a rule between them. */
+export declare function chatStrip(chats: ChatInfo[], width: number, style: {
+    shown: (text: string) => string;
+    muted: (text: string) => string;
+}, now?: number): string[];
+export declare function registerChats(pi: ExtensionAPI, session: TurriCore): void;

package/dist/chat-commands.js

@@ -0,0 +1,162 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { MAX_CHATS } from "./chats.js";
+import { spinner } from "./regenerate/job-panel.js";
+/**
+ * The terminal's chats, for the person: `/chat` - new, close, a number, or a pick - its keys, and the strip above the
+ * editor naming each chat with what it is doing.
+ */
+/** A fresh chat. */
+export const NEW_CHAT_KEY = "alt+n";
+/** The chat shown, closed. */
+export const CLOSE_CHAT_KEY = "alt+w";
+/** alt+1 … alt+9: that chat, shown. */
+const SHOW_KEYS = Array.from({ length: MAX_CHATS }, (_, index) => `alt+${index + 1}`);
+const STRIP_WIDGET = "turri-chats";
+/**
+ * On a Mac, alt is Option, which types ¡ and ñ unless the terminal sends it as Meta: said once a session, as the second
+ * chat opens - when the keys are first worth having.
+ */
+export const OPTION_AS_META = "Chats: ⌥1…⌥9 switch, ⌥N opens one, ⌥W closes the one shown - on macOS only once your terminal sends Option as Meta: " +
+    "Ghostty, macos-option-as-alt = true; iTerm2, Profiles → Keys → Left Option key: Esc+; Terminal.app, Profiles → Keyboard → " +
+    "Use Option as Meta key; Kitty, macos_option_as_alt yes. /chat works without it.";
+/** The sessions told already. */
+const toldOfOption = new WeakSet();
+/** Said once a session, as its second chat opens, on a Mac. */
+export function tellOfOptionOnce(session, platform = process.platform) {
+    if (platform !== "darwin" || toldOfOption.has(session))
+        return;
+    toldOfOption.add(session);
+    const stop = session.onChats(() => {
+        if (session.chats().length < 2)
+            return;
+        stop();
+        // Once the new chat is on the screen: said there.
+        setTimeout(() => session.notify(OPTION_AS_META, "info"), 0);
+    });
+}
+/** What a chat's mark in the strip and the picker says it is doing. */
+export function chatMark(chat, now = Date.now()) {
+    switch (chat.status) {
+        case "working":
+            return spinner(now);
+        case "question":
+            return "?";
+        case "unread":
+            return "•";
+        default:
+            return " ";
+    }
+}
+/** Between two chats in the strip. */
+const STRIP_DELIMITER = " │ ";
+/** The strip: each chat by its number, its title and its mark - the one shown set apart - on one line, a rule between them. */
+export function chatStrip(chats, width, style, now = Date.now()) {
+    if (chats.length < 2)
+        return [];
+    const room = Math.max(8, Math.floor((width - 2) / chats.length) - STRIP_DELIMITER.length - 4);
+    const parts = chats.map((chat, index) => {
+        const mark = chatMark(chat, now).trim();
+        const label = `${index + 1} ${truncateToWidth(chat.title, room, "…")}${mark !== "" ? ` ${mark}` : ""}`;
+        return chat.shown ? style.shown(label) : style.muted(label);
+    });
+    return [truncateToWidth(` ${parts.join(style.muted(STRIP_DELIMITER))}`, width, "…")];
+}
+const label = (chat, index) => `${index + 1}  ${chatMark(chat)} ${chat.title}${chat.shown ? "  (shown)" : ""}`;
+/** What the person asked of the chats, done once pi has finished with the command or key that asked it. */
+function later(ctx, session, work) {
+    setTimeout(() => {
+        work().catch((error) => {
+            try {
+                ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+            }
+            catch {
+                session.notify(error instanceof Error ? error.message : String(error), "warning");
+            }
+        });
+    }, 0);
+}
+/** The chat `which` names - its number, or the shown one when none - or why there is none. */
+function chatNamed(session, which) {
+    const chats = session.chats();
+    if (which === "")
+        return chats.find((chat) => chat.shown) ?? "No chat is shown.";
+    const number = Number.parseInt(which, 10);
+    const chat = Number.isInteger(number) ? chats[number - 1] : undefined;
+    return chat ?? `There is no chat ${which}: ${chats.length === 1 ? "there is one" : `there are ${chats.length}`}.`;
+}
+function closeChat(ctx, session, which) {
+    const chat = chatNamed(session, which);
+    if (typeof chat === "string")
+        return ctx.ui.notify(chat, "warning");
+    if (session.chats().length === 1)
+        return ctx.ui.notify("This is the only chat - /quit leaves turri.", "info");
+    later(ctx, session, () => session.close(chat.id));
+}
+function showChat(ctx, session, which) {
+    const chat = chatNamed(session, which);
+    if (typeof chat === "string")
+        return ctx.ui.notify(chat, "warning");
+    later(ctx, session, () => session.show(chat.id));
+}
+export function registerChats(pi, session) {
+    tellOfOptionOnce(session);
+    pi.registerCommand("chat", {
+        description: `Chats beside this one, each working while another is shown: /chat [new | close [n] | n] - ${NEW_CHAT_KEY} a new one, alt+1…9 to switch, ${CLOSE_CHAT_KEY} to close${process.platform === "darwin" ? " (alt is ⌥, once the terminal sends Option as Meta)" : ""}`,
+        getArgumentCompletions: (prefix) => {
+            const items = ["new", "close", ...session.chats().map((_, index) => `${index + 1}`)].filter((item) => item.startsWith(prefix)).map((item) => ({ value: item, label: item }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const [verb = "", rest = ""] = args.trim().split(/\s+(.*)/s);
+            if (verb === "new")
+                return later(ctx, session, () => session.open());
+            if (verb === "close")
+                return closeChat(ctx, session, rest.trim());
+            if (verb !== "")
+                return showChat(ctx, session, verb);
+            const chats = session.chats();
+            const fresh = `New chat  (${NEW_CHAT_KEY})`;
+            const picked = await ctx.ui.select(`Chats - ${chats.length} of ${MAX_CHATS}`, [...chats.map(label), ...(chats.length < MAX_CHATS ? [fresh] : [])]);
+            if (picked === undefined)
+                return;
+            if (picked === fresh)
+                return later(ctx, session, () => session.open());
+            const chosen = chats.find((chat, index) => label(chat, index) === picked);
+            if (chosen !== undefined)
+                later(ctx, session, () => session.show(chosen.id));
+        },
+    });
+    pi.registerShortcut(NEW_CHAT_KEY, {
+        description: "A new chat beside this one",
+        handler: async (ctx) => later(ctx, session, () => session.open()),
+    });
+    pi.registerShortcut(CLOSE_CHAT_KEY, {
+        description: "Close this chat",
+        handler: async (ctx) => closeChat(ctx, session, ""),
+    });
+    SHOW_KEYS.forEach((key, index) => pi.registerShortcut(key, {
+        description: `Show chat ${index + 1}`,
+        handler: async (ctx) => showChat(ctx, session, `${index + 1}`),
+    }));
+    // The strip above the editor, while there are two chats or more: drawn again as they change, and while one works.
+    pi.on("session_start", (_event, ctx) => {
+        if (!ctx.hasUI)
+            return;
+        ctx.ui.setWidget(STRIP_WIDGET, (tui, theme) => {
+            const stop = session.onChats(() => tui.requestRender());
+            const ticker = setInterval(() => {
+                if (session.chats().some((chat) => chat.status === "working"))
+                    tui.requestRender();
+            }, 250);
+            ticker.unref?.();
+            return {
+                render: (width) => chatStrip(session.chats(), width, { shown: (text) => theme.bold(theme.fg("accent", text)), muted: (text) => theme.fg("muted", text) }),
+                invalidate: () => { },
+                dispose: () => {
+                    stop();
+                    clearInterval(ticker);
+                },
+            };
+        });
+    });
+}

package/dist/chat-records.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Which chats a turri session has open, so `turri --continue` opens them all again, in their order: `.turri/chats.json`
+ * in the project, a run a turri process. A chat is pi's session file - its conversation - with the title turri shows
+ * it by; one with nothing said in it has no file, and is not recorded.
+ *
+ * Nothing piles up: a chat closed is gone from it, its session file deleted; a run's chats are kept until five newer
+ * runs have been recorded, then deleted with it. In debug mode nothing is deleted.
+ */
+export interface ChatRecord {
+    id: string;
+    title: string;
+    /** pi's session file: the chat's conversation. */
+    sessionFile: string;
+}
+export interface RunRecord {
+    run: string;
+    /** The turri process: a run whose process still runs is that turri's, and is never reopened by another. */
+    pid: number;
+    started: string;
+    chats: ChatRecord[];
+}
+/** How many runs' chats are kept: the most recent, the one `--continue` reopens, among them. */
+export declare const RUNS_KEPT = 5;
+export declare function chatsFile(project: string): string;
+/** The runs recorded here, the most recent first. */
+export declare function recordedRuns(project: string): RunRecord[];
+/**
+ * The run `--continue` reopens: the most recent whose turri has ended and that has a chat whose conversation is still
+ * there. Its chats, in their order, those still there alone.
+ */
+export declare function lastRun(project: string): RunRecord | undefined;
+/**
+ * This run's record: its chats written as they are now, in their order, and the runs past the newest RUNS_KEPT dropped
+ * with their conversations - unless `keep`, in debug mode.
+ */
+export declare function recordRun(project: string, run: RunRecord, options?: {
+    keep?: boolean;
+}): void;
+/** A run's record taken over by this one: its chats are this run's now, and it is gone. */
+export declare function adoptRun(project: string, adopted: string): void;
+/** A chat closed: out of its run's record, and its conversation deleted - unless `keep`, in debug mode. */
+export declare function forgetChat(project: string, run: string, chat: ChatRecord | undefined, options?: {
+    keep?: boolean;
+}): void;

package/dist/chat-records.js

@@ -0,0 +1,102 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** How many runs' chats are kept: the most recent, the one `--continue` reopens, among them. */
+export const RUNS_KEPT = 5;
+export function chatsFile(project) {
+    return join(project, ".turri", "chats.json");
+}
+function read(project) {
+    try {
+        const parsed = JSON.parse(readFileSync(chatsFile(project), "utf8"));
+        return { runs: Array.isArray(parsed.runs) ? parsed.runs.filter((run) => typeof run?.run === "string" && Array.isArray(run.chats)) : [] };
+    }
+    catch {
+        return { runs: [] };
+    }
+}
+function write(project, file) {
+    const path = chatsFile(project);
+    try {
+        if (file.runs.length === 0) {
+            rmSync(path, { force: true });
+            return;
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        // Whole or not at all: two turris may write it.
+        const partial = `${path}.${process.pid}.tmp`;
+        writeFileSync(partial, `${JSON.stringify(file, null, 2)}\n`);
+        renameSync(partial, path);
+    }
+    catch {
+        // A chat not recorded is not reopened; nothing else is lost.
+    }
+}
+function deleteSession(file) {
+    try {
+        rmSync(file, { force: true });
+    }
+    catch {
+        /* gone already, or not ours to delete */
+    }
+}
+function alive(pid) {
+    if (pid === process.pid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** The runs recorded here, the most recent first. */
+export function recordedRuns(project) {
+    return [...read(project).runs].sort((a, b) => b.started.localeCompare(a.started));
+}
+/**
+ * The run `--continue` reopens: the most recent whose turri has ended and that has a chat whose conversation is still
+ * there. Its chats, in their order, those still there alone.
+ */
+export function lastRun(project) {
+    for (const run of recordedRuns(project)) {
+        if (alive(run.pid))
+            continue;
+        const chats = run.chats.filter((chat) => existsSync(chat.sessionFile));
+        if (chats.length > 0)
+            return { ...run, chats };
+    }
+    return undefined;
+}
+/**
+ * This run's record: its chats written as they are now, in their order, and the runs past the newest RUNS_KEPT dropped
+ * with their conversations - unless `keep`, in debug mode.
+ */
+export function recordRun(project, run, options = {}) {
+    const file = read(project);
+    const others = file.runs.filter((other) => other.run !== run.run).sort((a, b) => b.started.localeCompare(a.started));
+    const runs = [run, ...others].filter((other) => other.chats.length > 0);
+    const kept = options.keep === true ? runs : runs.filter((other, index) => index < RUNS_KEPT || alive(other.pid));
+    if (options.keep !== true) {
+        for (const dropped of runs.filter((other) => !kept.includes(other)))
+            for (const chat of dropped.chats)
+                deleteSession(chat.sessionFile);
+    }
+    write(project, { runs: kept });
+}
+/** A run's record taken over by this one: its chats are this run's now, and it is gone. */
+export function adoptRun(project, adopted) {
+    const file = read(project);
+    write(project, { runs: file.runs.filter((run) => run.run !== adopted) });
+}
+/** A chat closed: out of its run's record, and its conversation deleted - unless `keep`, in debug mode. */
+export function forgetChat(project, run, chat, options = {}) {
+    if (chat === undefined)
+        return;
+    const file = read(project);
+    write(project, {
+        runs: file.runs.map((other) => (other.run === run ? { ...other, chats: other.chats.filter((kept) => kept.id !== chat.id) } : other)).filter((other) => other.chats.length > 0),
+    });
+    if (options.keep !== true)
+        deleteSession(chat.sessionFile);
+}

package/dist/chat-scope.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The chat a piece of work runs for: its tools, its commands, its event handlers - and what they start, a pulse
+ * queued from them among it. A turri session holds several chats (chats.ts); what each keeps for itself rides along
+ * with its work here: its id, which pulses and the ledger's events carry, and the stack it chose.
+ */
+export interface ChatScope {
+    id: string;
+    /** The stack this chat chose with /stack or the stack tool - none: the project's config alone. */
+    stack: string | undefined;
+}
+/** The chat this code runs for - undefined outside every chat: the command line, a test. */
+export declare function currentChat(): ChatScope | undefined;
+/** Run `work` for `chat`: what it starts, and what that starts, is the chat's. */
+export declare function inChat<T>(chat: ChatScope, work: () => T): T;

package/dist/chat-scope.js

@@ -0,0 +1,15 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * One store for the whole process. pi loads an extension through its own module loader when it is given a path rather
+ * than a factory - an older turri installed into every pi - and that copy of this module must find the same chat.
+ */
+const STORE = Symbol.for("turri.chat-scope");
+const scope = (globalThis[STORE] ??= new AsyncLocalStorage());
+/** The chat this code runs for - undefined outside every chat: the command line, a test. */
+export function currentChat() {
+    return scope.getStore();
+}
+/** Run `work` for `chat`: what it starts, and what that starts, is the chat's. */
+export function inChat(chat, work) {
+    return scope.run(chat, work);
+}

package/dist/chat-terminal.d.ts

@@ -0,0 +1,23 @@
+import type { RunRecord } from "./chat-records.ts";
+import { type Stoppable, type TurriCore } from "./chats.ts";
+/** What ctrl+c reaches of pi's screen: the chat shown, its editor, and leaving. */
+export interface CtrlCScreen {
+    session: Stoppable;
+    editor: {
+        getText(): string;
+    };
+    clearEditor(): void;
+    /** Its queued messages back in the editor - and, with `abort`, the turn stopped: pi's own esc. */
+    restoreQueuedMessagesToEditor(options?: {
+        abort?: boolean;
+    }): number;
+    shutdown(): Promise<void>;
+}
+/**
+ * ctrl+c, in the chat shown: what it is doing stopped, the other chats left as they are (`interruptChat`). In a chat
+ * doing nothing it clears a draft in the editor, and with none leaves turri, every chat with it.
+ */
+export declare function pressCtrlC(screen: CtrlCScreen, lastStop: number, now?: number): "stopped" | "ignored" | "cleared" | "left";
+export declare function driveTerminal(core: TurriCore, options?: {
+    restore?: RunRecord;
+}): void;

package/dist/chat-terminal.js

@@ -0,0 +1,163 @@
+import { AgentSessionRuntime, InteractiveMode, SessionManager } from "@earendil-works/pi-coding-agent";
+import { interruptChat, terminalUi } from "./chats.js";
+/**
+ * ctrl+c, in the chat shown: what it is doing stopped, the other chats left as they are (`interruptChat`). In a chat
+ * doing nothing it clears a draft in the editor, and with none leaves turri, every chat with it.
+ */
+export function pressCtrlC(screen, lastStop, now = Date.now()) {
+    return interruptChat(screen.session, {
+        lastStop,
+        now,
+        stopTurn: () => void screen.restoreQueuedMessagesToEditor({ abort: true }),
+        idle: () => {
+            if (screen.editor.getText().trim() !== "") {
+                screen.clearEditor();
+                return "cleared";
+            }
+            void screen.shutdown();
+            return "left";
+        },
+    });
+}
+export function driveTerminal(core, options = {}) {
+    let screen;
+    let runtime;
+    let real;
+    let restore = options.restore;
+    /** The screen has drawn a session: the chat it is, shown - drawing on its stand-in from now on. */
+    const bound = () => {
+        const session = runtime.session;
+        const chat = core.adopt(session, runtime._services);
+        const runner = session.extensionRunner;
+        real = runner.getUIContext();
+        const ui = terminalUi(chat, () => real, () => core.changed());
+        ui.show(real);
+        runner.setUIContext(ui.ui, runner.mode);
+        catchUp(session);
+        core.showing(chat);
+        // The run `--continue` reopens: its first chat is pi's own, the rest are opened beside it.
+        if (restore !== undefined) {
+            const saved = restore;
+            restore = undefined;
+            void core.restore(saved, { skipFirst: true });
+        }
+    };
+    /**
+     * A chat shown mid-turn: the screen draws what its session has saved, and the reply being written is not saved yet -
+     * the screen is told the turn and the reply began, and follows it from there.
+     */
+    const catchUp = (session) => {
+        if (!session.isStreaming || screen === undefined)
+            return;
+        void screen.handleEvent({ type: "agent_start" });
+        const writing = session.agent.state.streamingMessage;
+        if (writing !== undefined && writing.role === "assistant")
+            void screen.handleEvent({ type: "message_start", message: writing });
+    };
+    const prototype = InteractiveMode.prototype;
+    const rebind = prototype.rebindCurrentSession;
+    prototype.rebindCurrentSession = async function (...args) {
+        await rebind.apply(this, args);
+        screen = this;
+        runtime = this.runtimeHost;
+        bound();
+    };
+    const runtimes = AgentSessionRuntime.prototype;
+    const opening = async (open) => {
+        try {
+            await open();
+            return { cancelled: false };
+        }
+        catch (error) {
+            core.notify(error instanceof Error ? error.message : String(error), "warning");
+            return { cancelled: true };
+        }
+    };
+    // ctrl+c: pi's clears the editor and leaves on a second press; here it stops what the chat shown is doing, and leaves
+    // when it is doing nothing.
+    let lastStop = 0;
+    prototype.handleCtrlC = function () {
+        const did = pressCtrlC(this, lastStop);
+        if (did === "stopped")
+            lastStop = Date.now();
+    };
+    // /new: a fresh chat beside the others.
+    const newSession = runtimes.newSession;
+    runtimes.newSession = function (asked) {
+        if (this !== runtime || asked?.parentSession !== undefined || asked?.setup !== undefined)
+            return newSession.call(this, asked);
+        return opening(() => core.open());
+    };
+    // /resume: the saved chat, as a chat of its own - or shown, when one is open on it.
+    const switchSession = runtimes.switchSession;
+    runtimes.switchSession = function (path, asked) {
+        if (this !== runtime)
+            return switchSession.call(this, path, asked);
+        return opening(() => core.open({ sessionFile: path }));
+    };
+    // Leaving turri: every chat let go - the one shown by pi, as it always is.
+    const dispose = runtimes.dispose;
+    runtimes.dispose = async function () {
+        if (this === runtime)
+            await core.dispose({ except: runtime.session });
+        return dispose.call(this);
+    };
+    core.setDriver({
+        terminal: true,
+        async create(chat, sessionFile) {
+            if (runtime === undefined)
+                throw new Error("turri's screen is not up yet: open a chat once it is.");
+            const now = runtime;
+            const manager = now.session.sessionManager;
+            const sessionManager = sessionFile !== undefined
+                ? SessionManager.open(sessionFile, manager.getSessionDir())
+                : manager.isPersisted()
+                    ? SessionManager.create(now.cwd, manager.getSessionDir())
+                    : SessionManager.inMemory(now.cwd);
+            const made = await now.createRuntime({
+                cwd: now.cwd,
+                agentDir: now.services.agentDir,
+                sessionManager,
+                sessionStartEvent: { type: "session_start", reason: sessionFile !== undefined ? "resume" : "new", previousSessionFile: now.session.sessionFile },
+            });
+            chat.session = made.session;
+            chat.services = made.services;
+            // Up and working before it is ever shown: on its stand-in.
+            const ui = terminalUi(chat, () => real, () => core.changed());
+            await made.session.bindExtensions({ uiContext: ui.ui, mode: "tui" });
+        },
+        async show(chat, from) {
+            if (runtime === undefined || chat.session === undefined)
+                return;
+            from?.ui?.hide();
+            // pi takes the shown chat's widgets and dialogs off the screen, as it does before replacing a session - but not the
+            // overlay on it: the side panel, the session's and not the chat's, stays where it is, beside the chat or over it.
+            const tui = screen?.ui;
+            const hideOverlay = tui?.hideOverlay;
+            if (tui !== undefined)
+                tui.hideOverlay = () => { };
+            try {
+                runtime.beforeSessionInvalidate?.();
+            }
+            finally {
+                if (tui !== undefined && hideOverlay !== undefined)
+                    tui.hideOverlay = hideOverlay;
+            }
+            runtime._session = chat.session;
+            runtime._services = chat.services;
+            // The screen drawn from the chat's session, and bound to it: `bound` above.
+            await runtime.rebindSession?.(chat.session);
+        },
+        async dispose(chat) {
+            const session = chat.session;
+            if (session === undefined)
+                return;
+            try {
+                await session.abort();
+            }
+            finally {
+                session.dispose();
+            }
+        },
+    });
+}

package/dist/chat-ui.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+/**
+ * What a chat draws on, in a terminal of several chats: pi's screen while the chat is shown, and a stand-in while it is
+ * not. pi has one screen; a hidden chat goes on working - its turns, its tools, a pulse it hears of - and what it
+ * would draw must neither land on the chat shown nor be lost:
+ *
+ * - its questions - a dialog, a pick, a confirm - wait, and are asked once it is shown, one after another;
+ * - what it says in passing - a notice - is said when it is shown;
+ * - what it keeps on the screen - its widgets, statuses, the working line - is kept, and put back each time it is
+ *   shown: pi clears an extension's widgets as it shows another session;
+ * - what is typed in its editor and not sent stays its own.
+ *
+ * Everything else - the theme, how tools are drawn - is the screen's, read where it is.
+ */
+export interface ChatUi {
+    /** What the chat's extension is given as its ui, shown or not. */
+    readonly ui: ExtensionUIContext;
+    readonly shown: boolean;
+    /** Shown on `screen`: what it keeps put back, its draft in the editor, what it said told, its questions asked. */
+    show(screen: ExtensionUIContext): void;
+    /** Another chat is shown: its draft kept, what it draws from now on held back. */
+    hide(): void;
+    /** The questions waiting for it to be shown. */
+    waiting(): number;
+    /** The chat is closed: every question waiting is answered with nothing. */
+    close(): void;
+}
+export declare function createChatUi(options: {
+    /** The screen to read the theme and the like from before the chat was ever shown. */
+    screen: () => ExtensionUIContext | undefined;
+    /** Its questions waiting changed, or it was shown or hidden. */
+    onChange?: () => void;
+}): ChatUi;