@falkenslab/agent-kit 0.10.1

package/dist/tui/ink/progressView.d.ts

@@ -0,0 +1,27 @@
+import type { Mode } from "../../core/agentSpec.js";
+import { type ConsoleRenderer, type ConsoleRendererOptions } from "../consoleRenderer.js";
+import { type RenderApproval } from "./SessionView.js";
+import type { ToolPhrase } from "./toolGroup.js";
+export interface ProgressViewOptions extends Omit<ConsoleRendererOptions, "output"> {
+    /** How one of the agent's own tools counts in a folded group's summary (see `InkChatOptions.toolPhrase`). */
+    toolPhrase?: (toolName: string) => ToolPhrase | undefined;
+    /** Replaces the default preview in the approval and manual-intervention panels. */
+    renderApproval?: RenderApproval;
+    /** Shown in the status bar. */
+    mode?: Mode;
+    /** Use the plain console renderer even on a TTY. */
+    plain?: boolean;
+}
+export interface ProgressView extends ConsoleRenderer {
+    /** Removes the live area and restores the previous interaction port; await it before printing anything else. */
+    close(): Promise<void>;
+}
+/**
+ * The Ink counterpart of `createConsoleRenderer()` for one-shot ("run"-style) sessions: the
+ * same methods and the same text (so `onWrite` logs exactly what the console version
+ * would), plus a spinner with the current action, approval panels and a status bar.
+ * Checkpoints go through an Ink `InteractionPort` until `close()`.
+ *
+ * Without a TTY or with `plain`, it is `createConsoleRenderer()` with a no-op `close()`.
+ */
+export declare function createProgressView(options?: ProgressViewOptions): ProgressView;

package/dist/tui/ink/progressView.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { stdin, stdout } from "node:process";
+import { useSyncExternalStore } from "react";
+import { render, useInput } from "ink";
+import { getInteractionPort, setInteractionPort } from "../../core/interaction.js";
+import { createConsoleRenderer } from "../consoleRenderer.js";
+import { createInkInteraction } from "./inkInteraction.js";
+import { createSessionModel, liveWidth } from "./sessionModel.js";
+import { SessionView } from "./SessionView.js";
+function ProgressApp({ model, interaction, renderApproval, mode, closed }) {
+    const checkpoint = useSyncExternalStore(interaction.subscribe, interaction.getSnapshot);
+    // Only a panel reads the keyboard (and so puts stdin in raw mode, where Ctrl+C no longer
+    // raises SIGINT): there, Ctrl+C stops the checkpoint and is passed on as the SIGINT the
+    // caller's own handler expects.
+    useInput((text, key) => {
+        if (!(key.ctrl && text === "c") || !checkpoint)
+            return;
+        checkpoint.answer(checkpoint.kind === "decision" ? "q" : "");
+        process.kill(process.pid, "SIGINT");
+    }, { isActive: checkpoint !== null });
+    return _jsx(SessionView, { model: model, interaction: interaction, renderApproval: renderApproval, mode: mode, closed: closed });
+}
+/**
+ * The Ink counterpart of `createConsoleRenderer()` for one-shot ("run"-style) sessions: the
+ * same methods and the same text (so `onWrite` logs exactly what the console version
+ * would), plus a spinner with the current action, approval panels and a status bar.
+ * Checkpoints go through an Ink `InteractionPort` until `close()`.
+ *
+ * Without a TTY or with `plain`, it is `createConsoleRenderer()` with a no-op `close()`.
+ */
+export function createProgressView(options = {}) {
+    if (options.plain || !stdin.isTTY || !stdout.isTTY) {
+        const renderer = createConsoleRenderer(options);
+        return Object.assign(renderer, { close: async () => { } });
+    }
+    const model = createSessionModel({ ...options, width: () => liveWidth(stdout.columns) });
+    const interaction = createInkInteraction((text) => model.note(text));
+    const previousPort = getInteractionPort();
+    setInteractionPort(interaction.port);
+    const app = (closed) => (_jsx(ProgressApp, { model: model, interaction: interaction, renderApproval: options.renderApproval, mode: options.mode, closed: closed }));
+    const instance = render(app(false), { exitOnCtrlC: false });
+    model.startTurn();
+    let closing = null;
+    return {
+        render: model.render,
+        write: (text) => model.renderer.write(text),
+        writeLine: (text) => model.renderer.writeLine(text),
+        endLine: () => model.renderer.endLine(),
+        startTurn: () => model.startTurn(),
+        get atLineStart() {
+            return model.renderer.atLineStart;
+        },
+        close() {
+            closing ??= (async () => {
+                setInteractionPort(previousPort);
+                model.endTurn();
+                instance.rerender(app(true));
+                await new Promise((resolve) => setTimeout(resolve, 0));
+                instance.unmount();
+                await instance.waitUntilExit();
+            })();
+            return closing;
+        },
+    };
+}

