@jawcode-dev/coding-agent 1.1.0

package/src/modes/controllers/event-controller.ts

@@ -0,0 +1,1054 @@
+import { INTENT_FIELD } from "@jawcode-dev/agent-core";
+import { calculatePromptTokens } from "@jawcode-dev/agent-core/compaction/compaction";
+import type { AssistantMessage, ImageContent } from "@jawcode-dev/ai";
+import { parseRateLimitReason } from "@jawcode-dev/ai";
+import { type Component, Loader, TERMINAL, Text } from "@jawcode-dev/tui";
+import { settings } from "../../config/settings";
+import { isJawBrand } from "../../discovery/helpers";
+import { AssistantMessageComponent } from "../../modes/components/assistant-message";
+import {
+	ReadToolGroupComponent,
+	readArgsHaveTarget,
+	readArgsTargetInternalUrl,
+} from "../../modes/components/read-tool-group";
+import { TodoReminderComponent } from "../../modes/components/todo-reminder";
+import { ToolExecutionComponent } from "../../modes/components/tool-execution";
+import { TtsrNotificationComponent } from "../../modes/components/ttsr-notification";
+import { getSymbolTheme, theme } from "../../modes/theme/theme";
+import type { InteractiveModeContext, TodoPhase } from "../../modes/types";
+import { CompactionProgressPresenter } from "../../modes/utils/compaction-progress";
+import { commitLaneEnabled, markLiveToggleEligible } from "../../modes/utils/ui-helpers";
+import type { PlanApprovalDetails } from "../../plan-mode/approved-plan";
+import type { AgentSessionEvent } from "../../session/agent-session";
+import { isSilentAbort, readPendingDisplayTag } from "../../session/messages";
+import type { ResolveToolDetails } from "../../tools/resolve";
+import { interruptHint } from "../shared";
+
+type AgentSessionEventKind = AgentSessionEvent["type"];
+
+const IRC_MESSAGE_VISIBLE_TTL_MS = 10_000;
+
+function friendlyRetryReason(errorMessage: string | undefined): string {
+	if (!errorMessage) return "";
+	switch (parseRateLimitReason(errorMessage)) {
+		case "RATE_LIMIT_EXCEEDED":
+			return "rate limited";
+		case "QUOTA_EXHAUSTED":
+			return "usage limit";
+		case "MODEL_CAPACITY_EXHAUSTED":
+			return "overloaded";
+		case "SERVER_ERROR":
+			return "server error";
+		default:
+			return /network|connection|socket|fetch failed|terminated|timeout|timed out|stream/i.test(errorMessage)
+				? "connection error"
+				: "transient error";
+	}
+}
+
+type AgentSessionEventHandlers = {
+	[E in AgentSessionEventKind]: (event: Extract<AgentSessionEvent, { type: E }>) => Promise<void>;
+};
+
+export class EventController {
+	#lastReadGroup: ReadToolGroupComponent | undefined = undefined;
+	#lastThinkingCount = 0;
+	#renderedCustomMessages = new Set<string>();
+	#lastIntent: string | undefined = undefined;
+	#backgroundToolCallIds = new Set<string>();
+	/** 99.20.04 — active tool components currently rendered in the live zone. */
+	#liveToolComponents = new Set<ToolExecutionComponent>();
+	#readToolCallArgs = new Map<string, Record<string, unknown>>();
+	#readToolCallAssistantComponents = new Map<string, AssistantMessageComponent>();
+	#lastAssistantComponent: AssistantMessageComponent | undefined = undefined;
+	#idleCompactionTimer?: NodeJS.Timeout;
+	#ircExpiryTimers = new Map<string, NodeJS.Timeout>();
+	#handlers: AgentSessionEventHandlers;
+
+	constructor(private ctx: InteractiveModeContext) {
+		this.#handlers = {
+			agent_start: e => this.#handleAgentStart(e),
+			agent_end: e => this.#handleAgentEnd(e),
+			turn_start: async () => {},
+			turn_end: async () => {},
+			message_start: e => this.#handleMessageStart(e),
+			message_update: e => this.#handleMessageUpdate(e),
+			message_end: e => this.#handleMessageEnd(e),
+			tool_execution_start: e => this.#handleToolExecutionStart(e),
+			tool_execution_update: e => this.#handleToolExecutionUpdate(e),
+			tool_execution_end: e => this.#handleToolExecutionEnd(e),
+			auto_compaction_start: e => this.#handleAutoCompactionStart(e),
+			auto_compaction_end: e => this.#handleAutoCompactionEnd(e),
+			compaction_progress: e => this.#handleCompactionProgress(e),
+			auto_retry_start: e => this.#handleAutoRetryStart(e),
+			auto_retry_end: e => this.#handleAutoRetryEnd(e),
+			retry_fallback_applied: e => this.#handleRetryFallbackApplied(e),
+			retry_fallback_succeeded: e => this.#handleRetryFallbackSucceeded(e),
+			ttsr_triggered: e => this.#handleTtsrTriggered(e),
+			todo_reminder: e => this.#handleTodoReminder(e),
+			todo_auto_clear: e => this.#handleTodoAutoClear(e),
+			irc_message: e => this.#handleIrcMessage(e),
+			notice: e => this.#handleNotice(e),
+			thinking_level_changed: async () => {},
+			goal_updated: async () => {},
+		} satisfies AgentSessionEventHandlers;
+	}
+
+	dispose(): void {
+		this.#cancelIdleCompaction();
+		this.#clearRetryCountdown();
+		if (this.ctx.retryEscapeHandler) {
+			this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
+			this.ctx.retryEscapeHandler = undefined;
+		}
+		if (this.ctx.retryLoader) {
+			this.ctx.retryLoader.stop();
+			this.ctx.retryLoader = undefined;
+		}
+		this.ctx.autoCompactionProgressPresenter?.stop();
+		this.ctx.autoCompactionProgressPresenter = undefined;
+		for (const timer of this.#ircExpiryTimers.values()) {
+			clearTimeout(timer);
+		}
+		this.#ircExpiryTimers.clear();
+	}
+
+	#resetReadGroup(): void {
+		this.#lastReadGroup = undefined;
+	}
+
+	/** 99.20.04 — unset setting falls back to the brand default (jwc: commit). */
+	#commitFoldingEnabled(): boolean {
+		const mode = settings.get("tool.renderMode");
+		return (mode ?? (isJawBrand() ? "commit" : "verbose")) === "commit";
+	}
+
+	/**
+	 * 99.20.04 — move a finished live-zone tool into the chat history as a
+	 * collapsed line (commit-time folding). No-op for components that never
+	 * went through the live zone (verbose mode, read groups).
+	 */
+	#commitLiveTool(component: unknown): void {
+		if (!(component instanceof ToolExecutionComponent) || !this.#liveToolComponents.has(component)) return;
+		this.#liveToolComponents.delete(component);
+		this.ctx.liveToolContainer.removeChild(component);
+		component.setMinimized?.(true);
+		markLiveToggleEligible(component, true);
+		// 083.9 P4: stays interactive in the chat until the next prompt submit —
+		// the turn-boundary backlog sweep (commitFinalizedBacklog) commits it.
+		this.ctx.chatContainer.addChild(component);
+	}
+
+	#getReadGroup(): ReadToolGroupComponent {
+		if (!this.#lastReadGroup) {
+			this.ctx.chatContainer.addChild(new Text("", 0, 0));
+			const group = new ReadToolGroupComponent({
+				showContentPreview: this.ctx.settings.get("read.toolResultPreview"),
+			});
+			markLiveToggleEligible(group, true);
+			group.setExpanded(this.ctx.toolOutputExpanded);
+			this.ctx.chatContainer.addChild(group);
+			this.#lastReadGroup = group;
+		}
+		return this.#lastReadGroup;
+	}
+
+	#trackReadToolCall(toolCallId: string, args: unknown): void {
+		if (!toolCallId) return;
+		const normalizedArgs =
+			args && typeof args === "object" && !Array.isArray(args) ? (args as Record<string, unknown>) : {};
+		this.#readToolCallArgs.set(toolCallId, normalizedArgs);
+		const assistantComponent = this.ctx.streamingComponent ?? this.#lastAssistantComponent;
+		if (assistantComponent) {
+			this.#readToolCallAssistantComponents.set(toolCallId, assistantComponent);
+		}
+	}
+
+	#clearReadToolCall(toolCallId: string): void {
+		this.#readToolCallArgs.delete(toolCallId);
+		this.#readToolCallAssistantComponents.delete(toolCallId);
+	}
+
+	#inlineReadToolImages(
+		toolCallId: string,
+		result: { content: Array<{ type: string; data?: string; mimeType?: string }> },
+	): boolean {
+		if (!settings.get("terminal.showImages")) return false;
+		const assistantComponent = this.#readToolCallAssistantComponents.get(toolCallId);
+		if (!assistantComponent) return false;
+		const images: ImageContent[] = result.content
+			.filter(
+				(content): content is ImageContent =>
+					content.type === "image" && typeof content.data === "string" && typeof content.mimeType === "string",
+			)
+			.map(content => ({ type: "image", data: content.data, mimeType: content.mimeType }));
+		if (images.length === 0) return false;
+		assistantComponent.setToolResultImages(toolCallId, images);
+		return true;
+	}
+	#updateWorkingMessageFromIntent(intent: unknown): void {
+		// Streamed JSON can deliver non-string `_i` (object, number, boolean) before
+		// schema validation; `?.` only guards null/undefined, so guard the type too.
+		if (typeof intent !== "string") return;
+		const trimmed = intent.trim();
+		if (!trimmed || trimmed === this.#lastIntent) return;
+		this.#lastIntent = trimmed;
+		this.ctx.setWorkingMessage(`${trimmed}${interruptHint()}`);
+	}
+
+	subscribeToAgent(): void {
+		this.ctx.unsubscribe = this.ctx.session.subscribe(async (event: AgentSessionEvent) => {
+			await this.handleEvent(event);
+		});
+	}
+
+	async handleEvent(event: AgentSessionEvent): Promise<void> {
+		if (!this.ctx.isInitialized) {
+			await this.ctx.init();
+		}
+
+		this.ctx.statusLine.invalidate();
+		this.ctx.updateEditorTopBorder();
+
+		const run = this.#handlers[event.type] as (e: AgentSessionEvent) => Promise<void>;
+		await run(event);
+	}
+
+	async #handleAgentStart(_event: Extract<AgentSessionEvent, { type: "agent_start" }>): Promise<void> {
+		this.#lastIntent = undefined;
+		this.#readToolCallArgs.clear();
+		this.#readToolCallAssistantComponents.clear();
+		this.#lastAssistantComponent = undefined;
+		if (this.ctx.retryEscapeHandler) {
+			this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
+			this.ctx.retryEscapeHandler = undefined;
+		}
+		if (this.ctx.retryLoader) {
+			this.ctx.retryLoader.stop();
+			this.#clearRetryCountdown();
+			this.ctx.retryLoader = undefined;
+			this.ctx.statusContainer.clear();
+		}
+		this.#cancelIdleCompaction();
+		this.ctx.ensureLoadingAnimation();
+		this.ctx.ui.requestRender();
+	}
+
+	async #handleMessageStart(event: Extract<AgentSessionEvent, { type: "message_start" }>): Promise<void> {
+		if (event.message.role === "hookMessage" || event.message.role === "custom") {
+			const signature = `${event.message.role}:${event.message.customType}:${event.message.timestamp}`;
+			if (this.#renderedCustomMessages.has(signature)) {
+				return;
+			}
+			this.#renderedCustomMessages.add(signature);
+			this.#resetReadGroup();
+			this.ctx.addMessageToChat(event.message);
+			// Tag-keyed pending-bar refresh: when AgentSession.#handleAgentEvent
+			// spliced this dequeued custom message out of #steeringMessages /
+			// #followUpMessages (it ran before this emit), the array state is
+			// already correct — pendingMessagesContainer just needs to be
+			// re-rendered to match. Gated on tag presence so non-queued customs
+			// (ttsr-injection, irc:*, async-result, hookMessage) skip the
+			// rebuild; their dispatch path never registered a pending chip.
+			// Mirrors the user-role refresh at the bottom of this function.
+			if (event.message.role === "custom" && readPendingDisplayTag(event.message.details)) {
+				this.ctx.updatePendingMessagesDisplay();
+			}
+			this.ctx.ui.requestRender();
+		} else if (event.message.role === "user") {
+			const textContent = this.ctx.getUserMessageText(event.message);
+			const imageCount =
+				typeof event.message.content === "string"
+					? 0
+					: event.message.content.filter(content => content.type === "image").length;
+			const signature = `${textContent}\u0000${imageCount}`;
+
+			this.#resetReadGroup();
+			const wasOptimistic = this.ctx.optimisticUserMessageSignature === signature;
+			const wasLocallySubmitted = this.ctx.locallySubmittedUserSignatures.delete(signature) || wasOptimistic;
+			if (!wasOptimistic) {
+				this.ctx.addMessageToChat(event.message);
+			}
+			if (wasOptimistic) {
+				this.ctx.optimisticUserMessageSignature = undefined;
+			}
+
+			// Clear the editor only when the submission did not originate from a
+			// local submission (optimistic or queued-while-streaming). Both local
+			// paths already cleared the editor at submit time; clearing again here
+			// would race with the user typing the next prompt while the previous
+			// large redraw lands and erase their in-progress draft (#783).
+			if (!event.message.synthetic) {
+				this.ctx.currentTurnStartIndex = this.ctx.chatContainer.children.length;
+				if (!wasLocallySubmitted) {
+					this.ctx.editor.setText("");
+				}
+				this.ctx.updatePendingMessagesDisplay();
+			}
+			this.ctx.ui.requestRender();
+		} else if (event.message.role === "fileMention") {
+			this.#resetReadGroup();
+			this.ctx.addMessageToChat(event.message);
+			this.ctx.ui.requestRender();
+		} else if (event.message.role === "assistant") {
+			this.#lastThinkingCount = 0;
+			this.#segmentStartIndex = 0;
+			this.#resetReadGroup();
+			// 083.1: a new assistant message means the previous tool batch is done —
+			// collapse its last tool too (new tools in this message start a new chain).
+			this.ctx.lastToolComponent?.setMinimized?.(true);
+			this.ctx.lastToolComponent = undefined;
+			this.ctx.streamingComponent = new AssistantMessageComponent(undefined, this.ctx.hideThinkingBlock, () =>
+				this.ctx.ui.requestRender(),
+			);
+			this.ctx.streamingComponent.setThinkingExpanded(this.ctx.thinkingExpanded);
+			this.ctx.streamingComponent.setStreaming(true);
+			markLiveToggleEligible(this.ctx.streamingComponent, true);
+			this.ctx.streamingMessage = event.message;
+			this.ctx.chatContainer.addChild(this.ctx.streamingComponent);
+			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage);
+			this.ctx.ui.requestRender();
+		}
+	}
+
+	async #handleIrcMessage(event: Extract<AgentSessionEvent, { type: "irc_message" }>): Promise<void> {
+		const signature = `${event.message.role}:${event.message.customType}:${event.message.timestamp}`;
+		if (this.#renderedCustomMessages.has(signature)) {
+			return;
+		}
+		this.#renderedCustomMessages.add(signature);
+		this.#resetReadGroup();
+		const components = this.ctx.addMessageToChat(event.message);
+		this.#scheduleIrcExpiry(signature, components);
+		this.ctx.ui.requestRender();
+	}
+
+	#scheduleIrcExpiry(signature: string, components: Component[]): void {
+		if (components.length === 0 || this.#ircExpiryTimers.has(signature)) return;
+		const timer = setTimeout(() => {
+			this.#ircExpiryTimers.delete(signature);
+			for (const component of components) {
+				this.ctx.chatContainer.removeChild(component);
+			}
+			this.ctx.ui.requestRender();
+		}, IRC_MESSAGE_VISIBLE_TTL_MS);
+		timer.unref?.();
+		this.#ircExpiryTimers.set(signature, timer);
+	}
+
+	async #handleNotice(event: Extract<AgentSessionEvent, { type: "notice" }>): Promise<void> {
+		const message = event.source ? `${event.source}: ${event.message}` : event.message;
+		if (event.level === "error") {
+			this.ctx.showError(message);
+		} else if (event.level === "warning") {
+			this.ctx.showWarning(message);
+		} else {
+			this.ctx.showStatus(message);
+		}
+	}
+
+	/**
+	 * 083.3: first content-block index of the current assistant segment. Thinking/
+	 * text arriving after a toolCall starts a new segment component appended
+	 * below the tool rows, preserving the reasoning→tool→reasoning timeline.
+	 */
+	#segmentStartIndex = 0;
+
+	/** Render the current segment's slice of the streaming assistant message. */
+	#segmentSlice(message: AssistantMessage): AssistantMessage {
+		if (this.#segmentStartIndex === 0) return message;
+		return { ...message, content: message.content.slice(this.#segmentStartIndex) };
+	}
+
+	async #handleMessageUpdate(event: Extract<AgentSessionEvent, { type: "message_update" }>): Promise<void> {
+		if (this.ctx.streamingComponent && event.message.role === "assistant") {
+			this.ctx.streamingMessage = event.message;
+			// 083.3: visible thinking/text after the latest toolCall → cut a new
+			// segment so it renders below the tool rows instead of merging into
+			// the original block above them.
+			const content = event.message.content;
+			let lastToolIndex = -1;
+			for (let i = content.length - 1; i >= 0; i--) {
+				if (content[i].type === "toolCall") {
+					lastToolIndex = i;
+					break;
+				}
+			}
+			if (lastToolIndex >= this.#segmentStartIndex) {
+				const hasPostToolContent = content
+					.slice(lastToolIndex + 1)
+					.some(c => (c.type === "text" && c.text.trim()) || (c.type === "thinking" && c.thinking.trim()));
+				if (hasPostToolContent) {
+					this.#segmentStartIndex = lastToolIndex + 1;
+					// The tools above this segment are done — collapse the last one (083.1).
+					this.ctx.lastToolComponent?.setMinimized?.(true);
+					this.ctx.lastToolComponent = undefined;
+					// The previous segment is settled — its trailing thinking collapses (083.5).
+					this.ctx.streamingComponent.setStreaming(false);
+					this.ctx.streamingComponent = new AssistantMessageComponent(undefined, this.ctx.hideThinkingBlock, () =>
+						this.ctx.ui.requestRender(),
+					);
+					this.ctx.streamingComponent.setThinkingExpanded(this.ctx.thinkingExpanded);
+					this.ctx.streamingComponent.setStreaming(true);
+					markLiveToggleEligible(this.ctx.streamingComponent, true);
+					this.ctx.chatContainer.addChild(this.ctx.streamingComponent);
+				}
+			}
+			// 083.9 P3: under live-zone overflow, shed settled blocks (everything
+			// before the currently streaming block) from the frame — their pixels
+			// stay on screen/scrollback via the viewport repaint (083.8 S3), a
+			// de-facto commit. The component then renders only the active tail,
+			// keeping the frame near viewport size (Codex stable-line parity).
+			if (
+				commitLaneEnabled() &&
+				this.ctx.ui.viewportFillRows === 0 &&
+				typeof this.ctx.ui.commitLines === "function"
+			) {
+				let lastVisible = -1;
+				for (let i = content.length - 1; i >= this.#segmentStartIndex; i--) {
+					const c = content[i];
+					if ((c.type === "text" && c.text.trim()) || (c.type === "thinking" && c.thinking.trim())) {
+						lastVisible = i;
+						break;
+					}
+				}
+				if (lastVisible > this.#segmentStartIndex) {
+					this.#segmentStartIndex = lastVisible;
+				}
+			}
+			this.ctx.streamingComponent.updateContent(this.#segmentSlice(this.ctx.streamingMessage));
+
+			const thinkingCount = this.ctx.streamingMessage.content.filter(
+				content => content.type === "thinking" && content.thinking.trim(),
+			).length;
+			if (thinkingCount > this.#lastThinkingCount) {
+				this.#resetReadGroup();
+				this.#lastThinkingCount = thinkingCount;
+			}
+
+			// A toolcall_delta only mutates the block at its contentIndex. Re-sending
+			// every settled sibling through updateArgs re-clones and re-renders their
+			// full args per token, turning multi-tool turns quadratic in completed
+			// content (second-Write-crawls bug) — on delta events, skip blocks that
+			// already have a component and aren't the active one.
+			const activeToolCallIndex =
+				event.assistantMessageEvent.type === "toolcall_delta" &&
+				typeof event.assistantMessageEvent.contentIndex === "number"
+					? event.assistantMessageEvent.contentIndex
+					: undefined;
+			const streamingContent = this.ctx.streamingMessage.content;
+			for (let blockIndex = 0; blockIndex < streamingContent.length; blockIndex++) {
+				const content = streamingContent[blockIndex];
+				if (content.type !== "toolCall") continue;
+				if (
+					activeToolCallIndex !== undefined &&
+					blockIndex !== activeToolCallIndex &&
+					this.ctx.pendingTools.has(content.id)
+				) {
+					continue;
+				}
+				if (content.name === "read") {
+					if (!readArgsHaveTarget(content.arguments)) {
+						// Args still streaming — defer until path is parseable so we can route to the
+						// read group (regular files) vs ToolExecutionComponent (internal URLs).
+						// Creating either component now would lock the read into the wrong shape.
+						continue;
+					}
+					if (!readArgsTargetInternalUrl(content.arguments)) {
+						this.#trackReadToolCall(content.id, content.arguments);
+						const component = this.ctx.pendingTools.get(content.id);
+						if (component) {
+							component.updateArgs(content.arguments, content.id);
+						} else {
+							const group = this.#getReadGroup();
+							group.updateArgs(content.arguments, content.id);
+							this.ctx.pendingTools.set(content.id, group);
+						}
+						continue;
+					}
+					// Internal URL read falls through to ToolExecutionComponent below.
+				}
+
+				// Preserve the raw partial JSON for renderers that need to surface fields before the JSON object closes.
+				// Bash uses this to show inline env assignments during streaming instead of popping them in at completion.
+				const renderArgs =
+					"partialJson" in content
+						? { ...content.arguments, __partialJson: content.partialJson }
+						: content.arguments;
+				if (!this.ctx.pendingTools.has(content.id)) {
+					this.#resetReadGroup();
+					const tool = this.ctx.session.getToolByName(content.name);
+					const component = new ToolExecutionComponent(
+						content.name,
+						renderArgs,
+						{
+							showImages: settings.get("terminal.showImages"),
+							editFuzzyThreshold: settings.get("edit.fuzzyThreshold"),
+							editAllowFuzzy: settings.get("edit.fuzzyMatch"),
+							hashlineAutoDropPureInsertDuplicates: settings.get("edit.hashlineAutoDropPureInsertDuplicates"),
+						},
+						tool,
+						this.ctx.ui,
+						this.ctx.sessionManager.getCwd(),
+						content.id,
+					);
+					component.setExpanded(this.ctx.toolOutputExpanded);
+					markLiveToggleEligible(component, true);
+					if (this.#commitFoldingEnabled()) {
+						// Provider-streamed tool calls can arrive through message_update before a
+						// tool_execution_start event. Keep them in the same live zone used by
+						// tool_execution_start so active previews do not mutate chat history
+						// while the user is reading scrollback.
+						this.#liveToolComponents.add(component);
+						this.ctx.liveToolContainer.addChild(component);
+					} else {
+						this.ctx.chatContainer.addChild(new Text("", 0, 0));
+						// 083.1: a new tool starting collapses the previous one to a one-line summary
+						this.ctx.lastToolComponent?.setMinimized?.(true);
+						this.ctx.chatContainer.addChild(component);
+					}
+					this.ctx.lastToolComponent = component;
+					this.ctx.pendingTools.set(content.id, component);
+				} else {
+					const component = this.ctx.pendingTools.get(content.id);
+					if (component) {
+						component.updateArgs(renderArgs, content.id);
+					}
+				}
+			}
+
+			// Update working message with intent from streamed tool arguments
+			for (const content of this.ctx.streamingMessage.content) {
+				if (content.type !== "toolCall") continue;
+				const args = content.arguments;
+				if (!args || typeof args !== "object") continue;
+				if (INTENT_FIELD in args) {
+					this.#updateWorkingMessageFromIntent(args[INTENT_FIELD]);
+					continue;
+				}
+				const tool = this.ctx.session.getToolByName(content.name);
+				if (typeof tool?.intent !== "function") continue;
+				try {
+					const derived = tool.intent(args as never)?.trim();
+					if (derived) {
+						this.#updateWorkingMessageFromIntent(derived);
+					}
+				} catch {
+					// intent function must never break the UI
+				}
+			}
+
+			this.ctx.ui.requestRender();
+		}
+	}
+
+	async #handleMessageEnd(event: Extract<AgentSessionEvent, { type: "message_end" }>): Promise<void> {
+		if (event.message.role === "user") return;
+		if (this.ctx.streamingComponent && event.message.role === "assistant") {
+			this.ctx.streamingMessage = event.message;
+			// Message settled — the trailing thinking block collapses to its summary (083.5).
+			this.ctx.streamingComponent.setStreaming(false);
+			let errorMessage: string | undefined;
+			const aborted = this.ctx.streamingMessage.stopReason === "aborted";
+			const silentlyAborted = aborted && isSilentAbort(this.ctx.streamingMessage.errorMessage);
+			const ttsrSilenced = aborted && this.ctx.session.isTtsrAbortPending;
+			if (aborted && !silentlyAborted && !ttsrSilenced) {
+				// Real user-cancel / network / provider abort: surface the standard
+				// operator-facing label. AgentSession.#handleAgentEvent already stamped
+				// SILENT_ABORT_MARKER for the plan-compact transition before this
+				// controller ran, so reaching this branch implies the abort was NOT a
+				// silent internal transition.
+				const retryAttempt = this.ctx.session.retryAttempt;
+				errorMessage =
+					retryAttempt > 0
+						? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
+						: "Operation aborted";
+				this.ctx.streamingMessage.errorMessage = errorMessage;
+			}
+			if (silentlyAborted || ttsrSilenced) {
+				// Silence the streaming render by downgrading stopReason to "stop" for
+				// display only — does NOT mutate the persisted message's stopReason
+				// (the marker on errorMessage drives replay-side suppression).
+				const msgWithoutAbort = { ...this.ctx.streamingMessage, stopReason: "stop" as const };
+				this.ctx.streamingComponent.updateContent(this.#segmentSlice(msgWithoutAbort));
+			} else {
+				this.ctx.streamingComponent.updateContent(this.#segmentSlice(this.ctx.streamingMessage));
+			}
+
+			if (this.ctx.streamingMessage.stopReason !== "aborted" && this.ctx.streamingMessage.stopReason !== "error") {
+				// Push final fully-parsed args before marking complete. During
+				// streaming, updateArgs dedups on partialJson+keyCount; the final
+				// parsed `arguments` can share that fingerprint yet differ in value,
+				// so feed it explicitly (no __partialJson → bypasses the dedup) to
+				// guarantee the pre-execution diff preview uses complete args.
+				const finalToolArgs = new Map<string, unknown>();
+				for (const content of this.ctx.streamingMessage.content) {
+					if (content.type === "toolCall" && content.id) finalToolArgs.set(content.id, content.arguments);
+				}
+				for (const [toolCallId, component] of this.ctx.pendingTools.entries()) {
+					const finalArgs = finalToolArgs.get(toolCallId);
+					if (finalArgs !== undefined) component.updateArgs(finalArgs, toolCallId);
+					component.setArgsComplete(toolCallId);
+				}
+			}
+			this.#lastAssistantComponent = this.ctx.streamingComponent;
+			this.#lastAssistantComponent.setUsageInfo(event.message.usage);
+			this.ctx.streamingComponent = undefined;
+			this.ctx.streamingMessage = undefined;
+			this.ctx.statusLine.invalidate();
+			this.ctx.updateEditorTopBorder();
+		}
+		this.ctx.ui.requestRender();
+	}
+
+	async #handleToolExecutionStart(event: Extract<AgentSessionEvent, { type: "tool_execution_start" }>): Promise<void> {
+		this.#updateWorkingMessageFromIntent(event.intent);
+		if (!this.ctx.pendingTools.has(event.toolCallId)) {
+			if (event.toolName === "read" && readArgsHaveTarget(event.args) && !readArgsTargetInternalUrl(event.args)) {
+				this.#trackReadToolCall(event.toolCallId, event.args);
+				const component = this.ctx.pendingTools.get(event.toolCallId);
+				if (component) {
+					component.updateArgs(event.args, event.toolCallId);
+				} else {
+					const group = this.#getReadGroup();
+					group.updateArgs(event.args, event.toolCallId);
+					this.ctx.pendingTools.set(event.toolCallId, group);
+				}
+				this.ctx.ui.requestRender();
+				return;
+			}
+
+			this.#resetReadGroup();
+			const tool = this.ctx.session.getToolByName(event.toolName);
+			const component = new ToolExecutionComponent(
+				event.toolName,
+				event.args,
+				{
+					showImages: settings.get("terminal.showImages"),
+					editFuzzyThreshold: settings.get("edit.fuzzyThreshold"),
+					editAllowFuzzy: settings.get("edit.fuzzyMatch"),
+					hashlineAutoDropPureInsertDuplicates: settings.get("edit.hashlineAutoDropPureInsertDuplicates"),
+				},
+				tool,
+				this.ctx.ui,
+				this.ctx.sessionManager.getCwd(),
+				event.toolCallId,
+			);
+			component.setExpanded(this.ctx.toolOutputExpanded);
+			markLiveToggleEligible(component, true);
+			if (this.#commitFoldingEnabled()) {
+				// 99.20.04 commit-time folding: the active preview lives in the
+				// live zone only — history stays untouched until completion, so
+				// it grows monotonically (no retroactive shrink).
+				this.#liveToolComponents.add(component);
+				this.ctx.liveToolContainer.addChild(component);
+			} else {
+				// 083.1 (verbose mode): a new tool starting collapses the previous
+				// one to a one-line summary.
+				this.ctx.lastToolComponent?.setMinimized?.(true);
+				this.ctx.chatContainer.addChild(component);
+			}
+			this.ctx.lastToolComponent = component;
+			this.ctx.pendingTools.set(event.toolCallId, component);
+			this.ctx.ui.requestRender();
+		}
+	}
+
+	async #handleToolExecutionUpdate(
+		event: Extract<AgentSessionEvent, { type: "tool_execution_update" }>,
+	): Promise<void> {
+		const component = this.ctx.pendingTools.get(event.toolCallId);
+		if (component) {
+			const asyncState = (event.partialResult.details as { async?: { state?: string } } | undefined)?.async?.state;
+			const isFinalAsyncState = asyncState === "completed" || asyncState === "failed";
+			component.updateResult(
+				{ ...event.partialResult, isError: asyncState === "failed" },
+				!isFinalAsyncState,
+				event.toolCallId,
+			);
+			if (isFinalAsyncState) {
+				this.ctx.pendingTools.delete(event.toolCallId);
+				this.#backgroundToolCallIds.delete(event.toolCallId);
+				this.#commitLiveTool(component);
+			}
+			this.ctx.ui.requestRender();
+		}
+	}
+
+	async #handleToolExecutionEnd(event: Extract<AgentSessionEvent, { type: "tool_execution_end" }>): Promise<void> {
+		if (event.toolName === "read") {
+			if (this.#inlineReadToolImages(event.toolCallId, event.result)) {
+				const component = this.ctx.pendingTools.get(event.toolCallId);
+				if (component) {
+					component.updateResult({ ...event.result, isError: event.isError }, false, event.toolCallId);
+					this.ctx.pendingTools.delete(event.toolCallId);
+				}
+				const asyncState = (event.result.details as { async?: { state?: string } } | undefined)?.async?.state;
+				if (asyncState === "running") {
+					this.#backgroundToolCallIds.add(event.toolCallId);
+				} else {
+					this.#backgroundToolCallIds.delete(event.toolCallId);
+					this.#clearReadToolCall(event.toolCallId);
+					this.#commitLiveTool(component);
+				}
+				this.ctx.ui.requestRender();
+			} else {
+				let component = this.ctx.pendingTools.get(event.toolCallId);
+				if (!component) {
+					const group = this.#getReadGroup();
+					const args = this.#readToolCallArgs.get(event.toolCallId);
+					if (args) {
+						group.updateArgs(args, event.toolCallId);
+					}
+					component = group;
+					this.ctx.pendingTools.set(event.toolCallId, group);
+				}
+				const asyncState = (event.result.details as { async?: { state?: string } } | undefined)?.async?.state;
+				const isBackgroundRunning = asyncState === "running";
+				component.updateResult({ ...event.result, isError: event.isError }, isBackgroundRunning, event.toolCallId);
+				if (isBackgroundRunning) {
+					this.#backgroundToolCallIds.add(event.toolCallId);
+				} else {
+					this.ctx.pendingTools.delete(event.toolCallId);
+					this.#backgroundToolCallIds.delete(event.toolCallId);
+					this.#clearReadToolCall(event.toolCallId);
+					this.#commitLiveTool(component);
+				}
+				this.ctx.ui.requestRender();
+			}
+		} else {
+			const component = this.ctx.pendingTools.get(event.toolCallId);
+			if (component) {
+				const asyncState = (event.result.details as { async?: { state?: string } } | undefined)?.async?.state;
+				const isBackgroundRunning = asyncState === "running";
+				component.updateResult({ ...event.result, isError: event.isError }, isBackgroundRunning, event.toolCallId);
+				if (isBackgroundRunning) {
+					this.#backgroundToolCallIds.add(event.toolCallId);
+				} else {
+					this.ctx.pendingTools.delete(event.toolCallId);
+					this.#backgroundToolCallIds.delete(event.toolCallId);
+					this.#commitLiveTool(component);
+				}
+				this.ctx.ui.requestRender();
+			}
+		}
+		// Update todo display when todo_write tool completes
+		if (event.toolName === "todo_write" && !event.isError) {
+			const details = event.result.details as { phases?: TodoPhase[] } | undefined;
+			if (details?.phases) {
+				this.ctx.setTodos(details.phases);
+			}
+		} else if (event.toolName === "todo_write" && event.isError) {
+			const textContent = event.result.content.find(
+				(content: { type: string; text?: string }) => content.type === "text",
+			)?.text;
+			this.ctx.showWarning(
+				`Todo update failed${textContent ? `: ${textContent}` : ". Progress may be stale until todo_write succeeds."}`,
+			);
+		}
+		if (event.toolName === "resolve" && !event.isError) {
+			const details = event.result.details as ResolveToolDetails | undefined;
+			if (details?.sourceToolName === "plan_approval" && details.action === "apply") {
+				const planDetails = details.sourceResultDetails as PlanApprovalDetails | undefined;
+				if (planDetails) {
+					await this.ctx.handlePlanApproval(planDetails);
+				}
+			}
+		}
+	}
+
+	async #handleAgentEnd(_event: Extract<AgentSessionEvent, { type: "agent_end" }>): Promise<void> {
+		if (this.ctx.loadingAnimation) {
+			this.ctx.loadingAnimation.stop();
+			this.ctx.loadingAnimation = undefined;
+			this.ctx.statusContainer.clear();
+		}
+		if (this.ctx.streamingComponent) {
+			this.ctx.chatContainer.removeChild(this.ctx.streamingComponent);
+			this.ctx.streamingComponent = undefined;
+			this.ctx.streamingMessage = undefined;
+		}
+		await this.ctx.flushPendingModelSwitch();
+		for (const toolCallId of Array.from(this.ctx.pendingTools.keys())) {
+			if (!this.#backgroundToolCallIds.has(toolCallId)) {
+				this.ctx.pendingTools.delete(toolCallId);
+			}
+		}
+		this.#backgroundToolCallIds = new Set(
+			Array.from(this.#backgroundToolCallIds).filter(toolCallId => this.ctx.pendingTools.has(toolCallId)),
+		);
+		this.#readToolCallArgs.clear();
+		this.#readToolCallAssistantComponents.clear();
+		this.#lastAssistantComponent = undefined;
+		// 99.20.04: commit any tools still sitting in the live zone (aborted /
+		// background leftovers) so the zone is empty between turns.
+		for (const component of Array.from(this.#liveToolComponents)) {
+			this.#commitLiveTool(component);
+		}
+		// 083.1: turn is over — no tool is active anymore, collapse the last one.
+		this.ctx.lastToolComponent?.setMinimized?.(true);
+		this.ctx.lastToolComponent = undefined;
+		this.ctx.ui.requestRender();
+		// 083.8 S2: the post-overflow gap is NOT compacted here — the forced full
+		// rebuild made the final response visibly jump. It collapses at the next
+		// prompt submit instead (input-controller), where the screen changes anyway.
+		this.#scheduleIdleCompaction();
+		this.sendCompletionNotification();
+	}
+
+	async #handleAutoCompactionStart(
+		event: Extract<AgentSessionEvent, { type: "auto_compaction_start" }>,
+	): Promise<void> {
+		this.#cancelIdleCompaction();
+		this.ctx.autoCompactionEscapeHandler = this.ctx.editor.onEscape;
+		this.ctx.editor.onEscape = () => {
+			this.ctx.session.abortCompaction();
+		};
+		this.ctx.statusContainer.clear();
+		const reasonText =
+			event.reason === "overflow" ? "Context overflow detected, " : event.reason === "idle" ? "Idle " : "";
+		const actionLabel = event.action === "handoff" ? "Auto-handoff" : "Auto context-full maintenance";
+		this.ctx.autoCompactionLoader = new Loader(
+			this.ctx.ui,
+			spinner => theme.fg("accent", spinner),
+			text => theme.fg("muted", text),
+			`${reasonText}${actionLabel}… (esc to cancel)`,
+			getSymbolTheme().spinnerFrames,
+		);
+		this.ctx.statusContainer.addChild(this.ctx.autoCompactionLoader);
+		this.ctx.ui.requestRender();
+		const prefix =
+			event.reason === "overflow"
+				? "Recovering from context overflow"
+				: event.action === "handoff"
+					? "Preparing auto-handoff"
+					: event.reason === "idle"
+						? "Running idle context maintenance"
+						: "Running context maintenance";
+		this.ctx.autoCompactionProgressPresenter = new CompactionProgressPresenter({
+			setMessage: message => this.ctx.autoCompactionLoader?.setMessage(message),
+			getWidth: () => this.ctx.ui.terminal.columns,
+			prefix,
+			cancelHint: "(esc to cancel)",
+		});
+	}
+
+	async #handleCompactionProgress(event: Extract<AgentSessionEvent, { type: "compaction_progress" }>): Promise<void> {
+		if (event.update.trigger === "manual") return;
+		this.ctx.autoCompactionProgressPresenter?.update(event.update);
+	}
+
+	async #handleAutoCompactionEnd(event: Extract<AgentSessionEvent, { type: "auto_compaction_end" }>): Promise<void> {
+		this.#cancelIdleCompaction();
+		if (this.ctx.autoCompactionEscapeHandler) {
+			this.ctx.editor.onEscape = this.ctx.autoCompactionEscapeHandler;
+			this.ctx.autoCompactionEscapeHandler = undefined;
+		}
+		if (this.ctx.autoCompactionProgressPresenter) {
+			this.ctx.autoCompactionProgressPresenter.stop();
+			this.ctx.autoCompactionProgressPresenter = undefined;
+		}
+		if (this.ctx.autoCompactionLoader) {
+			this.ctx.autoCompactionLoader.stop();
+			this.ctx.autoCompactionLoader = undefined;
+			this.ctx.statusContainer.clear();
+		}
+		const isHandoffAction = event.action === "handoff";
+		if (event.aborted) {
+			this.ctx.showStatus(isHandoffAction ? "Auto-handoff cancelled" : "Auto context-full maintenance cancelled");
+		} else if (event.result) {
+			this.ctx.rebuildChatFromMessages();
+			this.ctx.statusLine.invalidate();
+			this.ctx.updateEditorTopBorder();
+		} else if (event.errorMessage) {
+			this.ctx.showWarning(event.errorMessage);
+		} else if (isHandoffAction) {
+			this.ctx.chatContainer.clear();
+			this.ctx.rebuildChatFromMessages();
+			this.ctx.statusLine.invalidate();
+			this.ctx.updateEditorTopBorder();
+			await this.ctx.reloadTodos();
+			this.ctx.showStatus("Auto-handoff completed");
+		} else if (event.skipped) {
+			// Benign skip: no model selected, no candidate models available, or nothing
+			// to compact yet. Not a failure — suppress the warning.
+		} else {
+			this.ctx.showWarning("Auto context-full maintenance failed; continuing without maintenance");
+		}
+		await this.ctx.flushCompactionQueue({ willRetry: event.willRetry });
+		this.ctx.ui.requestRender();
+	}
+
+	#clearRetryCountdown(): void {
+		if (this.ctx.retryCountdownTimer) {
+			clearInterval(this.ctx.retryCountdownTimer);
+			this.ctx.retryCountdownTimer = undefined;
+		}
+	}
+
+	async #handleAutoRetryStart(event: Extract<AgentSessionEvent, { type: "auto_retry_start" }>): Promise<void> {
+		// Preserve the ORIGINAL editor Escape handler across repeated retry
+		// starts: auto_retry_end only fires at final success/failure, so a
+		// second auto_retry_start must not snapshot the prior retry handler.
+		if (!this.ctx.retryEscapeHandler) {
+			this.ctx.retryEscapeHandler = this.ctx.editor.onEscape;
+		}
+		let escPressed = false;
+		this.ctx.editor.onEscape = () => {
+			if (!escPressed) {
+				// First Esc: skip the backoff and retry immediately.
+				escPressed = true;
+				this.ctx.session.retryNow();
+			} else {
+				// Second Esc: cancel the retry entirely.
+				this.ctx.session.abortRetry();
+			}
+		};
+		this.ctx.statusContainer.clear();
+		// Stop any prior retry loader/timer before installing a new one.
+		this.ctx.retryLoader?.stop();
+		this.#clearRetryCountdown();
+		const reason = friendlyRetryReason(event.errorMessage);
+		const attemptLabel = event.unbounded ? `attempt ${event.attempt}` : `${event.attempt}/${event.maxAttempts}`;
+		const reasonSuffix = reason ? ` — ${reason}` : "";
+		const deadline = Date.now() + event.delayMs;
+		const buildMessage = () => {
+			const remainingSeconds = Math.max(0, Math.round((deadline - Date.now()) / 1000));
+			// First Esc retries immediately; a second Esc cancels.
+			return `Retrying (${attemptLabel})${reasonSuffix}, next in ${remainingSeconds}s… (esc to retry now)`;
+		};
+		const retryLoader = new Loader(
+			this.ctx.ui,
+			spinner => theme.fg("warning", spinner),
+			text => theme.fg("muted", text),
+			buildMessage(),
+			getSymbolTheme().spinnerFrames,
+		);
+		this.ctx.retryLoader = retryLoader;
+		this.ctx.retryCountdownTimer = setInterval(() => {
+			retryLoader.setMessage(buildMessage());
+		}, 1000);
+		this.ctx.statusContainer.addChild(retryLoader);
+		this.ctx.ui.requestRender();
+	}
+
+	async #handleAutoRetryEnd(event: Extract<AgentSessionEvent, { type: "auto_retry_end" }>): Promise<void> {
+		if (this.ctx.retryEscapeHandler) {
+			this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
+			this.ctx.retryEscapeHandler = undefined;
+		}
+		if (this.ctx.retryLoader) {
+			this.ctx.retryLoader.stop();
+			this.#clearRetryCountdown();
+			this.ctx.retryLoader = undefined;
+			this.ctx.statusContainer.clear();
+		}
+		if (!event.success) {
+			this.ctx.showError(`Retry failed after ${event.attempt} attempts: ${event.finalError || "Unknown error"}`);
+		}
+		this.ctx.ui.requestRender();
+	}
+
+	async #handleRetryFallbackApplied(
+		event: Extract<AgentSessionEvent, { type: "retry_fallback_applied" }>,
+	): Promise<void> {
+		this.ctx.showWarning(`Fallback: ${event.from} -> ${event.to}`);
+	}
+
+	async #handleRetryFallbackSucceeded(
+		event: Extract<AgentSessionEvent, { type: "retry_fallback_succeeded" }>,
+	): Promise<void> {
+		this.ctx.showStatus(`Fallback succeeded on ${event.model}`);
+	}
+
+	async #handleTtsrTriggered(event: Extract<AgentSessionEvent, { type: "ttsr_triggered" }>): Promise<void> {
+		const component = new TtsrNotificationComponent(event.rules);
+		component.setExpanded(this.ctx.toolOutputExpanded);
+		markLiveToggleEligible(component, true);
+		this.ctx.chatContainer.addChild(component);
+		this.ctx.ui.requestRender();
+	}
+
+	async #handleTodoReminder(event: Extract<AgentSessionEvent, { type: "todo_reminder" }>): Promise<void> {
+		const component = new TodoReminderComponent(event.todos, event.attempt, event.maxAttempts);
+		this.ctx.chatContainer.addChild(component);
+		this.ctx.ui.requestRender();
+	}
+
+	async #handleTodoAutoClear(_event: Extract<AgentSessionEvent, { type: "todo_auto_clear" }>): Promise<void> {
+		await this.ctx.reloadTodos();
+	}
+
+	#cancelIdleCompaction(): void {
+		if (this.#idleCompactionTimer) {
+			clearTimeout(this.#idleCompactionTimer);
+			this.#idleCompactionTimer = undefined;
+		}
+	}
+
+	#scheduleIdleCompaction(): void {
+		this.#cancelIdleCompaction();
+		// Don't schedule idle work while context maintenance is already running; the
+		// maintenance flow may reset the session before this timer fires.
+		if (this.ctx.session.isCompacting) return;
+
+		const idleSettings = settings.getGroup("compaction");
+		if (!idleSettings.idleEnabled) return;
+
+		// Only if input is empty
+		if (this.ctx.editor.getText().trim()) return;
+
+		const threshold = idleSettings.idleThresholdTokens;
+		if (threshold <= 0) return;
+		if (this.#currentContextTokens() < threshold) return;
+
+		const timeoutMs = Math.max(60, Math.min(3600, idleSettings.idleTimeoutSeconds)) * 1000;
+		this.#idleCompactionTimer = setTimeout(() => {
+			this.#idleCompactionTimer = undefined;
+			// Re-check conditions before firing. Pruning may have run between arming
+			// the timer and now, dropping usage back below the idle threshold.
+			if (this.ctx.session.isStreaming) return;
+			if (this.ctx.session.isCompacting) return;
+			if (this.ctx.editor.getText().trim()) return;
+			if (this.#currentContextTokens() < threshold) return;
+			void this.ctx.session.runIdleCompaction();
+		}, timeoutMs);
+		this.#idleCompactionTimer.unref?.();
+	}
+
+	#currentContextTokens(): number {
+		const lastAssistant = this.ctx.session.agent.state.messages
+			.slice()
+			.reverse()
+			.find((m): m is AssistantMessage => m.role === "assistant" && m.stopReason !== "aborted");
+		return lastAssistant?.usage ? calculatePromptTokens(lastAssistant.usage) : 0;
+	}
+
+	sendCompletionNotification(): void {
+		if (this.ctx.isBackgrounded === false) return;
+		const notify = settings.get("completion.notify");
+		if (notify === "off") return;
+
+		// Skip when the turn was aborted (e.g. ask cancelled with Ctrl+C) or
+		// errored — those are not "Task complete" events. Mirrors the gate
+		// already used by #currentContextTokens, #handleMessageEnd, and the
+		// retry / TTSR / compaction skip paths across agent-session.ts.
+		const last = this.ctx.session.getLastAssistantMessage?.();
+		if (last?.stopReason === "aborted" || last?.stopReason === "error") return;
+
+		const title = this.ctx.sessionManager.getSessionName();
+		const message = title ? `${title}: Complete` : "Complete";
+		TERMINAL.sendNotification(message);
+	}
+
+	async handleBackgroundEvent(event: AgentSessionEvent): Promise<void> {
+		if (event.type !== "agent_end") {
+			return;
+		}
+		if (this.ctx.session.queuedMessageCount > 0 || this.ctx.session.isStreaming) {
+			return;
+		}
+		this.sendCompletionNotification();
+		await this.ctx.shutdown();
+	}
+}