Skip to main content

tea_cli/tui/
app.rs

1use std::collections::{BTreeMap, BTreeSet};
2use std::io;
3use std::path::{Path, PathBuf};
4use std::str::FromStr as _;
5use std::time::Duration;
6
7use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
8use ratatui::backend::{Backend as _, CrosstermBackend};
9use ratatui::layout::{Position, Rect, Size};
10use tea::RuntimeCommandOutcome;
11use tea_coding::{CodingAgentService, config::persist_global_model_settings};
12use tea_mcp::McpServerId;
13use tea_protocol::{
14    AgentEvent, CanonicalMessage, ContentBlock, ModelRef, ReasoningEffort, SessionId,
15};
16use tea_session::SessionName;
17use tokio::sync::mpsc;
18use tokio::time;
19use unicode_segmentation::UnicodeSegmentation as _;
20
21use super::attachment::{load_local_image, validate_addition};
22use super::clipboard::{Clipboard, SystemClipboard};
23use super::commands::{CommandCatalog, SlashCommand};
24use super::custom_terminal::Terminal;
25use super::editor::Editor;
26use super::input::{InputEvent, spawn_input_pump};
27use super::keymap::{BindingAction, EditorAction, KeyMap, resolve_editor_action};
28use super::layout::draw_lines;
29use super::overlay::{CommandCompletion, Overlay};
30use super::presentation::{CellNode, Presentation};
31use super::reducer::{Action, Effect, reduce};
32use super::render::{Renderer, workspace_trust_panel};
33use super::selectors::{Selector, SelectorItem, SelectorValue};
34use super::state::{ApprovalChoice, SessionEphemera, StartupContext, TuiState};
35use super::status::StatusIndicator;
36use super::terminal::{
37    CrosstermDriver, TerminalCapabilities, TerminalGuard, TerminalOptions, TerminalTitle,
38    ViewportMode,
39};
40use super::theme::Theme;
41use crate::args::{CliArgs, SessionSelection};
42use crate::bootstrap::WorkspaceTrustPrompt;
43use crate::session_views::{mcp_servers, session_list, session_tree};
44use crate::{CliBootstrap, CliFailure, ExitCategory};
45
46const INPUT_CAPACITY: usize = 128;
47const FRAME_DEADLINE: Duration = Duration::from_millis(100);
48const STREAM_FRAME_CADENCE: Duration = Duration::from_millis(50);
49const RUN_ACTIVITY_TICK: Duration = Duration::from_secs(1);
50
51fn sync_reasoning_projection(state: &mut TuiState, service: &CodingAgentService) -> bool {
52    let model_default = state
53        .model_ref()
54        .and_then(|model| service.model_spec(model))
55        .map(|model| {
56            model.reasoning_profile().map_or(
57                ReasoningEffort::Off,
58                tea_model::ReasoningProfile::default_effort,
59            )
60        });
61    state.set_model_default_reasoning_effort(model_default)
62}
63
64#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
65enum WorkspaceTrustChoice {
66    Trust,
67    #[default]
68    Exit,
69}
70
71impl WorkspaceTrustChoice {
72    const fn toggled(self) -> Self {
73        match self {
74            Self::Trust => Self::Exit,
75            Self::Exit => Self::Trust,
76        }
77    }
78
79    const fn should_trust(self) -> bool {
80        matches!(self, Self::Trust)
81    }
82}
83
84#[derive(Clone, Copy, Debug, PartialEq, Eq)]
85enum WorkspaceTrustKeyAction {
86    Select(WorkspaceTrustChoice),
87    Submit(bool),
88}
89
90/// Coalesces visible stream deltas while preserving immediate interactive frames.
91#[derive(Debug, Default)]
92struct FrameScheduler {
93    last_frame: Option<time::Instant>,
94    pending_stream_frame: bool,
95}
96
97impl FrameScheduler {
98    fn request(&mut self, stream_delta: bool, now: time::Instant) -> bool {
99        if !stream_delta {
100            self.pending_stream_frame = false;
101            return true;
102        }
103        if self
104            .last_frame
105            .is_none_or(|last_frame| now >= last_frame + STREAM_FRAME_CADENCE)
106        {
107            self.pending_stream_frame = false;
108            true
109        } else {
110            self.pending_stream_frame = true;
111            false
112        }
113    }
114
115    fn next_deadline(&self) -> Option<time::Instant> {
116        self.pending_stream_frame
117            .then(|| self.last_frame.map(|frame| frame + STREAM_FRAME_CADENCE))
118            .flatten()
119    }
120
121    fn take_pending(&mut self) -> bool {
122        std::mem::take(&mut self.pending_stream_frame)
123    }
124
125    fn record_frame(&mut self, now: time::Instant) {
126        self.last_frame = Some(now);
127        self.pending_stream_frame = false;
128    }
129}
130
131/// Tracks whole elapsed seconds from run acceptance without depending on wall-clock sleeps in tests.
132#[derive(Debug, Default)]
133struct RunActivityTimer {
134    started_at: Option<time::Instant>,
135    reported_seconds: u64,
136}
137
138impl RunActivityTimer {
139    fn from_state(running: bool, elapsed_seconds: u64, now: time::Instant) -> Self {
140        let started_at = running.then(|| {
141            now.checked_sub(Duration::from_secs(elapsed_seconds))
142                .unwrap_or(now)
143        });
144        Self {
145            started_at,
146            reported_seconds: elapsed_seconds,
147        }
148    }
149
150    fn sync(&mut self, was_running: bool, running: bool, elapsed_seconds: u64, now: time::Instant) {
151        match (was_running, running) {
152            (false, true) => {
153                self.started_at = Some(
154                    now.checked_sub(Duration::from_secs(elapsed_seconds))
155                        .unwrap_or(now),
156                );
157                self.reported_seconds = elapsed_seconds;
158            }
159            (true, false) => {
160                self.started_at = None;
161                self.reported_seconds = elapsed_seconds;
162            }
163            (true, true) => {
164                self.reported_seconds = self.reported_seconds.max(elapsed_seconds);
165            }
166            (false, false) => {}
167        }
168    }
169
170    fn next_deadline(&self) -> Option<time::Instant> {
171        self.started_at.map(|started_at| {
172            started_at + Duration::from_secs(self.reported_seconds) + RUN_ACTIVITY_TICK
173        })
174    }
175
176    fn advance(&mut self, now: time::Instant) -> u64 {
177        let Some(started_at) = self.started_at else {
178            return 0;
179        };
180        let elapsed_seconds = now.saturating_duration_since(started_at).as_secs();
181        let advance = elapsed_seconds.saturating_sub(self.reported_seconds);
182        self.reported_seconds = self.reported_seconds.max(elapsed_seconds);
183        advance
184    }
185}
186
187/// Synchronous frame boundary injected into the asynchronous application loop.
188pub trait FrameSink {
189    /// Queues finalized cells for one-time insertion into native terminal scrollback.
190    ///
191    /// # Errors
192    ///
193    /// Returns a terminal output failure.
194    fn insert_history_cells(&mut self, _cells: &[CellNode]) -> io::Result<()> {
195        Ok(())
196    }
197
198    /// Replaces source-backed history before a resize or canonical rebuild replay.
199    ///
200    /// # Errors
201    ///
202    /// Returns a terminal output failure.
203    fn replace_history_cells(&mut self, _cells: &[CellNode]) -> io::Result<()> {
204        Ok(())
205    }
206
207    /// Renders the current pure state projection and editor cursor.
208    ///
209    /// # Errors
210    ///
211    /// Returns a terminal output failure.
212    fn render(&mut self, state: &TuiState, cursor_byte: usize) -> io::Result<()>;
213}
214
215/// Runs the production crossterm interactive mode.
216///
217/// # Errors
218///
219/// Returns stable CLI failures for bootstrap, terminal, runtime, or input errors.
220pub async fn run(args: &CliArgs, bootstrap: &CliBootstrap) -> Result<(), CliFailure> {
221    if args.print || args.json || args.rpc {
222        return Err(CliFailure::usage(
223            "interactive mode cannot be combined with a headless mode",
224        ));
225    }
226    if let Some(prompt) = bootstrap.workspace_trust_prompt(args)? {
227        if !prompt_for_workspace_trust(&prompt).await? {
228            return Err(CliFailure::new(
229                ExitCategory::TrustOrConfig,
230                "project-local configuration is not trusted",
231            ));
232        }
233        CliBootstrap::accept_workspace_trust(&prompt)?;
234    }
235    let initial_prompt = interactive_initial_prompt(args, bootstrap)?;
236    let global_settings_path = bootstrap.global_settings_path(args)?;
237    let (service, selection, startup_notices) = bootstrap.build_tui_async(args).await?;
238    let mut interrupt = tokio::spawn(tokio::signal::ctrl_c());
239    tokio::task::yield_now().await;
240    let mut frames = match TerminalFrameSink::new(
241        service.settings().tui.viewport.as_str(),
242        service.settings().tui.reduced_motion,
243    ) {
244        Ok(frames) => frames,
245        Err(error) => {
246            interrupt.abort();
247            service.shutdown().await;
248            return Err(error);
249        }
250    };
251    let (pump, input) = spawn_input_pump(INPUT_CAPACITY);
252    let mut clipboard = SystemClipboard;
253    let interactive = Box::pin(run_with_channels_context(
254        &service,
255        selection,
256        input,
257        &mut frames,
258        &mut clipboard,
259        InteractiveStartup {
260            initial_prompt,
261            notices: startup_notices,
262            global_settings_path: Some(global_settings_path),
263        },
264    ));
265    let result = tokio::select! {
266        result = interactive => result.map(drop),
267        signal = &mut interrupt => match signal {
268            Ok(Ok(())) => Err(CliFailure::new(ExitCategory::Cancelled, "interrupted")),
269            Ok(Err(_)) | Err(_) => Err(CliFailure::new(
270                ExitCategory::Internal,
271                "interrupt handler failed",
272            )),
273        },
274    };
275    interrupt.abort();
276    pump.shutdown().await;
277    let _ = frames.clear_inline_viewport();
278    drop(frames);
279    service.shutdown().await;
280    result
281}
282
283async fn prompt_for_workspace_trust(prompt: &WorkspaceTrustPrompt) -> Result<bool, CliFailure> {
284    let mut frames = TerminalFrameSink::new("inline", true)?;
285    let (pump, input) = spawn_input_pump(INPUT_CAPACITY);
286    let mut interrupt = tokio::spawn(tokio::signal::ctrl_c());
287    tokio::task::yield_now().await;
288    let prompt_loop = Box::pin(run_workspace_trust_prompt(prompt, input, &mut frames));
289    let result = tokio::select! {
290        result = prompt_loop => result,
291        signal = &mut interrupt => match signal {
292            Ok(Ok(())) => Err(CliFailure::new(ExitCategory::Cancelled, "interrupted")),
293            Ok(Err(_)) | Err(_) => Err(CliFailure::new(
294                ExitCategory::Internal,
295                "interrupt handler failed",
296            )),
297        },
298    };
299    interrupt.abort();
300    pump.shutdown().await;
301    let cleanup = frames
302        .clear_inline_viewport()
303        .map_err(|_| CliFailure::new(ExitCategory::Internal, "terminal rendering failed"));
304    drop(frames);
305    cleanup?;
306    result
307}
308
309async fn run_workspace_trust_prompt(
310    prompt: &WorkspaceTrustPrompt,
311    mut input: mpsc::Receiver<InputEvent>,
312    frames: &mut TerminalFrameSink,
313) -> Result<bool, CliFailure> {
314    let mut choice = WorkspaceTrustChoice::default();
315    frames
316        .render_workspace_trust(prompt, choice)
317        .map_err(|_| CliFailure::new(ExitCategory::Internal, "terminal rendering failed"))?;
318    while let Some(input) = input.recv().await {
319        match input {
320            InputEvent::Resize { .. } => {
321                frames.render_workspace_trust(prompt, choice).map_err(|_| {
322                    CliFailure::new(ExitCategory::Internal, "terminal rendering failed")
323                })?;
324            }
325            InputEvent::Key(key) => match workspace_trust_key_action(choice, key) {
326                WorkspaceTrustKeyAction::Select(selected) => {
327                    choice = selected;
328                    frames.render_workspace_trust(prompt, choice).map_err(|_| {
329                        CliFailure::new(ExitCategory::Internal, "terminal rendering failed")
330                    })?;
331                }
332                WorkspaceTrustKeyAction::Submit(trusted) => return Ok(trusted),
333            },
334            InputEvent::Focus(_) | InputEvent::Paste(_) => {}
335        }
336    }
337    Ok(false)
338}
339
340fn workspace_trust_key_action(
341    choice: WorkspaceTrustChoice,
342    key: KeyEvent,
343) -> WorkspaceTrustKeyAction {
344    match key.code {
345        KeyCode::Left
346        | KeyCode::Right
347        | KeyCode::Up
348        | KeyCode::Down
349        | KeyCode::Tab
350        | KeyCode::BackTab => WorkspaceTrustKeyAction::Select(choice.toggled()),
351        KeyCode::Char('1') => WorkspaceTrustKeyAction::Select(WorkspaceTrustChoice::Trust),
352        KeyCode::Char('2') => WorkspaceTrustKeyAction::Select(WorkspaceTrustChoice::Exit),
353        KeyCode::Enter => WorkspaceTrustKeyAction::Submit(choice.should_trust()),
354        KeyCode::Esc => WorkspaceTrustKeyAction::Submit(false),
355        KeyCode::Char('c' | 'd') if key.modifiers.contains(KeyModifiers::CONTROL) => {
356            WorkspaceTrustKeyAction::Submit(false)
357        }
358        _ => WorkspaceTrustKeyAction::Select(choice),
359    }
360}
361
362/// Runs the bounded interactive loop with injected input, frame, and clipboard ports.
363///
364/// # Errors
365///
366/// Returns stable failures from session selection, settings, runtime, or rendering.
367pub async fn run_with_channels(
368    service: &CodingAgentService,
369    selection: SessionSelection,
370    input: mpsc::Receiver<InputEvent>,
371    frames: &mut dyn FrameSink,
372    clipboard: &mut dyn Clipboard,
373    initial_prompt: Option<String>,
374) -> Result<TuiState, CliFailure> {
375    Box::pin(run_with_channels_context(
376        service,
377        selection,
378        input,
379        frames,
380        clipboard,
381        InteractiveStartup {
382            initial_prompt,
383            notices: Vec::new(),
384            global_settings_path: None,
385        },
386    ))
387    .await
388}
389
390/// Runs the injected interactive loop with an explicit persistent settings target.
391///
392/// This is the embeddable counterpart of the production TUI startup path. Quick
393/// reasoning changes remain session-local; accepted model-and-effort choices may
394/// update only the supplied sparse global settings file.
395///
396/// # Errors
397///
398/// Returns stable failures from session selection, settings, runtime, or rendering.
399pub async fn run_with_channels_with_settings_path(
400    service: &CodingAgentService,
401    selection: SessionSelection,
402    input: mpsc::Receiver<InputEvent>,
403    frames: &mut dyn FrameSink,
404    clipboard: &mut dyn Clipboard,
405    initial_prompt: Option<String>,
406    global_settings_path: PathBuf,
407) -> Result<TuiState, CliFailure> {
408    Box::pin(run_with_channels_context(
409        service,
410        selection,
411        input,
412        frames,
413        clipboard,
414        InteractiveStartup {
415            initial_prompt,
416            notices: Vec::new(),
417            global_settings_path: Some(global_settings_path),
418        },
419    ))
420    .await
421}
422
423struct InteractiveStartup {
424    initial_prompt: Option<String>,
425    notices: Vec<String>,
426    global_settings_path: Option<PathBuf>,
427}
428
429async fn run_with_channels_context(
430    service: &CodingAgentService,
431    selection: SessionSelection,
432    input: mpsc::Receiver<InputEvent>,
433    frames: &mut dyn FrameSink,
434    clipboard: &mut dyn Clipboard,
435    startup_options: InteractiveStartup,
436) -> Result<TuiState, CliFailure> {
437    let InteractiveStartup {
438        initial_prompt,
439        notices,
440        global_settings_path,
441    } = startup_options;
442    let session_id = crate::modes::print::select_session(service, selection).await?;
443    let events = service.subscribe(session_id).map_err(CliFailure::from)?;
444    let snapshot = service
445        .session_snapshot(session_id)
446        .await
447        .map_err(CliFailure::from)?;
448    let startup = StartupContext::new(
449        service.workspace().host_path().display().to_string(),
450        service.resources().context().len(),
451        service.resources().skills().len(),
452        service.resources().prompts().len(),
453        service.resources().diagnostics().len(),
454    );
455    let mut state = TuiState::from_snapshot(&snapshot, startup.clone());
456    sync_reasoning_projection(&mut state, service);
457    for notice in notices {
458        let _ = reduce(&mut state, Action::Notify(notice));
459    }
460    if service.settings().tui.collapse_thinking {
461        let _ = reduce(&mut state, Action::ToggleThinking);
462    }
463    let editor = Editor::new();
464    let keymap = KeyMap::from_settings(&service.settings().tui)
465        .map_err(|_| CliFailure::new(ExitCategory::TrustOrConfig, "keybindings are invalid"))?;
466    let commands = command_catalog(service)?;
467    let activity_timer = RunActivityTimer::from_state(
468        StatusIndicator::needs_elapsed_tick(&state),
469        state.run_elapsed_seconds(),
470        time::Instant::now(),
471    );
472    let mut app = InteractiveApp {
473        service,
474        session_id,
475        events,
476        input,
477        frames,
478        clipboard,
479        state,
480        editor,
481        keymap,
482        commands,
483        startup,
484        global_settings_path,
485        pending_model_selection: None,
486        owned_runs: BTreeSet::new(),
487        session_ephemera: BTreeMap::new(),
488        frame_scheduler: FrameScheduler::default(),
489        activity_timer,
490        transcript_cells: Vec::new(),
491        quit: false,
492    };
493    app.sync_committed_history()?;
494    app.render()?;
495    if let Some(prompt) = initial_prompt {
496        app.start_prompt(prompt.clone()).await?;
497        app.apply(Action::ShowPendingUserPrompt(prompt)).await?;
498    }
499    Box::pin(app.run_loop()).await
500}
501
502struct InteractiveApp<'a> {
503    service: &'a CodingAgentService,
504    session_id: SessionId,
505    events: mpsc::Receiver<tea_protocol::EventEnvelope>,
506    input: mpsc::Receiver<InputEvent>,
507    frames: &'a mut dyn FrameSink,
508    clipboard: &'a mut dyn Clipboard,
509    state: TuiState,
510    editor: Editor,
511    keymap: KeyMap,
512    commands: CommandCatalog,
513    startup: StartupContext,
514    global_settings_path: Option<PathBuf>,
515    pending_model_selection: Option<ModelRef>,
516    owned_runs: BTreeSet<SessionId>,
517    session_ephemera: BTreeMap<SessionId, SessionEphemera>,
518    frame_scheduler: FrameScheduler,
519    activity_timer: RunActivityTimer,
520    transcript_cells: Vec<CellNode>,
521    quit: bool,
522}
523
524impl InteractiveApp<'_> {
525    async fn run_loop(mut self) -> Result<TuiState, CliFailure> {
526        while !self.quit {
527            let session_id = self.session_id;
528            let frame_deadline = self.frame_scheduler.next_deadline();
529            let activity_deadline = self.activity_timer.next_deadline();
530            tokio::select! {
531                () = time::sleep_until(frame_deadline.unwrap_or_else(time::Instant::now)), if frame_deadline.is_some() => {
532                    self.flush_pending_frame()?;
533                }
534                input = self.input.recv() => {
535                    match input {
536                        Some(input) => Box::pin(self.handle_input(input)).await?,
537                        None => self.quit = true,
538                    }
539                }
540                event = self.events.recv() => {
541                    match event {
542                        Some(event) => {
543                            let run_finished = matches!(event.event(), AgentEvent::RunFinished { .. });
544                            self.apply(Action::Event(Box::new(event))).await?;
545                            if run_finished {
546                                if self.owned_runs.contains(&session_id) {
547                                    let outcome = self.service.wait(session_id).await;
548                                    self.finish_owned_run(session_id, outcome).await?;
549                                } else {
550                                    tokio::task::yield_now().await;
551                                }
552                                self.flush_pending_reasoning_effort().await?;
553                            }
554                        }
555                        None => self.reconnect().await?,
556                    }
557                }
558                outcome = self.service.wait(session_id), if self.owned_runs.contains(&session_id) => {
559                    self.finish_owned_run(session_id, outcome).await?;
560                    self.flush_pending_reasoning_effort().await?;
561                }
562                () = time::sleep_until(activity_deadline.unwrap_or_else(time::Instant::now)), if activity_deadline.is_some() => {
563                    let elapsed_seconds = self.activity_timer.advance(time::Instant::now());
564                    if elapsed_seconds > 0 {
565                        self.apply(Action::AdvanceRunElapsed(elapsed_seconds)).await?;
566                    }
567                }
568            }
569        }
570        self.flush_pending_frame()?;
571        for session_id in self.owned_runs.iter().copied().collect::<Vec<_>>() {
572            let _ = self.service.abort(session_id).await;
573        }
574        Ok(self.state)
575    }
576
577    async fn handle_input(&mut self, input: InputEvent) -> Result<(), CliFailure> {
578        match input {
579            InputEvent::Resize { width, height } => {
580                self.apply(Action::Resize { width, height }).await?;
581            }
582            InputEvent::Focus(_) => {}
583            InputEvent::Paste(_) if self.state.approval.is_some() => {}
584            InputEvent::Paste(text)
585                if self
586                    .state
587                    .overlay
588                    .as_ref()
589                    .and_then(Overlay::selector)
590                    .is_some() =>
591            {
592                let selector = self
593                    .state
594                    .overlay
595                    .as_mut()
596                    .and_then(Overlay::selector_mut)
597                    .expect("selector checked above");
598                let mut query = selector.query().to_owned();
599                query.push_str(&text);
600                selector.set_query(&query);
601                self.state.bump_generation();
602                self.render()?;
603            }
604            InputEvent::Paste(text) => {
605                if self.editor.insert_paste(&text).is_err() {
606                    self.notify("paste exceeds the editor size limit").await?;
607                } else {
608                    self.sync_editor().await?;
609                }
610            }
611            InputEvent::Key(key) if self.state.approval.is_some() => {
612                self.handle_approval_key(key).await?;
613            }
614            InputEvent::Key(key) if self.state.overlay.is_some() => {
615                self.handle_overlay_key(key).await?;
616            }
617            InputEvent::Key(key) => Box::pin(self.handle_editor_key(key)).await?,
618        }
619        Ok(())
620    }
621
622    async fn handle_approval_key(&mut self, key: KeyEvent) -> Result<(), CliFailure> {
623        if self.state.approval_submitting() {
624            if self.keymap.resolve(key, false) == Some(BindingAction::Exit) {
625                self.quit = true;
626            }
627            return Ok(());
628        }
629        match key.code {
630            KeyCode::Left | KeyCode::Up | KeyCode::BackTab => {
631                let choice = self.state.approval_choice().previous();
632                self.apply(Action::SelectApproval(choice)).await?;
633            }
634            KeyCode::Right | KeyCode::Down | KeyCode::Tab => {
635                let choice = self.state.approval_choice().next();
636                self.apply(Action::SelectApproval(choice)).await?;
637            }
638            KeyCode::Char('1') => {
639                self.apply(Action::SelectApproval(ApprovalChoice::AllowOnce))
640                    .await?;
641            }
642            KeyCode::Char('2') => {
643                self.apply(Action::SelectApproval(ApprovalChoice::AllowSession))
644                    .await?;
645            }
646            KeyCode::Char('3') => {
647                self.apply(Action::SelectApproval(ApprovalChoice::Deny))
648                    .await?;
649            }
650            KeyCode::Enter => self.submit_approval().await?,
651            _ if self.keymap.resolve(key, false) == Some(BindingAction::Exit) => {
652                self.quit = true;
653            }
654            _ => {}
655        }
656        Ok(())
657    }
658
659    async fn submit_approval(&mut self) -> Result<(), CliFailure> {
660        if self.owns_current_run() || self.state.approval_submitting() {
661            return Ok(());
662        }
663        let Some(approval_id) = self.state.approval().map(|approval| approval.approval_id) else {
664            return Ok(());
665        };
666        let decision = self.state.approval_choice().decision();
667        match self.service.approve(self.session_id, approval_id, decision) {
668            Ok(_) => {
669                self.owned_runs.insert(self.session_id);
670                self.apply(Action::SetApprovalSubmitting(true)).await?;
671                self.apply(Action::StartRunActivity).await?;
672            }
673            Err(error) => self.notify(error.message()).await?,
674        }
675        Ok(())
676    }
677
678    async fn handle_editor_key(&mut self, key: KeyEvent) -> Result<(), CliFailure> {
679        if self.handle_transcript_navigation(key).await? {
680            return Ok(());
681        }
682        if key.code == KeyCode::BackTab {
683            return self.cycle_reasoning_effort().await;
684        }
685        let editor_action = resolve_editor_action(key);
686        let editor_preempts_binding = matches!(editor_action, Some(EditorAction::DeleteForward))
687            && !self.editor.text().is_empty()
688            || matches!(editor_action, Some(EditorAction::Yank)) && self.editor.has_kill_buffer();
689        if editor_preempts_binding {
690            return self
691                .handle_editor_action(editor_action.expect("editor action checked above"))
692                .await;
693        }
694        if let Some(action) = self
695            .keymap
696            .resolve(key, self.owns_current_run() || self.state.running)
697        {
698            return Box::pin(self.handle_binding(action)).await;
699        }
700        if let Some(action) = editor_action {
701            return self.handle_editor_action(action).await;
702        }
703        let changed = match key.code {
704            KeyCode::Tab => {
705                if let Some(completion) = self
706                    .commands
707                    .complete(self.editor.text(), 1)
708                    .into_iter()
709                    .next()
710                {
711                    self.editor = Editor::with_limit(completion, super::MAX_EDITOR_BYTES)
712                        .expect("bounded command completion");
713                    true
714                } else {
715                    false
716                }
717            }
718            KeyCode::Char(character)
719                if key
720                    .modifiers
721                    .contains(KeyModifiers::CONTROL | KeyModifiers::ALT)
722                    && !key.modifiers.contains(KeyModifiers::SUPER) =>
723            {
724                self.editor.insert_char(character).is_ok()
725            }
726            KeyCode::Char(character)
727                if !key.modifiers.intersects(
728                    KeyModifiers::CONTROL | KeyModifiers::ALT | KeyModifiers::SUPER,
729                ) =>
730            {
731                self.editor.insert_char(character).is_ok()
732            }
733            _ => false,
734        };
735        if changed {
736            self.sync_editor().await?;
737        }
738        Ok(())
739    }
740
741    async fn handle_editor_action(&mut self, action: EditorAction) -> Result<(), CliFailure> {
742        let changed = match action {
743            EditorAction::InsertNewline => {
744                if let Ok(()) = self.editor.insert_newline() {
745                    true
746                } else {
747                    self.notify("editor size limit reached").await?;
748                    false
749                }
750            }
751            EditorAction::MoveLeft => {
752                self.editor.move_left();
753                true
754            }
755            EditorAction::MoveRight => {
756                self.editor.move_right();
757                true
758            }
759            EditorAction::MoveUp if self.editor.text().contains('\n') => {
760                self.editor.move_up();
761                true
762            }
763            EditorAction::MoveDown if self.editor.text().contains('\n') => {
764                self.editor.move_down();
765                true
766            }
767            EditorAction::MoveUp => self.editor.previous_history(),
768            EditorAction::MoveDown => self.editor.next_history(),
769            EditorAction::MoveWordLeft => {
770                self.editor.move_word_left();
771                true
772            }
773            EditorAction::MoveWordRight => {
774                self.editor.move_word_right();
775                true
776            }
777            EditorAction::MoveLineStart { cross_line: true } => {
778                self.editor.move_home_or_previous_line();
779                true
780            }
781            EditorAction::MoveLineStart { cross_line: false } => {
782                self.editor.move_home();
783                true
784            }
785            EditorAction::MoveLineEnd { cross_line: true } => {
786                self.editor.move_end_or_next_line();
787                true
788            }
789            EditorAction::MoveLineEnd { cross_line: false } => {
790                self.editor.move_end();
791                true
792            }
793            EditorAction::DeleteBackward => self.editor.delete_backward(),
794            EditorAction::DeleteForward => self.editor.delete_forward(),
795            EditorAction::DeleteWordBackward => self.editor.delete_word_backward(),
796            EditorAction::DeleteWordForward => self.editor.delete_word_forward(),
797            EditorAction::KillLineStart => self.editor.kill_to_line_start(),
798            EditorAction::KillLineEnd => self.editor.kill_to_line_end(),
799            EditorAction::Yank => {
800                if let Ok(changed) = self.editor.yank() {
801                    changed
802                } else {
803                    self.notify("editor size limit reached").await?;
804                    false
805                }
806            }
807            EditorAction::Undo => self.editor.undo(),
808        };
809        if changed {
810            self.sync_editor().await?;
811        }
812        Ok(())
813    }
814
815    async fn handle_transcript_navigation(&mut self, key: KeyEvent) -> Result<bool, CliFailure> {
816        let page_rows = usize::from((self.state.viewport_height / 2).max(1));
817        let action = match (key.code, key.modifiers) {
818            (KeyCode::PageUp, KeyModifiers::NONE) => {
819                Some(Action::ScrollTranscriptUp { rows: page_rows })
820            }
821            (KeyCode::PageDown, KeyModifiers::NONE) => {
822                Some(Action::ScrollTranscriptDown { rows: page_rows })
823            }
824            (KeyCode::Up, KeyModifiers::SHIFT) => Some(Action::ScrollTranscriptUp { rows: 1 }),
825            (KeyCode::Down, KeyModifiers::SHIFT) => Some(Action::ScrollTranscriptDown { rows: 1 }),
826            (KeyCode::End, KeyModifiers::CONTROL) => Some(Action::FollowTranscriptTail),
827            _ => None,
828        };
829        if let Some(action) = action {
830            self.apply(action).await?;
831            return Ok(true);
832        }
833        Ok(false)
834    }
835
836    async fn handle_binding(&mut self, action: BindingAction) -> Result<(), CliFailure> {
837        match action {
838            BindingAction::Submit | BindingAction::Steer => {
839                let Some(text) = self.editor.submit() else {
840                    return Ok(());
841                };
842                self.sync_editor().await?;
843                if text.starts_with('/') {
844                    self.handle_command(&text).await?;
845                } else if !self.state.attachments().is_empty()
846                    && (self.owns_current_run() || self.state.running)
847                {
848                    self.restore_failed_input(text, "image attachments require an idle session")
849                        .await?;
850                } else if action == BindingAction::Steer {
851                    match self.service.steer(self.session_id, text.clone()).await {
852                        Ok(_) => self.apply(Action::QueueSteering(text)).await?,
853                        Err(error) => self.restore_failed_input(text, error.message()).await?,
854                    }
855                } else {
856                    match self.start_prompt(text.clone()).await {
857                        Ok(()) => self.apply(Action::ShowPendingUserPrompt(text)).await?,
858                        Err(error) => self.restore_failed_input(text, error.message()).await?,
859                    }
860                }
861            }
862            BindingAction::FollowUp => {
863                let Some(text) = self.editor.submit() else {
864                    return Ok(());
865                };
866                self.sync_editor().await?;
867                if !self.state.attachments().is_empty()
868                    && (self.owns_current_run() || self.state.running)
869                {
870                    self.restore_failed_input(text, "image attachments require an idle session")
871                        .await?;
872                } else {
873                    match self.service.follow_up(self.session_id, text.clone()).await {
874                        Ok(_) => self.apply(Action::QueueFollowUp(text)).await?,
875                        Err(error) => self.restore_failed_input(text, error.message()).await?,
876                    }
877                }
878            }
879            BindingAction::Newline => {
880                if self.editor.insert_newline().is_err() {
881                    self.notify("editor size limit reached").await?;
882                } else {
883                    self.sync_editor().await?;
884                }
885            }
886            BindingAction::Abort => {
887                if self.owns_current_run() || self.state.running {
888                    let queued = self.state.take_queued_text();
889                    if !queued.is_empty() {
890                        self.editor = Editor::with_limit(queued, super::MAX_EDITOR_BYTES)
891                            .expect("queued input is bounded");
892                        self.sync_editor().await?;
893                    }
894                    if let Err(error) = self.service.abort(self.session_id).await {
895                        self.notify(error.message()).await?;
896                    }
897                }
898            }
899            BindingAction::Clear => {
900                if self.editor.clear() {
901                    self.sync_editor().await?;
902                }
903            }
904            BindingAction::Exit => self.quit = true,
905            BindingAction::SelectModel => self.open_model_selector().await?,
906            BindingAction::ToggleThinking => self.apply(Action::ToggleThinking).await?,
907            BindingAction::ToggleTools => self.apply(Action::ToggleAllTools).await?,
908            BindingAction::Copy => self.copy_last_response().await?,
909            BindingAction::RetrieveQueued => {
910                let queued = self.state.take_queued_text();
911                if !queued.is_empty() {
912                    self.editor = Editor::with_limit(queued, super::MAX_EDITOR_BYTES)
913                        .expect("queued input is bounded");
914                    self.sync_editor().await?;
915                }
916            }
917        }
918        Ok(())
919    }
920
921    #[allow(clippy::too_many_lines)]
922    async fn handle_command(&mut self, input: &str) -> Result<(), CliFailure> {
923        let Ok(command) = self.commands.parse(input) else {
924            self.notify("unknown or invalid slash command").await?;
925            return Ok(());
926        };
927        match command {
928            SlashCommand::New => {
929                let session_id = self
930                    .service
931                    .create_session()
932                    .await
933                    .map_err(CliFailure::from)?;
934                self.switch_session(session_id, false).await?;
935            }
936            SlashCommand::Resume(Some(session_id)) => {
937                self.switch_session(session_id, true).await?;
938            }
939            SlashCommand::Resume(None) | SlashCommand::Session => {
940                self.open_session_selector().await?;
941            }
942            SlashCommand::Name(name) => {
943                if self.ensure_idle().await? {
944                    let name = name
945                        .map(|name| SessionName::from_str(&name))
946                        .transpose()
947                        .map_err(|_| CliFailure::usage("session name is invalid"))?;
948                    self.service
949                        .name_session(self.session_id, name)
950                        .await
951                        .map_err(CliFailure::from)?;
952                    self.notify("session name updated").await?;
953                }
954            }
955            SlashCommand::Model(Some(model_id)) => {
956                let model = self.resolve_model_id(&model_id)?;
957                self.select_model(model).await?;
958            }
959            SlashCommand::Model(None) => self.open_model_selector().await?,
960            SlashCommand::Reasoning(Some(reasoning_effort)) => {
961                self.request_reasoning_effort(reasoning_effort).await?;
962            }
963            SlashCommand::Reasoning(None) => self.open_reasoning_selector().await?,
964            SlashCommand::Compact => {
965                if self.ensure_idle().await? {
966                    self.service
967                        .compact(self.session_id)
968                        .await
969                        .map_err(CliFailure::from)?;
970                    self.reload_snapshot().await?;
971                }
972            }
973            SlashCommand::Tree => self.open_tree_selector().await?,
974            SlashCommand::Fork(message_id) => {
975                if self.ensure_idle().await? {
976                    let branch_id = uuid::Uuid::now_v7()
977                        .hyphenated()
978                        .to_string()
979                        .parse()
980                        .map_err(|_| {
981                            CliFailure::new(ExitCategory::Internal, "branch identity failed")
982                        })?;
983                    self.service
984                        .fork(self.session_id, message_id, branch_id)
985                        .await
986                        .map_err(CliFailure::from)?;
987                    self.reload_snapshot().await?;
988                }
989            }
990            SlashCommand::Copy => self.copy_last_response().await?,
991            SlashCommand::Image(path) => self.attach_image(input, &path).await?,
992            SlashCommand::ImageRemove(index) => {
993                self.apply(Action::RemoveAttachment { index }).await?;
994            }
995            SlashCommand::ImageClear => self.apply(Action::ClearAttachments).await?,
996            SlashCommand::Mcp => self.show_mcp_health().await?,
997            SlashCommand::McpReconnect(server_id) => self.reconnect_mcp(server_id).await?,
998            SlashCommand::Help => {
999                self.notify(
1000                    "/new /resume /session /name /model /reasoning /compact /tree /fork /copy /image /mcp /help /quit",
1001                )
1002                .await?;
1003            }
1004            SlashCommand::Quit => self.quit = true,
1005            SlashCommand::Template { name, arguments } => {
1006                let prompt = self
1007                    .service
1008                    .resources()
1009                    .prompts()
1010                    .iter()
1011                    .find(|template| template.name() == name)
1012                    .map(|template| template.expand(&arguments, &BTreeMap::new()))
1013                    .ok_or_else(|| CliFailure::usage("prompt template is unavailable"))?;
1014                self.submit_generated(prompt).await?;
1015            }
1016            SlashCommand::Skill(invocation) => {
1017                let skill = self
1018                    .service
1019                    .resources()
1020                    .invoke_skill(&invocation)
1021                    .map_err(CliFailure::from)?;
1022                let prompt = if skill.arguments().is_empty() {
1023                    skill.content().to_owned()
1024                } else {
1025                    format!("{}\n\nArguments: {}", skill.content(), skill.arguments())
1026                };
1027                self.submit_generated(prompt).await?;
1028            }
1029        }
1030        Ok(())
1031    }
1032
1033    async fn handle_selector_key(&mut self, key: KeyEvent) -> Result<(), CliFailure> {
1034        match key.code {
1035            KeyCode::Esc => {
1036                self.pending_model_selection = None;
1037                self.apply(Action::SetOverlay(None)).await?;
1038            }
1039            KeyCode::Up => {
1040                self.state
1041                    .overlay
1042                    .as_mut()
1043                    .and_then(Overlay::selector_mut)
1044                    .expect("selector exists")
1045                    .move_previous();
1046                self.state.bump_generation();
1047                self.render()?;
1048            }
1049            KeyCode::Down => {
1050                self.state
1051                    .overlay
1052                    .as_mut()
1053                    .and_then(Overlay::selector_mut)
1054                    .expect("selector exists")
1055                    .move_next();
1056                self.state.bump_generation();
1057                self.render()?;
1058            }
1059            KeyCode::Backspace => {
1060                let selector = self
1061                    .state
1062                    .overlay
1063                    .as_mut()
1064                    .and_then(Overlay::selector_mut)
1065                    .expect("selector exists");
1066                let mut query = selector.query().to_owned();
1067                if let Some((index, _)) = query.grapheme_indices(true).next_back() {
1068                    query.truncate(index);
1069                    selector.set_query(&query);
1070                    self.state.bump_generation();
1071                    self.render()?;
1072                }
1073            }
1074            KeyCode::Enter => {
1075                let value = self.state.selector().and_then(Selector::accept);
1076                self.apply(Action::SetOverlay(None)).await?;
1077                if let Some(value) = value {
1078                    self.accept_selector(value).await?;
1079                }
1080            }
1081            KeyCode::Char(character)
1082                if !key.modifiers.intersects(
1083                    KeyModifiers::CONTROL | KeyModifiers::ALT | KeyModifiers::SUPER,
1084                ) =>
1085            {
1086                let selector = self
1087                    .state
1088                    .overlay
1089                    .as_mut()
1090                    .and_then(Overlay::selector_mut)
1091                    .expect("selector exists");
1092                let mut query = selector.query().to_owned();
1093                query.push(character);
1094                selector.set_query(&query);
1095                self.state.bump_generation();
1096                self.render()?;
1097            }
1098            _ => {}
1099        }
1100        Ok(())
1101    }
1102
1103    async fn handle_overlay_key(&mut self, key: KeyEvent) -> Result<(), CliFailure> {
1104        if self
1105            .state
1106            .overlay
1107            .as_ref()
1108            .and_then(Overlay::selector)
1109            .is_some()
1110        {
1111            return Box::pin(self.handle_selector_key(key)).await;
1112        }
1113        Box::pin(self.handle_command_completion_key(key)).await
1114    }
1115
1116    async fn handle_command_completion_key(&mut self, key: KeyEvent) -> Result<(), CliFailure> {
1117        match key.code {
1118            KeyCode::Esc => self.apply(Action::SetOverlay(None)).await?,
1119            KeyCode::Up | KeyCode::BackTab => {
1120                self.state
1121                    .overlay
1122                    .as_mut()
1123                    .and_then(Overlay::command_completion_mut)
1124                    .expect("command completion exists")
1125                    .move_previous();
1126                self.state.bump_generation();
1127                self.render()?;
1128            }
1129            KeyCode::Down | KeyCode::Tab => {
1130                self.state
1131                    .overlay
1132                    .as_mut()
1133                    .and_then(Overlay::command_completion_mut)
1134                    .expect("command completion exists")
1135                    .move_next();
1136                self.state.bump_generation();
1137                self.render()?;
1138            }
1139            KeyCode::Enter => {
1140                let selected = self
1141                    .state
1142                    .overlay
1143                    .as_ref()
1144                    .and_then(Overlay::command_completion)
1145                    .and_then(CommandCompletion::selected)
1146                    .map(str::to_owned);
1147                self.apply(Action::SetOverlay(None)).await?;
1148                if let Some(selected) = selected {
1149                    self.editor = Editor::with_limit(selected, super::MAX_EDITOR_BYTES)
1150                        .expect("catalog completion remains bounded");
1151                    self.sync_editor().await?;
1152                }
1153            }
1154            _ => Box::pin(self.handle_editor_key(key)).await?,
1155        }
1156        Ok(())
1157    }
1158
1159    async fn accept_selector(&mut self, value: SelectorValue) -> Result<(), CliFailure> {
1160        match value {
1161            SelectorValue::Session(session_id) => {
1162                self.switch_session(session_id, true).await?;
1163            }
1164            SelectorValue::Model(model_id) => self.select_model(model_id).await?,
1165            SelectorValue::Reasoning(reasoning_effort) => {
1166                if let Some(model_id) = self.pending_model_selection.take() {
1167                    self.select_model_and_reasoning(model_id, reasoning_effort)
1168                        .await?;
1169                } else {
1170                    self.request_reasoning_effort(reasoning_effort).await?;
1171                }
1172            }
1173            SelectorValue::Branch(branch_id) => {
1174                let snapshot = self
1175                    .service
1176                    .session_snapshot(self.session_id)
1177                    .await
1178                    .map_err(CliFailure::from)?;
1179                let tree = session_tree(&snapshot);
1180                if let Some(branch) = tree
1181                    .branches()
1182                    .iter()
1183                    .find(|branch| branch.branch_id() == branch_id)
1184                {
1185                    let source = branch
1186                        .source_branch_id()
1187                        .map_or_else(|| "root".to_owned(), |source| source.to_string());
1188                    let marker = if branch.is_active() {
1189                        "active"
1190                    } else {
1191                        "inactive"
1192                    };
1193                    self.notify(format!(
1194                        "{marker} branch {branch_id} · source {source} · from {} · leaf {}",
1195                        branch.from_record_id(),
1196                        branch.leaf_record_id()
1197                    ))
1198                    .await?;
1199                }
1200            }
1201        }
1202        Ok(())
1203    }
1204
1205    async fn open_session_selector(&mut self) -> Result<(), CliFailure> {
1206        let entries = self
1207            .service
1208            .list_sessions()
1209            .await
1210            .map_err(CliFailure::from)?;
1211        let items = session_list(&entries).into_iter().map(|entry| {
1212            let name = entry
1213                .name()
1214                .map_or_else(|| entry.session_id().to_string(), str::to_owned);
1215            SelectorItem::new(
1216                format!("{name} · {} messages", entry.message_count()),
1217                SelectorValue::Session(entry.session_id()),
1218            )
1219        });
1220        let selector = Selector::new("sessions", items)
1221            .map_err(|_| CliFailure::new(ExitCategory::Internal, "session selector failed"))?;
1222        self.apply(Action::SetOverlay(Some(Overlay::Selector(selector))))
1223            .await
1224    }
1225
1226    async fn open_model_selector(&mut self) -> Result<(), CliFailure> {
1227        let items = self
1228            .service
1229            .models()
1230            .into_iter()
1231            .map(|model| SelectorItem::new(model.to_string(), SelectorValue::Model(model)));
1232        let mut selector = Selector::new("models", items)
1233            .map_err(|_| CliFailure::new(ExitCategory::Internal, "model selector failed"))?;
1234        if let Some(model) = self.state.model_ref() {
1235            selector.select_value(&SelectorValue::Model(model.clone()));
1236        }
1237        self.apply(Action::SetOverlay(Some(Overlay::Selector(selector))))
1238            .await
1239    }
1240
1241    async fn open_reasoning_selector(&mut self) -> Result<(), CliFailure> {
1242        let model = self
1243            .state
1244            .model_ref()
1245            .cloned()
1246            .ok_or_else(|| CliFailure::usage("session has no selected model"))?;
1247        self.open_reasoning_selector_for(model, false).await
1248    }
1249
1250    async fn open_reasoning_selector_for(
1251        &mut self,
1252        model_ref: ModelRef,
1253        persist_model: bool,
1254    ) -> Result<(), CliFailure> {
1255        let model = self
1256            .service
1257            .model_spec(&model_ref)
1258            .ok_or_else(|| CliFailure::usage("selected model is unavailable"))?;
1259        let efforts = model.reasoning_profile().map_or_else(
1260            || vec![ReasoningEffort::Off],
1261            |profile| profile.supported_efforts().to_vec(),
1262        );
1263        let current = model
1264            .resolve_reasoning(
1265                self.state
1266                    .pending_reasoning_effort()
1267                    .or(self.state.reasoning_effort()),
1268            )
1269            .map_or(
1270                ReasoningEffort::Off,
1271                tea_model::ReasoningResolution::effective,
1272            );
1273        let items = efforts
1274            .into_iter()
1275            .map(|effort| SelectorItem::new(effort.as_str(), SelectorValue::Reasoning(effort)));
1276        let mut selector = Selector::new("reasoning effort", items)
1277            .map_err(|_| CliFailure::new(ExitCategory::Internal, "reasoning selector failed"))?;
1278        selector.select_value(&SelectorValue::Reasoning(current));
1279        self.pending_model_selection = persist_model.then_some(model_ref);
1280        self.apply(Action::SetOverlay(Some(Overlay::Selector(selector))))
1281            .await
1282    }
1283
1284    async fn open_tree_selector(&mut self) -> Result<(), CliFailure> {
1285        let snapshot = self
1286            .service
1287            .session_snapshot(self.session_id)
1288            .await
1289            .map_err(CliFailure::from)?;
1290        let tree = session_tree(&snapshot);
1291        let items = tree.branches().iter().map(|branch| {
1292            let marker = if branch.is_active() { "*" } else { " " };
1293            let source = branch
1294                .source_branch_id()
1295                .map_or_else(|| "root".to_owned(), |source| source.to_string());
1296            SelectorItem::new(
1297                format!(
1298                    "{marker} {} · {source} · {}",
1299                    branch.branch_id(),
1300                    branch.leaf_record_id()
1301                ),
1302                SelectorValue::Branch(branch.branch_id()),
1303            )
1304        });
1305        let selector = Selector::new("branches", items)
1306            .map_err(|_| CliFailure::new(ExitCategory::Internal, "branch selector failed"))?;
1307        self.apply(Action::SetOverlay(Some(Overlay::Selector(selector))))
1308            .await
1309    }
1310
1311    async fn select_model(&mut self, model: ModelRef) -> Result<(), CliFailure> {
1312        if self.ensure_idle().await? {
1313            self.open_reasoning_selector_for(model, true).await?;
1314        }
1315        Ok(())
1316    }
1317
1318    fn resolve_model_id(&self, model_id: &tea_protocol::ModelId) -> Result<ModelRef, CliFailure> {
1319        let mut matches = self
1320            .service
1321            .models()
1322            .into_iter()
1323            .filter(|model| model.model_id() == model_id);
1324        let model = matches
1325            .next()
1326            .ok_or_else(|| CliFailure::usage("selected model is unavailable"))?;
1327        if matches.next().is_some() {
1328            return Err(CliFailure::usage(
1329                "model id is ambiguous; choose a provider-qualified model from the selector",
1330            ));
1331        }
1332        Ok(model)
1333    }
1334
1335    async fn request_reasoning_effort(
1336        &mut self,
1337        requested: ReasoningEffort,
1338    ) -> Result<(), CliFailure> {
1339        if self.owns_current_run() || self.state.running {
1340            let effective = self.resolve_current_reasoning_effort(requested)?;
1341            if effective != requested {
1342                self.notify(format!(
1343                    "reasoning {} adjusted to {} for the selected model",
1344                    requested.as_str(),
1345                    effective.as_str()
1346                ))
1347                .await?;
1348            }
1349            self.apply(Action::SetPendingReasoningEffort(Some(effective)))
1350                .await?;
1351            self.notify(format!(
1352                "reasoning {} queued for the next turn",
1353                effective.as_str()
1354            ))
1355            .await?;
1356            return Ok(());
1357        }
1358        self.apply_reasoning_effort_now(requested).await.map(drop)
1359    }
1360
1361    fn resolve_current_reasoning_effort(
1362        &self,
1363        requested: ReasoningEffort,
1364    ) -> Result<ReasoningEffort, CliFailure> {
1365        let model_ref = self
1366            .state
1367            .model_ref()
1368            .ok_or_else(|| CliFailure::usage("session has no selected model"))?;
1369        let model = self
1370            .service
1371            .model_spec(model_ref)
1372            .ok_or_else(|| CliFailure::usage("selected model is unavailable"))?;
1373        Ok(model
1374            .resolve_reasoning(Some(requested))
1375            .expect("an explicit effort always resolves")
1376            .effective())
1377    }
1378
1379    async fn apply_reasoning_effort_now(
1380        &mut self,
1381        requested: ReasoningEffort,
1382    ) -> Result<ReasoningEffort, CliFailure> {
1383        let outcome = self
1384            .service
1385            .set_reasoning_effort(self.session_id, requested)
1386            .await
1387            .map_err(CliFailure::from)?;
1388        let RuntimeCommandOutcome::ConfigurationChanged {
1389            reasoning_effort: Some(effective),
1390            requested_reasoning_effort,
1391            ..
1392        } = outcome
1393        else {
1394            return Err(CliFailure::new(
1395                ExitCategory::Internal,
1396                "reasoning change returned an unexpected result",
1397            ));
1398        };
1399        self.apply(Action::SetPendingReasoningEffort(None)).await?;
1400        self.reload_snapshot().await?;
1401        if let Some(requested) = requested_reasoning_effort {
1402            self.notify(format!(
1403                "reasoning {} adjusted to {} for the selected model",
1404                requested.as_str(),
1405                effective.as_str()
1406            ))
1407            .await?;
1408        }
1409        Ok(effective)
1410    }
1411
1412    async fn flush_pending_reasoning_effort(&mut self) -> Result<(), CliFailure> {
1413        if self.owns_current_run() || self.state.running {
1414            return Ok(());
1415        }
1416        let Some(effort) = self.state.pending_reasoning_effort() else {
1417            return Ok(());
1418        };
1419        if let Err(error) = self.apply_reasoning_effort_now(effort).await {
1420            self.notify(format!(
1421                "queued reasoning change failed: {}",
1422                error.message()
1423            ))
1424            .await?;
1425        }
1426        Ok(())
1427    }
1428
1429    async fn finish_owned_run(
1430        &mut self,
1431        session_id: SessionId,
1432        outcome: Result<RuntimeCommandOutcome, tea_coding::CodingError>,
1433    ) -> Result<(), CliFailure> {
1434        self.owned_runs.remove(&session_id);
1435        self.apply(Action::FinishRunActivity).await?;
1436        self.apply(Action::SetApprovalSubmitting(false)).await?;
1437        match outcome {
1438            Ok(RuntimeCommandOutcome::RunCompleted { .. }) => self.reload_snapshot().await,
1439            Ok(_) => {
1440                self.notify("runtime command returned an unexpected result")
1441                    .await
1442            }
1443            Err(error) => self.notify(error.message()).await,
1444        }
1445    }
1446
1447    async fn cycle_reasoning_effort(&mut self) -> Result<(), CliFailure> {
1448        let model_ref = self
1449            .state
1450            .model_ref()
1451            .ok_or_else(|| CliFailure::usage("session has no selected model"))?;
1452        let model = self
1453            .service
1454            .model_spec(model_ref)
1455            .ok_or_else(|| CliFailure::usage("selected model is unavailable"))?;
1456        let supported = model.reasoning_profile().map_or_else(
1457            || vec![ReasoningEffort::Off],
1458            |profile| {
1459                profile
1460                    .supported_efforts()
1461                    .iter()
1462                    .copied()
1463                    .filter(|effort| *effort <= ReasoningEffort::High)
1464                    .collect::<Vec<_>>()
1465            },
1466        );
1467        let Some(first) = supported.first().copied() else {
1468            return self
1469                .notify("selected model has no shortcut reasoning levels")
1470                .await;
1471        };
1472        let current = self
1473            .state
1474            .pending_reasoning_effort()
1475            .or(self.state.reasoning_effort())
1476            .or_else(|| {
1477                model
1478                    .reasoning_profile()
1479                    .map(tea_model::ReasoningProfile::default_effort)
1480            })
1481            .unwrap_or(ReasoningEffort::Off);
1482        let next = supported
1483            .iter()
1484            .position(|effort| *effort == current)
1485            .map_or(first, |index| supported[(index + 1) % supported.len()]);
1486        self.request_reasoning_effort(next).await
1487    }
1488
1489    async fn select_model_and_reasoning(
1490        &mut self,
1491        model_ref: ModelRef,
1492        requested: ReasoningEffort,
1493    ) -> Result<(), CliFailure> {
1494        if !self.ensure_idle().await? {
1495            return Ok(());
1496        }
1497        self.service
1498            .set_model(self.session_id, model_ref.clone())
1499            .await
1500            .map_err(CliFailure::from)?;
1501        let outcome = self
1502            .service
1503            .set_reasoning_effort(self.session_id, requested)
1504            .await
1505            .map_err(CliFailure::from)?;
1506        let RuntimeCommandOutcome::ConfigurationChanged {
1507            reasoning_effort: Some(effective),
1508            requested_reasoning_effort,
1509            ..
1510        } = outcome
1511        else {
1512            return Err(CliFailure::new(
1513                ExitCategory::Internal,
1514                "model reasoning change returned an unexpected result",
1515            ));
1516        };
1517        self.reload_snapshot().await?;
1518        if let Some(requested) = requested_reasoning_effort {
1519            self.notify(format!(
1520                "reasoning {} adjusted to {} for {model_ref}",
1521                requested.as_str(),
1522                effective.as_str()
1523            ))
1524            .await?;
1525        }
1526        self.persist_model_defaults(model_ref, effective).await
1527    }
1528
1529    async fn persist_model_defaults(
1530        &mut self,
1531        model: ModelRef,
1532        effort: ReasoningEffort,
1533    ) -> Result<(), CliFailure> {
1534        let Some(path) = self.global_settings_path.clone() else {
1535            return Ok(());
1536        };
1537        let result = tokio::task::spawn_blocking(move || {
1538            persist_global_model_settings(&path, &model, effort)
1539        })
1540        .await;
1541        if !matches!(result, Ok(Ok(()))) {
1542            self.notify("session updated, but global model defaults could not be saved")
1543                .await?;
1544        }
1545        Ok(())
1546    }
1547
1548    async fn switch_session(
1549        &mut self,
1550        session_id: SessionId,
1551        open: bool,
1552    ) -> Result<(), CliFailure> {
1553        let runtime_state = if open {
1554            self.service
1555                .open_session(session_id)
1556                .await
1557                .map_err(CliFailure::from)?
1558        } else {
1559            self.service
1560                .snapshot(session_id)
1561                .await
1562                .map_err(CliFailure::from)?
1563        };
1564        let events = self
1565            .service
1566            .subscribe(session_id)
1567            .map_err(CliFailure::from)?;
1568        let snapshot = self
1569            .service
1570            .session_snapshot(session_id)
1571            .await
1572            .map_err(CliFailure::from)?;
1573        let viewport = (self.state.viewport_width, self.state.viewport_height);
1574        let preferences = self.state.preferences.clone();
1575        let previous_ephemera = self.state.take_session_ephemera();
1576        self.session_ephemera
1577            .insert(self.session_id, previous_ephemera);
1578        self.session_id = session_id;
1579        self.events = events;
1580        let mut state = TuiState::from_snapshot(&snapshot, self.startup.clone());
1581        state.viewport_width = viewport.0;
1582        state.viewport_height = viewport.1;
1583        state.preferences = preferences;
1584        state.running = runtime_state.is_running();
1585        if let Some(ephemera) = self.session_ephemera.remove(&session_id) {
1586            state.restore_session_ephemera(ephemera);
1587        }
1588        sync_reasoning_projection(&mut state, self.service);
1589        self.state = state;
1590        self.sync_editor().await
1591    }
1592
1593    async fn start_prompt(&mut self, text: String) -> Result<(), CliFailure> {
1594        let has_attachments = !self.state.attachments().is_empty();
1595        if has_attachments {
1596            self.ensure_image_capability()?;
1597            let mut content = Vec::with_capacity(self.state.attachments().len() + 1);
1598            content.push(
1599                ContentBlock::text(text)
1600                    .map_err(|_| CliFailure::usage("prompt text is invalid"))?,
1601            );
1602            content.extend(self.state.attachment_blocks());
1603            self.service
1604                .prompt_content(self.session_id, content)
1605                .map_err(CliFailure::from)?;
1606            self.apply(Action::ClearAttachments).await?;
1607        } else {
1608            self.service
1609                .prompt(self.session_id, text)
1610                .map_err(CliFailure::from)?;
1611        }
1612        self.owned_runs.insert(self.session_id);
1613        self.apply(Action::StartRunActivity).await
1614    }
1615
1616    async fn attach_image(&mut self, input: &str, path: &str) -> Result<(), CliFailure> {
1617        if let Err(error) = self.ensure_image_capability() {
1618            return self
1619                .restore_failed_input(input.to_owned(), error.message())
1620                .await;
1621        }
1622        let path = Path::new(path);
1623        let workspace_path = path
1624            .is_relative()
1625            .then(|| self.service.workspace().host_path().join(path));
1626        let path = workspace_path.as_deref().unwrap_or(path);
1627        let attachment = match load_local_image(path) {
1628            Ok(attachment) => attachment,
1629            Err(error) => {
1630                return self
1631                    .restore_failed_input(input.to_owned(), &error.to_string())
1632                    .await;
1633            }
1634        };
1635        if let Err(error) = validate_addition(
1636            self.state.attachments().len(),
1637            self.state.attachment_encoded_bytes(),
1638            attachment.encoded_bytes(),
1639        ) {
1640            return self
1641                .restore_failed_input(input.to_owned(), &error.to_string())
1642                .await;
1643        }
1644        self.apply(Action::AddAttachment(attachment)).await
1645    }
1646
1647    fn ensure_image_capability(&self) -> Result<(), CliFailure> {
1648        let model_ref = self
1649            .state
1650            .model_ref()
1651            .ok_or_else(|| CliFailure::usage("no model is selected for image input"))?;
1652        let capabilities = self
1653            .service
1654            .model_capabilities(model_ref)
1655            .ok_or_else(|| CliFailure::usage("selected model is unavailable for image input"))?;
1656        if capabilities.accepts_images() {
1657            Ok(())
1658        } else {
1659            Err(CliFailure::usage(
1660                "selected model does not support image input",
1661            ))
1662        }
1663    }
1664
1665    async fn submit_generated(&mut self, prompt: String) -> Result<(), CliFailure> {
1666        if self.owns_current_run() || self.state.running {
1667            self.service
1668                .steer(self.session_id, prompt.clone())
1669                .await
1670                .map_err(CliFailure::from)?;
1671            self.apply(Action::QueueSteering(prompt)).await
1672        } else {
1673            self.start_prompt(prompt).await
1674        }
1675    }
1676
1677    async fn ensure_idle(&mut self) -> Result<bool, CliFailure> {
1678        if self.owns_current_run() || self.state.running {
1679            self.notify("command is unavailable while a run is active")
1680                .await?;
1681            Ok(false)
1682        } else {
1683            Ok(true)
1684        }
1685    }
1686
1687    fn owns_current_run(&self) -> bool {
1688        self.owned_runs.contains(&self.session_id)
1689    }
1690
1691    async fn copy_last_response(&mut self) -> Result<(), CliFailure> {
1692        let text = self.state.messages().iter().rev().find_map(assistant_text);
1693        match text {
1694            Some(text) => match self.clipboard.copy(&text) {
1695                Ok(()) => self.notify("copied last assistant response").await?,
1696                Err(_) => self.notify("system clipboard is unavailable").await?,
1697            },
1698            None => self.notify("no assistant response is available").await?,
1699        }
1700        Ok(())
1701    }
1702
1703    async fn show_mcp_health(&mut self) -> Result<(), CliFailure> {
1704        let snapshot = self.service.mcp_snapshot().map_err(mcp_failure)?;
1705        let servers = mcp_servers(&snapshot);
1706        if servers.is_empty() {
1707            return self
1708                .apply(Action::SetMcpHealth(vec![
1709                    "no MCP servers configured".to_owned(),
1710                ]))
1711                .await;
1712        }
1713        self.apply(Action::SetMcpHealth(
1714            servers.iter().map(mcp_health_row).collect::<Vec<_>>(),
1715        ))
1716        .await
1717    }
1718
1719    async fn reconnect_mcp(&mut self, server_id: McpServerId) -> Result<(), CliFailure> {
1720        match self.service.reconnect_mcp(&server_id).await {
1721            Ok(health) => {
1722                let _ = health;
1723                self.show_mcp_health().await
1724            }
1725            Err(error) => self.notify(mcp_error_message(error)).await,
1726        }
1727    }
1728
1729    async fn restore_failed_input(
1730        &mut self,
1731        text: String,
1732        message: &str,
1733    ) -> Result<(), CliFailure> {
1734        self.editor = Editor::with_limit(text, super::MAX_EDITOR_BYTES)
1735            .expect("previous editor input remains bounded");
1736        self.sync_editor().await?;
1737        self.notify(message).await
1738    }
1739
1740    async fn sync_editor(&mut self) -> Result<(), CliFailure> {
1741        self.apply(Action::SetEditor(self.editor.text().to_owned()))
1742            .await?;
1743        self.sync_command_completion().await
1744    }
1745
1746    async fn sync_command_completion(&mut self) -> Result<(), CliFailure> {
1747        if self
1748            .state
1749            .overlay
1750            .as_ref()
1751            .and_then(Overlay::selector)
1752            .is_some()
1753        {
1754            return Ok(());
1755        }
1756        let editor = self.editor.text();
1757        let completion = if self.state.approval().is_none()
1758            && editor.starts_with('/')
1759            && !editor.chars().any(char::is_whitespace)
1760        {
1761            let completion = CommandCompletion::new(self.commands.complete(editor, 16));
1762            completion.should_show(editor).then_some(completion)
1763        } else {
1764            None
1765        };
1766        self.apply(Action::SetOverlay(
1767            completion.map(Overlay::CommandCompletion),
1768        ))
1769        .await
1770    }
1771
1772    async fn notify(&mut self, message: impl Into<String>) -> Result<(), CliFailure> {
1773        self.apply(Action::Notify(message.into())).await
1774    }
1775
1776    async fn reload_snapshot(&mut self) -> Result<(), CliFailure> {
1777        let snapshot = self
1778            .service
1779            .session_snapshot(self.session_id)
1780            .await
1781            .map_err(CliFailure::from)?;
1782        self.apply(Action::SnapshotLoaded(Box::new(snapshot))).await
1783    }
1784
1785    async fn reconnect(&mut self) -> Result<(), CliFailure> {
1786        self.events = self
1787            .service
1788            .subscribe(self.session_id)
1789            .map_err(CliFailure::from)?;
1790        self.apply(Action::Reconnected).await
1791    }
1792
1793    async fn apply(&mut self, action: Action) -> Result<(), CliFailure> {
1794        let stream_delta = is_stream_delta(&action);
1795        let was_running = StatusIndicator::needs_elapsed_tick(&self.state);
1796        let mut effects = reduce(&mut self.state, action);
1797        let requires_snapshot = effects
1798            .iter()
1799            .any(|effect| matches!(effect, Effect::ReloadSnapshot { .. }));
1800        if requires_snapshot {
1801            let snapshot = self
1802                .service
1803                .session_snapshot(self.session_id)
1804                .await
1805                .map_err(CliFailure::from)?;
1806            effects.extend(reduce(
1807                &mut self.state,
1808                Action::SnapshotLoaded(Box::new(snapshot)),
1809            ));
1810        }
1811        if sync_reasoning_projection(&mut self.state, self.service)
1812            && !effects.contains(&Effect::Render)
1813        {
1814            effects.push(Effect::Render);
1815        }
1816        let now = time::Instant::now();
1817        self.activity_timer.sync(
1818            was_running,
1819            StatusIndicator::needs_elapsed_tick(&self.state),
1820            self.state.run_elapsed_seconds(),
1821            now,
1822        );
1823        self.sync_committed_history()?;
1824        if effects.contains(&Effect::Render)
1825            && self
1826                .frame_scheduler
1827                .request(stream_delta && !requires_snapshot, now)
1828        {
1829            self.render()?;
1830        }
1831        Ok(())
1832    }
1833
1834    fn sync_committed_history(&mut self) -> Result<(), CliFailure> {
1835        let next = Presentation::from_state(&self.state).history().to_vec();
1836        if next == self.transcript_cells {
1837            return Ok(());
1838        }
1839
1840        let output = if next.starts_with(&self.transcript_cells) {
1841            self.frames
1842                .insert_history_cells(&next[self.transcript_cells.len()..])
1843        } else {
1844            self.frames.replace_history_cells(&next)
1845        };
1846        output.map_err(|_| {
1847            CliFailure::new(ExitCategory::Internal, "terminal history insertion failed")
1848        })?;
1849        self.transcript_cells = next;
1850        Ok(())
1851    }
1852
1853    fn flush_pending_frame(&mut self) -> Result<(), CliFailure> {
1854        if self.frame_scheduler.take_pending() {
1855            self.render()?;
1856        }
1857        Ok(())
1858    }
1859
1860    fn render(&mut self) -> Result<(), CliFailure> {
1861        self.frames
1862            .render(&self.state, self.editor.cursor_byte())
1863            .map_err(|_| CliFailure::new(ExitCategory::Internal, "terminal render failed"))?;
1864        self.frame_scheduler.record_frame(time::Instant::now());
1865        Ok(())
1866    }
1867}
1868
1869fn is_stream_delta(action: &Action) -> bool {
1870    matches!(
1871        action,
1872        Action::Event(envelope)
1873            if matches!(envelope.event(), AgentEvent::MessageDelta { .. })
1874    )
1875}
1876
1877fn command_catalog(service: &CodingAgentService) -> Result<CommandCatalog, CliFailure> {
1878    CommandCatalog::new(
1879        service
1880            .resources()
1881            .prompts()
1882            .iter()
1883            .map(tea_coding::resources::PromptTemplate::name),
1884        service
1885            .resources()
1886            .skills()
1887            .iter()
1888            .map(|skill| skill.metadata().id().as_str()),
1889    )
1890    .map_err(|_| CliFailure::new(ExitCategory::TrustOrConfig, "command catalog is invalid"))
1891}
1892
1893fn mcp_failure(error: tea_mcp::McpError) -> CliFailure {
1894    CliFailure::new(ExitCategory::Internal, mcp_error_message(error))
1895}
1896
1897fn mcp_error_message(error: tea_mcp::McpError) -> &'static str {
1898    match error.code() {
1899        tea_mcp::McpErrorCode::Descriptor
1900        | tea_mcp::McpErrorCode::Identity
1901        | tea_mcp::McpErrorCode::StaleCatalog => {
1902            "MCP catalog changed; close and rebuild the CLI service"
1903        }
1904        tea_mcp::McpErrorCode::Unavailable => "MCP server is unavailable for reconnect",
1905        tea_mcp::McpErrorCode::Cancellation => "MCP reconnect was cancelled",
1906        _ => "MCP service operation failed",
1907    }
1908}
1909
1910fn mcp_health_row(server: &crate::session_views::McpServerView) -> String {
1911    const MAX_TUI_MCP_TOOLS: usize = 8;
1912
1913    let mut tools = server
1914        .tools()
1915        .iter()
1916        .take(MAX_TUI_MCP_TOOLS)
1917        .cloned()
1918        .collect::<Vec<_>>();
1919    if server.tools().len() > tools.len() {
1920        tools.push(format!("+{} more", server.tools().len() - tools.len()));
1921    }
1922    let tools = if tools.is_empty() {
1923        "no enabled tools".to_owned()
1924    } else {
1925        tools.join(", ")
1926    };
1927    let code = server
1928        .code()
1929        .map(|code| format!("; {code:?}"))
1930        .unwrap_or_default();
1931    format!(
1932        "{}: {:?}{code}; restarts {}; {tools}",
1933        server.server_id(),
1934        server.state(),
1935        server.restart_count(),
1936    )
1937}
1938
1939fn assistant_text(message: &CanonicalMessage) -> Option<String> {
1940    let CanonicalMessage::Assistant { content, .. } = message else {
1941        return None;
1942    };
1943    let text = content
1944        .iter()
1945        .filter_map(|block| match block {
1946            ContentBlock::Text { text } => Some(text.as_str()),
1947            ContentBlock::Thinking { .. }
1948            | ContentBlock::Image { .. }
1949            | ContentBlock::ToolCall { .. }
1950            | ContentBlock::HostedTool { .. }
1951            | ContentBlock::Citation { .. } => None,
1952        })
1953        .collect::<String>();
1954    (!text.is_empty()).then_some(text)
1955}
1956
1957fn interactive_initial_prompt(
1958    args: &CliArgs,
1959    bootstrap: &CliBootstrap,
1960) -> Result<Option<String>, CliFailure> {
1961    if args.prompt.is_empty() {
1962        return Ok(None);
1963    }
1964    if args.prompt.len() > 128 {
1965        return Err(CliFailure::usage("too many prompt arguments"));
1966    }
1967    let mut prompt = String::new();
1968    for value in &args.prompt {
1969        let part = if let Some(path) = value.strip_prefix('@') {
1970            bootstrap.read_prompt_file(args, path)?
1971        } else {
1972            value.clone()
1973        };
1974        if prompt.len().saturating_add(part.len()).saturating_add(1) > super::MAX_EDITOR_BYTES {
1975            return Err(CliFailure::usage("prompt exceeds input size limit"));
1976        }
1977        if !prompt.is_empty() {
1978            prompt.push('\n');
1979        }
1980        prompt.push_str(&part);
1981    }
1982    Ok(Some(prompt))
1983}
1984
1985struct TerminalFrameSink {
1986    guard: TerminalGuard,
1987    terminal: Terminal<CrosstermBackend<io::Stdout>>,
1988    renderer: Renderer,
1989    theme: Theme,
1990    viewport: ViewportMode,
1991    transcript_cells: Vec<CellNode>,
1992    pending_history_cells: Vec<CellNode>,
1993    rebuild_history: bool,
1994    initial_clear: bool,
1995}
1996
1997impl TerminalFrameSink {
1998    fn new(viewport: &str, reduced_motion: bool) -> Result<Self, CliFailure> {
1999        let capabilities = TerminalCapabilities::detect(reduced_motion);
2000        let options = terminal_options(viewport, capabilities)?;
2001        let guard =
2002            TerminalGuard::enter(CrosstermDriver::new(io::stdout()), options).map_err(|_| {
2003                CliFailure::new(ExitCategory::Internal, "terminal initialization failed")
2004            })?;
2005        let mut backend = CrosstermBackend::new(io::stdout());
2006        let screen_size = backend.size().map_err(|_| {
2007            CliFailure::new(ExitCategory::Internal, "terminal initialization failed")
2008        })?;
2009        let cursor_position = if options.viewport == ViewportMode::Inline {
2010            backend.get_cursor_position().unwrap_or(Position::ORIGIN)
2011        } else {
2012            Position::ORIGIN
2013        };
2014        let mut terminal = Terminal::with_cursor_position(
2015            backend,
2016            screen_size,
2017            cursor_position,
2018            options.hyperlinks,
2019        );
2020        if options.viewport == ViewportMode::Fullscreen {
2021            terminal.set_viewport_area(Rect::new(0, 0, screen_size.width, screen_size.height));
2022        }
2023        Ok(Self {
2024            guard,
2025            terminal,
2026            renderer: Renderer::new(),
2027            theme: Theme::for_capabilities(capabilities),
2028            viewport: options.viewport,
2029            transcript_cells: Vec::new(),
2030            pending_history_cells: Vec::new(),
2031            rebuild_history: false,
2032            initial_clear: options.viewport == ViewportMode::Inline,
2033        })
2034    }
2035
2036    fn render_workspace_trust(
2037        &mut self,
2038        prompt: &WorkspaceTrustPrompt,
2039        choice: WorkspaceTrustChoice,
2040    ) -> io::Result<()> {
2041        self.guard.begin_frame()?;
2042        let draw = self.draw_workspace_trust(prompt, choice);
2043        let end = self.guard.end_frame(FRAME_DEADLINE);
2044        draw.and(end)
2045    }
2046
2047    fn draw_workspace_trust(
2048        &mut self,
2049        prompt: &WorkspaceTrustPrompt,
2050        choice: WorkspaceTrustChoice,
2051    ) -> io::Result<()> {
2052        let screen_size = self.terminal.size()?;
2053        if screen_size.width == 0 || screen_size.height == 0 {
2054            return Ok(());
2055        }
2056        let lines = workspace_trust_panel(
2057            prompt.workspace(),
2058            usize::from(screen_size.width),
2059            choice.should_trust(),
2060            &self.theme,
2061        );
2062        let height = u16::try_from(lines.len())
2063            .unwrap_or(u16::MAX)
2064            .min(screen_size.height);
2065        match self.viewport {
2066            ViewportMode::Inline => {
2067                if std::mem::take(&mut self.initial_clear) {
2068                    self.terminal.clear_visible_screen()?;
2069                    self.terminal.set_viewport_area(Rect::new(
2070                        0,
2071                        screen_size.height.saturating_sub(height),
2072                        screen_size.width,
2073                        height,
2074                    ));
2075                } else {
2076                    Self::update_inline_viewport(&mut self.terminal, height, screen_size)?;
2077                }
2078            }
2079            ViewportMode::Fullscreen => {
2080                let area = Rect::new(0, 0, screen_size.width, screen_size.height);
2081                if area != self.terminal.viewport_area {
2082                    self.terminal.clear_after_position(Position::ORIGIN)?;
2083                    self.terminal.set_viewport_area(area);
2084                }
2085            }
2086        }
2087        self.terminal.draw(|frame| {
2088            let area = frame.area();
2089            let visible_start = lines.len().saturating_sub(usize::from(area.height));
2090            let (buffer, _) = frame.buffers_mut();
2091            draw_lines(&lines[visible_start..], area, buffer);
2092        })
2093    }
2094
2095    fn clear_inline_viewport(&mut self) -> io::Result<()> {
2096        if self.viewport == ViewportMode::Inline {
2097            self.terminal.clear()?;
2098        }
2099        Ok(())
2100    }
2101
2102    fn update_inline_viewport(
2103        terminal: &mut Terminal<CrosstermBackend<io::Stdout>>,
2104        height: u16,
2105        screen_size: Size,
2106    ) -> io::Result<()> {
2107        let terminal_height_shrank = screen_size.height < terminal.last_known_screen_size.height;
2108        let terminal_height_grew = screen_size.height > terminal.last_known_screen_size.height;
2109        let viewport_was_bottom_aligned =
2110            terminal.viewport_area.bottom() == terminal.last_known_screen_size.height;
2111        let previous_area = terminal.viewport_area;
2112
2113        let mut area = terminal.viewport_area;
2114        area.height = height.min(screen_size.height);
2115        area.width = screen_size.width;
2116        if area.bottom() > screen_size.height {
2117            let scroll_by = area.bottom() - screen_size.height;
2118            if !terminal_height_shrank && area.top() > 0 {
2119                terminal.scroll_region_up(0..area.top(), scroll_by)?;
2120            }
2121            area.y = screen_size.height - area.height;
2122        } else if terminal_height_grew && viewport_was_bottom_aligned {
2123            area.y = screen_size.height - area.height;
2124        }
2125
2126        if area != previous_area {
2127            terminal.clear_after_position(Position::new(0, previous_area.y.min(area.y)))?;
2128            terminal.set_viewport_area(area);
2129        }
2130        Ok(())
2131    }
2132
2133    fn draw_inline(&mut self, state: &TuiState, cursor_byte: usize) -> io::Result<()> {
2134        let screen_size = self.terminal.size()?;
2135        let screen_changed = screen_size != self.terminal.last_known_screen_size;
2136        let height = self.renderer.inline_height(
2137            state,
2138            screen_size.width,
2139            screen_size.height,
2140            &self.theme,
2141            cursor_byte,
2142        );
2143        let initial_frame = std::mem::take(&mut self.initial_clear);
2144        if initial_frame {
2145            self.terminal.clear_visible_screen()?;
2146            self.terminal.set_viewport_area(Rect::new(
2147                0,
2148                screen_size.height.saturating_sub(height),
2149                screen_size.width,
2150                height.min(screen_size.height),
2151            ));
2152        } else {
2153            Self::update_inline_viewport(&mut self.terminal, height, screen_size)?;
2154        }
2155
2156        if (!initial_frame && screen_changed) || self.rebuild_history {
2157            self.terminal.clear_scrollback_and_visible_screen()?;
2158            let mut area = self.terminal.viewport_area;
2159            area.y = 0;
2160            self.terminal.set_viewport_area(area);
2161            let lines =
2162                self.renderer
2163                    .history_lines(&self.transcript_cells, screen_size.width, &self.theme);
2164            super::insert_history::insert_history_lines(&mut self.terminal, &lines)?;
2165            self.pending_history_cells.clear();
2166            self.rebuild_history = false;
2167        } else if !self.pending_history_cells.is_empty() {
2168            let lines = self.renderer.history_lines(
2169                &self.pending_history_cells,
2170                screen_size.width,
2171                &self.theme,
2172            );
2173            super::insert_history::insert_history_lines(&mut self.terminal, &lines)?;
2174            self.pending_history_cells.clear();
2175        }
2176
2177        let terminal = &mut self.terminal;
2178        let renderer = &mut self.renderer;
2179        let theme = &self.theme;
2180        terminal.draw(|frame| {
2181            let area = frame.area();
2182            let (buffer, hyperlinks) = frame.buffers_mut();
2183            renderer.render_inline_with_cursor(state, area, buffer, hyperlinks, theme, cursor_byte);
2184            if let Some((column, row)) =
2185                renderer.cursor_position(state, area.width, area.height, cursor_byte)
2186            {
2187                frame.set_cursor_position((area.x + column, area.y + row));
2188            }
2189        })
2190    }
2191
2192    fn draw_fullscreen(&mut self, state: &TuiState, cursor_byte: usize) -> io::Result<()> {
2193        let size = self.terminal.size()?;
2194        let area = Rect::new(0, 0, size.width, size.height);
2195        if area != self.terminal.viewport_area {
2196            self.terminal.clear_after_position(Position::ORIGIN)?;
2197            self.terminal.set_viewport_area(area);
2198        }
2199        let terminal = &mut self.terminal;
2200        let renderer = &mut self.renderer;
2201        let theme = &self.theme;
2202        terminal.draw(|frame| {
2203            let area = frame.area();
2204            let (buffer, hyperlinks) = frame.buffers_mut();
2205            renderer.render_with_cursor_and_hyperlinks(
2206                state,
2207                area,
2208                buffer,
2209                hyperlinks,
2210                theme,
2211                cursor_byte,
2212            );
2213            if let Some((column, row)) =
2214                renderer.cursor_position(state, area.width, area.height, cursor_byte)
2215            {
2216                frame.set_cursor_position((area.x + column, area.y + row));
2217            }
2218        })
2219    }
2220}
2221
2222fn terminal_options(
2223    viewport: &str,
2224    capabilities: TerminalCapabilities,
2225) -> Result<TerminalOptions, CliFailure> {
2226    let viewport = match viewport {
2227        "fullscreen" => ViewportMode::Fullscreen,
2228        "inline" => ViewportMode::Inline,
2229        _ => {
2230            return Err(CliFailure::new(
2231                ExitCategory::TrustOrConfig,
2232                "viewport is invalid",
2233            ));
2234        }
2235    };
2236    Ok(TerminalOptions {
2237        title: capabilities
2238            .supports_title()
2239            .then_some(TerminalTitle::default()),
2240        hyperlinks: capabilities.supports_hyperlinks(),
2241        viewport,
2242        synchronized_output: capabilities.supports_synchronized_output(),
2243        focus_events: capabilities.supports_focus_events(),
2244        mouse_capture: false,
2245        keyboard_enhancement: true,
2246        cursor_visible: true,
2247    })
2248}
2249
2250impl FrameSink for TerminalFrameSink {
2251    fn insert_history_cells(&mut self, cells: &[CellNode]) -> io::Result<()> {
2252        self.transcript_cells.extend_from_slice(cells);
2253        if self.viewport == ViewportMode::Inline {
2254            self.pending_history_cells.extend_from_slice(cells);
2255        }
2256        Ok(())
2257    }
2258
2259    fn replace_history_cells(&mut self, cells: &[CellNode]) -> io::Result<()> {
2260        self.transcript_cells.clear();
2261        self.transcript_cells.extend_from_slice(cells);
2262        self.pending_history_cells.clear();
2263        self.rebuild_history = self.viewport == ViewportMode::Inline;
2264        Ok(())
2265    }
2266
2267    fn render(&mut self, state: &TuiState, cursor_byte: usize) -> io::Result<()> {
2268        self.guard.begin_frame()?;
2269        let draw = match self.viewport {
2270            ViewportMode::Fullscreen => self.draw_fullscreen(state, cursor_byte),
2271            ViewportMode::Inline => self.draw_inline(state, cursor_byte),
2272        };
2273        let end = self.guard.end_frame(FRAME_DEADLINE);
2274        draw.and(end)
2275    }
2276}
2277
2278#[cfg(test)]
2279mod frame_scheduler_tests {
2280    use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
2281    use tokio::time::Instant;
2282
2283    use super::{
2284        FrameScheduler, RUN_ACTIVITY_TICK, RunActivityTimer, STREAM_FRAME_CADENCE,
2285        WorkspaceTrustChoice, WorkspaceTrustKeyAction, terminal_options,
2286        workspace_trust_key_action,
2287    };
2288    use crate::tui::TerminalCapabilities;
2289
2290    #[test]
2291    fn stream_bursts_coalesce_without_dropping_the_latest_content() {
2292        let mut scheduler = FrameScheduler::default();
2293        let start = Instant::now();
2294        let mut visible = String::new();
2295        let mut latest = "first".to_owned();
2296
2297        assert!(scheduler.request(true, start));
2298        visible.clone_from(&latest);
2299        scheduler.record_frame(start);
2300
2301        latest.push_str(" second");
2302        assert!(!scheduler.request(true, start + STREAM_FRAME_CADENCE / 4));
2303        latest.push_str(" final");
2304        assert!(!scheduler.request(true, start + STREAM_FRAME_CADENCE / 2));
2305        assert_eq!(
2306            scheduler.next_deadline(),
2307            Some(start + STREAM_FRAME_CADENCE)
2308        );
2309
2310        assert!(scheduler.take_pending());
2311        visible.clone_from(&latest);
2312        scheduler.record_frame(start + STREAM_FRAME_CADENCE);
2313        assert_eq!(visible, "first second final");
2314        assert!(scheduler.next_deadline().is_none());
2315    }
2316
2317    #[test]
2318    fn non_stream_frames_cancel_a_pending_stream_frame() {
2319        let mut scheduler = FrameScheduler::default();
2320        let start = Instant::now();
2321        scheduler.record_frame(start);
2322
2323        assert!(!scheduler.request(true, start + STREAM_FRAME_CADENCE / 4));
2324        assert!(scheduler.request(false, start + STREAM_FRAME_CADENCE / 2));
2325        assert!(!scheduler.take_pending());
2326    }
2327
2328    #[test]
2329    fn run_activity_timer_starts_at_acceptance_and_catches_up_missed_ticks() {
2330        let start = Instant::now();
2331        let mut timer = RunActivityTimer::from_state(false, 0, start);
2332        assert!(timer.next_deadline().is_none());
2333
2334        timer.sync(false, true, 0, start);
2335        assert_eq!(timer.next_deadline(), Some(start + RUN_ACTIVITY_TICK));
2336        assert_eq!(timer.advance(start + RUN_ACTIVITY_TICK / 2), 0);
2337        assert_eq!(timer.advance(start + RUN_ACTIVITY_TICK * 3), 3);
2338        assert_eq!(timer.next_deadline(), Some(start + RUN_ACTIVITY_TICK * 4));
2339
2340        timer.sync(true, false, 3, start + RUN_ACTIVITY_TICK * 3);
2341        assert!(timer.next_deadline().is_none());
2342    }
2343
2344    #[test]
2345    fn run_activity_timer_resumes_from_existing_elapsed_state() {
2346        let now = Instant::now();
2347        let timer = RunActivityTimer::from_state(true, 5, now);
2348        assert_eq!(timer.next_deadline(), Some(now + RUN_ACTIVITY_TICK));
2349    }
2350
2351    #[test]
2352    fn production_options_leave_mouse_scrollback_to_the_terminal() {
2353        let interactive =
2354            TerminalCapabilities::from_environment(Some("xterm-256color"), None, false, false);
2355        let fullscreen = terminal_options("fullscreen", interactive).unwrap();
2356        let inline = terminal_options("inline", interactive).unwrap();
2357        assert!(!fullscreen.mouse_capture);
2358        assert!(!inline.mouse_capture);
2359        assert!(fullscreen.keyboard_enhancement);
2360        assert!(inline.keyboard_enhancement);
2361    }
2362
2363    #[test]
2364    fn workspace_trust_requires_an_explicit_acceptance() {
2365        let choice = WorkspaceTrustChoice::default();
2366        assert_eq!(choice, WorkspaceTrustChoice::Exit);
2367        assert_eq!(
2368            workspace_trust_key_action(choice, KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE)),
2369            WorkspaceTrustKeyAction::Submit(false)
2370        );
2371
2372        let selected =
2373            workspace_trust_key_action(choice, KeyEvent::new(KeyCode::Up, KeyModifiers::NONE));
2374        assert_eq!(
2375            selected,
2376            WorkspaceTrustKeyAction::Select(WorkspaceTrustChoice::Trust)
2377        );
2378        assert_eq!(
2379            workspace_trust_key_action(
2380                WorkspaceTrustChoice::Trust,
2381                KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE)
2382            ),
2383            WorkspaceTrustKeyAction::Submit(true)
2384        );
2385        assert_eq!(
2386            workspace_trust_key_action(
2387                WorkspaceTrustChoice::Trust,
2388                KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL)
2389            ),
2390            WorkspaceTrustKeyAction::Submit(false)
2391        );
2392    }
2393}