package/dist/tui/ink/promptEditing.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure editing operations on the prompt's text and cursor (a UTF-16 index into `value`),
+ * so PromptInput.tsx only maps keys to them. The value may hold line breaks ("\n"): a
+ * multi-line prompt.
+ */
+export interface EditState {
+    value: string;
+    cursor: number;
+}
+export declare function insert({ value, cursor }: EditState, text: string): EditState;
+export declare function deleteBack({ value, cursor }: EditState): EditState;
+/** Ctrl+W: deletes the word before the cursor. */
+export declare function deleteWordBack({ value, cursor }: EditState): EditState;
+/** Ctrl+K: deletes from the cursor to the end of its line. */
+export declare function killToLineEnd({ value, cursor }: EditState): EditState;
+export declare const wordLeft: ({ value, cursor }: EditState) => EditState;
+export declare const wordRight: ({ value, cursor }: EditState) => EditState;
+/** Home / Ctrl+A and End / Ctrl+E act on the cursor's line. */
+export declare const toLineStart: ({ value, cursor }: EditState) => EditState;
+export declare const toLineEnd: ({ value, cursor }: EditState) => EditState;
+/** The cursor's line and column (0-based, in UTF-16 units). */
+export declare function cursorLine({ value, cursor }: EditState): {
+    line: number;
+    column: number;
+};
+/**
+ * ↑/↓ inside a multi-line prompt: the same column on the line above or below (or its end
+ * if shorter), or null on the first/last line, where the arrows go to the history instead.
+ */
+export declare function moveLine(state: EditState, direction: -1 | 1): EditState | null;
+/**
+ * Enter after a backslash, as in a shell, continues the prompt on a new line: the
+ * backslash becomes the line break. Null when there's no backslash right before the cursor.
+ */
+export declare function continueLine(state: EditState): EditState | null;
+/** Pasted blocks, shown in the prompt as a short token and expanded when it's sent. */
+export interface PasteRegistry {
+    /** Stores `text` and returns the token to insert in its place. */
+    add(text: string): string;
+    /** Adds `more` to the paste behind `token` (the same paste arriving in pieces); returns its new token. */
+    extend(token: string, more: string): string;
+    /** `value` with every token replaced by its text. */
+    expand(value: string): string;
+}
+/** Normalizes a pasted chunk's line breaks (terminals send "\r" or "\r\n"). */
+export declare function normalizePaste(text: string): string;
+/** A paste worth folding into a token: more than one line. */
+export declare function isBlockPaste(text: string): boolean;
+export declare function createPasteRegistry(): PasteRegistry;
+/**
+ * Ctrl+R: the most recent history entry containing `query`, searching back from before
+ * `from` (exclusive; history is oldest first). Returns its index, or -1.
+ */
+export declare function searchHistory(history: readonly string[], query: string, from?: number): number;

package/dist/tui/ink/promptEditing.js

