Lightweight coding agent that runs in your terminal
Rust
Expose Codex lifecycle status in iTerm2 sessions (#52203)
Felipe Couryade12342e21c
diff --git a/codex-rs/tui/src/app_backtrack.rs b/codex-rs/tui/src/app_backtrack.rsindex f55b75c1bb..22e6db168d 100644--- a/codex-rs/tui/src/app_backtrack.rs+++ b/codex-rs/tui/src/app_backtrack.rs@@ -349,6 +349,12 @@ impl App {/// source of truth for the active cell and its cache invalidation key, and because `App` owns/// overlay lifecycle and frame scheduling for animations.fn overlay_forward_event(&mut self, tui: &mut tui::Tui, event: TuiEvent) -> Result<()> {+ if matches!(+ &event,+ TuiEvent::Draw | TuiEvent::Resume | TuiEvent::Resize(_) | TuiEvent::FocusGained+ ) {+ self.chat_widget.refresh_iterm_session_status();+ }let width = tui.terminal.last_known_screen_size.width.max(/*other*/ 1);let footer = self.prompt_navigation_footer(width.saturating_sub(/*rhs*/ 2));if let Some(Overlay::Transcript(overlay)) = &mut self.overlay {diff --git a/codex-rs/tui/src/chatwidget.rs b/codex-rs/tui/src/chatwidget.rsindex 7dbb54bb85..994f1a75ef 100644--- a/codex-rs/tui/src/chatwidget.rs+++ b/codex-rs/tui/src/chatwidget.rs@@ -1181,6 +1181,15 @@ impl ChatWidget {}self.refresh_status_line_if_workspace_headline_due();self.refresh_thread_usage_if_settlement_due();+ self.refresh_iterm_session_status();+ }++ pub(crate) fn refresh_iterm_session_status(&self) {+ if let Err(err) = crate::iterm_session_status::set_iterm_session_status(+ self.desired_iterm_session_status(),+ ) {+ tracing::debug!(error = %err, "failed to set iTerm2 session status");+ }}fn flush_active_cell(&mut self) {diff --git a/codex-rs/tui/src/chatwidget/status_surfaces.rs b/codex-rs/tui/src/chatwidget/status_surfaces.rsindex 46727cfc32..eb9022d30a 100644--- a/codex-rs/tui/src/chatwidget/status_surfaces.rs+++ b/codex-rs/tui/src/chatwidget/status_surfaces.rs@@ -8,6 +8,7 @@ use crate::bottom_pane::status_line_from_segments;use crate::branch_summary;use crate::chatwidget::limit_label_for_window;use crate::chatwidget::rate_limits::get_limits_duration;+use crate::iterm_session_status::ItermSessionStatus;use crate::legacy_core::config::Config;use crate::model_catalog::LUNA_RESERVE_MODEL;use crate::status::format_credit_micros;@@ -321,6 +322,16 @@ impl ChatWidget {self.bottom_pane.terminal_title_requires_action()}+ pub(super) fn desired_iterm_session_status(&self) -> ItermSessionStatus {+ if self.terminal_title_requires_action() {+ ItermSessionStatus::Waiting+ } else if self.bottom_pane.is_task_running() || !self.unified_exec_processes.is_empty() {+ ItermSessionStatus::Working+ } else {+ ItermSessionStatus::Idle+ }+ }+pub(super) fn terminal_title_shows_action_required(&self) -> bool {self.terminal_title_requires_action() && self.terminal_title_uses_activity()}diff --git a/codex-rs/tui/src/chatwidget/tests.rs b/codex-rs/tui/src/chatwidget/tests.rsindex fd24d3260b..2928d3cfe6 100644--- a/codex-rs/tui/src/chatwidget/tests.rs+++ b/codex-rs/tui/src/chatwidget/tests.rs@@ -257,6 +257,8 @@ mod history_projection;mod history_replay;#[path = "tests/home_cleanup_tests.rs"]mod home_cleanup_tests;+#[path = "tests/iterm_session_status.rs"]+mod iterm_session_status;#[path = "tests/luna_reserve_usage_tests.rs"]mod luna_reserve_usage_tests;mod mcp_startup;diff --git a/codex-rs/tui/src/chatwidget/tests/iterm_session_status.rs b/codex-rs/tui/src/chatwidget/tests/iterm_session_status.rsnew file mode 100644index 0000000000..90d8ff1a07--- /dev/null+++ b/codex-rs/tui/src/chatwidget/tests/iterm_session_status.rs@@ -0,0 +1,56 @@+use super::*;+use crate::iterm_session_status::ItermSessionStatus::Idle;+use crate::iterm_session_status::ItermSessionStatus::Waiting;+use crate::iterm_session_status::ItermSessionStatus::Working;+use pretty_assertions::assert_eq;++#[tokio::test]+async fn session_status_follows_existing_lifecycle_state() {+ let (mut chat, _rx, _op_rx) = make_chatwidget_manual(/*model_override*/ None).await;+ let mut states = vec![chat.desired_iterm_session_status()];++ chat.bottom_pane.set_task_running(/*running*/ true);+ states.push(chat.desired_iterm_session_status());++ handle_exec_approval_request(+ &mut chat,+ "session-status-approval",+ ExecApprovalRequestEvent {+ kind: Default::default(),+ call_id: "session-status-call".to_string(),+ approval_id: Some("session-status-call".to_string()),+ turn_id: "session-status-turn".to_string(),+ environment_id: None,+ command: vec!["echo".to_string(), "hello".to_string()],+ cwd: AbsolutePathBuf::current_dir().expect("current dir"),+ reason: Some("need confirmation".to_string()),+ network_approval_context: None,+ proposed_execpolicy_amendment: None,+ proposed_network_policy_amendments: None,+ additional_permissions: None,+ available_decisions: None,+ },+ );+ states.push(chat.desired_iterm_session_status());++ chat.handle_key_event(KeyEvent::new(KeyCode::Char('y'), KeyModifiers::NONE));+ states.push(chat.desired_iterm_session_status());++ chat.bottom_pane.set_task_running(/*running*/ false);+ states.push(chat.desired_iterm_session_status());++ chat.unified_exec_processes.push(UnifiedExecProcessSummary {+ key: "background-process".to_string(),+ call_id: "background-call".to_string(),+ command_display: "sleep 5".to_string(),+ recent_chunks: Vec::new(),+ });+ states.push(chat.desired_iterm_session_status());+ chat.unified_exec_processes.clear();+ states.push(chat.desired_iterm_session_status());++ assert_eq!(+ states,+ [Idle, Working, Waiting, Working, Idle, Working, Idle]+ );+}diff --git a/codex-rs/tui/src/iterm_session_status.rs b/codex-rs/tui/src/iterm_session_status.rsnew file mode 100644index 0000000000..f1a1005492--- /dev/null+++ b/codex-rs/tui/src/iterm_session_status.rs@@ -0,0 +1,184 @@+//! Emits coarse Codex lifecycle state through iTerm2's OSC 21337 protocol.+//!+//! This first integration is intentionally limited to direct iTerm2 sessions.+//! The payload uses fixed strings, so it needs no dynamic text escaping or+//! throttling. A process-wide cache matches the terminal session's ownership+//! and prevents stale per-thread state when the active chat changes.++use std::fmt;+use std::io;+use std::io::IsTerminal;+use std::io::stdout;+use std::sync::Mutex;+use std::sync::OnceLock;++use codex_terminal_detection::TerminalInfo;+use codex_terminal_detection::TerminalName;+use codex_terminal_detection::terminal_info;+use crossterm::Command;+use ratatui::crossterm::execute;++const NO_EMITTED_STATUS: u8 = 0;+const INVALIDATED_EMITTED_STATUS: u8 = u8::MAX;+static SESSION_STATUS_STATE: SessionStatusState = SessionStatusState::new();+static ITERM_SESSION_STATUS_SUPPORTED: OnceLock<bool> = OnceLock::new();++struct SessionStatusState {+ last_emitted: Mutex<u8>,+}++impl SessionStatusState {+ const fn new() -> Self {+ Self {+ last_emitted: Mutex::new(NO_EMITTED_STATUS),+ }+ }++ fn update(&self, status: u8, emit: impl FnOnce() -> io::Result<()>) -> io::Result<()> {+ // Keep the terminal write and cache mutation together so panic-hook cleanup cannot+ // interleave with a draw from another thread.+ let mut last_emitted = self+ .last_emitted+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner);+ if *last_emitted == status {+ return Ok(());+ }++ emit()?;+ *last_emitted = status;+ Ok(())+ }++ fn invalidate(&self) {+ let mut last_emitted = self+ .last_emitted+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner);+ if *last_emitted != NO_EMITTED_STATUS {+ *last_emitted = INVALIDATED_EMITTED_STATUS;+ }+ }+}++#[derive(Clone, Copy, Debug, Eq, PartialEq)]+#[repr(u8)]+pub(crate) enum ItermSessionStatus {+ Idle = 1,+ Working = 2,+ Waiting = 3,+}++impl ItermSessionStatus {+ fn label(self) -> &'static str {+ match self {+ Self::Idle => "Idle",+ Self::Working => "Working",+ Self::Waiting => "Waiting",+ }+ }++ fn indicator(self) -> &'static str {+ match self {+ Self::Idle => "#00d75f",+ Self::Working => "#ff9500",+ Self::Waiting => "#5f87ff",+ }+ }+}++pub(crate) fn set_iterm_session_status(status: ItermSessionStatus) -> io::Result<()> {+ if cfg!(test) {+ return Ok(());+ }++ if !*ITERM_SESSION_STATUS_SUPPORTED.get_or_init(|| {+ iterm_session_status_supported(+ &terminal_info(),+ /*stdout_is_terminal*/ stdout().is_terminal(),+ /*screen_active*/ std::env::var_os("STY").is_some(),+ )+ }) {+ return Ok(());+ }++ SESSION_STATUS_STATE.update(status as u8, || {+ execute!(stdout(), SetItermSessionStatus(status))+ })+}++pub(crate) fn clear_iterm_session_status() -> io::Result<()> {+ SESSION_STATUS_STATE.update(NO_EMITTED_STATUS, || {+ execute!(stdout(), ClearItermSessionStatus)+ })+}++/// Forgets the cached state after another process has owned the terminal.+///+/// The next active draw will re-emit Codex's current status even if its+/// lifecycle state did not change during the handoff.+pub(crate) fn invalidate_iterm_session_status() {+ SESSION_STATUS_STATE.invalidate();+}++fn iterm_session_status_supported(+ terminal: &TerminalInfo,+ stdout_is_terminal: bool,+ screen_active: bool,+) -> bool {+ stdout_is_terminal+ && terminal.name == TerminalName::Iterm2+ && terminal.multiplexer.is_none()+ && !screen_active+}++#[derive(Clone, Copy, Debug)]+struct SetItermSessionStatus(ItermSessionStatus);++impl Command for SetItermSessionStatus {+ fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {+ write!(+ f,+ "\x1b]21337;status={};indicator={};status-color=;detail=\x07",+ self.0.label(),+ self.0.indicator(),+ )+ }++ #[cfg(windows)]+ fn execute_winapi(&self) -> io::Result<()> {+ Err(io::Error::other(+ "tried to set iTerm2 session status using WinAPI; use ANSI instead",+ ))+ }++ #[cfg(windows)]+ fn is_ansi_code_supported(&self) -> bool {+ true+ }+}++#[derive(Clone, Copy, Debug)]+struct ClearItermSessionStatus;++impl Command for ClearItermSessionStatus {+ fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {+ write!(f, "\x1b]21337;status=;indicator=;status-color=;detail=\x07")+ }++ #[cfg(windows)]+ fn execute_winapi(&self) -> io::Result<()> {+ Err(io::Error::other(+ "tried to clear iTerm2 session status using WinAPI; use ANSI instead",+ ))+ }++ #[cfg(windows)]+ fn is_ansi_code_supported(&self) -> bool {+ true+ }+}++#[cfg(test)]+#[path = "iterm_session_status_tests.rs"]+mod tests;diff --git a/codex-rs/tui/src/iterm_session_status_tests.rs b/codex-rs/tui/src/iterm_session_status_tests.rsnew file mode 100644index 0000000000..770e5bd769--- /dev/null+++ b/codex-rs/tui/src/iterm_session_status_tests.rs@@ -0,0 +1,140 @@+use std::io;++use codex_terminal_detection::Multiplexer;+use codex_terminal_detection::TerminalInfo;+use codex_terminal_detection::TerminalName;+use crossterm::Command;+use pretty_assertions::assert_eq;++use super::ClearItermSessionStatus;+use super::ItermSessionStatus;+use super::NO_EMITTED_STATUS;+use super::SessionStatusState;+use super::SetItermSessionStatus;+use super::iterm_session_status_supported;++#[test]+fn encodes_session_status_fields() {+ let mut encoded = Vec::new();+ for status in [+ ItermSessionStatus::Idle,+ ItermSessionStatus::Working,+ ItermSessionStatus::Waiting,+ ] {+ let mut value = String::new();+ SetItermSessionStatus(status)+ .write_ansi(&mut value)+ .expect("encode iTerm2 session status");+ encoded.push(value);+ }++ let snapshot = encoded+ .iter()+ .map(|value| value.escape_debug().to_string())+ .collect::<Vec<_>>()+ .join("\n");+ insta::assert_snapshot!("iterm_session_status_fields", snapshot);+}++#[test]+fn clear_empties_every_owned_field() {+ let mut encoded = String::new();+ ClearItermSessionStatus+ .write_ansi(&mut encoded)+ .expect("encode iTerm2 session status clear");++ assert_eq!(+ encoded,+ "\x1b]21337;status=;indicator=;status-color=;detail=\x07"+ );+}++#[test]+fn cache_changes_only_after_a_successful_write() {+ let state = SessionStatusState::new();+ let mut emitted = Vec::new();++ state+ .update(ItermSessionStatus::Working as u8, || {+ Err(io::Error::other("write failed"))+ })+ .expect_err("failed write should be returned");++ state+ .update(ItermSessionStatus::Working as u8, || {+ emitted.push(ItermSessionStatus::Working as u8);+ Ok(())+ })+ .expect("retry status write");+ state+ .update(ItermSessionStatus::Working as u8, || {+ emitted.push(ItermSessionStatus::Waiting as u8);+ Ok(())+ })+ .expect("deduplicate status write");+ state.invalidate();+ state+ .update(ItermSessionStatus::Working as u8, || {+ emitted.push(ItermSessionStatus::Working as u8);+ Ok(())+ })+ .expect("re-emit status after terminal handoff");+ state+ .update(NO_EMITTED_STATUS, || {+ emitted.push(NO_EMITTED_STATUS);+ Ok(())+ })+ .expect("clear status");++ assert_eq!(+ emitted,+ [+ ItermSessionStatus::Working as u8,+ ItermSessionStatus::Working as u8,+ NO_EMITTED_STATUS,+ ]+ );+}++#[test]+fn supports_only_direct_iterm_ttys() {+ let direct_iterm = TerminalInfo {+ name: TerminalName::Iterm2,+ term_program: Some("iTerm.app".to_string()),+ version: Some("3.7.0".to_string()),+ term: None,+ multiplexer: None,+ };+ assert!(iterm_session_status_supported(+ &direct_iterm,+ /*stdout_is_terminal*/ true,+ /*screen_active*/ false,+ ));+ assert!(!iterm_session_status_supported(+ &direct_iterm,+ /*stdout_is_terminal*/ false,+ /*screen_active*/ false,+ ));+ assert!(!iterm_session_status_supported(+ &direct_iterm,+ /*stdout_is_terminal*/ true,+ /*screen_active*/ true,+ ));++ assert!(!iterm_session_status_supported(+ &TerminalInfo {+ multiplexer: Some(Multiplexer::Tmux { version: None }),+ ..direct_iterm.clone()+ },+ /*stdout_is_terminal*/ true,+ /*screen_active*/ false,+ ));+ assert!(!iterm_session_status_supported(+ &TerminalInfo {+ name: TerminalName::Ghostty,+ ..direct_iterm+ },+ /*stdout_is_terminal*/ true,+ /*screen_active*/ false,+ ));+}diff --git a/codex-rs/tui/src/lib.rs b/codex-rs/tui/src/lib.rsindex 934d732d1b..a30587b3cb 100644--- a/codex-rs/tui/src/lib.rs+++ b/codex-rs/tui/src/lib.rs@@ -162,6 +162,7 @@ mod hooks_rpc;mod ide_context;mod inline_visualization;pub(crate) mod insert_history;+mod iterm_session_status;mod managed_worktree_tool_specs;mod managed_worktree_tools;pub use insert_history::insert_history_lines;diff --git a/codex-rs/tui/src/snapshots/codex_tui__iterm_session_status__tests__iterm_session_status_fields.snap b/codex-rs/tui/src/snapshots/codex_tui__iterm_session_status__tests__iterm_session_status_fields.snapnew file mode 100644index 0000000000..b6dfa21dd2--- /dev/null+++ b/codex-rs/tui/src/snapshots/codex_tui__iterm_session_status__tests__iterm_session_status_fields.snap@@ -0,0 +1,8 @@+---+source: tui/src/iterm_session_status_tests.rs+assertion_line: 36+expression: snapshot+---+\u{1b}]21337;status=Idle;indicator=#00d75f;status-color=;detail=\u{7}+\u{1b}]21337;status=Working;indicator=#ff9500;status-color=;detail=\u{7}+\u{1b}]21337;status=Waiting;indicator=#5f87ff;status-color=;detail=\u{7}diff --git a/codex-rs/tui/src/tui.rs b/codex-rs/tui/src/tui.rsindex 9f49da4adb..3ce906fc18 100644--- a/codex-rs/tui/src/tui.rs+++ b/codex-rs/tui/src/tui.rs@@ -408,6 +408,9 @@ pub fn restore_after_exit() -> Result<()> {if let Err(err) = terminal_stderr::finish() {first_error.get_or_insert(err);}+ if let Err(err) = crate::iterm_session_status::clear_iterm_session_status() {+ first_error.get_or_insert(err);+ }match first_error {Some(err) => Err(err),@@ -996,6 +999,7 @@ impl Tui {let _ = self.enter_alt_screen();}+ crate::iterm_session_status::invalidate_iterm_session_status();self.resume_events();self.schedule_screen_size_recheck(Duration::ZERO);outputdiff --git a/codex-rs/tui/src/tui/job_control.rs b/codex-rs/tui/src/tui/job_control.rsindex 7cb12c874b..56d099cc0f 100644--- a/codex-rs/tui/src/tui/job_control.rs+++ b/codex-rs/tui/src/tui/job_control.rs@@ -69,7 +69,12 @@ impl SuspendContext {}let y = self.suspend_cursor_y.load(Ordering::Relaxed);let _ = execute!(stdout(), MoveTo(0, y), Show);- suspend_process()?;+ if let Err(err) = crate::iterm_session_status::clear_iterm_session_status() {+ tracing::debug!(error = %err, "failed to clear iTerm2 session status before suspend");+ }+ let suspend_result = suspend_process();+ crate::iterm_session_status::invalidate_iterm_session_status();+ suspend_result?;super::reapply_raw_mode_after_resume()?;// The shell writes its job-control status and the resumed command after `fg`, so the