comate-cli 0.1.0__py3-none-any.whl

comate_cli/terminal_agent/tui.py

@@ -0,0 +1,1006 @@
+"""Terminal Agent TUI implementation.
+
+This module was split out from `terminal_agent.app` to keep the entrypoint small.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+import time
+from collections import deque
+from collections.abc import Callable
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+from prompt_toolkit.application import Application
+from prompt_toolkit.completion import (
+    merge_completers,
+)
+from prompt_toolkit.filters import Condition, has_completions, has_focus
+from prompt_toolkit.history import InMemoryHistory
+from prompt_toolkit.layout import FloatContainer, HSplit, Layout, Window
+from prompt_toolkit.layout.containers import ConditionalContainer
+from prompt_toolkit.layout.controls import FormattedTextControl
+from prompt_toolkit.patch_stdout import patch_stdout
+from prompt_toolkit.styles import Style as PTStyle
+from prompt_toolkit.utils import get_cwidth
+from prompt_toolkit.widgets import TextArea
+
+from comate_agent_sdk.agent import ChatSession
+from comate_agent_sdk.agent.events import PlanApprovalRequiredEvent
+
+from comate_cli.terminal_agent.animations import (
+    DEFAULT_STATUS_PHRASES,
+    StreamAnimationController,
+    SubmissionAnimator,
+)
+from comate_cli.terminal_agent.env_utils import read_env_float, read_env_int
+from comate_cli.terminal_agent.event_renderer import EventRenderer
+from comate_cli.terminal_agent.mention_completer import LocalFileMentionCompleter
+from comate_cli.terminal_agent.question_view import AskUserQuestionUI
+from comate_cli.terminal_agent.rewind_store import RewindStore
+from comate_cli.terminal_agent.selection_menu import (
+    SelectionMenuUI,
+)
+from comate_cli.terminal_agent.slash_commands import (
+    SLASH_COMMAND_SPECS,
+    SlashCommandCompleter,
+)
+from comate_cli.terminal_agent.status_bar import StatusBar
+from comate_cli.terminal_agent.tui_parts import (
+    CommandsMixin,
+    HistorySyncMixin,
+    InputBehaviorMixin,
+    KeyBindingsMixin,
+    RenderPanelsMixin,
+    SlashCommandRegistry,
+    UIMode,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TerminalAgentTUI(
+    KeyBindingsMixin,
+    InputBehaviorMixin,
+    CommandsMixin,
+    HistorySyncMixin,
+    RenderPanelsMixin,
+):
+    def __init__(
+        self,
+        session: ChatSession,
+        status_bar: StatusBar,
+        renderer: EventRenderer,
+    ) -> None:
+        self._session = session
+        self._status_bar = status_bar
+        try:
+            self._status_bar.set_mode(self._session.get_mode())
+        except Exception:
+            pass
+        self._renderer = renderer
+        self._rewind_store = RewindStore(session=self._session, project_root=Path.cwd())
+
+        self._tool_panel_max_lines = read_env_int(
+            "AGENT_SDK_TUI_TOOL_PANEL_MAX_LINES",
+            4,
+        )
+        self._todo_panel_max_lines = read_env_int(
+            "AGENT_SDK_TUI_TODO_PANEL_MAX_LINES",
+            6,
+        )
+        self._message_queue_max_size = read_env_int(
+            "AGENT_SDK_TUI_MESSAGE_QUEUE_MAX_SIZE",
+            3,
+        )
+        self._queued_preview_max_chars = read_env_int(
+            "AGENT_SDK_TUI_QUEUED_PREVIEW_MAX_CHARS",
+            24,
+        )
+
+        self._busy = False
+        self._initializing = False  # MCP 加载中
+        self._is_compacting = False
+        self._compact_task: asyncio.Task[Any] | None = None
+        self._compact_cancel_requested = False
+        self._pending_exit_after_compact_cancel = False
+        self._queued_messages: deque[str] = deque()  # busy 时入队的消息（FIFO）
+        self._waiting_for_input = False
+        self._pending_questions: list[dict[str, Any]] | None = None
+        self._pending_plan_approval: dict[str, str] | None = None
+        self._ui_mode = UIMode.NORMAL
+        self._show_thinking = True  # Ctrl+T 开关，默认打开
+
+        self._slash_registry = SlashCommandRegistry()
+        self._build_slash_registry()
+        self._slash_completer = SlashCommandCompleter(
+            self._slash_registry.command_specs()
+        )
+        self._mention_completer = LocalFileMentionCompleter(Path.cwd())
+        self._input_completer = merge_completers(
+            [self._slash_completer, self._mention_completer],
+            deduplicate=True,
+        )
+        self._loading_frame = 0
+        self._fallback_loading_phrase = (
+            random.choice(DEFAULT_STATUS_PHRASES)
+            if DEFAULT_STATUS_PHRASES
+            else "Thinking…"
+        )
+        self._fallback_phrase_refresh_at = 0.0
+
+        self._tool_result_flash_seconds = read_env_float(
+            "AGENT_SDK_TUI_TOOL_RESULT_FLASH_SECONDS",
+            0.55,
+        )
+        self._tool_result_flash_gen = 0
+        self._tool_result_flash_until_monotonic: float | None = None
+        self._tool_result_flash_active = False
+
+        # 初始化提交动画控制器
+        self._animator = SubmissionAnimator()
+        self._animation_controller = StreamAnimationController(self._animator)
+        self._tool_result_animator = SubmissionAnimator()
+
+        self._closing = False
+        self._printed_history_index = 0
+        self._render_dirty = True
+        self._diff_panel_visible = False
+        self._diff_panel_scroll = 0
+        self._last_loading_line = ""
+
+        self._app: Application[None] | None = None
+        self._stream_task: asyncio.Task[Any] | None = None
+        self._ui_tick_task: asyncio.Task[None] | None = None
+        self._mcp_init_task: asyncio.Task[None] | None = None
+        self._interrupt_requested_at: float | None = None
+        self._interrupt_force_window_seconds = 1.5
+
+        self._esc_last_pressed_at: float = 0.0
+        self._esc_press_count: int = 0
+        esc_window_ms = read_env_int("AGENT_SDK_TUI_ESC_CLEAR_WINDOW_MS", 700)
+        self._esc_clear_window_seconds = esc_window_ms / 1000.0
+
+        self._ctrl_c_last_pressed_at: float = 0.0
+        self._ctrl_c_press_count: int = 0
+        ctrl_c_window_ms = read_env_int("AGENT_SDK_TUI_CTRL_C_EXIT_WINDOW_MS", 700)
+        self._ctrl_c_exit_window_seconds = ctrl_c_window_ms / 1000.0
+
+        self._paste_threshold_chars = read_env_int(
+            "AGENT_SDK_TUI_PASTE_PLACEHOLDER_THRESHOLD_CHARS",
+            500,
+        )
+        self._paste_placeholder_text: str | None = None
+        self._active_paste_token: str | None = None
+        self._paste_payload_by_token: dict[str, str] = {}
+        self._paste_token_seq = 0
+        self._suppress_input_change_hook = False
+        self._last_input_len = 0
+        self._last_input_text = ""
+
+        # Running 计时：记录本次 busy 开始的单调时间，结束后清空
+        self._run_start_time: float | None = None
+
+        self._input_prompt_text = "> "
+        self._input_prompt_width = max(1, get_cwidth(self._input_prompt_text))
+        self._queued_input_hint = "Press ↑ to edit"
+
+        def _input_line_prefix(
+            _line_number: int,
+            wrap_count: int,
+        ) -> list[tuple[str, str]]:
+            if wrap_count <= 0:
+                fragments: list[tuple[str, str]] = [
+                    ("class:input.prompt", self._input_prompt_text)
+                ]
+                hint_text = self._input_placeholder_hint()
+                if hint_text:
+                    fragments.append(("class:input.placeholder", f"{hint_text}  "))
+                return fragments
+            return [("class:input.prompt", " " * self._input_prompt_width)]
+
+        self._input_area = TextArea(
+            text="",
+            multiline=True,
+            prompt="",
+            wrap_lines=True,
+            dont_extend_height=True,
+            completer=self._input_completer,
+            complete_while_typing=False,  # 通过 Tab/上下键手动触发补全
+            history=InMemoryHistory(),
+            style="class:input.line",
+            get_line_prefix=_input_line_prefix,
+        )
+        # Fill the entire input area with styled spaces to avoid VT100
+        # erase-to-end-of-line resetting the background to the terminal default.
+        # (prompt_toolkit renderer resets attributes before erase_end_of_line.)
+        self._input_area.window.char = " "
+
+        @self._input_area.buffer.on_text_changed.add_handler
+        def _trigger_completion(_buffer) -> None:
+            if self._handle_large_paste(_buffer):
+                return
+            if self._busy:
+                return
+            doc = self._input_area.buffer.document
+            if self._completion_context_active(
+                doc.text_before_cursor,
+                doc.text_after_cursor,
+            ):
+                # 输入 / 或 @ 时自动弹出（不会选中第一项）
+                self._input_area.buffer.start_completion(select_first=False)
+
+        self._question_ui = AskUserQuestionUI()
+        self._selection_ui = SelectionMenuUI()
+        self._todo_control = FormattedTextControl(text=self._todo_text)
+        self._loading_control = FormattedTextControl(text=self._loading_text)
+        self._status_control = FormattedTextControl(text=self._status_text)
+        self._completion_status_control = FormattedTextControl(
+            text=self._completion_panel_text
+        )
+
+        self._todo_window = Window(
+            content=self._todo_control,
+            height=self._todo_height,
+            dont_extend_height=True,
+            style="class:loading",
+        )
+        self._todo_container = ConditionalContainer(
+            content=self._todo_window,
+            filter=Condition(lambda: self._renderer.has_active_todos()),
+        )
+
+        self._loading_window = Window(
+            content=self._loading_control,
+            height=self._loading_height,
+            dont_extend_height=True,
+            style="class:loading",
+        )
+        self._loading_placeholder_window = Window(
+            content=FormattedTextControl(text=[("", " ")]),
+            height=1,
+            dont_extend_height=True,
+            style="class:loading",
+        )
+        self._loading_container = ConditionalContainer(
+            content=self._loading_window,
+            filter=Condition(lambda: not self._should_hide_loading_panel()),
+            alternative_content=self._loading_placeholder_window,
+        )
+        self._queue_control = FormattedTextControl(text=self._queue_text)
+        self._queue_window = Window(
+            content=self._queue_control,
+            height=self._queue_height,
+            dont_extend_height=True,
+            style="class:queue",
+        )
+        self._queue_container = ConditionalContainer(
+            content=self._queue_window,
+            filter=Condition(self._should_show_queue_panel),
+        )
+
+        # Diff preview panel
+        self._diff_panel_control = FormattedTextControl(text=self._diff_panel_text)
+        self._diff_panel_window = Window(
+            content=self._diff_panel_control,
+            height=self._diff_panel_height,
+            dont_extend_height=True,
+            style="class:diff-panel",
+            wrap_lines=False,
+        )
+        self._diff_panel_container = ConditionalContainer(
+            content=self._diff_panel_window,
+            filter=Condition(
+                lambda: self._diff_panel_visible
+                and self._renderer.latest_diff_lines is not None
+            ),
+        )
+
+        self._status_window = Window(
+            content=self._status_control,
+            height=1,
+            dont_extend_height=True,
+            style="class:status",
+        )
+
+        self._completion_status_window = Window(
+            content=self._completion_status_control,
+            height=self._completion_panel_height,
+            dont_extend_height=True,
+            style="class:completion.status",
+        )
+
+        self._completion_visible = (
+            Condition(lambda: self._ui_mode == UIMode.NORMAL)
+            & has_focus(self._input_area)
+            & has_completions
+        )
+        self._bottom_container = ConditionalContainer(
+            content=self._completion_status_window,
+            filter=self._completion_visible,
+            alternative_content=self._status_window,
+        )
+
+        self._input_container = ConditionalContainer(
+            content=self._input_area,
+            filter=Condition(lambda: self._ui_mode == UIMode.NORMAL),
+        )
+        self._question_container = ConditionalContainer(
+            content=self._question_ui.container,
+            filter=Condition(lambda: self._ui_mode == UIMode.QUESTION),
+        )
+        self._selection_container = ConditionalContainer(
+            content=self._selection_ui.container,
+            filter=Condition(lambda: self._ui_mode == UIMode.SELECTION),
+        )
+
+        self._main_container = HSplit(
+            [
+                self._todo_container,
+                self._loading_container,
+                self._diff_panel_container,
+                self._queue_container,
+                Window(height=1, char=" ", style="class:input.pad"),
+                self._input_container,
+                self._question_container,
+                self._selection_container,
+                Window(height=1, char=" ", style="class:input.pad"),
+                self._bottom_container,
+            ]
+        )
+
+        self._root = FloatContainer(
+            content=self._main_container,
+            floats=[],
+        )
+
+        self._layout = Layout(self._root, focused_element=self._input_area.window)
+        self._bindings = self._build_key_bindings()
+        self._style = PTStyle.from_dict(
+            {
+                "": "bg:#1f232a #e5e9f0",
+                "history": "bg:#1a1e24 #d8dee9",
+                "input.pad": "fg:default bg:default",
+                "input.prompt": "bg:default #f2f4f8",
+                "input.line": "bg:default #f2f4f8",
+                "input-line": "bg:default #f2f4f8",
+                "status": "bg:#2d3138 #c3ccd8",
+                "status.mode.act": "bg:#2d3138 #60a5fa bold",
+                "status.mode.plan": "bg:#2d3138 #7AC9CA bold",
+                "status.hint": "bg:#2d3138 #6B7280",
+                "input.placeholder": "bg:default #9CA3AF",
+                "queue": "bg:#1d222a #d8dee9",
+                "queue.item": "bg:#1d222a #cbd5e1",
+                "git-diff.added": "#4ade80",
+                "git-diff.removed": "#f87171",
+                "question.tabs": "bg:#30353f #c7d2fe",
+                "question.tabs.nav": "bg:#30353f #93c5fd",
+                "question.tab": "bg:#374151 #cbd5e1",
+                "question.tab.submit": "bg:#14532d #86efac bold",
+                "question.tab.active": "bg:#1d4ed8 #eff6ff bold",
+                "question.divider": "fg:#4b5563",
+                "question.body": "bg:#252a33 #d8dee9",
+                "question.title": "fg:#f8fafc bold",
+                "question.hint": "fg:#94a3b8",
+                "question.option": "fg:#dbeafe",
+                "question.option.cursor": "bg:#1e3a8a #f8fafc bold",
+                "question.option.selected": "fg:#93c5fd bold",
+                "question.option.description": "fg:#9ca3af",
+                "question.custom_input": "bg:#0f172a #f8fafc",
+                "question.custom_input.border": "fg:#334155",
+                "question.preview.title": "fg:#e2e8f0 bold",
+                "question.preview.question": "fg:#bfdbfe",
+                "question.preview.answer": "fg:#f1f5f9",
+                "selection.title": "bg:#2d3138 #c3ccd8 bold",
+                "selection.divider": "fg:#4b5563",
+                "selection.body": "bg:#252a33 #d8dee9",
+                "selection.option": "fg:#dbeafe",
+                "selection.option.selected": "bg:#1e3a8a #f8fafc bold",
+                "selection.description": "fg:#9ca3af",
+                "selection.description.selected": "fg:#93c5fd",
+                "selection.hint": "fg:#94a3b8",
+                "completion.status": "bg:#2d3441 #d8dee9",
+                "completion.status.item": "bg:#2d3441 #d8dee9",
+                "completion.status.current": "bg:#5e81ac #eceff4 bold",
+                "completion.status.more": "bg:#2d3441 #81a1c1",
+                "loading": "fg:default bg:default",
+            }
+        )
+
+        self._app = Application(
+            layout=self._layout,
+            key_bindings=self._bindings,
+            style=self._style,
+            full_screen=False,
+            mouse_support=False,
+        )
+
+    def _should_show_queue_panel(self) -> bool:
+        return self._ui_mode == UIMode.NORMAL and len(self._queued_messages) >= 1
+
+    def _build_slash_registry(self) -> None:
+        handlers: dict[str, Callable[[str], Any]] = {
+            "help": self._slash_help,
+            "model": self._slash_model,
+            "session": self._slash_session,
+            "usage": self._slash_usage,
+            "context": self._slash_context,
+            "compact": self._slash_compact,
+            "rewind": self._slash_rewind,
+            "exit": self._slash_exit,
+        }
+        allow_when_busy = {"help", "session", "usage", "context", "exit"}
+
+        for spec in SLASH_COMMAND_SPECS:
+            handler = handlers.get(spec.name)
+            if handler is None:
+                logger.warning(f"missing slash command handler: {spec.name}")
+                continue
+            self._slash_registry.register(
+                spec=spec,
+                handler=handler,
+                allow_when_busy=spec.name in allow_when_busy,
+            )
+
+    def _input_placeholder_hint(self) -> str | None:
+        if self._ui_mode != UIMode.NORMAL:
+            return None
+        if not self._queued_messages:
+            return None
+        input_text = str(getattr(getattr(self, "_input_area", None), "text", ""))
+        if input_text.strip():
+            return None
+        if len(self._queued_messages) >= 2:
+            return self._queued_input_hint
+
+        preview = " ".join(self._queued_messages[0].split())
+        max_chars = max(8, int(self._queued_preview_max_chars))
+        if len(preview) > max_chars:
+            preview = f"{preview[: max_chars - 3]}..."
+        return f"已排队: {preview}  |  {self._queued_input_hint}"
+
+    # 极客风运行完成词语，随机选一个拼成 history 记录
+    _RUN_ELAPSED_VERBS: tuple[str, ...] = (
+        "Executed",
+        "Compiled",
+        "Dispatched",
+        "Processed",
+        "Computed",
+        "Resolved",
+        "Terminated",
+        "Committed",
+        "Deployed",
+        "Brewed",
+        "Flushed",
+        "Finalized",
+        "Propagated",
+        "Synchronized",
+        "Yielded",
+        "Emitted",
+    )
+
+    @staticmethod
+    def _format_run_elapsed(seconds: float) -> str:
+        """将秒数格式化为人类可读的时间字符串."""
+        if seconds < 10.0:
+            return f"{seconds:.1f}s"
+        if seconds < 60.0:
+            return f"{int(seconds)}s"
+        minutes = int(seconds) // 60
+        secs = int(seconds) % 60
+        return f"{minutes}m {secs}s"
+
+    def _append_run_elapsed_to_history(self) -> None:
+        """将本次 running 耗时以极客风格写入 history scrollback."""
+        if self._run_start_time is None:
+            return
+        elapsed = time.monotonic() - self._run_start_time
+        verb = random.choice(self._RUN_ELAPSED_VERBS)
+        duration_str = self._format_run_elapsed(elapsed)
+        self._renderer.append_elapsed_message(f"{verb} in {duration_str}")
+
+    def _set_busy(self, value: bool) -> None:
+        self._busy = value
+        self._render_dirty = True
+        self._invalidate()
+
+    async def _submit_user_message(
+        self,
+        text: str,
+        *,
+        display_text: str | None = None,
+    ) -> None:
+        if self._busy:
+            self._renderer.append_system_message(
+                "当前已有任务在运行，请稍候。", severity="error"
+            )
+            return
+
+        if self._ui_mode == UIMode.QUESTION:
+            self._exit_question_mode()
+
+        self._session.run_controller.clear()
+        self._interrupt_requested_at = None
+
+        self._set_busy(True)
+        self._run_start_time = time.monotonic()
+        self._waiting_for_input = False
+        self._pending_questions = None
+        # 本轮默认 loading 文案：避免出现 Working… 这种突兀 fallback
+        self._fallback_loading_phrase = (
+            random.choice(DEFAULT_STATUS_PHRASES)
+            if DEFAULT_STATUS_PHRASES
+            else "Thinking…"
+        )
+        self._fallback_phrase_refresh_at = time.monotonic() + 3.0  # 每 3 秒允许换一次
+
+        self._renderer.start_turn()
+        self._renderer.seed_user_message(
+            display_text if display_text is not None else text
+        )
+        self._refresh_layers()
+
+        # 启动提交动画
+        await self._animation_controller.start()
+
+        waiting_for_input = False
+        questions: list[dict[str, Any]] | None = None
+        plan_approval: dict[str, str] | None = None
+        stream_completed = False
+
+        stream_task = asyncio.create_task(
+            self._consume_stream(text),
+            name="terminal-tui-stream",
+        )
+        self._stream_task = stream_task
+        try:
+            waiting_for_input, questions, plan_approval = await stream_task
+            stream_completed = True
+        except asyncio.CancelledError:
+            logger.debug("stream task cancelled")
+        except Exception as exc:
+            logger.exception("stream failed")
+            from comate_cli.terminal_agent.error_display import format_error
+
+            error_msg, suggestion = format_error(exc)
+            self._renderer.append_system_message(error_msg, severity="error")
+            if suggestion:
+                self._renderer.append_system_message(f"💡 {suggestion}")
+
+            # 清理 UI 状态
+            self._renderer.interrupt_turn()
+            await self._animation_controller.shutdown()
+        finally:
+            if stream_completed:
+                self._maybe_capture_checkpoint(
+                    user_preview=display_text if display_text is not None else text
+                )
+            self._stream_task = None
+            self._interrupt_requested_at = None
+            self._append_run_elapsed_to_history()
+            self._run_start_time = None
+            self._set_busy(False)
+            await self._status_bar.refresh()
+
+        if waiting_for_input:
+            self._waiting_for_input = True
+            self._pending_questions = questions
+            self._pending_plan_approval = None
+            if questions:
+                self._enter_question_mode(questions)
+            else:
+                self._renderer.append_system_message(
+                    "请输入对上述问题的回答后回车提交。"
+                )
+        elif plan_approval is not None:
+            self._waiting_for_input = False
+            self._pending_questions = None
+            self._pending_plan_approval = plan_approval
+            self._exit_question_mode()
+            self._open_plan_approval_menu(plan_approval)
+        else:
+            self._waiting_for_input = False
+            self._pending_questions = None
+            self._pending_plan_approval = None
+            self._exit_question_mode()
+
+        self._refresh_layers()
+
+        # 正常结束后自动提交队列消息
+        if (
+            stream_completed
+            and self._queued_messages
+            and not waiting_for_input
+            and plan_approval is None
+        ):
+            queued = self._queued_messages.popleft()
+            self._schedule_background(self._submit_user_message(queued))
+
+    async def _consume_stream(
+        self,
+        text: str,
+    ) -> tuple[bool, list[dict[str, Any]] | None, dict[str, str] | None]:
+        waiting_for_input = False
+        questions: list[dict[str, Any]] | None = None
+        plan_approval: dict[str, str] | None = None
+
+        async for event in self._session.query_stream(text):
+            self._maybe_cancel_tool_result_flash(event)
+            # 将事件传递给动画控制器以控制动画生命周期
+            await self._animation_controller.on_event(event)
+            if isinstance(event, PlanApprovalRequiredEvent):
+                plan_approval = {
+                    "plan_path": str(event.plan_path),
+                    "summary": str(event.summary),
+                    "execution_prompt": str(event.execution_prompt),
+                    "context_utilization_pct": event.context_utilization_pct,
+                }
+            is_waiting, new_questions = self._renderer.handle_event(event)
+            self._maybe_flash_tool_result(event)
+            if is_waiting:
+                waiting_for_input = True
+                if new_questions is not None:
+                    questions = new_questions
+            self._refresh_layers()
+
+        self._renderer.finalize_turn()
+        await self._animation_controller.shutdown()
+        return waiting_for_input, questions, plan_approval
+
+    def _open_plan_approval_menu(self, approval: dict[str, str]) -> None:
+        plan_path = str(approval.get("plan_path", "")).strip()
+        summary = str(approval.get("summary", "")).strip()
+        execution_prompt = str(approval.get("execution_prompt", "")).strip()
+        context_utilization_pct = int(approval.get("context_utilization_pct", 0))
+        clear_label = (
+            f"Yes, clear context ({context_utilization_pct}% used) and execute"
+        )
+
+        options = [
+            {
+                "value": "approve_execute",
+                "label": "Approve and execute",
+                "description": "Switch to Act Mode and execute immediately.",
+            },
+            {
+                "value": "approve_clear_execute",
+                "label": clear_label,
+                "description": "Clear conversation history, then switch to Act Mode and execute.",
+            },
+            {
+                "value": "reject_continue",
+                "label": "Reject and continue planning",
+                "description": "Stay in Plan Mode and continue refining the plan.",
+            },
+        ]
+
+        title = "Plan approval required"
+        if summary:
+            title = f"Plan approval: {summary}"
+
+        def on_confirm(value: str) -> None:
+            if value == "approve_execute":
+                self._schedule_background(
+                    self._approve_plan_and_execute(
+                        plan_path=plan_path,
+                        execution_prompt=execution_prompt,
+                        clear_context=False,
+                    )
+                )
+                return
+            if value == "approve_clear_execute":
+                self._schedule_background(
+                    self._approve_plan_and_execute(
+                        plan_path=plan_path,
+                        execution_prompt=execution_prompt,
+                        clear_context=True,
+                    )
+                )
+                return
+            if value == "reject_continue":
+                self._reject_plan_and_continue(plan_path=plan_path)
+
+        def on_cancel() -> None:
+            self._reject_plan_and_continue(plan_path=plan_path)
+
+        ok = self._selection_ui.set_options(
+            title=title,
+            options=options,
+            on_confirm=on_confirm,
+            on_cancel=on_cancel,
+        )
+        if not ok:
+            self._renderer.append_system_message(
+                "No plan approval options available.",
+                severity="error",
+            )
+            return
+        self._selection_ui.refresh()
+        self._ui_mode = UIMode.SELECTION
+        self._sync_focus_for_mode()
+        self._invalidate()
+
+    async def _approve_plan_and_execute(
+        self,
+        *,
+        plan_path: str,
+        execution_prompt: str,
+        clear_context: bool = False,
+    ) -> None:
+        prompt = self._session.approve_plan(clear_context=clear_context)
+        if execution_prompt.strip():
+            prompt = execution_prompt.strip()
+        self._pending_plan_approval = None
+        try:
+            self._status_bar.set_mode(self._session.get_mode())
+        except Exception:
+            pass
+        self._renderer.append_system_message(f"Plan approved: {plan_path}")
+        self._refresh_layers()
+        await self._submit_user_message(prompt, display_text="Execute approved plan")
+
+    def _reject_plan_and_continue(self, *, plan_path: str) -> None:
+        self._session.reject_plan()
+        self._pending_plan_approval = None
+        try:
+            self._status_bar.set_mode(self._session.get_mode())
+        except Exception:
+            pass
+        self._renderer.append_system_message(f"Plan rejected: {plan_path}")
+        self._refresh_layers()
+
+    def _maybe_cancel_tool_result_flash(self, event: object) -> None:
+        if not self._tool_result_flash_active:
+            return
+
+        from comate_agent_sdk.agent.events import StopEvent, TextEvent
+
+        if isinstance(event, TextEvent) or isinstance(event, StopEvent):
+            self._schedule_background(self._stop_tool_result_flash())
+
+    def _maybe_flash_tool_result(self, event: object) -> None:
+        from comate_agent_sdk.agent.events import ToolResultEvent
+
+        if not isinstance(event, ToolResultEvent):
+            return
+        tool_name = str(event.tool or "").strip()
+        if tool_name.lower() == "todowrite":
+            return
+        if self._renderer.has_running_tools():
+            return
+        self._trigger_tool_result_flash(
+            tool_name=tool_name or "Tool",
+            is_error=bool(event.is_error),
+        )
+
+    def _trigger_tool_result_flash(self, *, tool_name: str, is_error: bool) -> None:
+        del is_error, tool_name
+        phrase = (
+            random.choice(DEFAULT_STATUS_PHRASES)
+            if DEFAULT_STATUS_PHRASES
+            else "Vibing..."
+        )
+        duration_seconds = max(0.15, float(self._tool_result_flash_seconds))
+        self._tool_result_flash_gen += 1
+        self._tool_result_flash_active = True
+        self._tool_result_flash_until_monotonic = time.monotonic() + duration_seconds
+        gen = self._tool_result_flash_gen
+        self._schedule_background(self._start_tool_result_flash(gen=gen, hint=phrase))
+
+    async def _start_tool_result_flash(self, *, gen: int, hint: str) -> None:
+        if gen != self._tool_result_flash_gen:
+            return
+        await self._tool_result_animator.start()
+        if gen != self._tool_result_flash_gen:
+            return
+        self._tool_result_animator.set_status_hint(hint)
+        self._render_dirty = True
+        self._invalidate()
+
+    async def _stop_tool_result_flash(self) -> None:
+        if not self._tool_result_flash_active:
+            return
+        self._tool_result_flash_gen += 1
+        self._tool_result_flash_active = False
+        self._tool_result_flash_until_monotonic = None
+        self._tool_result_animator.set_status_hint(None)
+        await self._tool_result_animator.stop()
+        self._render_dirty = True
+        self._invalidate()
+
+    def _schedule_background(self, coroutine: Any) -> None:
+        task = asyncio.create_task(coroutine)
+
+        def _done(done_task: asyncio.Task[Any]) -> None:
+            try:
+                done_task.result()
+            except asyncio.CancelledError:
+                return
+            except Exception:
+                logger.exception("background task failed")
+
+        task.add_done_callback(_done)
+
+    def _refresh_layers(self) -> None:
+        self._sync_focus_for_mode()
+        self._render_dirty = True
+
+    async def _ui_tick(self) -> None:
+        try:
+            while not self._closing:
+                self._renderer.tick_progress()
+                self._loading_frame += 1
+                # busy 时每隔几秒换一个短语，让 loading 更“活”
+                if self._busy and time.monotonic() >= self._fallback_phrase_refresh_at:
+                    self._fallback_loading_phrase = (
+                        random.choice(DEFAULT_STATUS_PHRASES)
+                        if DEFAULT_STATUS_PHRASES
+                        else "Thinking…"
+                    )
+                    self._fallback_phrase_refresh_at = time.monotonic() + 3.0
+                    self._render_dirty = True
+
+                await self._drain_history_async()
+
+                # 检查动画器是否需要刷新
+                if self._animator.consume_dirty():
+                    self._render_dirty = True
+                if self._tool_result_animator.consume_dirty():
+                    self._render_dirty = True
+
+                if self._tool_result_flash_active:
+                    until = self._tool_result_flash_until_monotonic
+                    if until is None or time.monotonic() >= until:
+                        self._schedule_background(self._stop_tool_result_flash())
+                    else:
+                        self._render_dirty = True
+
+                loading_line = self._renderer.loading_line().strip()
+                loading_changed = loading_line != self._last_loading_line
+                if loading_changed:
+                    self._last_loading_line = loading_line
+                    self._render_dirty = True
+
+                if self._renderer.has_running_tools():
+                    # Keep repainting for breathing animation.
+                    self._render_dirty = True
+                elif self._busy or self._initializing:
+                    self._render_dirty = True
+
+                if self._render_dirty:
+                    self._invalidate()
+                    self._render_dirty = False
+
+                # 动态帧率：busy/动画/initializing 时降为 6fps（缓解 scrollback 污染），idle 时 4fps
+                fast = (
+                    self._busy
+                    or self._initializing
+                    or self._animator.is_active
+                    or self._renderer.has_running_tools()
+                )
+                sleep_s = 1 / 6 if fast else 1 / 4
+                await asyncio.sleep(sleep_s)
+        except asyncio.CancelledError:
+            return
+
+    def _invalidate(self) -> None:
+        if self._app is None:
+            return
+        self._app.invalidate()
+
+    def _maybe_capture_checkpoint(self, *, user_preview: str) -> None:
+        try:
+            checkpoint = self._rewind_store.capture_checkpoint_for_latest_turn(
+                user_preview=user_preview,
+            )
+            if checkpoint is not None:
+                logger.info(
+                    "checkpoint captured: session=%s id=%s turn=%s",
+                    self._session.session_id,
+                    checkpoint.checkpoint_id,
+                    checkpoint.turn_number,
+                )
+        except Exception as exc:
+            logger.warning(f"failed to capture checkpoint: {exc}", exc_info=True)
+
+    async def _replace_session(
+        self,
+        new_session: ChatSession,
+        *,
+        close_old: bool = True,
+        replay_history: bool = True,
+    ) -> None:
+        old_session = self._session
+        self._session = new_session
+        self._status_bar.set_session(new_session)
+        self._rewind_store.bind_session(new_session)
+        await self._status_bar.refresh()
+        self._renderer.reset_history_view()
+        self._printed_history_index = 0
+        if replay_history:
+            self.add_resume_history("resume")
+        if close_old and old_session is not new_session:
+            await old_session.close()
+
+    @property
+    def session(self) -> ChatSession:
+        return self._session
+
+    def _request_exit(self) -> None:
+        if self._is_compacting and self._compact_task is not None:
+            self._pending_exit_after_compact_cancel = True
+            if not self._compact_cancel_requested:
+                self._compact_cancel_requested = True
+                self._renderer.append_system_message(
+                    "正在取消 /compact，请等待回滚完成后退出。",
+                    severity="warning",
+                )
+                self._compact_task.cancel()
+            else:
+                self._renderer.append_system_message(
+                    "已请求取消 /compact，等待回滚完成。",
+                    severity="warning",
+                )
+            self._refresh_layers()
+            return
+        self._exit_app()
+
+    def _exit_app(self) -> None:
+        self._closing = True
+        self._session.run_controller.clear()
+        if self._stream_task is not None:
+            self._stream_task.cancel()
+        if self._app is not None:
+            self._app.exit(result=None)
+
+    async def run(
+        self,
+        *,
+        mcp_init: Callable[[], Any] | None = None,
+    ) -> None:
+        if self._app is None:
+            return
+
+        self._refresh_layers()
+
+        if mcp_init is not None:
+            self._initializing = True
+
+            async def _do_init() -> None:
+                try:
+                    await mcp_init()
+                except asyncio.CancelledError:
+                    return
+                finally:
+                    self._initializing = False
+                    if self._queued_messages and not self._busy:
+                        queued = self._queued_messages.popleft()
+                        self._schedule_background(self._submit_user_message(queued))
+                    self._refresh_layers()
+
+            self._mcp_init_task = asyncio.create_task(_do_init(), name="terminal-mcp-init")
+
+        self._ui_tick_task = asyncio.create_task(
+            self._ui_tick(),
+            name="terminal-ui-tick",
+        )
+        try:
+            # Ensure scrollback prints don't mix with the inline (full_screen=False) UI.
+            with patch_stdout(raw=True):
+                await self._app.run_async()
+        finally:
+            self._closing = True
+            if self._mcp_init_task is not None:
+                self._mcp_init_task.cancel()
+                with suppress(asyncio.CancelledError):
+                    await self._mcp_init_task
+                self._mcp_init_task = None
+            if self._ui_tick_task is not None:
+                self._ui_tick_task.cancel()
+                with suppress(asyncio.CancelledError):
+                    await self._ui_tick_task
+            self._renderer.close()