@@ -0,0 +1,123 @@
+export function insert({ value, cursor }, text) {
+    return { value: value.slice(0, cursor) + text + value.slice(cursor), cursor: cursor + text.length };
+}
+export function deleteBack({ value, cursor }) {
+    if (cursor === 0)
+        return { value, cursor };
+    return { value: value.slice(0, cursor - 1) + value.slice(cursor), cursor: cursor - 1 };
+}
+const isSpace = (char) => char !== undefined && /\s/.test(char);
+/** Where the word before the cursor starts (spaces right before it skipped). */
+function wordStartBefore(value, cursor) {
+    let i = cursor;
+    while (i > 0 && isSpace(value[i - 1]))
+        i--;
+    while (i > 0 && !isSpace(value[i - 1]))
+        i--;
+    return i;
+}
+/** Where the word after the cursor ends (spaces right after it skipped). */
+function wordEndAfter(value, cursor) {
+    let i = cursor;
+    while (i < value.length && isSpace(value[i]))
+        i++;
+    while (i < value.length && !isSpace(value[i]))
+        i++;
+    return i;
+}
+/** Ctrl+W: deletes the word before the cursor. */
+export function deleteWordBack({ value, cursor }) {
+    const start = wordStartBefore(value, cursor);
+    return { value: value.slice(0, start) + value.slice(cursor), cursor: start };
+}
+/** Ctrl+K: deletes from the cursor to the end of its line. */
+export function killToLineEnd({ value, cursor }) {
+    const end = lineEnd(value, cursor);
+    return { value: value.slice(0, cursor) + value.slice(end), cursor };
+}
+export const wordLeft = ({ value, cursor }) => ({ value, cursor: wordStartBefore(value, cursor) });
+export const wordRight = ({ value, cursor }) => ({ value, cursor: wordEndAfter(value, cursor) });
+function lineStart(value, cursor) {
+    return value.lastIndexOf("\n", cursor - 1) + 1;
+}
+function lineEnd(value, cursor) {
+    const next = value.indexOf("\n", cursor);
+    return next === -1 ? value.length : next;
+}
+/** Home / Ctrl+A and End / Ctrl+E act on the cursor's line. */
+export const toLineStart = ({ value, cursor }) => ({ value, cursor: lineStart(value, cursor) });
+export const toLineEnd = ({ value, cursor }) => ({ value, cursor: lineEnd(value, cursor) });
+/** The cursor's line and column (0-based, in UTF-16 units). */
+export function cursorLine({ value, cursor }) {
+    const before = value.slice(0, cursor).split("\n");
+    return { line: before.length - 1, column: before.at(-1)?.length ?? 0 };
+}
+/**
+ * ↑/↓ inside a multi-line prompt: the same column on the line above or below (or its end
+ * if shorter), or null on the first/last line, where the arrows go to the history instead.
+ */
+export function moveLine(state, direction) {
+    const lines = state.value.split("\n");
+    const { line, column } = cursorLine(state);
+    const target = line + direction;
+    if (target < 0 || target >= lines.length)
+        return null;
+    const offset = lines.slice(0, target).reduce((sum, text) => sum + text.length + 1, 0);
+    return { value: state.value, cursor: offset + Math.min(column, lines[target].length) };
+}
+/**
+ * Enter after a backslash, as in a shell, continues the prompt on a new line: the
+ * backslash becomes the line break. Null when there's no backslash right before the cursor.
+ */
+export function continueLine(state) {
+    if (state.value[state.cursor - 1] !== "\\")
+        return null;
+    return insert(deleteBack(state), "\n");
+}
+const PASTE_TOKEN = /\[Pasted text #(\d+) \+\d+ lines?\]/g;
+function pasteToken(id, text) {
+    const extra = text.split("\n").length - 1;
+    return `[Pasted text #${id} +${extra} ${extra === 1 ? "line" : "lines"}]`;
+}
+/** Normalizes a pasted chunk's line breaks (terminals send "\r" or "\r\n"). */
+export function normalizePaste(text) {
+    return text.replace(/\r\n?/g, "\n");
+}
+/** A paste worth folding into a token: more than one line. */
+export function isBlockPaste(text) {
+    return normalizePaste(text).includes("\n");
+}
+export function createPasteRegistry() {
+    const pastes = new Map();
+    let nextId = 1;
+    return {
+        add(text) {
+            const id = nextId++;
+            pastes.set(id, text);
+            return pasteToken(id, text);
+        },
+        extend(token, more) {
+            const id = Number(/#(\d+)/.exec(token)?.[1]);
+            const text = (pastes.get(id) ?? "") + more;
+            pastes.set(id, text);
+            return pasteToken(id, text);
+        },
+        expand(value) {
+            return value.replace(PASTE_TOKEN, (token, id) => pastes.get(Number(id)) ?? token);
+        },
+    };
+}
+/**
+ * Ctrl+R: the most recent history entry containing `query`, searching back from before
+ * `from` (exclusive; history is oldest first). Returns its index, or -1.
+ */
+export function searchHistory(history, query, from = history.length) {
+    if (!query)
+        return -1;
+    const needle = query.toLowerCase();
+    for (let i = Math.min(from, history.length) - 1; i >= 0; i--) {
+        if (history[i].toLowerCase().includes(needle))
+            return i;
+    }
+    return -1;
+}

package/dist/tui/ink/runChatInk.d.ts

@@ -0,0 +1,103 @@
+import type { Options } from "@anthropic-ai/claude-agent-sdk";
+import type { Mode } from "../../core/agentSpec.js";
+import { type ModeControl } from "../../core/session.js";
+import { type ChatTuiOptions } from "../chatTui.js";
+import { type RenderApproval } from "./SessionView.js";
+import type { ToolPhrase } from "./toolGroup.js";
+import { type HeaderInfo } from "./header.js";
+export type { HeaderInfo } from "./header.js";
+export interface InkChatOptions extends ChatTuiOptions {
+    /**
+     * Title, fields and an optional logo for the top of the chat: fixed at the top in full
+     * screen, printed once at the start otherwise. Not written to the session log.
+     */
+    header?: HeaderInfo;
+    /** Replaces the default preview in the approval and manual-intervention panels. */
+    renderApproval?: RenderApproval;
+    /** Shown in the status bar. */
+    mode?: Mode;
+    /** Use the plain readline chat (`runChatTui()`) even on a TTY. */
+    plain?: boolean;
+    /**
+     * Take the whole terminal (its alternate screen): the history scrolls in its own view
+     * above a prompt pinned at the bottom (PageUp/PageDown and the wheel scroll, Ctrl+End or
+     * typing goes back to the bottom), dragging selects text and a right-click copies it,
+     * and the terminal is left cleared on exit. Off by default.
+     */
+    fullscreen?: boolean;
+    /**
+     * Show the model's predicted next prompt in the empty prompt, accepted with Tab (the SDK's
+     * `promptSuggestions`: after every turn but the first, from the parent's prompt cache).
+     * On by default; `false` turns it off.
+     */
+    promptSuggestions?: boolean;
+    /**
+     * Show the chat's state outside it (on by default): the tab title during a turn, the
+     * taskbar button's progress, and a mark on it when a turn ends while the window isn't
+     * focused (Windows Terminal). Also enables `/copy`, which copies the last reply.
+     */
+    terminalIntegration?: boolean;
+    /**
+     * How one of the agent's own tools counts in a folded group's summary, e.g.
+     * `["opened {n} page", "opened {n} pages"]`; built-in tools have their own, and any other
+     * counts as "used {n} tools".
+     */
+    toolPhrase?: (toolName: string) => ToolPhrase | undefined;
+    /**
+     * The session's mode control (`buildSessionOptions()` returns it): the status bar shows the
+     * current mode, and Shift+Tab switches between the modes it allows ("guided" and
+     * "interactive"; an autonomous session can't switch).
+     */
+    modeControl?: ModeControl;
+    /**
+     * The suggestion shown (and taken with Tab) until the first turn starts: the SDK never
+     * suggests after the first turn, so without it the prompt is empty until the second reply.
+     */
+    firstPromptSuggestion?: string;
+}
+export interface ChatInputSnapshot {
+    /** The chat loop is waiting for a line (no turn in flight). */
+    prompting: boolean;
+    history: string[];
+    commands: string[];
+    /** Lines submitted during a turn, sent in order once the loop asks for the next one. */
+    queued: string[];
+    /** The model's predicted next prompt, if any (see `InkChatOptions.promptSuggestions`). */
+    suggestion: string | null;
+    /** Project files for `@` mentions. */
+    files: string[];
+    /** The current mode, when a mode control is given. */
+    mode: Mode | null;
+    closed: boolean;
+}
+/**
+ * Hands typed lines from the React prompt to the chat loop. The prompt stays on screen
+ * during a turn, as in Claude Code: a line submitted then waits in `queued` and is the
+ * next one the loop gets.
+ */
+export declare function createChatInput(): {
+    subscribe(listener: () => void): () => void;
+    getSnapshot: () => ChatInputSnapshot;
+    /** Resolves with the next line (a queued one first), or null once the human asked to leave. */
+    next(history: string[]): Promise<string | null>;
+    submit(line: string | null): void;
+    setCommands: (commands: string[]) => void;
+    setSuggestion: (suggestion: string | null) => void;
+    setFiles: (files: string[]) => void;
+    setMode: (mode: Mode | null) => void;
+    /** Takes the last queued line back out of the queue (to edit it in the prompt), or null. */
+    unqueueLast(): string | null;
+    close: () => void;
+};
+/**
+ * The Ink counterpart of `runChatTui()`, with the same options, session log and history
+ * file: history in the scrollback, the reply streaming in place, a spinner with the
+ * current action (and a subagent's), approval panels, "/command" completion and a status
+ * bar. Checkpoints go through an Ink `InteractionPort` while the chat runs, so no second
+ * stdin reader ever competes with Ink's; the response file keeps working as always.
+ *
+ * With `fullscreen` it takes the whole terminal instead (see `InkChatOptions.fullscreen`).
+ *
+ * Without a TTY (piped, background) or with `plain`, it is `runChatTui()` unchanged.
+ */
+export declare function runChatInk(options: Options, tuiOptions?: InkChatOptions): Promise<void>;

package/dist/tui/ink/runChatInk.js

@@ -0,0 +1,298 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createWriteStream } from "node:fs";
+import { stdin, stdout } from "node:process";
+import { useSyncExternalStore } from "react";
+import { Box, render, Text, useInput } from "ink";
+import { getInteractionPort, setInteractionPort } from "../../core/interaction.js";
+import { createInputQueue } from "../../core/session.js";
+import { runQuery } from "../../core/runner.js";
+import { capHistory, loadHistory, runChatTui, saveHistory, slashCommandToken } from "../chatTui.js";
+import * as ui from "../ui.js";
+import { createInkInteraction } from "./inkInteraction.js";
+import { PromptInput } from "./PromptInput.js";
+import { createSessionModel, liveWidth } from "./sessionModel.js";
+import { SessionView } from "./SessionView.js";
+import { stripAnsi } from "./lineBuffer.js";
+import { clipboardSequence, enterFullscreen } from "./fullscreen.js";
+import { createCursorController, CursorContext } from "./terminalCursor.js";
+import { createTerminalStatus, focusFromReport } from "./terminalStatus.js";
+import { listProjectFiles } from "./fileMentions.js";
+import { headerLines } from "./header.js";
+const DEFAULT_PROMPT_LABEL = "\n> ";
+const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
+const DEFAULT_HISTORY_LIMIT = 100;
+// The prompt's frame: a border and one column of padding on each side.
+const PROMPT_FRAME_COLUMNS = 4;
+/**
+ * Hands typed lines from the React prompt to the chat loop. The prompt stays on screen
+ * during a turn, as in Claude Code: a line submitted then waits in `queued` and is the
+ * next one the loop gets.
+ */
+export function createChatInput() {
+    const listeners = new Set();
+    let snapshot = { prompting: false, history: [], commands: [], queued: [], suggestion: null, files: [], mode: null, closed: false };
+    let pending = null;
+    let exited = false;
+    function update(changes) {
+        snapshot = { ...snapshot, ...changes };
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        getSnapshot: () => snapshot,
+        /** Resolves with the next line (a queued one first), or null once the human asked to leave. */
+        next(history) {
+            if (exited)
+                return Promise.resolve(null);
+            const [first, ...rest] = snapshot.queued;
+            if (first !== undefined) {
+                update({ queued: rest, history });
+                return Promise.resolve(first);
+            }
+            update({ prompting: true, history });
+            return new Promise((resolve) => (pending = resolve));
+        },
+        submit(line) {
+            if (line === null)
+                exited = true;
+            const resolve = pending;
+            if (!resolve) {
+                // A turn is in flight: keep the line for later (an empty one means nothing).
+                if (line !== null && line.trim())
+                    update({ queued: [...snapshot.queued, line] });
+                return;
+            }
+            pending = null;
+            update({ prompting: false });
+            resolve(line);
+        },
+        setCommands: (commands) => update({ commands }),
+        setSuggestion: (suggestion) => update({ suggestion }),
+        setFiles: (files) => update({ files }),
+        setMode: (mode) => update({ mode }),
+        /** Takes the last queued line back out of the queue (to edit it in the prompt), or null. */
+        unqueueLast() {
+            const last = snapshot.queued.at(-1);
+            if (last === undefined)
+                return null;
+            update({ queued: snapshot.queued.slice(0, -1) });
+            return last;
+        },
+        close: () => update({ prompting: false, closed: true }),
+    };
+}
+function ChatApp({ model, interaction, input, promptLabel, renderApproval, mode, fullscreen, header, onFocusChange, modeControl, onInterrupt }) {
+    const chat = useSyncExternalStore(input.subscribe, input.getSnapshot);
+    const session = useSyncExternalStore(model.subscribe, model.getSnapshot);
+    const checkpoint = useSyncExternalStore(interaction.subscribe, interaction.getSnapshot);
+    // Ctrl+C stops what is running (a checkpoint, then the turn) and leaves only when idle;
+    // Esc interrupts the turn but never answers a checkpoint or leaves.
+    useInput((text, key) => {
+        const focused = focusFromReport(text);
+        if (focused !== null) {
+            onFocusChange?.(focused);
+            return;
+        }
+        if (key.ctrl && text === "o") {
+            model.toggleExpanded(); // folds or unfolds the tool groups
+            return;
+        }
+        if (key.shift && key.tab) {
+            // Shift+Tab: the next mode this session allows.
+            if (!modeControl || modeControl.switchable.length < 2) {
+                model.note(ui.dim(`(${modeControl?.mode ?? mode ?? "this"} mode can't be switched during the session)`), "notice");
+                return;
+            }
+            const next = modeControl.switchable[(modeControl.switchable.indexOf(modeControl.mode) + 1) % modeControl.switchable.length];
+            modeControl.set(next);
+            input.setMode(next);
+            return;
+        }
+        if (key.ctrl && text === "c") {
+            if (checkpoint)
+                checkpoint.answer(checkpoint.kind === "decision" ? "q" : "");
+            if (checkpoint || session.busy)
+                onInterrupt();
+            else
+                input.submit(null);
+        }
+        else if (key.escape && session.busy && !checkpoint) {
+            onInterrupt();
+        }
+    });
+    return (_jsx(SessionView, { model: model, interaction: interaction, renderApproval: renderApproval, mode: chat.mode ?? mode, modeSwitchable: (modeControl?.switchable.length ?? 0) > 1, closed: chat.closed, fullscreen: fullscreen, header: header, onCopy: fullscreen ? (text) => void stdout.write(clipboardSequence(text)) : undefined, children: _jsxs(Box, { flexDirection: "column", children: [chat.queued.map((line, index) => (_jsx(Text, { wrap: "truncate-end", children: ui.dim(`  queued: ${line}`) }, index))), _jsx(Box, { borderStyle: "round", borderColor: "gray", paddingX: 1, children: _jsx(PromptInput, { label: promptLabel.replace(/^\n+/, ""), history: chat.history, commands: chat.commands, inset: PROMPT_FRAME_COLUMNS, suggestion: chat.suggestion, onSubmit: (line) => input.submit(line), onRecallQueued: () => input.unqueueLast(), files: chat.files, onExit: () => input.submit(null) }) })] }) }));
+}
+/**
+ * The Ink counterpart of `runChatTui()`, with the same options, session log and history
+ * file: history in the scrollback, the reply streaming in place, a spinner with the
+ * current action (and a subagent's), approval panels, "/command" completion and a status
+ * bar. Checkpoints go through an Ink `InteractionPort` while the chat runs, so no second
+ * stdin reader ever competes with Ink's; the response file keeps working as always.
+ *
+ * With `fullscreen` it takes the whole terminal instead (see `InkChatOptions.fullscreen`).
+ *
+ * Without a TTY (piped, background) or with `plain`, it is `runChatTui()` unchanged.
+ */
+export async function runChatInk(options, tuiOptions = {}) {
+    if (tuiOptions.plain || !stdin.isTTY || !stdout.isTTY)
+        return await runChatTui(options, tuiOptions);
+    const exitCommands = new Set((tuiOptions.exitCommands ?? DEFAULT_EXIT_COMMANDS).map((c) => c.toLowerCase()));
+    const promptLabel = tuiOptions.promptLabel ?? DEFAULT_PROMPT_LABEL;
+    const historyLimit = tuiOptions.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+    let historyEntries = tuiOptions.historyPath ? capHistory(await loadHistory(tuiOptions.historyPath), historyLimit) : [];
+    const queue = createInputQueue();
+    const run = runQuery(queue.iterable, { ...options, promptSuggestions: tuiOptions.promptSuggestions ?? true });
+    const events = run.events[Symbol.asyncIterator]();
+    const sessionLog = tuiOptions.sessionLogPath ? createWriteStream(tuiOptions.sessionLogPath, { flags: "a" }) : null;
+    const mirror = (text) => void sessionLog?.write(stripAnsi(text));
+    const model = createSessionModel({
+        formatAction: tuiOptions.formatAction,
+        toolPhrase: tuiOptions.toolPhrase,
+        agentLabel: tuiOptions.agentLabel,
+        onWrite: mirror,
+        width: () => liveWidth(stdout.columns),
+    });
+    const interaction = createInkInteraction((text) => model.note(text));
+    const input = createChatInput();
+    if (tuiOptions.firstPromptSuggestion)
+        input.setSuggestion(tuiOptions.firstPromptSuggestion);
+    if (tuiOptions.modeControl)
+        input.setMode(tuiOptions.modeControl.mode);
+    void listProjectFiles(options.cwd ?? process.cwd()).then((files) => input.setFiles(files));
+    // Every registered command name and alias, built-ins included, for completion and for
+    // catching an unknown "/command" before it reaches the model as plain text (see chatTui.ts).
+    const knownCommands = run.supportedCommands().then((commands) => new Set(commands.flatMap((c) => [c.name, ...(c.aliases ?? [])])), () => null);
+    void knownCommands.then((names) => {
+        const exits = [...exitCommands].filter((c) => c.startsWith("/")).map((c) => c.slice(1));
+        const local = tuiOptions.terminalIntegration === false ? [] : ["copy"];
+        input.setCommands([...new Set([...(names ?? []), ...exits, ...local])].sort());
+    });
+    let turnInterrupted = false;
+    function interruptTurn() {
+        if (turnInterrupted)
+            return;
+        turnInterrupted = true;
+        void run.interrupt();
+        model.writeLine(ui.warn("(interrupted)"));
+    }
+    // One reader for the whole session instead of drainTurn()'s one per turn: the prompt
+    // suggestion arrives after its turn's turn-end, while the human is already at the prompt,
+    // and MCP errors arrive before the first turn. Still manual .next() calls, never a
+    // for-await that could be broken out of (ADR-010).
+    let turnDone = null;
+    let readError = null;
+    function finishTurn() {
+        const done = turnDone;
+        turnDone = null;
+        done?.();
+    }
+    void (async () => {
+        try {
+            while (true) {
+                const { value, done } = await events.next();
+                if (done)
+                    break;
+                if (value.type === "prompt-suggestion") {
+                    input.setSuggestion(value.suggestion);
+                    continue;
+                }
+                model.render(value);
+                if (value.type === "turn-end")
+                    finishTurn();
+            }
+        }
+        catch (error) {
+            readError = error;
+        }
+        finishTurn();
+    })();
+    async function runTurn(line) {
+        input.setSuggestion(null);
+        status?.turnStarted();
+        turnInterrupted = false;
+        model.separate();
+        model.startTurn();
+        const finished = new Promise((resolve) => (turnDone = resolve));
+        queue.push(line);
+        await finished;
+        model.endTurn();
+        status?.turnEnded();
+        void run.contextUsage().then((usage) => usage && model.setContextPercent(usage.percentage));
+        if (readError)
+            throw readError;
+    }
+    const previousPort = getInteractionPort();
+    setInteractionPort(interaction.port);
+    const restoreTerminal = tuiOptions.fullscreen ? enterFullscreen(stdout) : null;
+    const cursor = tuiOptions.fullscreen ? createCursorController(stdout) : null;
+    const status = tuiOptions.terminalIntegration === false ? null : createTerminalStatus((text) => void stdout.write(text), tuiOptions.header?.title ?? "agent");
+    status?.start();
+    const app = render(_jsx(CursorContext.Provider, { value: cursor, children: _jsx(ChatApp, { model: model, interaction: interaction, input: input, promptLabel: promptLabel, renderApproval: tuiOptions.renderApproval, mode: tuiOptions.mode, fullscreen: tuiOptions.fullscreen, header: tuiOptions.header && tuiOptions.fullscreen ? headerLines(tuiOptions.header) : undefined, onFocusChange: status ? (focused) => status.setFocused(focused) : undefined, modeControl: tuiOptions.modeControl, onInterrupt: interruptTurn }) }), 
+    // In full screen Ink writes through the cursor controller, which places the terminal's cursor.
+    { exitOnCtrlC: false, ...(cursor ? { stdout: cursor.stream } : {}) });
+    try {
+        // In full screen the header is pinned above the history (see SessionView) instead.
+        if (tuiOptions.header && !tuiOptions.fullscreen)
+            model.note(headerLines(tuiOptions.header).join("\n"));
+        if (tuiOptions.welcomeMessage)
+            model.writeLine(tuiOptions.welcomeMessage);
+        if (tuiOptions.initialPrompt) {
+            // Logged but not shown, like runChatTui(): it is the agent's cue, not something typed.
+            mirror(`${promptLabel}${tuiOptions.initialPrompt}\n`);
+            await runTurn(tuiOptions.initialPrompt);
+        }
+        while (true) {
+            // The blank line before the prompt is in place while typing, so Enter doesn't push
+            // everything down a line: promptLabel's own leading newlines only reach the log.
+            model.separate();
+            const raw = await input.next(historyEntries.map((entry) => entry.text));
+            if (raw === null)
+                break;
+            const line = raw.trim();
+            if (!line)
+                continue;
+            mirror(`${promptLabel}${line}\n`);
+            model.note(`${promptLabel.replace(/^\n+/, "")}${line}`, "user");
+            if (tuiOptions.historyPath) {
+                historyEntries = capHistory([...historyEntries, { text: line, timestamp: new Date().toISOString() }], historyLimit);
+                await saveHistory(tuiOptions.historyPath, historyEntries);
+            }
+            if (exitCommands.has(line.toLowerCase()))
+                break;
+            // A local command, never sent to the model: the last reply to the clipboard (OSC 52).
+            if (status && line.toLowerCase() === "/copy") {
+                const reply = model.lastReply();
+                if (reply)
+                    stdout.write(clipboardSequence(reply));
+                model.writeLine(ui.dim(reply ? `(copied the last reply: ${reply.length} characters)` : "(nothing to copy yet)"));
+                continue;
+            }
+            const commandToken = slashCommandToken(line);
+            if (commandToken) {
+                const names = await knownCommands;
+                if (names && !names.has(commandToken)) {
+                    model.writeLine(ui.warn(`Unknown command: /${commandToken}`));
+                    continue;
+                }
+            }
+            await runTurn(line);
+        }
+    }
+    finally {
+        setInteractionPort(previousPort);
+        queue.end();
+        run.close();
+        input.close();
+        // One more frame with only the history, so the prompt and status bar don't stay behind.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        app.unmount();
+        await app.waitUntilExit();
+        status?.stop();
+        restoreTerminal?.();
+        sessionLog?.end();
+    }
+}