@bubblebrain-ai/bubble 0.0.52 → 0.0.54

package/dist/tui/controller/composer-controller.js

@@ -0,0 +1,502 @@
+import { appendHistoryEntry, loadHistoryEntriesSync, pushHistoryEntry, stepHistory, } from "../model/input-history.js";
+import { bareImageFilenameFromPaste, extractImagePathTokens, ingestClipboardImage, ingestImagePath, } from "../model/image-paste.js";
+import { PasteOperationTracker } from "../model/paste-operation-tracker.js";
+import { imageDisplayLabel, stripInlineImageLabels } from "../image-display.js";
+import { darkTheme } from "../model/theme.js";
+import { themeBackground, themeForeground } from "../model/theme-style.js";
+const READING_IMAGE_PREFIX = "Reading image";
+function cloneHistoryEntry(entry) {
+    return {
+        text: entry.text,
+        images: entry.images.map((image) => ({ ...image })),
+        ...(entry.imageDisplayStart !== undefined ? { imageDisplayStart: entry.imageDisplayStart } : {}),
+    };
+}
+function normalizedScope(scope) {
+    return {
+        sessionFile: scope.sessionFile?.trim() || undefined,
+        cwd: scope.cwd?.trim() || undefined,
+    };
+}
+function scopesEqual(a, b) {
+    return a.sessionFile === b.sessionFile && a.cwd === b.cwd;
+}
+/**
+ * Owns semantic composer state that Pi Editor deliberately does not know about:
+ * image attachments, asynchronous paste operations and scoped persistent
+ * history. Text editing and cursor mechanics remain inside Editor.
+ */
+export class ComposerController {
+    options;
+    editor;
+    scope;
+    history = [];
+    historyIndex = null;
+    historyDraft = { text: "", images: [] };
+    attachments = [];
+    imageDisplayStart;
+    nextImageLabelStart;
+    pasteOperations = new PasteOperationTracker();
+    draftGeneration = 0;
+    applyingEditorState = false;
+    historyNavigationChangePending = false;
+    editorSubmitting = false;
+    disposed = false;
+    recentPreviewLabel;
+    recentPreviewCursorOffset;
+    openImageHandler;
+    constructor(options) {
+        this.options = options;
+        this.editor = options.editor;
+        this.scope = normalizedScope(options.scope);
+        this.nextImageLabelStart = Math.max(1, options.nextImageLabelStart);
+        this.openImageHandler = options.onOpenImage;
+        this.attachEditor(options.editor);
+        this.reloadHistory();
+    }
+    attachEditor(editor) {
+        if (this.editor !== editor) {
+            const previousText = this.editor.getText();
+            this.detachEditor(this.editor);
+            this.editor = editor;
+            this.applyingEditorState = true;
+            editor.setText(previousText);
+            this.applyingEditorState = false;
+        }
+        editor.onPaste = (text) => this.handlePaste(text);
+        editor.onHistoryNavigate = (direction, currentText) => this.navigateHistory(direction, currentText);
+        editor.onChange = () => this.handleEditorChange();
+        editor.onCursorMove = () => {
+            if (this.applyingEditorState)
+                return;
+            this.recentPreviewLabel = undefined;
+            this.recentPreviewCursorOffset = undefined;
+            this.options.onStateChange();
+        };
+        editor.onBeforeSubmit = () => {
+            this.editorSubmitting = true;
+        };
+        editor.onSubmit = (text) => this.handleEditorSubmit(text);
+        this.syncOpenImageActivation();
+        editor.disableSubmit = this.pasteOperations.hasPending;
+        this.syncEditorDecorations();
+    }
+    detachEditor(editor) {
+        editor.onPaste = undefined;
+        editor.onHistoryNavigate = undefined;
+        editor.onChange = undefined;
+        editor.onCursorMove = undefined;
+        editor.onBeforeSubmit = undefined;
+        editor.onSubmit = undefined;
+        editor.onInlineDecorationActivate = undefined;
+        editor.setInlineDecorations([]);
+        editor.disableSubmit = false;
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.invalidateDraftAsyncWork();
+        this.detachEditor(this.editor);
+    }
+    pendingImageCount() {
+        return this.pasteOperations.pendingCount;
+    }
+    setOpenImageHandler(handler) {
+        this.openImageHandler = handler;
+        this.syncOpenImageActivation();
+    }
+    syncOpenImageActivation() {
+        this.editor.onInlineDecorationActivate = this.openImageHandler
+            ? (id) => {
+                const item = this.attachments.find((candidate) => candidate.label === id);
+                if (item)
+                    this.openImageHandler?.({ label: item.label, attachment: { ...item.attachment } });
+            }
+            : undefined;
+    }
+    /**
+     * Explicit keyboard-driven clipboard probe. Image-only clipboards do not
+     * produce text for many terminals, so Cmd+V may have no bracketed-paste body
+     * and Ctrl+V arrives as a key chord instead of a paste event.
+     */
+    requestClipboardImagePaste() {
+        if (this.disposed)
+            return;
+        if (this.pasteOperations.hasPending)
+            return;
+        if (!(this.options.allowImageAttachments?.() ?? true)) {
+            this.options.onNotice("Image attachments are disabled in this runtime session.");
+            return;
+        }
+        this.startClipboardPaste("", true);
+    }
+    historyTexts() {
+        return this.history.map((entry) => entry.text);
+    }
+    getText() {
+        return this.editor.getText();
+    }
+    snapshotDraft() {
+        return {
+            text: this.editor.getText(),
+            attachments: this.attachments.map((item) => ({
+                label: item.label,
+                attachment: { ...item.attachment },
+            })),
+            ...(this.imageDisplayStart !== undefined ? { imageDisplayStart: this.imageDisplayStart } : {}),
+        };
+    }
+    /** Image whose chip was just inserted, is under the cursor, or is hovered. */
+    previewAttachment() {
+        const recentStillAtInsertionPoint = this.recentPreviewCursorOffset === this.editor.getCursorOffset();
+        const activeLabel = this.editor.getActiveInlineDecorationId()
+            ?? (recentStillAtInsertionPoint ? this.recentPreviewLabel : undefined);
+        const item = this.attachments.find((candidate) => candidate.label === activeLabel);
+        return item ? { label: item.label, attachment: { ...item.attachment } } : undefined;
+    }
+    restoreDraft(snapshot) {
+        this.invalidateDraftAsyncWork();
+        this.attachments = snapshot.attachments.map((item) => ({
+            label: item.label,
+            attachment: { ...item.attachment },
+        }));
+        this.imageDisplayStart = snapshot.imageDisplayStart;
+        this.historyIndex = null;
+        this.historyDraft = { text: "", images: [] };
+        this.applyingEditorState = true;
+        this.editor.setText(snapshot.text);
+        this.applyingEditorState = false;
+        this.syncEditorDecorations();
+        this.options.onStateChange();
+    }
+    /** Replace the complete draft and invalidate attachments/pastes/history browse. */
+    replaceDraft(text) {
+        this.invalidateDraftAsyncWork();
+        this.attachments = [];
+        this.imageDisplayStart = undefined;
+        this.historyIndex = null;
+        this.historyDraft = { text: "", images: [] };
+        this.applyingEditorState = true;
+        this.editor.setText(text);
+        this.applyingEditorState = false;
+        this.recentPreviewLabel = undefined;
+        this.recentPreviewCursorOffset = undefined;
+        this.syncEditorDecorations();
+        this.options.onStateChange();
+    }
+    /** Rebind persistent history after a successful session transition. */
+    setScope(scope, nextImageLabelStart) {
+        const nextScope = normalizedScope(scope);
+        const changed = !scopesEqual(this.scope, nextScope);
+        this.scope = nextScope;
+        this.nextImageLabelStart = Math.max(1, nextImageLabelStart);
+        if (!changed)
+            return;
+        this.invalidateDraftAsyncWork();
+        this.attachments = [];
+        this.imageDisplayStart = undefined;
+        this.historyIndex = null;
+        this.historyDraft = { text: "", images: [] };
+        this.reloadHistory();
+        this.applyingEditorState = true;
+        this.editor.setText("");
+        this.applyingEditorState = false;
+        this.recentPreviewLabel = undefined;
+        this.recentPreviewCursorOffset = undefined;
+        this.syncEditorDecorations();
+        this.options.onStateChange();
+    }
+    reloadHistory() {
+        if (this.options.persistHistory === false) {
+            this.history = [];
+            return;
+        }
+        this.history = loadHistoryEntriesSync({
+            scope: this.scope,
+            ...(this.options.historyFilePath ? { filePath: this.options.historyFilePath } : {}),
+        }).map(cloneHistoryEntry);
+    }
+    handleEditorChange() {
+        if (this.applyingEditorState)
+            return;
+        if (this.editorSubmitting)
+            return;
+        if (this.historyNavigationChangePending) {
+            this.historyNavigationChangePending = false;
+            this.syncEditorDecorations();
+            return;
+        }
+        this.recentPreviewLabel = undefined;
+        this.recentPreviewCursorOffset = undefined;
+        // Editing a recalled entry starts a new draft, matching Editor's native
+        // history semantics. Attachments stay attached until their labels are gone.
+        if (this.historyIndex !== null) {
+            this.historyIndex = null;
+            this.historyDraft = { text: "", images: [] };
+        }
+        if (this.attachments.length > 0) {
+            const text = this.editor.getText();
+            const retained = this.attachments.filter((item) => text.includes(item.label));
+            if (retained.length !== this.attachments.length) {
+                if (retained.length === 0) {
+                    this.attachments = [];
+                    this.imageDisplayStart = undefined;
+                }
+                else {
+                    const labelStart = this.imageDisplayStart ?? this.nextImageLabelStart;
+                    this.applyingEditorState = true;
+                    for (let index = 0; index < retained.length; index++) {
+                        const item = retained[index];
+                        const nextLabel = imageDisplayLabel(labelStart + index);
+                        if (item.label !== nextLabel) {
+                            const current = this.editor.getText();
+                            const offset = current.indexOf(item.label);
+                            if (offset >= 0)
+                                this.editor.replaceRange(offset, offset + item.label.length, nextLabel);
+                            item.label = nextLabel;
+                        }
+                    }
+                    this.applyingEditorState = false;
+                    this.attachments = retained;
+                    this.imageDisplayStart = labelStart;
+                }
+                this.options.onStateChange();
+            }
+        }
+        this.syncEditorDecorations();
+    }
+    handleEditorSubmit(submittedText) {
+        this.editorSubmitting = false;
+        const labels = this.attachments.map((item) => item.label);
+        const modelText = stripInlineImageLabels(submittedText, labels).trim();
+        const isSlashCommand = modelText.startsWith("/");
+        const images = isSlashCommand ? [] : this.attachments.map((item) => ({ ...item.attachment }));
+        if (!modelText && images.length === 0) {
+            this.resetAfterSubmit();
+            return;
+        }
+        if (isSlashCommand && this.attachments.length > 0) {
+            this.options.onNotice("Image attachments were ignored for the slash command.");
+        }
+        const payload = {
+            text: modelText,
+            ...(images.length > 0 && submittedText !== modelText ? { displayText: submittedText } : {}),
+            images,
+            ...(images.length > 0 && this.imageDisplayStart !== undefined
+                ? { imageDisplayStart: this.imageDisplayStart }
+                : {}),
+        };
+        const historyEntry = {
+            // History restores the draft surface, not the provider prompt. Keep the
+            // chip exactly where it was submitted and derive modelText again on the
+            // next submit.
+            text: images.length > 0 ? submittedText : modelText,
+            images,
+            ...(images.length > 0 && this.imageDisplayStart !== undefined
+                ? { imageDisplayStart: this.imageDisplayStart }
+                : {}),
+        };
+        const nextHistory = pushHistoryEntry(this.history, historyEntry);
+        if (nextHistory !== this.history) {
+            this.history = nextHistory;
+            if (this.options.persistHistory !== false) {
+                appendHistoryEntry(historyEntry, {
+                    scope: this.scope,
+                    ...(this.options.historyFilePath ? { filePath: this.options.historyFilePath } : {}),
+                });
+            }
+        }
+        if (images.length > 0) {
+            this.nextImageLabelStart = Math.max(this.nextImageLabelStart, (this.imageDisplayStart ?? this.nextImageLabelStart) + images.length);
+        }
+        this.resetAfterSubmit();
+        this.options.onSubmit(payload);
+    }
+    resetAfterSubmit() {
+        this.invalidateDraftAsyncWork();
+        this.attachments = [];
+        this.imageDisplayStart = undefined;
+        this.recentPreviewLabel = undefined;
+        this.recentPreviewCursorOffset = undefined;
+        this.syncEditorDecorations();
+        this.historyIndex = null;
+        this.historyDraft = { text: "", images: [] };
+        this.options.onStateChange();
+    }
+    navigateHistory(direction, currentText) {
+        if (this.pasteOperations.hasPending)
+            return undefined;
+        const currentEntry = {
+            text: currentText,
+            images: this.attachments.map((item) => ({ ...item.attachment })),
+            ...(this.imageDisplayStart !== undefined ? { imageDisplayStart: this.imageDisplayStart } : {}),
+        };
+        const result = stepHistory({
+            history: this.history,
+            index: this.historyIndex,
+            draft: this.historyDraft,
+        }, direction, currentEntry);
+        if (!result.changed)
+            return undefined;
+        if (this.historyIndex === null && result.index !== null) {
+            this.historyDraft = cloneHistoryEntry(currentEntry);
+        }
+        const restoredImages = (result.images ?? []).map((image) => ({ ...image }));
+        const labelStart = restoredImages.length > 0
+            ? result.imageDisplayStart ?? this.nextImageLabelStart
+            : undefined;
+        this.attachments = restoredImages.map((attachment, index) => ({
+            attachment,
+            label: imageDisplayLabel((labelStart ?? 1) + index),
+        }));
+        this.imageDisplayStart = labelStart;
+        this.historyIndex = result.index;
+        if (result.index === null)
+            this.historyDraft = { text: "", images: [] };
+        const labels = this.attachments.map((item) => item.label);
+        const restoredText = labels.length > 0 && !labels.some((label) => result.text.includes(label))
+            ? `${labels.join(" ")} ${result.text}`.trimEnd()
+            : result.text;
+        this.historyNavigationChangePending = true;
+        this.options.onStateChange();
+        return { text: restoredText, active: result.index !== null };
+    }
+    handlePaste(raw) {
+        if (this.disposed)
+            return false;
+        const clean = raw
+            .replace(/\x1b\[I$/, "")
+            .replace(/\x1b\[O$/, "")
+            .replace(/\r\n?/g, "\n");
+        const allowImages = this.options.allowImageAttachments?.() ?? true;
+        const pathTokens = extractImagePathTokens(clean);
+        const bareName = bareImageFilenameFromPaste(clean);
+        const imageIntent = clean.length === 0 || pathTokens.length > 0 || bareName !== null;
+        if (!imageIntent)
+            return false;
+        if (!allowImages) {
+            this.options.onNotice("Image attachments are disabled in this runtime session.");
+            return true;
+        }
+        if (clean.length === 0 || bareName !== null) {
+            this.startClipboardPaste(clean);
+            return true;
+        }
+        this.startPathPaste(clean, pathTokens);
+        return true;
+    }
+    beginPastePlaceholder() {
+        const id = this.pasteOperations.begin();
+        const marker = `[${READING_IMAGE_PREFIX} #${id}…]`;
+        this.editor.disableSubmit = true;
+        this.editor.insertTextAtCursor(`${marker} `);
+        this.options.onStateChange();
+        return { id, marker, generation: this.draftGeneration };
+    }
+    finishPaste(id) {
+        this.pasteOperations.finish(id);
+        this.editor.disableSubmit = this.pasteOperations.hasPending;
+        this.options.onStateChange();
+    }
+    replacePasteMarker(marker, replacement, removeTrailingSeparator = false) {
+        const text = this.editor.getText();
+        const start = text.indexOf(marker);
+        if (start < 0)
+            return false;
+        const markerEnd = start + marker.length;
+        const end = removeTrailingSeparator && text[markerEnd] === " "
+            ? markerEnd + 1
+            : markerEnd;
+        this.applyingEditorState = true;
+        this.editor.replaceRange(start, end, replacement);
+        this.applyingEditorState = false;
+        if (this.recentPreviewLabel && replacement.includes(this.recentPreviewLabel)) {
+            this.recentPreviewCursorOffset = this.editor.getCursorOffset();
+        }
+        return true;
+    }
+    startClipboardPaste(fallbackText, notifyWhenEmpty = false) {
+        const pending = this.beginPastePlaceholder();
+        const readClipboardImage = this.options.readClipboardImage ?? ingestClipboardImage;
+        void readClipboardImage()
+            .then(({ attachment, error }) => {
+            if (this.disposed || pending.generation !== this.draftGeneration)
+                return;
+            if (!attachment) {
+                this.replacePasteMarker(pending.marker, fallbackText, fallbackText.length === 0);
+                if (notifyWhenEmpty && error === "clipboard has no image") {
+                    this.options.onNotice("Clipboard does not contain a supported image.");
+                }
+                else if (error && error !== "clipboard has no image") {
+                    this.options.onNotice(`Image paste failed: ${error}`);
+                }
+                return;
+            }
+            if (!this.editor.getText().includes(pending.marker))
+                return;
+            const item = this.registerAttachment(attachment);
+            this.replacePasteMarker(pending.marker, item.label);
+        })
+            .finally(() => this.finishPaste(pending.id));
+    }
+    startPathPaste(pastedText, tokens) {
+        const pending = this.beginPastePlaceholder();
+        void Promise.all(tokens.map(async (token) => ({ token, result: await ingestImagePath(token.rawPath) })))
+            .then((results) => {
+            if (this.disposed || pending.generation !== this.draftGeneration)
+                return;
+            if (!this.editor.getText().includes(pending.marker))
+                return;
+            let replacement = "";
+            let cursor = 0;
+            for (const { token, result } of results) {
+                replacement += pastedText.slice(cursor, token.start);
+                if (result.attachment) {
+                    replacement += this.registerAttachment(result.attachment).label;
+                }
+                else {
+                    replacement += pastedText.slice(token.start, token.end);
+                    this.options.onNotice(`${token.rawPath}: ${result.error ?? "could not attach image"}`);
+                }
+                cursor = token.end;
+            }
+            replacement += pastedText.slice(cursor);
+            this.replacePasteMarker(pending.marker, replacement);
+        })
+            .finally(() => this.finishPaste(pending.id));
+    }
+    registerAttachment(attachment) {
+        if (this.imageDisplayStart === undefined)
+            this.imageDisplayStart = this.nextImageLabelStart;
+        const item = {
+            attachment: { ...attachment },
+            label: imageDisplayLabel(this.imageDisplayStart + this.attachments.length),
+        };
+        this.attachments.push(item);
+        this.recentPreviewLabel = item.label;
+        this.syncEditorDecorations();
+        return item;
+    }
+    syncEditorDecorations() {
+        const decorations = this.attachments.map((item) => ({
+            id: item.label,
+            text: item.label,
+            style: (text, state) => {
+                const theme = this.options.getTheme?.() ?? darkTheme;
+                const background = state.focused
+                    ? theme.traceSelectedBg
+                    : state.hovered
+                        ? theme.traceHoverBg
+                        : theme.backgroundElement;
+                return themeForeground(theme.inputText, themeBackground(background, text));
+            },
+        }));
+        this.editor.setInlineDecorations(decorations);
+    }
+    invalidateDraftAsyncWork() {
+        this.draftGeneration++;
+        this.pasteOperations.invalidateAll();
+        this.editor.disableSubmit = false;
+    }
+}

package/dist/tui/controller/controller.d.ts

@@ -0,0 +1,194 @@
+/**
+ * BubbleTuiController — the framework-neutral runtime orchestrator
+ * (design doc §8.1). Assembles the extracted sub-modules:
+ *
+ *   - agent-event-reducer (stream/tool/turn semantics)
+ *   - input-queue-machine (steer/queue lifecycle)
+ *   - overlay-controller (blocking request lifecycle)
+ *   - session-transition (two-phase atomic switch)
+ *   - task-runtime-controller (task markers/wakes)
+ *
+ * The controller consumes an Agent event stream, applies effects, batches
+ * streaming updates behind the 40ms FlushScheduler, and publishes immutable
+ * snapshots. Renderers subscribe; they never mutate.
+ */
+import type { Agent, AgentRunOptions } from "../../agent.js";
+import type { WorkflowRunSnapshot } from "../../agent/workflow/control.js";
+import type { BackgroundTaskInfo, ProcessManager } from "../../tasks/manager.js";
+import { SessionManager } from "../../session.js";
+import type { GoalStore } from "../../goal/store.js";
+import type { BubbleTuiPorts } from "./ports.js";
+import type { ControllerEffect } from "./effects.js";
+import { type DisplayMessage, type DisplayMessagePart, type DisplayToolCall } from "../model/display-history.js";
+import { type SubagentGroup } from "../model/subagent-view.js";
+import type { SubmitPayload } from "../model/composer-types.js";
+import type { PromotionChannel } from "../../tasks/promotion.js";
+import { type RewindExecutionResult, type RewindScope } from "../../rewind.js";
+import type { Message } from "../../types.js";
+export interface TuiExitSummary {
+    reason: string;
+    wallMs: number;
+}
+export interface BubbleTuiControllerDeps {
+    readonly agent: Pick<Agent, "run" | "messages" | "setSessionID" | "listSubAgents" | "listWorkflows" | "getSubAgentMessages" | "closeSubAgent" | "closeWorkflow" | "resetContextUsageAnchor"> & {
+        messages: Message[];
+        backgroundTasks?: Agent["backgroundTasks"];
+    };
+    readonly sessionManager: SessionManager;
+    readonly goalStore?: GoalStore;
+    readonly processManager?: ProcessManager;
+    readonly tasksAutoResume?: boolean;
+    readonly promotionChannel?: PromotionChannel;
+    readonly workspaceCwd?: string;
+    readonly ports: BubbleTuiPorts;
+    readonly onEffect?: (effect: ControllerEffect) => void;
+}
+export interface TuiAgentRunOptions extends AgentRunOptions {
+    /** Internal Goal continuation; never forwarded to Agent.run(). */
+    goalRun?: boolean;
+}
+export interface CommandActivity {
+    kind: "compact";
+    status: "running" | "cancelling";
+    startedAt: number;
+}
+export declare class BubbleTuiController {
+    private readonly deps;
+    private readonly state;
+    private readonly listeners;
+    private readonly overlays;
+    private readonly queue;
+    private readonly sessionTransition;
+    private readonly startedAtMs;
+    private readonly goalRuntime?;
+    private readonly taskRuntime?;
+    private readonly pendingTaskAnnouncements;
+    private sessionManager;
+    private transcript;
+    private runActive;
+    private runState;
+    /** Background subagent updates can outlive the provider turn that launched
+     * them. Keep their latest synthetic tool snapshot in the live trace. */
+    private readonly liveSubagentTools;
+    /** Provider-turn accumulators for true child-session inspection. */
+    private readonly childRuns;
+    private activeInputController;
+    private activeAbortController;
+    private commandActivity;
+    /** False after a provider turn commits, so settled and live rows never coexist. */
+    private liveStreamVisible;
+    private readonly backgroundTaskUnsubscribe?;
+    private disposed;
+    constructor(deps: BubbleTuiControllerDeps);
+    private externalGeneration;
+    private liveSubagentVersion;
+    subscribe(listener: (version: number) => void): () => void;
+    getSnapshotVersion(): number;
+    getTranscript(): readonly DisplayMessage[];
+    getSessionManager(): SessionManager;
+    getGoalIndicator(): string | undefined;
+    handleGoalCommand(input: string, cwd: string): void;
+    getSubagentGroups(): SubagentGroup[];
+    getWorkflows(): WorkflowRunSnapshot[];
+    getBackgroundTasks(): BackgroundTaskInfo[];
+    getChildTranscript(agentId: string): DisplayMessage[];
+    getChildStreamingTail(agentId: string): {
+        content: string;
+        reasoning: string;
+        tools: DisplayToolCall[];
+        parts: DisplayMessagePart[];
+    } | null;
+    stopSubagent(agentId: string): void;
+    stopWorkflow(runId: string): void;
+    stopBackgroundTask(id: string): void;
+    getBackgroundTaskOutput(id: string): string;
+    /** Called by the host after graceful task reaping on TUI exit. */
+    persistFinalTaskMarkers(): void;
+    private appendTaskMarker;
+    private announceTaskCompletion;
+    /** Move the newest live Bash Execute into the unified task manager. */
+    promoteActiveBash(): string | undefined;
+    /** Drop every transcript row (/clear). */
+    clearTranscript(): void;
+    /** Re-project the visible transcript after a non-controller command rewrites Agent history. */
+    rebuildTranscriptFromAgent(): void;
+    /**
+     * Rewind persistence and every renderer-facing mirror as one observable
+     * transition. File restoration can take time, but no partial transcript is
+     * published while it runs.
+     */
+    rewindToTurn(targetId: string, scope: RewindScope): Promise<RewindExecutionResult>;
+    /** Host-side row injection (user echo, notices) — single append point. */
+    appendDisplayMessage(message: DisplayMessage): void;
+    isRunning(): boolean;
+    /** A slash command that owns the activity lane without masquerading as an
+     * Agent turn. This keeps streaming/steering state separate while still
+     * giving Escape and Ctrl+C one cancellation boundary. */
+    beginCommandActivity(kind: CommandActivity["kind"]): AbortSignal;
+    finishCommandActivity(kind: CommandActivity["kind"], event?: DisplayMessage): void;
+    getCommandActivity(): CommandActivity | null;
+    isBusy(): boolean;
+    /** Queue composer input while a command owns the pane. Grok keeps the
+     * composer available during Compact; the message starts after the command
+     * reaches its terminal event instead of racing the history rewrite. */
+    queueAfterCommand(input: string | SubmitPayload): boolean;
+    /** Queue a complete composer payload for the next provider turn. */
+    queueInput(input: string | SubmitPayload): void;
+    drainQueuedInputs(cwd: string, agentOptions?: AgentRunOptions): Promise<void>;
+    pendingSteerCount(): number;
+    queuedInputCount(): number;
+    private submitDisplayText;
+    private submitAgentInput;
+    /** Add input to the current Agent run without creating a second run that
+     * would overwrite the shared streaming accumulator. */
+    steer(content: string): boolean;
+    cancelActiveRun(reason?: string): boolean;
+    /**
+     * Live streaming tail for the render loop: the in-flight accumulator's
+     * content/reasoning/tool summary. Renderers draw it in the live region
+     * (never committed to scrollback) until the turn commits.
+     */
+    getStreamingTail(): {
+        content: string;
+        reasoning: string;
+        tools: DisplayToolCall[];
+        parts: DisplayMessagePart[];
+        phase: "thinking" | "working";
+    } | null;
+    pendingOverlayCount(): number;
+    /**
+     * Drive one agent run: reduce the event stream, apply effects, and finish.
+     * Mirrors runAgentInput (app.tsx:1438-1958) minus the rendering.
+     */
+    runTurn(input: unknown, cwd: string, options?: TuiAgentRunOptions): Promise<void>;
+    /** Apply one reducer transition and publish exactly one observable snapshot. */
+    private applyEffects;
+    /** Mutate for one effect; callers own the surrounding transaction + notify. */
+    private applyEffectMutation;
+    private notify;
+    private reduceChildEvent;
+    private isAbortLike;
+    /** Drain leftover steers at run end (cancelled drops, normal requeues). */
+    drainLeftovers(leftovers: Array<{
+        id: string;
+        content: string;
+    }>, cancelled: boolean): void;
+    /** Atomic session switch through the two-phase transaction. */
+    switchSession(plan: {
+        targetFile: string;
+        notice?: string;
+    }): {
+        ok: boolean;
+        error?: string;
+    };
+    /** Start an empty native session using the same atomic lifecycle as resume. */
+    createFreshSession(cwd: string, notice?: string): {
+        ok: boolean;
+        error?: string;
+    };
+    /**
+     * Shutdown: settle overlays, cancel any run, and report the exit summary.
+     * Idempotent — a second call is a no-op.
+     */
+    shutdown(reason: string): TuiExitSummary;
+}