@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/tui/controller/controller.js

@@ -0,0 +1,1034 @@
+import { SessionManager } from "../../session.js";
+import { tokenUsageTotal } from "../../goal/usage.js";
+import { ControllerState } from "./state.js";
+import { buildAssistantMessage, createRunState, reduceAgentEvent, reduceRunFinish, STREAMING_FLUSH_INTERVAL_MS, } from "./agent-event-reducer.js";
+import { beginSteer, createInputQueueState, drainLeftoverSteers, purgeForSessionSwitch, } from "./input-queue-machine.js";
+import { AgentRunInputQueue } from "../../agent/input-controller.js";
+import { OverlayRequestController } from "./overlay-controller.js";
+import { SessionTransitionController } from "./session-transition.js";
+import { moveStatusMessageToEnd, nextDisplayMessageKey, setUserInputStatus, snapshotDisplayParts, } from "../model/display-history.js";
+import { applySubagentUpdateToMessages, collectSubagentGroups, mergeSubagentSnapshotsIntoMessages, } from "../model/subagent-view.js";
+import { reconstructDisplayMessages } from "../model/display-reconstruct.js";
+import { applyTaskLifecycleToMessages, landTaskLifecycles, mergeTaskLifecycleIntoLiveTools, taskLifecycleDisplayMessage, UNMATCHED_LAUNCH, } from "../model/task-lifecycle.js";
+import { buildImageContentParts, buildImageContentPartsFromDisplayText } from "../model/image-paste.js";
+import { displayImagesFromPayload, formatImageUserDisplayText } from "../image-display.js";
+import { GoalRuntimeController } from "./goal-runtime-controller.js";
+import { TaskRuntimeController } from "./task-runtime-controller.js";
+import { formatInternalContextBlock } from "../../agent/internal-reminder-sanitizer.js";
+import { executeRewind } from "../../rewind.js";
+function isSubmitPayload(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const payload = value;
+    return typeof payload.text === "string" && Array.isArray(payload.images);
+}
+export class BubbleTuiController {
+    deps;
+    state = new ControllerState();
+    listeners = new Set();
+    overlays;
+    queue = createInputQueueState();
+    sessionTransition;
+    startedAtMs;
+    turnStartedAt;
+    goalRuntime;
+    taskRuntime;
+    pendingTaskAnnouncements = new Map();
+    sessionManager;
+    transcript = [];
+    runActive = false;
+    runState = null;
+    /** Provider-turn accumulators for true child-session inspection. */
+    childRuns = new Map();
+    activeInputController = null;
+    activeAbortController = null;
+    commandActivity = null;
+    /** False after a provider turn commits, so settled and live rows never coexist. */
+    liveStreamVisible = false;
+    backgroundTaskUnsubscribe;
+    disposed = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.sessionManager = deps.sessionManager;
+        this.transcript = landTaskLifecycles(reconstructDisplayMessages([...deps.agent.messages]), restoredTaskLifecycles(this.sessionManager));
+        this.overlays = new OverlayRequestController();
+        this.startedAtMs = Date.now();
+        this.sessionTransition = new SessionTransitionController({
+            host: deps.ports.sessionHost,
+            state: this.state,
+            overlays: this.overlays,
+            queue: this.queue,
+            agent: {
+                getMessages: () => deps.agent.messages,
+                setSessionID: (file) => deps.agent.setSessionID(file),
+            },
+            bumpExternalGeneration: () => {
+                this.externalGeneration += 1;
+            },
+            clearLiveSubagentTools: () => {
+                this.childRuns.clear();
+            },
+            commit: (manager, transcript) => {
+                this.sessionManager = manager;
+                this.deps.ports.flush.cancelFlush();
+                this.transcript = landTaskLifecycles(transcript, restoredTaskLifecycles(manager));
+                this.queue.queued.length = 0;
+                this.liveStreamVisible = false;
+                this.runState = null;
+                // Session-scoped: the restored session has not started a run, so none
+                // of its subagents or tasks belong to a "current turn".
+                this.turnStartedAt = undefined;
+                this.activeInputController = null;
+                this.activeAbortController = null;
+                this.commandActivity = null;
+                this.state.touch();
+            },
+        });
+        this.overlays.onChange(() => this.state.touch());
+        if (deps.goalStore) {
+            this.goalRuntime = new GoalRuntimeController({
+                store: deps.goalStore,
+                getSessionManager: () => this.sessionManager,
+                isRunActive: () => this.isBusy(),
+                queuedInputs: () => this.queue.queued.length,
+                isDisposed: () => this.disposed,
+                startRun: (input, cwd) => {
+                    void this.runTurn(input, cwd, { goalRun: true });
+                },
+                appendMessage: (role, content) => {
+                    this.appendDisplayMessage({
+                        key: nextDisplayMessageKey(role === "user" ? "user" : role === "error" ? "error" : "notice"),
+                        role,
+                        content,
+                        syntheticKind: role === "assistant" ? "ui_notice" : undefined,
+                    });
+                },
+                onStateChanged: () => {
+                    this.state.touch();
+                    this.notify();
+                },
+            });
+        }
+        if (deps.processManager) {
+            this.taskRuntime = new TaskRuntimeController({
+                processManager: deps.processManager,
+                getSessionFile: () => this.sessionManager.getSessionFile(),
+                appendMarker: (file, marker, payload) => this.appendTaskMarker(file, marker, payload),
+                announceCompletion: (task) => this.announceTaskCompletion(task),
+                submitTaskWake: (summary) => {
+                    const cwd = this.sessionManager.getMetadata().cwd ?? deps.workspaceCwd ?? process.cwd();
+                    void this.runTurn(formatInternalContextBlock("background-task", summary), cwd);
+                },
+                tasksAutoResume: deps.tasksAutoResume !== false,
+                gates: () => ({
+                    turnRunning: this.isBusy(),
+                    queuedInputs: this.queue.queued.length,
+                    exiting: this.disposed,
+                    goalActive: this.goalRuntime?.snapshot()?.status === "active",
+                }),
+            });
+            this.taskRuntime.start();
+        }
+        this.backgroundTaskUnsubscribe = (deps.processManager
+            ? deps.processManager.onChange(() => {
+                this.state.touch();
+                this.notify();
+            })
+            : deps.agent.backgroundTasks?.subscribe?.(() => {
+                this.state.touch();
+                this.notify();
+            }));
+    }
+    externalGeneration = 0;
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    getSnapshotVersion() {
+        return this.state.version;
+    }
+    getTranscript() {
+        return this.transcript;
+    }
+    getSessionManager() {
+        return this.sessionManager;
+    }
+    getGoalIndicator() {
+        return this.goalRuntime?.indicatorLine();
+    }
+    handleGoalCommand(input, cwd) {
+        if (!this.goalRuntime) {
+            this.appendDisplayMessage({
+                key: nextDisplayMessageKey("error"),
+                role: "error",
+                content: "Goals are not available in this session.",
+            });
+            return;
+        }
+        this.goalRuntime.handleCommand(input, cwd);
+    }
+    getSubagentGroups() {
+        // Launches from earlier rounds live in the transcript (kept current by
+        // applySubagentUpdateToMessages); this round's launches are still in the
+        // streaming accumulator until turn_end commits them.
+        const streamingTools = this.runActive && this.runState ? this.runState.accumulator.toolCalls : [];
+        const fromTrace = collectSubagentGroups(this.transcript, streamingTools);
+        const claimed = new Set(fromTrace.flatMap((group) => group.members.map((member) => member.subAgentId).filter(Boolean)));
+        const direct = this.deps.agent.listSubAgents()
+            .filter((snapshot) => !claimed.has(snapshot.agentId))
+            .map((snapshot) => ({
+            id: `single:${snapshot.agentId}`,
+            runId: snapshot.runId,
+            kind: "single",
+            label: snapshot.nickname,
+            members: [{
+                    subAgentId: snapshot.agentId,
+                    agentName: snapshot.agentName,
+                    nickname: snapshot.nickname,
+                    status: snapshot.status,
+                    category: snapshot.category,
+                    phase: snapshot.phase,
+                    route: snapshot.route,
+                    profileSource: snapshot.profileSource,
+                    task: snapshot.task,
+                    summary: snapshot.summary,
+                    toolNotes: snapshot.toolNotes,
+                    error: snapshot.error,
+                    usage: snapshot.usage,
+                    createdAt: snapshot.createdAt,
+                    updatedAt: snapshot.updatedAt,
+                }],
+        }));
+        return [...fromTrace, ...direct];
+    }
+    /**
+     * Start of the current (or, when idle, the latest) agent run. The tasks pane
+     * keeps finished work that was launched since then; wall clock on purpose,
+     * it is compared with subagent/task/workflow creation stamps.
+     */
+    getTurnStartedAt() {
+        return this.turnStartedAt;
+    }
+    getWorkflows() {
+        return this.deps.agent.listWorkflows();
+    }
+    getBackgroundTasks() {
+        return this.deps.processManager?.listTasks(this.sessionManager.getSessionFile())
+            ?? this.deps.agent.backgroundTasks?.list()
+            ?? [];
+    }
+    getChildTranscript(agentId) {
+        return reconstructDisplayMessages(this.deps.agent.getSubAgentMessages(agentId));
+    }
+    getChildStreamingTail(agentId) {
+        const child = this.childRuns.get(agentId);
+        if (!child?.visible)
+            return null;
+        const acc = child.state.accumulator;
+        return {
+            content: acc.content,
+            reasoning: acc.reasoning,
+            tools: acc.toolCalls.map((tool) => ({
+                ...tool,
+                args: { ...tool.args },
+                metadata: tool.metadata ? { ...tool.metadata } : undefined,
+            })),
+            parts: snapshotDisplayParts(acc.parts),
+        };
+    }
+    stopSubagent(agentId) {
+        void this.deps.agent.closeSubAgent(agentId);
+    }
+    stopWorkflow(runId) {
+        this.deps.agent.closeWorkflow(runId);
+    }
+    stopBackgroundTask(id) {
+        if (this.deps.processManager)
+            void this.deps.processManager.killTask(id);
+        else
+            void this.deps.agent.backgroundTasks?.kill?.(id);
+    }
+    getBackgroundTaskOutput(id) {
+        return this.deps.processManager?.taskOutputTail(id) ?? this.deps.agent.backgroundTasks?.outputTail(id) ?? "";
+    }
+    /** Called by the host after graceful task reaping on TUI exit. */
+    persistFinalTaskMarkers() {
+        this.taskRuntime?.persistTerminalSnapshot();
+    }
+    appendTaskMarker(file, marker, payload) {
+        try {
+            const manager = this.sessionManager.getSessionFile() === file
+                ? this.sessionManager
+                : new SessionManager(file);
+            manager.appendMarker(marker, payload);
+        }
+        catch {
+            // Lifecycle persistence is best-effort; it must never break the child.
+        }
+    }
+    announceTaskCompletion(task) {
+        // Switching back to the owner session reconstructs terminal task rows
+        // from its persisted marker before held completions are released. Treat
+        // that row as the same lifecycle event instead of appending a duplicate.
+        // Task ids repeat across processes, so the row must be this very run.
+        if (this.transcript.some((message) => message.toolCalls?.some((tool) => tool.metadata?.taskId === task.id
+            && tool.metadata?.taskLifecycle !== undefined
+            && tool.metadata?.endedAt === task.endedAt))) {
+            return;
+        }
+        const output = this.deps.processManager?.taskOutputTail(task.id, 12_000);
+        // Land the outcome on the launch row: this round's launches are still in
+        // the streaming accumulator, earlier rounds' have committed.
+        if (this.runActive && this.runState
+            && mergeTaskLifecycleIntoLiveTools(this.runState.accumulator.toolCalls, task, output)) {
+            this.state.touch();
+            this.notify();
+            return;
+        }
+        const landed = applyTaskLifecycleToMessages(this.transcript, task, output);
+        if (landed.merged) {
+            this.transcript = landed.messages;
+            this.state.touch();
+            this.notify();
+            return;
+        }
+        if (this.runActive) {
+            // Launch row not settled yet (or absent): retry on the next tool_end,
+            // and fall back to a detached row when the round commits.
+            this.pendingTaskAnnouncements.set(task.id, task);
+            this.state.touch();
+            this.notify();
+            return;
+        }
+        this.appendDisplayMessage(taskLifecycleDisplayMessage(task, output));
+    }
+    /** Pending completions whose launch row has settled since they arrived. */
+    landPendingTaskAnnouncementsInLiveRound() {
+        if (!this.runState || this.pendingTaskAnnouncements.size === 0)
+            return;
+        for (const [id, task] of this.pendingTaskAnnouncements) {
+            const output = this.deps.processManager?.taskOutputTail(task.id, 12_000);
+            if (mergeTaskLifecycleIntoLiveTools(this.runState.accumulator.toolCalls, task, output)) {
+                this.pendingTaskAnnouncements.delete(id);
+            }
+        }
+    }
+    /** Move the newest live Bash Execute into the unified task manager. */
+    promoteActiveBash() {
+        const channel = this.deps.promotionChannel;
+        if (!channel || !this.runState)
+            return undefined;
+        const tool = [...this.runState.accumulator.toolCalls]
+            .reverse()
+            .find((candidate) => candidate.name === "bash"
+            && candidate.status === "running"
+            && channel.hasPromotable(candidate.id));
+        return tool ? channel.requestPromotion(tool.id) : undefined;
+    }
+    /** Drop every transcript row (/clear). */
+    clearTranscript() {
+        this.transcript = [];
+        this.childRuns.clear();
+        this.state.touch();
+        this.notify();
+    }
+    /** Re-project the visible transcript after a non-controller command rewrites Agent history. */
+    rebuildTranscriptFromAgent() {
+        this.state.withTransaction(() => {
+            this.transcript = landTaskLifecycles(reconstructDisplayMessages([...this.deps.agent.messages]), restoredTaskLifecycles(this.sessionManager));
+            this.childRuns.clear();
+            this.state.touch();
+        });
+        this.notify();
+    }
+    /**
+     * 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.
+     */
+    async rewindToTurn(targetId, scope) {
+        if (this.runActive)
+            throw new Error("Cancel the active turn before rewinding.");
+        const result = await executeRewind(this.sessionManager, this.deps.agent, targetId, scope);
+        if (scope !== "code") {
+            this.state.withTransaction(() => {
+                purgeForSessionSwitch(this.queue);
+                this.queue.queued.length = 0;
+                this.transcript = landTaskLifecycles(reconstructDisplayMessages([...this.deps.agent.messages]), restoredTaskLifecycles(this.sessionManager));
+                this.childRuns.clear();
+                this.liveStreamVisible = false;
+                this.runState = null;
+                this.state.touch();
+            });
+            this.notify();
+        }
+        return result;
+    }
+    /** Host-side row injection (user echo, notices) — single append point. */
+    appendDisplayMessage(message) {
+        this.transcript = [...this.transcript, message];
+        this.state.touch();
+        this.notify();
+    }
+    isRunning() {
+        return this.runActive;
+    }
+    /** 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) {
+        if (this.runActive || this.commandActivity) {
+            throw new Error("Another operation is already running.");
+        }
+        const abortController = new AbortController();
+        this.commandActivity = {
+            kind,
+            status: "running",
+            startedAt: this.deps.ports.clock.now(),
+            abortController,
+        };
+        this.state.touch();
+        this.notify();
+        return abortController.signal;
+    }
+    finishCommandActivity(kind, event) {
+        if (this.commandActivity?.kind !== kind)
+            return;
+        this.state.withTransaction(() => {
+            if (event)
+                this.transcript = [...this.transcript, event];
+            this.commandActivity = null;
+            this.state.touch();
+        });
+        this.notify();
+        this.taskRuntime?.onIdle();
+    }
+    getCommandActivity() {
+        const activity = this.commandActivity;
+        if (!activity)
+            return null;
+        return {
+            kind: activity.kind,
+            status: activity.status,
+            startedAt: activity.startedAt,
+        };
+    }
+    isBusy() {
+        return this.runActive || this.commandActivity !== null;
+    }
+    /** 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) {
+        if (!this.commandActivity)
+            return false;
+        this.queueInput(input);
+        return true;
+    }
+    /** Queue a complete composer payload for the next provider turn. */
+    queueInput(input) {
+        const payload = typeof input === "string" ? { text: input, images: [] } : input;
+        const displayKey = nextDisplayMessageKey("queued");
+        this.queue.queued.push({
+            payload,
+            displayKey,
+            sessionFile: this.sessionManager.getSessionFile(),
+        });
+        this.transcript = [...this.transcript, {
+                key: displayKey,
+                role: "user",
+                content: this.submitDisplayText(payload),
+                images: displayImagesFromPayload(payload),
+                inputStatus: "queued",
+            }];
+        this.state.touch();
+        this.notify();
+    }
+    async drainQueuedInputs(cwd, agentOptions = {}) {
+        if (this.isBusy())
+            return;
+        const next = this.queue.queued.shift();
+        if (!next || this.disposed)
+            return;
+        if (next.displayKey) {
+            this.transcript = moveStatusMessageToEnd(this.transcript, next.displayKey);
+        }
+        this.state.touch();
+        this.notify();
+        await this.runTurn(next.payload, cwd, agentOptions);
+    }
+    pendingSteerCount() {
+        return this.queue.pendingSteers.size;
+    }
+    queuedInputCount() {
+        return this.queue.queued.length;
+    }
+    submitDisplayText(payload) {
+        return formatImageUserDisplayText(payload.displayText ?? payload.text, payload.images.length, payload.imageDisplayStart);
+    }
+    submitAgentInput(payload) {
+        if (payload.images.length === 0)
+            return payload.text;
+        return payload.displayText
+            ? buildImageContentPartsFromDisplayText(payload.displayText, payload.text, payload.images, payload.imageDisplayStart)
+            : buildImageContentParts(payload.text, payload.images);
+    }
+    /** Add input to the current Agent run without creating a second run that
+     * would overwrite the shared streaming accumulator. */
+    steer(content) {
+        if (!this.runActive || !this.activeInputController)
+            return false;
+        const input = this.activeInputController.tryEnqueue(content);
+        if (!input)
+            return false;
+        const displayKey = nextDisplayMessageKey("steer");
+        beginSteer(this.queue, {
+            id: input.id,
+            content,
+            displayKey,
+            sessionFile: this.sessionManager.getSessionFile(),
+        });
+        this.transcript = [...this.transcript, {
+                key: displayKey,
+                clientId: input.id,
+                role: "user",
+                content,
+                inputStatus: "pending_steer",
+            }];
+        this.state.touch();
+        this.notify();
+        return true;
+    }
+    cancelActiveRun(reason = "Interrupted by user") {
+        if (this.activeAbortController && !this.activeAbortController.signal.aborted) {
+            this.activeAbortController.abort(Object.assign(new Error(reason), { name: "AgentAbortError" }));
+            return true;
+        }
+        if (this.commandActivity && !this.commandActivity.abortController.signal.aborted) {
+            this.commandActivity.status = "cancelling";
+            this.commandActivity.abortController.abort(Object.assign(new Error(reason), { name: "AgentAbortError" }));
+            this.state.touch();
+            this.notify();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 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() {
+        if (!this.runActive || !this.runState || !this.liveStreamVisible)
+            return null;
+        const acc = this.runState.accumulator;
+        const parts = snapshotDisplayParts(acc.parts);
+        return {
+            content: acc.content,
+            // Ink kept the current provider turn's reasoning visible even after
+            // answer/tool bytes arrived. Never hide it based on another live field.
+            reasoning: acc.reasoning,
+            // Return a render-safe snapshot: reducer events continue mutating the
+            // accumulator in place while the TUI may still hold the previous tail.
+            tools: acc.toolCalls.map((tool) => ({
+                ...tool,
+                args: { ...tool.args },
+                metadata: tool.metadata ? { ...tool.metadata } : undefined,
+            })),
+            // Parts are the canonical commentary/tool/commentary timeline. Without
+            // them a live renderer necessarily moves every tool before all text.
+            parts,
+            // Phase is provider-turn local, matching Ink's clearAssistantStream().
+            // A tool in an earlier committed turn must not suppress fresh Thinking.
+            phase: acc.toolCalls.length > 0 ? "working" : "thinking",
+        };
+    }
+    pendingOverlayCount() {
+        return this.overlays.pendingCount();
+    }
+    /**
+     * Drive one agent run: reduce the event stream, apply effects, and finish.
+     * Mirrors runAgentInput (app.tsx:1438-1958) minus the rendering.
+     */
+    async runTurn(input, cwd, options) {
+        if (this.disposed)
+            throw new Error("controller disposed");
+        if (this.commandActivity) {
+            throw new Error("A command is already running.");
+        }
+        if (this.runActive) {
+            if (typeof input === "string") {
+                if (!this.steer(input))
+                    this.queueInput(input);
+            }
+            else if (isSubmitPayload(input)) {
+                if (input.images.length === 0) {
+                    if (!this.steer(input.text))
+                        this.queueInput(input);
+                }
+                else
+                    this.queueInput(input);
+            }
+            return;
+        }
+        const agentInput = isSubmitPayload(input) ? this.submitAgentInput(input) : input;
+        this.runActive = true;
+        this.liveStreamVisible = true;
+        this.turnStartedAt = Date.now();
+        this.runState = createRunState(Date.now());
+        const inputController = new AgentRunInputQueue(`run-${this.runState.accumulator.runId}`);
+        const abortController = new AbortController();
+        const goalStatusAtStart = this.goalRuntime?.snapshot()?.status;
+        const goalRun = options?.goalRun === true;
+        const agentOptions = { ...options };
+        delete agentOptions.goalRun;
+        if (isSubmitPayload(input) && input.images.length > 0 && input.displayText) {
+            agentOptions.userMessageUi = {
+                displayText: input.displayText,
+                ...(input.imageDisplayStart !== undefined
+                    ? { imageDisplayStart: input.imageDisplayStart }
+                    : {}),
+            };
+        }
+        let runUsageTokens = 0;
+        let runUsageReported = false;
+        let taskResultsForNextTurn = this.taskRuntime?.captureCurrentUndeliveredIds() ?? [];
+        this.activeInputController = inputController;
+        this.activeAbortController = abortController;
+        const upstreamAbort = () => abortController.abort(options?.abortSignal?.reason);
+        if (options?.abortSignal?.aborted)
+            upstreamAbort();
+        else
+            options?.abortSignal?.addEventListener("abort", upstreamAbort, { once: true });
+        this.state.touch();
+        this.notify();
+        const ctx = {
+            external: false,
+            isCurrentRun: () => !this.disposed,
+            now: () => this.deps.ports.clock.now(),
+            runStartedAt: this.deps.ports.clock.now(),
+            pendingSteers: this.queue.pendingSteers,
+        };
+        let runError;
+        let cancelled = false;
+        try {
+            for await (const event of this.deps.agent.run(agentInput, cwd, {
+                ...agentOptions,
+                abortSignal: abortController.signal,
+                inputController,
+            })) {
+                if (event.type === "turn_start") {
+                    this.taskRuntime?.markResultsDelivered(taskResultsForNextTurn);
+                    taskResultsForNextTurn = [];
+                }
+                if (event.type === "turn_end" && event.usage) {
+                    runUsageReported = true;
+                    runUsageTokens += tokenUsageTotal(event.usage);
+                }
+                const { state, effects } = reduceAgentEvent(this.runState, event, ctx);
+                this.runState = state;
+                if (event.type === "tool_end")
+                    this.landPendingTaskAnnouncementsInLiveRound();
+                const subagentMetadata = event.type === "tool_update"
+                    ? event.update.metadata
+                    : event.type === "tool_end"
+                        ? event.result.metadata
+                        : undefined;
+                if (event.type === "tool_update"
+                    && subagentMetadata?.kind === "subagent"
+                    && effects.some((effect) => effect.kind === "live-subagent-changed")) {
+                    // The launching call already committed: merge the update into its
+                    // transcript entry so the settled row stays the single source of
+                    // truth for live and settled rendering alike.
+                    this.transcript = applySubagentUpdateToMessages(this.transcript, {
+                        id: event.id,
+                        name: event.name,
+                        metadata: subagentMetadata,
+                    });
+                }
+                else if (subagentMetadata?.kind === "subagent") {
+                    this.transcript = mergeSubagentSnapshotsIntoMessages(this.transcript, subagentMetadata);
+                }
+                if (event.type === "tool_update" && event.update.childEvent) {
+                    this.reduceChildEvent(event.update.subAgentId, event.update.childEvent);
+                }
+                if (event.type === "input_rejected") {
+                    const steer = this.queue.pendingSteers.get(event.id);
+                    if (steer) {
+                        this.queue.pendingSteers.delete(event.id);
+                        this.queue.queued.push({
+                            payload: { text: event.content, images: [] },
+                            displayKey: steer.displayKey,
+                            sessionFile: steer.sessionFile ?? this.sessionManager.getSessionFile(),
+                        });
+                        this.transcript = this.transcript.map((message) => (message.key === steer.displayKey ? setUserInputStatus(message, "queued") : message));
+                    }
+                }
+                else if (event.type === "input_applied") {
+                    this.queue.pendingSteers.delete(event.id);
+                }
+                // Visibility is an event-boundary concern, not a generic consequence
+                // of clearing the accumulator. A provider turn_start/retry must keep
+                // the empty waiting spinner mounted; only turn_end hides the live tail
+                // in the same transaction that commits its settled replacement.
+                if (event.type === "turn_end") {
+                    if (event.willContinue) {
+                        taskResultsForNextTurn = this.taskRuntime?.captureCurrentUndeliveredIds() ?? [];
+                    }
+                    this.liveStreamVisible = !!event.willContinue;
+                }
+                else if (event.type === "turn_start"
+                    || event.type === "text_delta"
+                    || event.type === "reasoning_delta"
+                    || event.type === "tool_call_start"
+                    || event.type === "tool_start") {
+                    this.liveStreamVisible = true;
+                }
+                if (event.type === "turn_end") {
+                    // Commit the provider turn and replace its accumulator in the same
+                    // observable frame. For a continuation, keep an empty waiting tail;
+                    // for a final boundary, keep it hidden. Clearing the accumulator at
+                    // BOTH boundaries is important: Agent still performs cleanup after
+                    // final turn_end, and an error there must not commit the settled
+                    // answer a second time from the stale accumulator.
+                    this.state.withTransaction(() => {
+                        for (const effect of effects)
+                            this.applyEffectMutation(effect);
+                        this.runState = createRunState(this.runState?.accumulator.runId ?? Date.now());
+                        this.liveStreamVisible = !!event.willContinue;
+                        this.state.touch();
+                    });
+                    this.notify();
+                }
+                else {
+                    this.applyEffects(effects);
+                }
+                const hasDirty = Object.values(this.runState.dirty).some(Boolean);
+                // Streamed text, reasoning, and tool arguments share one 40ms paint.
+                // Repainting each argument chunk can starve input/timers while a
+                // buffered response drains, especially with a long reasoning preview.
+                // Tool lifecycle events still notify immediately through their effects.
+                // Dirty means "paint pending", not
+                // "this run has ever changed", and must never remain latched forever.
+                if (hasDirty && (event.type === "text_delta" || event.type === "reasoning_delta" || event.type === "tool_call_delta")) {
+                    this.deps.ports.flush.scheduleFlush(STREAMING_FLUSH_INTERVAL_MS, () => {
+                        if (this.disposed || !this.runActive)
+                            return;
+                        this.state.touch();
+                        this.notify();
+                    });
+                }
+                if (hasDirty) {
+                    this.runState = {
+                        ...this.runState,
+                        dirty: { content: false, reasoning: false, parts: false, tools: false },
+                    };
+                }
+            }
+        }
+        catch (error) {
+            runError = error;
+            cancelled = this.isAbortLike(error);
+            // Legacy catch (app.tsx:1855-1861): commit the partial answer before
+            // surfacing the interrupt/error so streamed content is not lost.
+            const partial = this.runState ? buildAssistantMessage(this.runState) : null;
+            // The partial commit, error effect, and live-tail removal are one frame.
+            // Publishing the partial first used to expose {settled, live:true}, then
+            // finally removed the tail in a second frame (visible duplication).
+            this.state.withTransaction(() => {
+                if (partial)
+                    this.transcript = [...this.transcript, partial];
+                this.liveStreamVisible = false;
+                this.applyEffectMutation({ kind: "run-error", error });
+                this.state.touch();
+            });
+            this.notify();
+        }
+        finally {
+            const leftoverSteers = inputController.closePendingInputs();
+            // The signal is the source of truth. A provider may observe cancellation
+            // and end its iterator without throwing, but the user's pending steers
+            // must still be dropped exactly as they are in the Ink implementation.
+            cancelled ||= abortController.signal.aborted;
+            for (const leftover of leftoverSteers) {
+                const steer = this.queue.pendingSteers.get(leftover.id);
+                if (!steer)
+                    continue;
+                this.queue.pendingSteers.delete(leftover.id);
+                if (cancelled) {
+                    this.transcript = this.transcript.filter((message) => message.key !== steer.displayKey);
+                }
+                else {
+                    this.queue.queued.push({
+                        payload: { text: leftover.content, images: [] },
+                        displayKey: steer.displayKey,
+                        sessionFile: steer.sessionFile ?? this.sessionManager.getSessionFile(),
+                    });
+                    this.transcript = this.transcript.map((message) => (message.key === steer.displayKey ? setUserInputStatus(message, "queued") : message));
+                }
+            }
+            const finish = reduceRunFinish(this.runState ?? createRunState(0), {
+                cancelled,
+                errored: runError != null && !cancelled,
+                // Leftovers were already applied above while their display metadata
+                // was still available. Do not ask the reducer to emit a second drain.
+                leftoverSteers: [],
+                ownsCurrentGeneration: true,
+            });
+            this.state.withTransaction(() => {
+                for (const effect of finish.effects)
+                    this.applyEffectMutation(effect);
+                this.deps.ports.flush.cancelFlush();
+                this.runActive = false;
+                this.liveStreamVisible = false;
+                this.runState = null;
+                this.activeInputController = null;
+                this.activeAbortController = null;
+                if (this.pendingTaskAnnouncements.size > 0) {
+                    this.transcript = landTaskLifecycles(this.transcript, [...this.pendingTaskAnnouncements.values()].map((task) => ({
+                        task,
+                        output: this.deps.processManager?.taskOutputTail(task.id, 12_000),
+                    })));
+                    this.pendingTaskAnnouncements.clear();
+                }
+                this.state.touch();
+            });
+            this.notify();
+            options?.abortSignal?.removeEventListener("abort", upstreamAbort);
+        }
+        this.goalRuntime?.afterRun({
+            goalRun,
+            goalStatusAtStart,
+            cancelled,
+            errored: runError != null && !cancelled,
+            usageTokens: runUsageTokens,
+            usageReported: runUsageReported,
+        }, cwd);
+        this.taskRuntime?.onIdle();
+        await this.drainQueuedInputs(cwd, agentOptions);
+    }
+    /** Apply one reducer transition and publish exactly one observable snapshot. */
+    applyEffects(effects) {
+        if (effects.length === 0)
+            return;
+        this.state.withTransaction(() => {
+            for (const effect of effects)
+                this.applyEffectMutation(effect);
+        });
+        this.notify();
+    }
+    /** Mutate for one effect; callers own the surrounding transaction + notify. */
+    applyEffectMutation(effect) {
+        this.deps.onEffect?.(effect);
+        switch (effect.kind) {
+            case "stream-cleared":
+                this.deps.ports.flush.cancelFlush();
+                break;
+            case "assistant-committed": {
+                const message = this.runState ? buildAssistantMessage(this.runState, effect.taskElapsedMs) : null;
+                if (message)
+                    this.transcript = [...this.transcript, message];
+                break;
+            }
+            case "transcript-append":
+                this.transcript = [...this.transcript, effect.message];
+                break;
+            case "notice":
+                this.transcript = [...this.transcript, {
+                        key: `notice-${this.transcript.length}`,
+                        role: effect.role === "error" ? "error" : "assistant",
+                        content: effect.text,
+                        syntheticKind: effect.role === "error" ? undefined : "ui_notice",
+                    }];
+                break;
+            case "queue-updated":
+                void effect.pending;
+                break;
+            case "steer-applied":
+                this.transcript = moveStatusMessageToEnd(this.transcript, effect.displayKey);
+                break;
+            case "steer-requeued":
+                // The event loop records the rejected content and queued badge.
+                break;
+            case "run-error": {
+                const message = effect.error instanceof Error ? effect.error.message : String(effect.error);
+                if (this.isAbortLike(effect.error)) {
+                    this.transcript = [...this.transcript, {
+                            key: nextDisplayMessageKey("interrupt"),
+                            role: "assistant",
+                            content: message || "Interrupted by user",
+                            syntheticKind: "ui_interrupt",
+                        }];
+                }
+                else {
+                    this.transcript = [...this.transcript, {
+                            key: nextDisplayMessageKey("error"),
+                            role: "error",
+                            content: message || "Agent run failed",
+                        }];
+                }
+                break;
+            }
+            default:
+                break;
+        }
+        this.state.touch();
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener(this.state.version);
+    }
+    reduceChildEvent(agentId, event) {
+        const current = this.childRuns.get(agentId) ?? {
+            state: createRunState(Date.now()),
+            visible: true,
+            updatedAt: Date.now(),
+        };
+        const reduced = reduceAgentEvent(current.state, event, {
+            external: false,
+            isCurrentRun: () => !this.disposed,
+            now: () => this.deps.ports.clock.now(),
+            runStartedAt: current.state.accumulator.runId,
+            pendingSteers: new Map(),
+        });
+        let state = reduced.state;
+        let visible = current.visible;
+        if (event.type === "turn_start")
+            visible = true;
+        if (event.type === "turn_end") {
+            state = createRunState(current.state.accumulator.runId);
+            visible = !!event.willContinue;
+        }
+        this.childRuns.set(agentId, { state, visible, updatedAt: Date.now() });
+    }
+    isAbortLike(error) {
+        return error instanceof Error && (error.name === "AbortError" || error.name === "AgentAbortError");
+    }
+    /** Drain leftover steers at run end (cancelled drops, normal requeues). */
+    drainLeftovers(leftovers, cancelled) {
+        drainLeftoverSteers(this.queue, leftovers, { cancelled });
+        this.state.touch();
+    }
+    /** Atomic session switch through the two-phase transaction. */
+    switchSession(plan) {
+        if (this.isBusy())
+            return { ok: false, error: "Stop the current run before switching sessions." };
+        const outcome = this.sessionTransition.switchTo(plan);
+        if (outcome.ok && outcome.manager) {
+            this.goalRuntime?.loadCurrentSession();
+            this.taskRuntime?.releaseHeldCompletions(outcome.manager.getSessionFile());
+            this.notify();
+        }
+        return outcome.ok ? { ok: true } : { ok: false, error: outcome.error };
+    }
+    /** Start an empty native session using the same atomic lifecycle as resume. */
+    createFreshSession(cwd, notice) {
+        if (this.isBusy())
+            return { ok: false, error: "Stop the current run before starting a new session." };
+        const outcome = this.sessionTransition.createFresh(cwd, notice);
+        if (outcome.ok && outcome.manager) {
+            this.goalRuntime?.loadCurrentSession();
+            this.taskRuntime?.releaseHeldCompletions(outcome.manager.getSessionFile());
+            this.notify();
+        }
+        return outcome.ok ? { ok: true } : { ok: false, error: outcome.error };
+    }
+    /**
+     * Shutdown: settle overlays, cancel any run, and report the exit summary.
+     * Idempotent — a second call is a no-op.
+     */
+    shutdown(reason) {
+        if (this.disposed) {
+            return { reason, wallMs: Date.now() - this.startedAtMs };
+        }
+        this.disposed = true;
+        this.cancelActiveRun(reason);
+        this.goalRuntime?.dispose();
+        this.taskRuntime?.dispose();
+        this.overlays.dispose();
+        this.backgroundTaskUnsubscribe?.();
+        this.deps.ports.flush.cancelFlush();
+        return { reason, wallMs: Date.now() - this.startedAtMs };
+    }
+}
+function restoredTaskLifecycles(manager) {
+    let entries;
+    try {
+        entries = manager.getEntries();
+    }
+    catch {
+        return [];
+    }
+    let startIndex = 0;
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.type === "marker" && entry.kind === "conversation_clear") {
+            startIndex = index + 1;
+            break;
+        }
+    }
+    const starts = new Map();
+    // Ids restart at task_0001 per process: count launches per id so each
+    // terminal marker lands on the launch row it belongs to.
+    const launches = new Map();
+    const terminals = [];
+    for (let index = startIndex; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (entry?.type !== "marker" || !entry.value)
+            continue;
+        let payload;
+        try {
+            payload = JSON.parse(entry.value);
+        }
+        catch {
+            continue;
+        }
+        const id = typeof payload.id === "string" ? payload.id : undefined;
+        if (!id)
+            continue;
+        if (entry.kind === "task_started") {
+            starts.set(id, payload);
+            launches.set(id, (launches.get(id) ?? 0) + 1);
+            continue;
+        }
+        if (entry.kind !== "task_finished" && entry.kind !== "task_killed")
+            continue;
+        const start = starts.get(id) ?? {};
+        const status = entry.kind === "task_killed"
+            ? "killed"
+            : payload.status === "failed"
+                ? "failed"
+                : "completed";
+        const startedAt = numeric(payload.startedAt) ?? numeric(start.startedAt) ?? entry.timestamp;
+        const endedAt = numeric(payload.endedAt) ?? entry.timestamp;
+        const seen = launches.get(id) ?? 0;
+        terminals.push({
+            // A start persisted before conversation_clear is out of scope: keep its
+            // terminal state detached rather than landing it on a later reuse.
+            occurrence: seen > 0 ? seen - 1 : UNMATCHED_LAUNCH,
+            task: {
+                kind: "task",
+                id,
+                command: stringValue(payload.command) ?? stringValue(start.command) ?? id,
+                description: stringValue(payload.description) ?? stringValue(start.description),
+                cwd: manager.getMetadata().cwd ?? process.cwd(),
+                pid: numeric(start.pid),
+                status,
+                exitCode: typeof payload.exitCode === "number" ? payload.exitCode : null,
+                startedAt,
+                endedAt,
+                outputTruncated: false,
+                outputLines: numeric(payload.outputLines) ?? 0,
+                ownerSessionId: manager.getSessionFile(),
+            },
+            output: stringValue(payload.output),
+        });
+    }
+    return terminals;
+}
+function numeric(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}