Merge branch 'main' into user-friendly-error-handling

## Session snapshot
For POSIX shell, the goal is to take a snapshot of the interactive shell
environment, store it in a session file located in `.codex/` and only
source this file for every command that is run.
As a result, if a snapshot files exist, `bash -lc <CALL>` get replaced
by `bash -c <CALL>`.

This also fixes the issue that `bash -lc` does not source `.bashrc`,
resulting in missing env variables and aliases in the codex session.
## POSIX unification
Unify `bash` and `zsh` shell into a POSIX shell. The rational is that
the tool will not use any `zsh` specific capabilities.

---------

Co-authored-by: Michael Bolin <mbolin@openai.com>

.github/workflows/ci.yml

@@ -14,33 +14,18 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v5
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10.8.1
           run_install: false
 
-      - name: Get pnpm store directory
-        id: pnpm-cache
-        shell: bash
-        run: |
-          echo "store_path=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
-
-      - name: Setup pnpm cache
-        uses: actions/cache@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
         with:
-          path: ${{ steps.pnpm-cache.outputs.store_path }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
+          node-version: 22
 
       - name: Install dependencies
-        run: pnpm install
+        run: pnpm install --frozen-lockfile
 
       # Run all tasks using workspace filters
 

.github/workflows/rust-ci.yml

@@ -63,6 +63,24 @@ jobs:
       - name: cargo fmt
         run: cargo fmt -- --config imports_granularity=Item --check
 
+  cargo_shear:
+    name: cargo shear
+    runs-on: ubuntu-24.04
+    needs: changed
+    if: ${{ needs.changed.outputs.codex == 'true' || needs.changed.outputs.workflows == 'true' || github.event_name == 'push' }}
+    defaults:
+      run:
+        working-directory: codex-rs
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.89
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-shear
+          version: 1.5.1
+      - name: cargo shear
+        run: cargo shear
+
   # --- CI to validate on different os/targets --------------------------------
   lint_build_test:
     name: ${{ matrix.runner }} - ${{ matrix.target }}${{ matrix.profile == 'release' && ' (release)' || '' }}
@@ -182,7 +200,7 @@ jobs:
   # --- Gatherer job that you mark as the ONLY required status -----------------
   results:
     name: CI results (required)
-    needs: [changed, general, lint_build_test]
+    needs: [changed, general, cargo_shear, lint_build_test]
     if: always()
     runs-on: ubuntu-24.04
     steps:
@@ -190,6 +208,7 @@ jobs:
         shell: bash
         run: |
           echo "general: ${{ needs.general.result }}"
+          echo "shear  : ${{ needs.cargo_shear.result }}"
           echo "matrix : ${{ needs.lint_build_test.result }}"
 
           # If nothing relevant changed (PR touching only root README, etc.),
@@ -201,4 +220,5 @@ jobs:
 
           # Otherwise require the jobs to have succeeded
           [[ '${{ needs.general.result }}' == 'success' ]] || { echo 'general failed'; exit 1; }
+          [[ '${{ needs.cargo_shear.result }}' == 'success' ]] || { echo 'cargo_shear failed'; exit 1; }
           [[ '${{ needs.lint_build_test.result }}' == 'success' ]] || { echo 'matrix failed'; exit 1; }

README.md

@@ -75,7 +75,7 @@ Codex CLI supports a rich set of configuration options, with preferences stored
   - [CLI usage](./docs/getting-started.md#cli-usage)
   - [Running with a prompt as input](./docs/getting-started.md#running-with-a-prompt-as-input)
   - [Example prompts](./docs/getting-started.md#example-prompts)
-  - [Memory with AGENTS.md](./docs/getting-started.md#memory--project-docs)
+  - [Memory with AGENTS.md](./docs/getting-started.md#memory-with-agentsmd)
   - [Configuration](./docs/config.md)
 - [**Sandbox & approvals**](./docs/sandbox.md)
 - [**Authentication**](./docs/authentication.md)

codex-rs/Cargo.toml

@@ -22,7 +22,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "0.31.0-alpha.1"
+version = "0.0.0"
 # Track the edition for all workspace crates in one place. Individual
 # crates can still override this value, but keeping it here means new
 # crates created with `cargo new -w ...` automatically inherit the 2024

codex-rs/apply-patch/Cargo.toml

@@ -18,7 +18,7 @@ workspace = true
 anyhow = "1"
 similar = "2.7.0"
 thiserror = "2.0.16"
-tree-sitter = "0.25.8"
+tree-sitter = "0.25.9"
 tree-sitter-bash = "0.25.0"
 once_cell = "1"
 

codex-rs/chatgpt/Cargo.toml

@@ -12,7 +12,6 @@ clap = { version = "4", features = ["derive"] }
 codex-common = { path = "../common", features = ["cli"] }
 codex-core = { path = "../core" }
 codex-protocol = { path = "../protocol" }
-reqwest = { version = "0.12", features = ["json", "stream"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 tokio = { version = "1", features = ["full"] }

codex-rs/core/Cargo.toml

@@ -26,14 +26,12 @@ eventsource-stream = "0.2.3"
 futures = "0.3"
 libc = "0.2.175"
 mcp-types = { path = "../mcp-types" }
-mime_guess = "2.0"
 os_info = "3.12.0"
 portable-pty = "0.9.0"
 rand = "0.9"
 regex-lite = "0.1.7"
 reqwest = { version = "0.12", features = ["json", "stream"] }
 serde = { version = "1", features = ["derive"] }
-serde_bytes = "0.11"
 serde_json = "1"
 sha1 = "0.10.6"
 shlex = "1.3.0"
@@ -53,10 +51,9 @@ tokio-util = "0.7.16"
 toml = "0.9.5"
 toml_edit = "0.23.4"
 tracing = { version = "0.1.41", features = ["log"] }
-tree-sitter = "0.25.8"
+tree-sitter = "0.25.9"
 tree-sitter-bash = "0.25.0"
 uuid = { version = "1", features = ["serde", "v4"] }
-whoami = "1.6.1"
 wildmatch = "2.4.0"
 
 
@@ -85,3 +82,6 @@ tempfile = "3"
 tokio-test = "0.4"
 walkdir = "2.5.0"
 wiremock = "0.6"
+
+[package.metadata.cargo-shear]
+ignored = ["openssl-sys"]

codex-rs/core/src/client.rs

@@ -6,6 +6,7 @@ use std::time::Duration;
 use crate::AuthManager;
 use bytes::Bytes;
 use codex_protocol::mcp_protocol::AuthMode;
+use codex_protocol::mcp_protocol::ConversationId;
 use eventsource_stream::Eventsource;
 use futures::prelude::*;
 use regex_lite::Regex;
@@ -19,7 +20,6 @@ use tokio_util::io::ReaderStream;
 use tracing::debug;
 use tracing::trace;
 use tracing::warn;
-use uuid::Uuid;
 
 use crate::chat_completions::AggregateStreamExt;
 use crate::chat_completions::stream_chat_completions;
@@ -70,7 +70,7 @@ pub struct ModelClient {
     auth_manager: Option<Arc<AuthManager>>,
     client: reqwest::Client,
     provider: ModelProviderInfo,
-    session_id: Uuid,
+    conversation_id: ConversationId,
     effort: ReasoningEffortConfig,
     summary: ReasoningSummaryConfig,
 }
@@ -82,7 +82,7 @@ impl ModelClient {
         provider: ModelProviderInfo,
         effort: ReasoningEffortConfig,
         summary: ReasoningSummaryConfig,
-        session_id: Uuid,
+        conversation_id: ConversationId,
     ) -> Self {
         let client = create_client(&config.responses_originator_header);
 
@@ -91,7 +91,7 @@ impl ModelClient {
             auth_manager,
             client,
             provider,
-            session_id,
+            conversation_id,
             effort,
             summary,
         }
@@ -197,7 +197,7 @@ impl ModelClient {
             store: false,
             stream: true,
             include,
-            prompt_cache_key: Some(self.session_id.to_string()),
+            prompt_cache_key: Some(self.conversation_id.to_string()),
             text,
         };
 
@@ -223,7 +223,9 @@ impl ModelClient {
 
             req_builder = req_builder
                 .header("OpenAI-Beta", "responses=experimental")
-                .header("session_id", self.session_id.to_string())
+                // Send session_id for compatibility.
+                .header("conversation_id", self.conversation_id.to_string())
+                .header("session_id", self.conversation_id.to_string())
                 .header(reqwest::header::ACCEPT, "text/event-stream")
                 .json(&payload);
 
@@ -318,6 +320,9 @@ impl ModelClient {
                         if status == StatusCode::INTERNAL_SERVER_ERROR {
                             return Err(CodexErr::InternalServerError);
                         }
+                        if status == StatusCode::UNAUTHORIZED {
+                            return Err(CodexErr::UnauthorizedError);
+                        }
 
                         return Err(CodexErr::RetryLimit(status));
                     }
@@ -398,9 +403,15 @@ impl From<ResponseCompletedUsage> for TokenUsage {
     fn from(val: ResponseCompletedUsage) -> Self {
         TokenUsage {
             input_tokens: val.input_tokens,
-            cached_input_tokens: val.input_tokens_details.map(|d| d.cached_tokens),
+            cached_input_tokens: val
+                .input_tokens_details
+                .map(|d| d.cached_tokens)
+                .unwrap_or(0),
             output_tokens: val.output_tokens,
-            reasoning_output_tokens: val.output_tokens_details.map(|d| d.reasoning_tokens),
+            reasoning_output_tokens: val
+                .output_tokens_details
+                .map(|d| d.reasoning_tokens)
+                .unwrap_or(0),
             total_tokens: val.total_tokens,
         }
     }

codex-rs/core/src/codex.rs

@@ -15,6 +15,7 @@ use async_channel::Sender;
 use codex_apply_patch::ApplyPatchAction;
 use codex_apply_patch::MaybeApplyPatchVerified;
 use codex_apply_patch::maybe_parse_apply_patch_verified;
+use codex_protocol::mcp_protocol::ConversationId;
 use codex_protocol::protocol::ConversationHistoryResponseEvent;
 use codex_protocol::protocol::TaskStartedEvent;
 use codex_protocol::protocol::TurnAbortReason;
@@ -30,7 +31,6 @@ use tracing::error;
 use tracing::info;
 use tracing::trace;
 use tracing::warn;
-use uuid::Uuid;
 
 use crate::ModelProviderInfo;
 use crate::apply_patch;
@@ -99,9 +99,11 @@ use crate::protocol::SessionConfiguredEvent;
 use crate::protocol::StreamErrorEvent;
 use crate::protocol::Submission;
 use crate::protocol::TaskCompleteEvent;
+use crate::protocol::TokenUsageInfo;
 use crate::protocol::TurnDiffEvent;
 use crate::protocol::WebSearchBeginEvent;
 use crate::rollout::RolloutRecorder;
+use crate::rollout::RolloutRecorderParams;
 use crate::safety::SafetyCheck;
 use crate::safety::assess_command_safety;
 use crate::safety::assess_safety_for_untrusted_command;
@@ -148,7 +150,7 @@ pub struct Codex {
 /// unique session id.
 pub struct CodexSpawnOk {
     pub codex: Codex,
-    pub session_id: Uuid,
+    pub conversation_id: ConversationId,
 }
 
 pub(crate) const INITIAL_SUBMIT_ID: &str = "";
@@ -204,7 +206,7 @@ impl Codex {
         session
             .record_initial_history(&turn_context, conversation_history)
             .await;
-        let session_id = session.session_id;
+        let conversation_id = session.conversation_id;
 
         // This task will run until Op::Shutdown is received.
         tokio::spawn(submission_loop(
@@ -219,7 +221,10 @@ impl Codex {
             rx_event,
         };
 
-        Ok(CodexSpawnOk { codex, session_id })
+        Ok(CodexSpawnOk {
+            codex,
+            conversation_id,
+        })
     }
 
     /// Submit the `op` wrapped in a `Submission` with a unique ID.
@@ -261,13 +266,14 @@ struct State {
     pending_approvals: HashMap<String, oneshot::Sender<ReviewDecision>>,
     pending_input: Vec<ResponseInputItem>,
     history: ConversationHistory,
+    token_info: Option<TokenUsageInfo>,
 }
 
 /// Context for an initialized model agent
 ///
 /// A session has at most 1 running task at a time, and can be interrupted by user input.
 pub(crate) struct Session {
-    session_id: Uuid,
+    conversation_id: ConversationId,
     tx_event: Sender<Event>,
 
     /// Manager for external MCP servers/tools.
@@ -356,7 +362,6 @@ impl Session {
         tx_event: Sender<Event>,
         initial_history: InitialHistory,
     ) -> anyhow::Result<(Arc<Self>, TurnContext)> {
-        let session_id = Uuid::new_v4();
         let ConfigureSession {
             provider,
             model,
@@ -374,6 +379,20 @@ impl Session {
             return Err(anyhow::anyhow!("cwd is not absolute: {cwd:?}"));
         }
 
+        let (conversation_id, rollout_params) = match &initial_history {
+            InitialHistory::New | InitialHistory::Forked(_) => {
+                let conversation_id = ConversationId::default();
+                (
+                    conversation_id,
+                    RolloutRecorderParams::new(conversation_id, user_instructions.clone()),
+                )
+            }
+            InitialHistory::Resumed(resumed_history) => (
+                resumed_history.conversation_id,
+                RolloutRecorderParams::resume(resumed_history.rollout_path.clone()),
+            ),
+        };
+
         // Error messages to dispatch after SessionConfigured is sent.
         let mut post_session_configured_error_events = Vec::<Event>::new();
 
@@ -383,10 +402,10 @@ impl Session {
         // - spin up MCP connection manager
         // - perform default shell discovery
         // - load history metadata
-        let rollout_fut = RolloutRecorder::new(&config, session_id, user_instructions.clone());
+        let rollout_fut = RolloutRecorder::new(&config, rollout_params);
 
         let mcp_fut = McpConnectionManager::new(config.mcp_servers.clone());
-        let default_shell_fut = shell::default_user_shell();
+        let default_shell_fut = shell::default_user_shell(conversation_id.0, &config.codex_home);
         let history_meta_fut = crate::message_history::history_metadata(&config);
 
         // Join all independent futures.
@@ -429,7 +448,7 @@ impl Session {
             }
         }
 
-        // Now that `session_id` is final (may have been updated by resume),
+        // Now that the conversation id is final (may have been updated by resume),
         // construct the model client.
         let client = ModelClient::new(
             config.clone(),
@@ -437,7 +456,7 @@ impl Session {
             provider.clone(),
             model_reasoning_effort,
             model_reasoning_summary,
-            session_id,
+            conversation_id,
         );
         let turn_context = TurnContext {
             client,
@@ -458,8 +477,9 @@ impl Session {
             shell_environment_policy: config.shell_environment_policy.clone(),
             cwd,
         };
+
         let sess = Arc::new(Session {
-            session_id,
+            conversation_id,
             tx_event: tx_event.clone(),
             mcp_connection_manager,
             session_manager: ExecSessionManager::default(),
@@ -475,13 +495,16 @@ impl Session {
         // If resuming, include converted initial messages in the payload so UIs can render them immediately.
         let initial_messages = match &initial_history {
             InitialHistory::New => None,
-            InitialHistory::Resumed(items) => Some(sess.build_initial_messages(items)),
+            InitialHistory::Forked(items) => Some(sess.build_initial_messages(items)),
+            InitialHistory::Resumed(resumed_history) => {
+                Some(sess.build_initial_messages(&resumed_history.history))
+            }
         };
 
         let events = std::iter::once(Event {
             id: INITIAL_SUBMIT_ID.to_owned(),
             msg: EventMsg::SessionConfigured(SessionConfiguredEvent {
-                session_id,
+                session_id: conversation_id,
                 model,
                 history_log_id,
                 history_entry_count,
@@ -524,8 +547,12 @@ impl Session {
             InitialHistory::New => {
                 self.record_initial_history_new(turn_context).await;
             }
-            InitialHistory::Resumed(items) => {
-                self.record_initial_history_resumed(items).await;
+            InitialHistory::Forked(items) => {
+                self.record_initial_history_from_items(items).await;
+            }
+            InitialHistory::Resumed(resumed_history) => {
+                self.record_initial_history_from_items(resumed_history.history)
+                    .await;
             }
         }
     }
@@ -547,8 +574,8 @@ impl Session {
         self.record_conversation_items(&conversation_items).await;
     }
 
-    async fn record_initial_history_resumed(&self, items: Vec<ResponseItem>) {
-        self.record_conversation_items(&items).await;
+    async fn record_initial_history_from_items(&self, items: Vec<ResponseItem>) {
+        self.record_conversation_items_internal(&items, false).await;
     }
 
     /// build the initial messages vector for SessionConfigured by converting
@@ -657,8 +684,14 @@ impl Session {
     /// Records items to both the rollout and the chat completions/ZDR
     /// transcript, if enabled.
     async fn record_conversation_items(&self, items: &[ResponseItem]) {
+        self.record_conversation_items_internal(items, true).await;
+    }
+
+    async fn record_conversation_items_internal(&self, items: &[ResponseItem], persist: bool) {
         debug!("Recording items for conversation: {items:?}");
-        self.record_state_snapshot(items).await;
+        if persist {
+            self.record_state_snapshot(items).await;
+        }
 
         self.state.lock_unchecked().history.record_items(items);
     }
@@ -1082,7 +1115,7 @@ async fn submission_loop(
                     provider,
                     effective_effort,
                     effective_summary,
-                    sess.session_id,
+                    sess.conversation_id,
                 );
 
                 let new_approval_policy = approval_policy.unwrap_or(prev.approval_policy);
@@ -1170,7 +1203,7 @@ async fn submission_loop(
                         provider,
                         effort,
                         summary,
-                        sess.session_id,
+                        sess.conversation_id,
                     );
 
                     let fresh_turn_context = TurnContext {
@@ -1213,7 +1246,7 @@ async fn submission_loop(
                 other => sess.notify_approval(&id, other),
             },
             Op::AddToHistory { text } => {
-                let id = sess.session_id;
+                let id = sess.conversation_id;
                 let config = config.clone();
                 tokio::spawn(async move {
                     if let Err(e) = crate::message_history::append_entry(&text, &id, &config).await
@@ -1244,7 +1277,7 @@ async fn submission_loop(
                                 log_id,
                                 entry: entry_opt.map(|e| {
                                     codex_protocol::message_history::HistoryEntry {
-                                        session_id: e.session_id,
+                                        conversation_id: e.session_id,
                                         ts: e.ts,
                                         text: e.text,
                                     }
@@ -1350,7 +1383,7 @@ async fn submission_loop(
                 let event = Event {
                     id: sub_id.clone(),
                     msg: EventMsg::ConversationHistory(ConversationHistoryResponseEvent {
-                        conversation_id: sess.session_id,
+                        conversation_id: sess.conversation_id,
                         entries: sess.state.lock_unchecked().history.contents(),
                     }),
                 };
@@ -1606,7 +1639,14 @@ async fn run_turn(
             Ok(output) => return Ok(output),
             Err(CodexErr::Interrupted) => return Err(CodexErr::Interrupted),
             Err(CodexErr::EnvVar(var)) => return Err(CodexErr::EnvVar(var)),
-            Err(e @ (CodexErr::UsageLimitReached(_) | CodexErr::UsageNotIncluded)) => {
+            Err(
+                e @ (CodexErr::UsageLimitReached(_)
+                | CodexErr::UsageNotIncluded
+                | CodexErr::UnexpectedStatus(_, _)
+                | CodexErr::RetryLimit(_)
+                | CodexErr::UnauthorizedError
+                | CodexErr::InternalServerError),
+            ) => {
                 return Err(e);
             }
             Err(e) => {
@@ -1767,15 +1807,23 @@ async fn try_run_turn(
                 response_id: _,
                 token_usage,
             } => {
-                if let Some(token_usage) = token_usage {
-                    sess.tx_event
-                        .send(Event {
-                            id: sub_id.to_string(),
-                            msg: EventMsg::TokenCount(token_usage),
-                        })
-                        .await
-                        .ok();
-                }
+                let info = {
+                    let mut st = sess.state.lock_unchecked();
+                    let info = TokenUsageInfo::new_or_append(
+                        &st.token_info,
+                        &token_usage,
+                        turn_context.client.get_model_context_window(),
+                    );
+                    st.token_info = info.clone();
+                    info
+                };
+                sess.tx_event
+                    .send(Event {
+                        id: sub_id.to_string(),
+                        msg: EventMsg::TokenCount(crate::protocol::TokenCountEvent { info }),
+                    })
+                    .await
+                    .ok();
 
                 let unified_diff = turn_diff_tracker.get_unified_diff();
                 if let Ok(Some(unified_diff)) = unified_diff {
@@ -2283,13 +2331,25 @@ pub struct ExecInvokeArgs<'a> {
     pub stdout_stream: Option<StdoutStream>,
 }
 
+fn should_translate_shell_command(
+    shell: &crate::shell::Shell,
+    shell_policy: &ShellEnvironmentPolicy,
+) -> bool {
+    matches!(shell, crate::shell::Shell::PowerShell(_))
+        || shell_policy.use_profile
+        || matches!(
+            shell,
+            crate::shell::Shell::Posix(shell) if shell.shell_snapshot.is_some()
+        )
+}
+
 fn maybe_translate_shell_command(
     params: ExecParams,
     sess: &Session,
     turn_context: &TurnContext,
 ) -> ExecParams {
-    let should_translate = matches!(sess.user_shell, crate::shell::Shell::PowerShell(_))
-        || turn_context.shell_environment_policy.use_profile;
+    let should_translate =
+        should_translate_shell_command(&sess.user_shell, &turn_context.shell_environment_policy);
 
     if should_translate
         && let Some(command) = sess
@@ -2841,13 +2901,21 @@ async fn drain_to_completed(
                 response_id: _,
                 token_usage,
             }) => {
-                // some providers don't return token usage, so we default
-                // TODO: consider approximate token usage
-                let token_usage = token_usage.unwrap_or_default();
+                let info = {
+                    let mut st = sess.state.lock_unchecked();
+                    let info = TokenUsageInfo::new_or_append(
+                        &st.token_info,
+                        &token_usage,
+                        turn_context.client.get_model_context_window(),
+                    );
+                    st.token_info = info.clone();
+                    info
+                };
+
                 sess.tx_event
                     .send(Event {
                         id: sub_id.to_string(),
-                        msg: EventMsg::TokenCount(token_usage),
+                        msg: EventMsg::TokenCount(crate::protocol::TokenCountEvent { info }),
                     })
                     .await
                     .ok();
@@ -2898,10 +2966,15 @@ fn convert_call_tool_result_to_function_call_output_payload(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::config_types::ShellEnvironmentPolicyInherit;
     use mcp_types::ContentBlock;
     use mcp_types::TextContent;
     use pretty_assertions::assert_eq;
     use serde_json::json;
+    use shell::ShellSnapshot;
+    use std::collections::HashMap;
+    use std::path::PathBuf;
+    use std::sync::Arc;
     use std::time::Duration as StdDuration;
 
     fn text_block(s: &str) -> ContentBlock {
@@ -2912,6 +2985,48 @@ mod tests {
         })
     }
 
+    fn shell_policy_with_profile(use_profile: bool) -> ShellEnvironmentPolicy {
+        ShellEnvironmentPolicy {
+            inherit: ShellEnvironmentPolicyInherit::All,
+            ignore_default_excludes: false,
+            exclude: Vec::new(),
+            r#set: HashMap::new(),
+            include_only: Vec::new(),
+            use_profile,
+        }
+    }
+
+    fn zsh_shell(shell_snapshot: Option<Arc<ShellSnapshot>>) -> shell::Shell {
+        shell::Shell::Posix(shell::PosixShell {
+            shell_path: "/bin/zsh".to_string(),
+            rc_path: "/Users/example/.zshrc".to_string(),
+            shell_snapshot,
+        })
+    }
+
+    #[test]
+    fn translates_commands_when_shell_policy_requests_profile() {
+        let policy = shell_policy_with_profile(true);
+        let shell = zsh_shell(None);
+        assert!(should_translate_shell_command(&shell, &policy));
+    }
+
+    #[test]
+    fn translates_commands_for_zsh_with_snapshot() {
+        let policy = shell_policy_with_profile(false);
+        let shell = zsh_shell(Some(Arc::new(ShellSnapshot::new(PathBuf::from(
+            "/tmp/snapshot",
+        )))));
+        assert!(should_translate_shell_command(&shell, &policy));
+    }
+
+    #[test]
+    fn bypasses_translation_for_zsh_without_snapshot_or_profile() {
+        let policy = shell_policy_with_profile(false);
+        let shell = zsh_shell(None);
+        assert!(!should_translate_shell_command(&shell, &policy));
+    }
+
     #[test]
     fn prefers_structured_content_when_present() {
         let ctr = CallToolResult {

codex-rs/core/src/config_types.rs

@@ -18,6 +18,10 @@ pub struct McpServerConfig {
 
     #[serde(default)]
     pub env: Option<HashMap<String, String>>,
+
+    /// Startup timeout in milliseconds for initializing MCP server & initially listing tools.
+    #[serde(default)]
+    pub startup_timeout_ms: Option<u64>,
 }
 
 #[derive(Deserialize, Debug, Copy, Clone, PartialEq)]

codex-rs/core/src/conversation_manager.rs

@@ -1,12 +1,5 @@
-use std::collections::HashMap;
-use std::path::PathBuf;
-use std::sync::Arc;
-
 use crate::AuthManager;
 use crate::CodexAuth;
-use tokio::sync::RwLock;
-use uuid::Uuid;
-
 use crate::codex::Codex;
 use crate::codex::CodexSpawnOk;
 use crate::codex::INITIAL_SUBMIT_ID;
@@ -18,18 +11,31 @@ use crate::protocol::Event;
 use crate::protocol::EventMsg;
 use crate::protocol::SessionConfiguredEvent;
 use crate::rollout::RolloutRecorder;
+use codex_protocol::mcp_protocol::ConversationId;
 use codex_protocol::models::ResponseItem;
+use std::collections::HashMap;
+use std::path::PathBuf;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct ResumedHistory {
+    pub conversation_id: ConversationId,
+    pub history: Vec<ResponseItem>,
+    pub rollout_path: PathBuf,
+}
 
 #[derive(Debug, Clone, PartialEq)]
 pub enum InitialHistory {
     New,
-    Resumed(Vec<ResponseItem>),
+    Resumed(ResumedHistory),
+    Forked(Vec<ResponseItem>),
 }
 
 /// Represents a newly created Codex conversation, including the first event
 /// (which is [`EventMsg::SessionConfigured`]).
 pub struct NewConversation {
-    pub conversation_id: Uuid,
+    pub conversation_id: ConversationId,
     pub conversation: Arc<CodexConversation>,
     pub session_configured: SessionConfiguredEvent,
 }
@@ -37,7 +43,7 @@ pub struct NewConversation {
 /// [`ConversationManager`] is responsible for creating conversations and
 /// maintaining them in memory.
 pub struct ConversationManager {
-    conversations: Arc<RwLock<HashMap<Uuid, Arc<CodexConversation>>>>,
+    conversations: Arc<RwLock<HashMap<ConversationId, Arc<CodexConversation>>>>,
     auth_manager: Arc<AuthManager>,
 }
 
@@ -70,14 +76,14 @@ impl ConversationManager {
             let initial_history = RolloutRecorder::get_rollout_history(resume_path).await?;
             let CodexSpawnOk {
                 codex,
-                session_id: conversation_id,
+                conversation_id,
             } = Codex::spawn(config, auth_manager, initial_history).await?;
             self.finalize_spawn(codex, conversation_id).await
         } else {
             let CodexSpawnOk {
                 codex,
-                session_id: conversation_id,
-            } = { Codex::spawn(config, auth_manager, InitialHistory::New).await? };
+                conversation_id,
+            } = Codex::spawn(config, auth_manager, InitialHistory::New).await?;
             self.finalize_spawn(codex, conversation_id).await
         }
     }
@@ -85,7 +91,7 @@ impl ConversationManager {
     async fn finalize_spawn(
         &self,
         codex: Codex,
-        conversation_id: Uuid,
+        conversation_id: ConversationId,
     ) -> CodexResult<NewConversation> {
         // The first event must be `SessionInitialized`. Validate and forward it
         // to the caller so that they can display it in the conversation
@@ -116,7 +122,7 @@ impl ConversationManager {
 
     pub async fn get_conversation(
         &self,
-        conversation_id: Uuid,
+        conversation_id: ConversationId,
     ) -> CodexResult<Arc<CodexConversation>> {
         let conversations = self.conversations.read().await;
         conversations
@@ -134,12 +140,12 @@ impl ConversationManager {
         let initial_history = RolloutRecorder::get_rollout_history(&rollout_path).await?;
         let CodexSpawnOk {
             codex,
-            session_id: conversation_id,
+            conversation_id,
         } = Codex::spawn(config, auth_manager, initial_history).await?;
         self.finalize_spawn(codex, conversation_id).await
     }
 
-    pub async fn remove_conversation(&self, conversation_id: Uuid) {
+    pub async fn remove_conversation(&self, conversation_id: ConversationId) {
         self.conversations.write().await.remove(&conversation_id);
     }
 
@@ -161,7 +167,7 @@ impl ConversationManager {
         let auth_manager = self.auth_manager.clone();
         let CodexSpawnOk {
             codex,
-            session_id: conversation_id,
+            conversation_id,
         } = Codex::spawn(config, auth_manager, history).await?;
 
         self.finalize_spawn(codex, conversation_id).await
@@ -172,7 +178,7 @@ impl ConversationManager {
 /// and all items that follow them.
 fn truncate_after_dropping_last_messages(items: Vec<ResponseItem>, n: usize) -> InitialHistory {
     if n == 0 {
-        return InitialHistory::Resumed(items);
+        return InitialHistory::Forked(items);
     }
 
     // Walk backwards counting only `user` Message items, find cut index.
@@ -194,7 +200,7 @@ fn truncate_after_dropping_last_messages(items: Vec<ResponseItem>, n: usize) ->
         // No prefix remains after dropping; start a new conversation.
         InitialHistory::New
     } else {
-        InitialHistory::Resumed(items.into_iter().take(cut_index).collect())
+        InitialHistory::Forked(items.into_iter().take(cut_index).collect())
     }
 }
 
@@ -252,7 +258,7 @@ mod tests {
         let truncated = truncate_after_dropping_last_messages(items.clone(), 1);
         assert_eq!(
             truncated,
-            InitialHistory::Resumed(vec![items[0].clone(), items[1].clone(), items[2].clone(),])
+            InitialHistory::Forked(vec![items[0].clone(), items[1].clone(), items[2].clone(),])
         );
 
         let truncated2 = truncate_after_dropping_last_messages(items, 2);

codex-rs/core/src/error.rs

@@ -1,10 +1,10 @@
+use codex_protocol::mcp_protocol::ConversationId;
 use reqwest::StatusCode;
 use serde_json;
 use std::io;
 use std::time::Duration;
 use thiserror::Error;
 use tokio::task::JoinError;
-use uuid::Uuid;
 
 pub type Result<T> = std::result::Result<T, CodexErr>;
 
@@ -49,7 +49,7 @@ pub enum CodexErr {
     Stream(String, Option<Duration>),
 
     #[error("no conversation with id: {0}")]
-    ConversationNotFound(Uuid),
+    ConversationNotFound(ConversationId),
 
     #[error("session configured event was not the first event in the stream")]
     SessionConfiguredNotFirstEvent,
@@ -83,6 +83,9 @@ pub enum CodexErr {
     #[error("We're currently experiencing high demand, which may cause temporary errors.")]
     InternalServerError,
 
+    #[error("The API key is invalid or has expired. Please check your API key and try again.")]
+    UnauthorizedError,
+
     /// Retry limit exceeded.
     #[error("exceeded retry limit, last status: {0}")]
     RetryLimit(StatusCode),

codex-rs/core/src/lib.rs

@@ -62,6 +62,7 @@ pub mod terminal;
 mod tool_apply_patch;
 pub mod turn_diff_tracker;
 pub use rollout::RolloutRecorder;
+pub use rollout::SessionMeta;
 pub use rollout::list::ConversationItem;
 pub use rollout::list::ConversationsPage;
 pub use rollout::list::Cursor;

codex-rs/core/src/mcp_connection_manager.rs

@@ -9,6 +9,7 @@
 use std::collections::HashMap;
 use std::collections::HashSet;
 use std::ffi::OsString;
+use std::sync::Arc;
 use std::time::Duration;
 
 use anyhow::Context;
@@ -36,8 +37,8 @@ use crate::config_types::McpServerConfig;
 const MCP_TOOL_NAME_DELIMITER: &str = "__";
 const MAX_TOOL_NAME_LENGTH: usize = 64;
 
-/// Timeout for the `tools/list` request.
-const LIST_TOOLS_TIMEOUT: Duration = Duration::from_secs(10);
+/// Default timeout for initializing MCP server & initially listing tools.
+const DEFAULT_STARTUP_TIMEOUT: Duration = Duration::from_secs(10);
 
 /// Map that holds a startup error for every MCP server that could **not** be
 /// spawned successfully.
@@ -81,6 +82,11 @@ struct ToolInfo {
     tool: Tool,
 }
 
+struct ManagedClient {
+    client: Arc<McpClient>,
+    startup_timeout: Duration,
+}
+
 /// A thin wrapper around a set of running [`McpClient`] instances.
 #[derive(Default)]
 pub(crate) struct McpConnectionManager {
@@ -88,7 +94,7 @@ pub(crate) struct McpConnectionManager {
     ///
     /// The server name originates from the keys of the `mcp_servers` map in
     /// the user configuration.
-    clients: HashMap<String, std::sync::Arc<McpClient>>,
+    clients: HashMap<String, ManagedClient>,
 
     /// Fully qualified tool name -> tool instance.
     tools: HashMap<String, ToolInfo>,
@@ -126,8 +132,15 @@ impl McpConnectionManager {
                 continue;
             }
 
+            let startup_timeout = cfg
+                .startup_timeout_ms
+                .map(Duration::from_millis)
+                .unwrap_or(DEFAULT_STARTUP_TIMEOUT);
+
             join_set.spawn(async move {
-                let McpServerConfig { command, args, env } = cfg;
+                let McpServerConfig {
+                    command, args, env, ..
+                } = cfg;
                 let client_res = McpClient::new_stdio_client(
                     command.into(),
                     args.into_iter().map(OsString::from).collect(),
@@ -154,12 +167,15 @@ impl McpConnectionManager {
                             protocol_version: mcp_types::MCP_SCHEMA_VERSION.to_owned(),
                         };
                         let initialize_notification_params = None;
-                        let timeout = Some(Duration::from_secs(10));
                         match client
-                            .initialize(params, initialize_notification_params, timeout)
+                            .initialize(
+                                params,
+                                initialize_notification_params,
+                                Some(startup_timeout),
+                            )
                             .await
                         {
-                            Ok(_response) => (server_name, Ok(client)),
+                            Ok(_response) => (server_name, Ok((client, startup_timeout))),
                             Err(e) => (server_name, Err(e)),
                         }
                     }
@@ -168,15 +184,26 @@ impl McpConnectionManager {
             });
         }
 
-        let mut clients: HashMap<String, std::sync::Arc<McpClient>> =
-            HashMap::with_capacity(join_set.len());
+        let mut clients: HashMap<String, ManagedClient> = HashMap::with_capacity(join_set.len());
 
         while let Some(res) = join_set.join_next().await {
-            let (server_name, client_res) = res?; // JoinError propagation
+            let (server_name, client_res) = match res {
+                Ok((server_name, client_res)) => (server_name, client_res),
+                Err(e) => {
+                    warn!("Task panic when starting MCP server: {e:#}");
+                    continue;
+                }
+            };
 
             match client_res {
-                Ok(client) => {
-                    clients.insert(server_name, std::sync::Arc::new(client));
+                Ok((client, startup_timeout)) => {
+                    clients.insert(
+                        server_name,
+                        ManagedClient {
+                            client: Arc::new(client),
+                            startup_timeout,
+                        },
+                    );
                 }
                 Err(e) => {
                     errors.insert(server_name, e);
@@ -184,7 +211,13 @@ impl McpConnectionManager {
             }
         }
 
-        let all_tools = list_all_tools(&clients).await?;
+        let all_tools = match list_all_tools(&clients).await {
+            Ok(tools) => tools,
+            Err(e) => {
+                warn!("Failed to list tools from some MCP servers: {e:#}");
+                Vec::new()
+            }
+        };
 
         let tools = qualify_tools(all_tools);
 
@@ -212,6 +245,7 @@ impl McpConnectionManager {
             .clients
             .get(server)
             .ok_or_else(|| anyhow!("unknown MCP server '{server}'"))?
+            .client
             .clone();
 
         client
@@ -229,21 +263,18 @@ impl McpConnectionManager {
 
 /// Query every server for its available tools and return a single map that
 /// contains **all** tools. Each key is the fully-qualified name for the tool.
-async fn list_all_tools(
-    clients: &HashMap<String, std::sync::Arc<McpClient>>,
-) -> Result<Vec<ToolInfo>> {
+async fn list_all_tools(clients: &HashMap<String, ManagedClient>) -> Result<Vec<ToolInfo>> {
     let mut join_set = JoinSet::new();
 
     // Spawn one task per server so we can query them concurrently. This
     // keeps the overall latency roughly at the slowest server instead of
     // the cumulative latency.
-    for (server_name, client) in clients {
+    for (server_name, managed_client) in clients {
         let server_name_cloned = server_name.clone();
-        let client_clone = client.clone();
+        let client_clone = managed_client.client.clone();
+        let startup_timeout = managed_client.startup_timeout;
         join_set.spawn(async move {
-            let res = client_clone
-                .list_tools(None, Some(LIST_TOOLS_TIMEOUT))
-                .await;
+            let res = client_clone.list_tools(None, Some(startup_timeout)).await;
             (server_name_cloned, res)
         });
     }
@@ -251,8 +282,19 @@ async fn list_all_tools(
     let mut aggregated: Vec<ToolInfo> = Vec::with_capacity(join_set.len());
 
     while let Some(join_res) = join_set.join_next().await {
-        let (server_name, list_result) = join_res?;
-        let list_result = list_result?;
+        let (server_name, list_result) = if let Ok(result) = join_res {
+            result
+        } else {
+            warn!("Task panic when listing tools for MCP server: {join_res:#?}");
+            continue;
+        };
+
+        let list_result = if let Ok(result) = list_result {
+            result
+        } else {
+            warn!("Failed to list tools for MCP server '{server_name}': {list_result:#?}");
+            continue;
+        };
 
         for tool in list_result.tools {
             let tool_info = ToolInfo {

codex-rs/core/src/message_history.rs

@@ -5,7 +5,7 @@
 //! JSON-Lines tooling. Each record has the following schema:
 //!
 //! ````text
-//! {"session_id":"<uuid>","ts":<unix_seconds>,"text":"<message>"}
+//! {"conversation_id":"<uuid>","ts":<unix_seconds>,"text":"<message>"}
 //! ````
 //!
 //! To minimise the chance of interleaved writes when multiple processes are
@@ -22,14 +22,15 @@ use std::path::PathBuf;
 
 use serde::Deserialize;
 use serde::Serialize;
+
 use std::time::Duration;
 use tokio::fs;
 use tokio::io::AsyncReadExt;
-use uuid::Uuid;
 
 use crate::config::Config;
 use crate::config_types::HistoryPersistence;
 
+use codex_protocol::mcp_protocol::ConversationId;
 #[cfg(unix)]
 use std::os::unix::fs::OpenOptionsExt;
 #[cfg(unix)]
@@ -54,10 +55,14 @@ fn history_filepath(config: &Config) -> PathBuf {
     path
 }
 
-/// Append a `text` entry associated with `session_id` to the history file. Uses
+/// Append a `text` entry associated with `conversation_id` to the history file. Uses
 /// advisory file locking to ensure that concurrent writes do not interleave,
 /// which entails a small amount of blocking I/O internally.
-pub(crate) async fn append_entry(text: &str, session_id: &Uuid, config: &Config) -> Result<()> {
+pub(crate) async fn append_entry(
+    text: &str,
+    conversation_id: &ConversationId,
+    config: &Config,
+) -> Result<()> {
     match config.history.persistence {
         HistoryPersistence::SaveAll => {
             // Save everything: proceed.
@@ -84,7 +89,7 @@ pub(crate) async fn append_entry(text: &str, session_id: &Uuid, config: &Config)
 
     // Construct the JSON line first so we can write it in a single syscall.
     let entry = HistoryEntry {
-        session_id: session_id.to_string(),
+        session_id: conversation_id.to_string(),
         ts,
         text: text.to_string(),
     };

codex-rs/core/src/rollout/mod.rs

@@ -7,6 +7,8 @@ pub(crate) mod policy;
 pub mod recorder;
 
 pub use recorder::RolloutRecorder;
+pub use recorder::RolloutRecorderParams;
+pub use recorder::SessionMeta;
 pub use recorder::SessionStateSnapshot;
 
 #[cfg(test)]

codex-rs/core/src/rollout/recorder.rs

@@ -4,7 +4,9 @@ use std::fs::File;
 use std::fs::{self};
 use std::io::Error as IoError;
 use std::path::Path;
+use std::path::PathBuf;
 
+use codex_protocol::mcp_protocol::ConversationId;
 use serde::Deserialize;
 use serde::Serialize;
 use serde_json::Value;
@@ -17,7 +19,6 @@ use tokio::sync::mpsc::{self};
 use tokio::sync::oneshot;
 use tracing::info;
 use tracing::warn;
-use uuid::Uuid;
 
 use super::SESSIONS_SUBDIR;
 use super::list::ConversationsPage;
@@ -26,13 +27,14 @@ use super::list::get_conversations;
 use super::policy::is_persisted_response_item;
 use crate::config::Config;
 use crate::conversation_manager::InitialHistory;
+use crate::conversation_manager::ResumedHistory;
 use crate::git_info::GitInfo;
 use crate::git_info::collect_git_info;
 use codex_protocol::models::ResponseItem;
 
 #[derive(Serialize, Deserialize, Clone, Default)]
 pub struct SessionMeta {
-    pub id: Uuid,
+    pub id: ConversationId,
     pub timestamp: String,
     pub instructions: Option<String>,
 }
@@ -55,7 +57,7 @@ pub struct SavedSession {
     pub items: Vec<ResponseItem>,
     #[serde(default)]
     pub state: SessionStateSnapshot,
-    pub session_id: Uuid,
+    pub session_id: ConversationId,
 }
 
 /// Records all [`ResponseItem`]s for a session and flushes them to disk after
@@ -72,12 +74,36 @@ pub struct RolloutRecorder {
     tx: Sender<RolloutCmd>,
 }
 
+#[derive(Clone)]
+pub enum RolloutRecorderParams {
+    Create {
+        conversation_id: ConversationId,
+        instructions: Option<String>,
+    },
+    Resume {
+        path: PathBuf,
+    },
+}
+
 enum RolloutCmd {
     AddItems(Vec<ResponseItem>),
     UpdateState(SessionStateSnapshot),
     Shutdown { ack: oneshot::Sender<()> },
 }
 
+impl RolloutRecorderParams {
+    pub fn new(conversation_id: ConversationId, instructions: Option<String>) -> Self {
+        Self::Create {
+            conversation_id,
+            instructions,
+        }
+    }
+
+    pub fn resume(path: PathBuf) -> Self {
+        Self::Resume { path }
+    }
+}
+
 impl RolloutRecorder {
     #[allow(dead_code)]
     /// List conversations (rollout files) under the provided Codex home directory.
@@ -92,24 +118,43 @@ impl RolloutRecorder {
     /// Attempt to create a new [`RolloutRecorder`]. If the sessions directory
     /// cannot be created or the rollout file cannot be opened we return the
     /// error so the caller can decide whether to disable persistence.
-    pub async fn new(
-        config: &Config,
-        uuid: Uuid,
-        instructions: Option<String>,
-    ) -> std::io::Result<Self> {
-        let LogFileInfo {
-            file,
-            session_id,
-            timestamp,
-        } = create_log_file(config, uuid)?;
+    pub async fn new(config: &Config, params: RolloutRecorderParams) -> std::io::Result<Self> {
+        let (file, meta) = match params {
+            RolloutRecorderParams::Create {
+                conversation_id,
+                instructions,
+            } => {
+                let LogFileInfo {
+                    file,
+                    conversation_id: session_id,
+                    timestamp,
+                } = create_log_file(config, conversation_id)?;
 
-        let timestamp_format: &[FormatItem] = format_description!(
-            "[year]-[month]-[day]T[hour]:[minute]:[second].[subsecond digits:3]Z"
-        );
-        let timestamp = timestamp
-            .to_offset(time::UtcOffset::UTC)
-            .format(timestamp_format)
-            .map_err(|e| IoError::other(format!("failed to format timestamp: {e}")))?;
+                let timestamp_format: &[FormatItem] = format_description!(
+                    "[year]-[month]-[day]T[hour]:[minute]:[second].[subsecond digits:3]Z"
+                );
+                let timestamp = timestamp
+                    .to_offset(time::UtcOffset::UTC)
+                    .format(timestamp_format)
+                    .map_err(|e| IoError::other(format!("failed to format timestamp: {e}")))?;
+
+                (
+                    tokio::fs::File::from_std(file),
+                    Some(SessionMeta {
+                        timestamp,
+                        id: session_id,
+                        instructions,
+                    }),
+                )
+            }
+            RolloutRecorderParams::Resume { path } => (
+                tokio::fs::OpenOptions::new()
+                    .append(true)
+                    .open(path)
+                    .await?,
+                None,
+            ),
+        };
 
         // Clone the cwd for the spawned task to collect git info asynchronously
         let cwd = config.cwd.clone();
@@ -122,16 +167,7 @@ impl RolloutRecorder {
         // Spawn a Tokio task that owns the file handle and performs async
         // writes. Using `tokio::fs::File` keeps everything on the async I/O
         // driver instead of blocking the runtime.
-        tokio::task::spawn(rollout_writer(
-            tokio::fs::File::from_std(file),
-            rx,
-            Some(SessionMeta {
-                timestamp,
-                id: session_id,
-                instructions,
-            }),
-            cwd,
-        ));
+        tokio::task::spawn(rollout_writer(file, rx, meta, cwd));
 
         Ok(Self { tx })
     }
@@ -164,13 +200,28 @@ impl RolloutRecorder {
 
     pub async fn get_rollout_history(path: &Path) -> std::io::Result<InitialHistory> {
         info!("Resuming rollout from {path:?}");
+        tracing::error!("Resuming rollout from {path:?}");
         let text = tokio::fs::read_to_string(path).await?;
         let mut lines = text.lines();
-        let _ = lines
+        let first_line = lines
             .next()
             .ok_or_else(|| IoError::other("empty session file"))?;
-        let mut items = Vec::new();
+        let conversation_id = match serde_json::from_str::<SessionMeta>(first_line) {
+            Ok(rollout_session_meta) => {
+                tracing::error!(
+                    "Parsed conversation ID from rollout file: {:?}",
+                    rollout_session_meta.id
+                );
+                Some(rollout_session_meta.id)
+            }
+            Err(e) => {
+                return Err(IoError::other(format!(
+                    "failed to parse first line of rollout file as SessionMeta: {e}"
+                )));
+            }
+        };
 
+        let mut items = Vec::new();
         for line in lines {
             if line.trim().is_empty() {
                 continue;
@@ -198,12 +249,24 @@ impl RolloutRecorder {
             }
         }
 
-        info!("Resumed rollout successfully from {path:?}");
+        tracing::error!(
+            "Resumed rollout with {} items, conversation ID: {:?}",
+            items.len(),
+            conversation_id
+        );
+        let conversation_id = conversation_id
+            .ok_or_else(|| IoError::other("failed to parse conversation ID from rollout file"))?;
+
         if items.is_empty() {
-            Ok(InitialHistory::New)
-        } else {
-            Ok(InitialHistory::Resumed(items))
+            return Ok(InitialHistory::New);
         }
+
+        info!("Resumed rollout successfully from {path:?}");
+        Ok(InitialHistory::Resumed(ResumedHistory {
+            conversation_id,
+            history: items,
+            rollout_path: path.to_path_buf(),
+        }))
     }
 
     pub async fn shutdown(&self) -> std::io::Result<()> {
@@ -227,13 +290,16 @@ struct LogFileInfo {
     file: File,
 
     /// Session ID (also embedded in filename).
-    session_id: Uuid,
+    conversation_id: ConversationId,
 
     /// Timestamp for the start of the session.
     timestamp: OffsetDateTime,
 }
 
-fn create_log_file(config: &Config, session_id: Uuid) -> std::io::Result<LogFileInfo> {
+fn create_log_file(
+    config: &Config,
+    conversation_id: ConversationId,
+) -> std::io::Result<LogFileInfo> {
     // Resolve ~/.codex/sessions/YYYY/MM/DD and create it if missing.
     let timestamp = OffsetDateTime::now_local()
         .map_err(|e| IoError::other(format!("failed to get local time: {e}")))?;
@@ -252,7 +318,7 @@ fn create_log_file(config: &Config, session_id: Uuid) -> std::io::Result<LogFile
         .format(format)
         .map_err(|e| IoError::other(format!("failed to format timestamp: {e}")))?;
 
-    let filename = format!("rollout-{date_str}-{session_id}.jsonl");
+    let filename = format!("rollout-{date_str}-{conversation_id}.jsonl");
 
     let path = dir.join(filename);
     let file = std::fs::OpenOptions::new()
@@ -262,7 +328,7 @@ fn create_log_file(config: &Config, session_id: Uuid) -> std::io::Result<LogFile
 
     Ok(LogFileInfo {
         file,
-        session_id,
+        conversation_id,
         timestamp,
     })
 }
@@ -328,7 +394,7 @@ impl JsonlWriter {
     async fn write_line(&mut self, item: &impl serde::Serialize) -> std::io::Result<()> {
         let mut json = serde_json::to_string(item)?;
         json.push('\n');
-        let _ = self.file.write_all(json.as_bytes()).await;
+        self.file.write_all(json.as_bytes()).await?;
         self.file.flush().await?;
         Ok(())
     }

codex-rs/core/src/seatbelt_base_policy.sbpl

@@ -69,3 +69,8 @@
 ; Added on top of Chrome profile
 ; Needed for python multiprocessing on MacOS for the SemLock
 (allow ipc-posix-sem)
+
+; needed to look up user info, see https://crbug.com/792228
+(allow mach-lookup
+  (global-name "com.apple.system.opendirectoryd.libinfo")
+)

codex-rs/core/src/shell.rs

@@ -1,18 +1,36 @@
 use serde::Deserialize;
 use serde::Serialize;
 use shlex;
+use std::path::Path;
 use std::path::PathBuf;
+use std::sync::Arc;
+use tracing::trace;
+use uuid::Uuid;
 
-#[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
-pub struct ZshShell {
-    shell_path: String,
-    zshrc_path: String,
+#[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
+/// This structure cannot derive Clone or this will break the Drop implementation.
+pub struct ShellSnapshot {
+    pub(crate) path: PathBuf,
+}
+
+impl ShellSnapshot {
+    pub fn new(path: PathBuf) -> Self {
+        Self { path }
+    }
+}
+
+impl Drop for ShellSnapshot {
+    fn drop(&mut self) {
+        delete_shell_snapshot(&self.path);
+    }
 }
 
 #[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
-pub struct BashShell {
-    shell_path: String,
-    bashrc_path: String,
+pub struct PosixShell {
+    pub(crate) shell_path: String,
+    pub(crate) rc_path: String,
+    #[serde(skip_serializing, skip_deserializing)]
+    pub(crate) shell_snapshot: Option<Arc<ShellSnapshot>>,
 }
 
 #[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
@@ -23,8 +41,7 @@ pub struct PowerShellConfig {
 
 #[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
 pub enum Shell {
-    Zsh(ZshShell),
-    Bash(BashShell),
+    Posix(PosixShell),
     PowerShell(PowerShellConfig),
     Unknown,
 }
@@ -32,11 +49,27 @@ pub enum Shell {
 impl Shell {
     pub fn format_default_shell_invocation(&self, command: Vec<String>) -> Option<Vec<String>> {
         match self {
-            Shell::Zsh(zsh) => {
-                format_shell_invocation_with_rc(&command, &zsh.shell_path, &zsh.zshrc_path)
-            }
-            Shell::Bash(bash) => {
-                format_shell_invocation_with_rc(&command, &bash.shell_path, &bash.bashrc_path)
+            Shell::Posix(shell) => {
+                let joined = strip_bash_lc(&command)
+                    .or_else(|| shlex::try_join(command.iter().map(|s| s.as_str())).ok())?;
+
+                let mut source_path = Path::new(&shell.rc_path);
+
+                let session_cmd = if let Some(shell_snapshot) = &shell.shell_snapshot
+                    && shell_snapshot.path.exists()
+                {
+                    source_path = shell_snapshot.path.as_path();
+                    "-c".to_string()
+                } else {
+                    "-lc".to_string()
+                };
+
+                let source_path_str = source_path.to_string_lossy().to_string();
+                let quoted_source_path = shlex::try_quote(&source_path_str).ok()?;
+                let rc_command =
+                    format!("[ -f {quoted_source_path} ] && . {quoted_source_path}; ({joined})");
+
+                Some(vec![shell.shell_path.clone(), session_cmd, rc_command])
             }
             Shell::PowerShell(ps) => {
                 // If model generated a bash command, prefer a detected bash fallback
@@ -89,33 +122,20 @@ impl Shell {
 
     pub fn name(&self) -> Option<String> {
         match self {
-            Shell::Zsh(zsh) => std::path::Path::new(&zsh.shell_path)
-                .file_name()
-                .map(|s| s.to_string_lossy().to_string()),
-            Shell::Bash(bash) => std::path::Path::new(&bash.shell_path)
+            Shell::Posix(shell) => Path::new(&shell.shell_path)
                 .file_name()
                 .map(|s| s.to_string_lossy().to_string()),
             Shell::PowerShell(ps) => Some(ps.exe.clone()),
             Shell::Unknown => None,
         }
     }
-}
 
-fn format_shell_invocation_with_rc(
-    command: &Vec<String>,
-    shell_path: &str,
-    rc_path: &str,
-) -> Option<Vec<String>> {
-    let joined = strip_bash_lc(command)
-        .or_else(|| shlex::try_join(command.iter().map(|s| s.as_str())).ok())?;
-
-    let rc_command = if std::path::Path::new(rc_path).exists() {
-        format!("source {rc_path} && ({joined})")
-    } else {
-        joined
-    };
-
-    Some(vec![shell_path.to_string(), "-lc".to_string(), rc_command])
+    pub fn get_snapshot(&self) -> Option<Arc<ShellSnapshot>> {
+        match self {
+            Shell::Posix(shell) => shell.shell_snapshot.clone(),
+            _ => None,
+        }
+    }
 }
 
 fn strip_bash_lc(command: &Vec<String>) -> Option<String> {
@@ -132,7 +152,7 @@ fn strip_bash_lc(command: &Vec<String>) -> Option<String> {
 }
 
 #[cfg(unix)]
-fn detect_default_user_shell() -> Shell {
+async fn detect_default_user_shell(session_id: Uuid, codex_home: &Path) -> Shell {
     use libc::getpwuid;
     use libc::getuid;
     use std::ffi::CStr;
@@ -147,31 +167,45 @@ fn detect_default_user_shell() -> Shell {
                 .into_owned();
             let home_path = CStr::from_ptr((*pw).pw_dir).to_string_lossy().into_owned();
 
-            if shell_path.ends_with("/zsh") {
-                return Shell::Zsh(ZshShell {
-                    shell_path,
-                    zshrc_path: format!("{home_path}/.zshrc"),
-                });
-            }
+            let rc_path = if shell_path.ends_with("/zsh") {
+                format!("{home_path}/.zshrc")
+            } else if shell_path.ends_with("/bash") {
+                format!("{home_path}/.bashrc")
+            } else {
+                return Shell::Unknown;
+            };
 
-            if shell_path.ends_with("/bash") {
-                return Shell::Bash(BashShell {
-                    shell_path,
-                    bashrc_path: format!("{home_path}/.bashrc"),
-                });
+            let snapshot_path = snapshots::ensure_posix_snapshot(
+                &shell_path,
+                &rc_path,
+                Path::new(&home_path),
+                codex_home,
+                session_id,
+            )
+            .await;
+            if snapshot_path.is_none() {
+                trace!("failed to prepare posix snapshot; using live profile");
             }
+            let shell_snapshot =
+                snapshot_path.map(|snapshot| Arc::new(ShellSnapshot::new(snapshot)));
+
+            return Shell::Posix(PosixShell {
+                shell_path,
+                rc_path,
+                shell_snapshot,
+            });
         }
     }
     Shell::Unknown
 }
 
 #[cfg(unix)]
-pub async fn default_user_shell() -> Shell {
-    detect_default_user_shell()
+pub async fn default_user_shell(session_id: Uuid, codex_home: &Path) -> Shell {
+    detect_default_user_shell(session_id, codex_home).await
 }
 
 #[cfg(target_os = "windows")]
-pub async fn default_user_shell() -> Shell {
+pub async fn default_user_shell(_session_id: Uuid, _codex_home: &Path) -> Shell {
     use tokio::process::Command;
 
     // Prefer PowerShell 7+ (`pwsh`) if available, otherwise fall back to Windows PowerShell.
@@ -211,42 +245,158 @@ pub async fn default_user_shell() -> Shell {
 }
 
 #[cfg(all(not(target_os = "windows"), not(unix)))]
-pub async fn default_user_shell() -> Shell {
+pub async fn default_user_shell(_session_id: Uuid, _codex_home: &Path) -> Shell {
     Shell::Unknown
 }
 
+#[cfg(unix)]
+mod snapshots {
+    use super::*;
+
+    fn zsh_profile_paths(home: &Path) -> Vec<PathBuf> {
+        [".zshenv", ".zprofile", ".zshrc", ".zlogin"]
+            .into_iter()
+            .map(|name| home.join(name))
+            .collect()
+    }
+
+    fn posix_profile_source_script(home: &Path) -> String {
+        zsh_profile_paths(home)
+            .into_iter()
+            .map(|profile| {
+                let profile_string = profile.to_string_lossy().into_owned();
+                let quoted = shlex::try_quote(&profile_string)
+                    .map(|cow| cow.into_owned())
+                    .unwrap_or(profile_string.clone());
+
+                format!("[ -f {quoted} ] && . {quoted}")
+            })
+            .collect::<Vec<_>>()
+            .join("; ")
+    }
+
+    pub(crate) async fn ensure_posix_snapshot(
+        shell_path: &str,
+        rc_path: &str,
+        home: &Path,
+        codex_home: &Path,
+        session_id: Uuid,
+    ) -> Option<PathBuf> {
+        let snapshot_path = codex_home.join(format!("shell_snapshots/snapshot_{session_id}.zsh"));
+
+        // Check if an update in the profile requires to re-generate the snapshot.
+        let snapshot_is_stale = async {
+            let snapshot_metadata = tokio::fs::metadata(&snapshot_path).await.ok()?;
+            let snapshot_modified = snapshot_metadata.modified().ok()?;
+
+            for profile in zsh_profile_paths(home) {
+                let Ok(profile_metadata) = tokio::fs::metadata(&profile).await else {
+                    continue;
+                };
+
+                let Ok(profile_modified) = profile_metadata.modified() else {
+                    return Some(true);
+                };
+
+                if profile_modified > snapshot_modified {
+                    return Some(true);
+                }
+            }
+
+            Some(false)
+        }
+        .await
+        .unwrap_or(true);
+
+        if !snapshot_is_stale {
+            return Some(snapshot_path);
+        }
+
+        match regenerate_posix_snapshot(shell_path, rc_path, home, &snapshot_path).await {
+            Ok(()) => Some(snapshot_path),
+            Err(err) => {
+                tracing::warn!("failed to generate posix snapshot: {err}");
+                None
+            }
+        }
+    }
+
+    async fn regenerate_posix_snapshot(
+        shell_path: &str,
+        rc_path: &str,
+        home: &Path,
+        snapshot_path: &Path,
+    ) -> std::io::Result<()> {
+        // Use `emulate -L sh` instead of `set -o posix` so we work on zsh builds
+        // that disable that option. Guard `alias -p` with `|| true` so the script
+        // keeps a zero exit status even if aliases are disabled.
+        let mut capture_script = String::new();
+        let profile_sources = posix_profile_source_script(home);
+        if !profile_sources.is_empty() {
+            capture_script.push_str(&format!("{profile_sources}; "));
+        }
+
+        let zshrc = home.join(rc_path);
+
+        capture_script.push_str(
+            &format!(". {}; setopt posixbuiltins; export -p; {{ alias | sed 's/^/alias /'; }} 2>/dev/null || true", zshrc.display()),
+        );
+        let output = tokio::process::Command::new(shell_path)
+            .arg("-lc")
+            .arg(capture_script)
+            .env("HOME", home)
+            .output()
+            .await?;
+
+        if !output.status.success() {
+            return Err(std::io::Error::other(format!(
+                "snapshot capture exited with status {}",
+                output.status
+            )));
+        }
+
+        let mut contents = String::from("# Generated by Codex. Do not edit.\n");
+
+        contents.push_str(&String::from_utf8_lossy(&output.stdout));
+        contents.push('\n');
+
+        if let Some(parent) = snapshot_path.parent() {
+            tokio::fs::create_dir_all(parent).await?;
+        }
+
+        let tmp_path = snapshot_path.with_extension("tmp");
+        tokio::fs::write(&tmp_path, contents).await?;
+
+        // Restrict the snapshot to user read/write so that environment variables or aliases
+        // that may contain secrets are not exposed to other users on the system.
+        use std::os::unix::fs::PermissionsExt;
+        let permissions = std::fs::Permissions::from_mode(0o600);
+        tokio::fs::set_permissions(&tmp_path, permissions).await?;
+
+        tokio::fs::rename(&tmp_path, snapshot_path).await?;
+        Ok(())
+    }
+}
+
+pub(crate) fn delete_shell_snapshot(path: &Path) {
+    if let Err(err) = std::fs::remove_file(path) {
+        trace!("failed to delete shell snapshot {path:?}: {err}");
+    }
+}
+
 #[cfg(test)]
 #[cfg(unix)]
 mod tests {
     use super::*;
-    use std::process::Command;
 
-    #[tokio::test]
-    async fn test_current_shell_detects_zsh() {
-        let shell = Command::new("sh")
-            .arg("-c")
-            .arg("echo $SHELL")
-            .output()
-            .unwrap();
-
-        let home = std::env::var("HOME").unwrap();
-        let shell_path = String::from_utf8_lossy(&shell.stdout).trim().to_string();
-        if shell_path.ends_with("/zsh") {
-            assert_eq!(
-                default_user_shell().await,
-                Shell::Zsh(ZshShell {
-                    shell_path: shell_path.to_string(),
-                    zshrc_path: format!("{home}/.zshrc",),
-                })
-            );
-        }
-    }
+    use std::path::PathBuf;
 
     #[tokio::test]
     async fn test_run_with_profile_zshrc_not_exists() {
-        let shell = Shell::Zsh(ZshShell {
+        let shell = Shell::Posix(PosixShell {
             shell_path: "/bin/zsh".to_string(),
-            zshrc_path: "/does/not/exist/.zshrc".to_string(),
+            rc_path: "/does/not/exist/.zshrc".to_string(),
+            shell_snapshot: None,
         });
         let actual_cmd = shell.format_default_shell_invocation(vec!["myecho".to_string()]);
         assert_eq!(
@@ -254,24 +404,7 @@ mod tests {
             Some(vec![
                 "/bin/zsh".to_string(),
                 "-lc".to_string(),
-                "myecho".to_string()
-            ])
-        );
-    }
-
-    #[tokio::test]
-    async fn test_run_with_profile_bashrc_not_exists() {
-        let shell = Shell::Bash(BashShell {
-            shell_path: "/bin/bash".to_string(),
-            bashrc_path: "/does/not/exist/.bashrc".to_string(),
-        });
-        let actual_cmd = shell.format_default_shell_invocation(vec!["myecho".to_string()]);
-        assert_eq!(
-            actual_cmd,
-            Some(vec![
-                "/bin/bash".to_string(),
-                "-lc".to_string(),
-                "myecho".to_string()
+                "[ -f /does/not/exist/.zshrc ] && . /does/not/exist/.zshrc; (myecho)".to_string(),
             ])
         );
     }
@@ -283,7 +416,11 @@ mod tests {
         let cases = vec![
             (
                 vec!["myecho"],
-                vec![shell_path, "-lc", "source BASHRC_PATH && (myecho)"],
+                vec![
+                    shell_path,
+                    "-lc",
+                    "[ -f BASHRC_PATH ] && . BASHRC_PATH; (myecho)",
+                ],
                 Some("It works!\n"),
             ),
             (
@@ -291,7 +428,7 @@ mod tests {
                 vec![
                     shell_path,
                     "-lc",
-                    "source BASHRC_PATH && (echo 'single' \"double\")",
+                    "[ -f BASHRC_PATH ] && . BASHRC_PATH; (echo 'single' \"double\")",
                 ],
                 Some("single double\n"),
             ),
@@ -317,9 +454,10 @@ mod tests {
                     "#,
             )
             .unwrap();
-            let shell = Shell::Bash(BashShell {
+            let shell = Shell::Posix(PosixShell {
                 shell_path: shell_path.to_string(),
-                bashrc_path: bashrc_path.to_str().unwrap().to_string(),
+                rc_path: bashrc_path.to_str().unwrap().to_string(),
+                shell_snapshot: None,
             });
 
             let actual_cmd = shell
@@ -369,6 +507,82 @@ mod tests {
 #[cfg(target_os = "macos")]
 mod macos_tests {
     use super::*;
+    use crate::shell::snapshots::ensure_posix_snapshot;
+
+    #[tokio::test]
+    async fn test_snapshot_generation_uses_session_id_and_cleanup() {
+        let shell_path = "/bin/zsh";
+
+        let temp_home = tempfile::tempdir().unwrap();
+        let codex_home = tempfile::tempdir().unwrap();
+        std::fs::write(
+            temp_home.path().join(".zshrc"),
+            "export SNAPSHOT_TEST_VAR=1\nalias snapshot_test_alias='echo hi'\n",
+        )
+        .unwrap();
+
+        let session_id = Uuid::new_v4();
+        let snapshot_path = ensure_posix_snapshot(
+            shell_path,
+            ".zshrc",
+            temp_home.path(),
+            codex_home.path(),
+            session_id,
+        )
+        .await
+        .expect("snapshot path");
+
+        let filename = snapshot_path
+            .file_name()
+            .unwrap()
+            .to_string_lossy()
+            .to_string();
+        assert!(filename.contains(&session_id.to_string()));
+        assert!(snapshot_path.exists());
+
+        let snapshot_path_second = ensure_posix_snapshot(
+            shell_path,
+            ".zshrc",
+            temp_home.path(),
+            codex_home.path(),
+            session_id,
+        )
+        .await
+        .expect("snapshot path");
+        assert_eq!(snapshot_path, snapshot_path_second);
+
+        let contents = std::fs::read_to_string(&snapshot_path).unwrap();
+        assert!(contents.contains("alias snapshot_test_alias='echo hi'"));
+        assert!(contents.contains("SNAPSHOT_TEST_VAR=1"));
+
+        delete_shell_snapshot(&snapshot_path);
+        assert!(!snapshot_path.exists());
+    }
+
+    #[test]
+    fn format_default_shell_invocation_prefers_snapshot_when_available() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let snapshot_path = temp_dir.path().join("snapshot.zsh");
+        std::fs::write(&snapshot_path, "export SNAPSHOT_READY=1").unwrap();
+
+        let shell = Shell::Posix(PosixShell {
+            shell_path: "/bin/zsh".to_string(),
+            rc_path: {
+                let path = temp_dir.path().join(".zshrc");
+                std::fs::write(&path, "# test zshrc").unwrap();
+                path.to_string_lossy().to_string()
+            },
+            shell_snapshot: Some(Arc::new(ShellSnapshot::new(snapshot_path.clone()))),
+        });
+
+        let invocation = shell.format_default_shell_invocation(vec!["echo".to_string()]);
+        let expected_command = vec!["/bin/zsh".to_string(), "-c".to_string(), {
+            let snapshot_path = snapshot_path.to_string_lossy();
+            format!("[ -f {snapshot_path} ] && . {snapshot_path}; (echo)")
+        }];
+
+        assert_eq!(invocation, Some(expected_command));
+    }
 
     #[tokio::test]
     async fn test_run_with_profile_escaping_and_execution() {
@@ -377,12 +591,20 @@ mod macos_tests {
         let cases = vec![
             (
                 vec!["myecho"],
-                vec![shell_path, "-lc", "source ZSHRC_PATH && (myecho)"],
+                vec![
+                    shell_path,
+                    "-lc",
+                    "[ -f ZSHRC_PATH ] && . ZSHRC_PATH; (myecho)",
+                ],
                 Some("It works!\n"),
             ),
             (
                 vec!["myecho"],
-                vec![shell_path, "-lc", "source ZSHRC_PATH && (myecho)"],
+                vec![
+                    shell_path,
+                    "-lc",
+                    "[ -f ZSHRC_PATH ] && . ZSHRC_PATH; (myecho)",
+                ],
                 Some("It works!\n"),
             ),
             (
@@ -390,7 +612,7 @@ mod macos_tests {
                 vec![
                     shell_path,
                     "-lc",
-                    "source ZSHRC_PATH && (bash -c \"echo 'single' \\\"double\\\"\")",
+                    "[ -f ZSHRC_PATH ] && . ZSHRC_PATH; (bash -c \"echo 'single' \\\"double\\\"\")",
                 ],
                 Some("single double\n"),
             ),
@@ -399,7 +621,7 @@ mod macos_tests {
                 vec![
                     shell_path,
                     "-lc",
-                    "source ZSHRC_PATH && (echo 'single' \"double\")",
+                    "[ -f ZSHRC_PATH ] && . ZSHRC_PATH; (echo 'single' \"double\")",
                 ],
                 Some("single double\n"),
             ),
@@ -426,9 +648,10 @@ mod macos_tests {
                     "#,
             )
             .unwrap();
-            let shell = Shell::Zsh(ZshShell {
+            let shell = Shell::Posix(PosixShell {
                 shell_path: shell_path.to_string(),
-                zshrc_path: zshrc_path.to_str().unwrap().to_string(),
+                rc_path: zshrc_path.to_str().unwrap().to_string(),
+                shell_snapshot: None,
             });
 
             let actual_cmd = shell

codex-rs/core/tests/chat_completions_payload.rs

@@ -11,11 +11,11 @@ use codex_core::ReasoningItemContent;
 use codex_core::ResponseItem;
 use codex_core::WireApi;
 use codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR;
+use codex_protocol::mcp_protocol::ConversationId;
 use core_test_support::load_default_config_for_test;
 use futures::StreamExt;
 use serde_json::Value;
 use tempfile::TempDir;
-use uuid::Uuid;
 use wiremock::Mock;
 use wiremock::MockServer;
 use wiremock::ResponseTemplate;
@@ -76,7 +76,7 @@ async fn run_request(input: Vec<ResponseItem>) -> Value {
         provider,
         effort,
         summary,
-        Uuid::new_v4(),
+        ConversationId::new(),
     );
 
     let mut prompt = Prompt::default();

codex-rs/core/tests/chat_completions_sse.rs

@@ -8,10 +8,10 @@ use codex_core::ResponseEvent;
 use codex_core::ResponseItem;
 use codex_core::WireApi;
 use codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR;
+use codex_protocol::mcp_protocol::ConversationId;
 use core_test_support::load_default_config_for_test;
 use futures::StreamExt;
 use tempfile::TempDir;
-use uuid::Uuid;
 use wiremock::Mock;
 use wiremock::MockServer;
 use wiremock::ResponseTemplate;
@@ -69,7 +69,7 @@ async fn run_stream(sse_body: &str) -> Vec<ResponseEvent> {
         provider,
         effort,
         summary,
-        Uuid::new_v4(),
+        ConversationId::new(),
     );
 
     let mut prompt = Prompt::default();

codex-rs/core/tests/suite/cli_stream.rs

@@ -388,8 +388,7 @@ async fn integration_creates_and_checks_session_file() {
         "No message found in session file containing the marker"
     );
 
-    // Second run: resume should create a NEW session file that contains both old and new history.
-    let orig_len = content.lines().count();
+    // Second run: resume should update the existing file.
     let marker2 = format!("integration-resume-{}", Uuid::new_v4());
     let prompt2 = format!("echo {marker2}");
     // Cross‑platform safe resume override.  On Windows, backslashes in a TOML string must be escaped
@@ -449,8 +448,8 @@ async fn integration_creates_and_checks_session_file() {
     }
 
     let resumed_path = resumed_path.expect("No resumed session file found containing the marker2");
-    // Resume should have written to a new file, not the original one.
-    assert_ne!(
+    // Resume should write to the existing log file.
+    assert_eq!(
         resumed_path, path,
         "resume should create a new session file"
     );
@@ -464,14 +463,6 @@ async fn integration_creates_and_checks_session_file() {
         resumed_content.contains(&marker2),
         "resumed file missing resumed marker"
     );
-
-    // Original file should remain unchanged.
-    let content_after = std::fs::read_to_string(&path).unwrap();
-    assert_eq!(
-        content_after.lines().count(),
-        orig_len,
-        "original rollout file should not change on resume"
-    );
 }
 
 /// Integration test to verify git info is collected and recorded in session files.

codex-rs/core/tests/suite/client.rs

@@ -15,6 +15,7 @@ use core_test_support::wait_for_event;
 use serde_json::json;
 use std::io::Write;
 use tempfile::TempDir;
+use uuid::Uuid;
 use wiremock::Mock;
 use wiremock::MockServer;
 use wiremock::ResponseTemplate;
@@ -122,11 +123,10 @@ async fn resume_includes_initial_messages_and_sends_prior_items() {
     let tmpdir = TempDir::new().unwrap();
     let session_path = tmpdir.path().join("resume-session.jsonl");
     let mut f = std::fs::File::create(&session_path).unwrap();
-    // First line: meta (content not used by reader other than non-empty)
     writeln!(
         f,
         "{}",
-        serde_json::json!({"meta":"test","instructions":"be nice"})
+        json!({"meta":"test","instructions":"be nice", "id": Uuid::new_v4(), "timestamp": "2024-01-01T00:00:00Z"})
     )
     .unwrap();
 
@@ -202,7 +202,7 @@ async fn resume_includes_initial_messages_and_sends_prior_items() {
         .clone()
         .expect("expected initial messages for resumed session");
     let initial_json = serde_json::to_value(&initial_msgs).unwrap();
-    let expected_initial_json = serde_json::json!([
+    let expected_initial_json = json!([
         { "type": "user_message", "message": "resumed user message", "kind": "plain" },
         { "type": "agent_message", "message": "resumed assistant message" }
     ]);
@@ -221,7 +221,7 @@ async fn resume_includes_initial_messages_and_sends_prior_items() {
 
     let request = &server.received_requests().await.unwrap()[0];
     let request_body = request.body_json::<serde_json::Value>().unwrap();
-    let expected_input = serde_json::json!([
+    let expected_input = json!([
         {
             "type": "message",
             "role": "user",
@@ -242,7 +242,7 @@ async fn resume_includes_initial_messages_and_sends_prior_items() {
 }
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn includes_session_id_and_model_headers_in_request() {
+async fn includes_conversation_id_and_model_headers_in_request() {
     if std::env::var(CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR).is_ok() {
         println!(
             "Skipping test because it cannot execute when network is disabled in a Codex sandbox."
@@ -299,12 +299,12 @@ async fn includes_session_id_and_model_headers_in_request() {
 
     // get request from the server
     let request = &server.received_requests().await.unwrap()[0];
-    let request_session_id = request.headers.get("session_id").unwrap();
+    let request_conversation_id = request.headers.get("conversation_id").unwrap();
     let request_authorization = request.headers.get("authorization").unwrap();
     let request_originator = request.headers.get("originator").unwrap();
 
     assert_eq!(
-        request_session_id.to_str().unwrap(),
+        request_conversation_id.to_str().unwrap(),
         conversation_id.to_string()
     );
     assert_eq!(request_originator.to_str().unwrap(), "codex_cli_rs");
@@ -477,14 +477,14 @@ async fn chatgpt_auth_sends_correct_request() {
 
     // get request from the server
     let request = &server.received_requests().await.unwrap()[0];
-    let request_session_id = request.headers.get("session_id").unwrap();
+    let request_conversation_id = request.headers.get("conversation_id").unwrap();
     let request_authorization = request.headers.get("authorization").unwrap();
     let request_originator = request.headers.get("originator").unwrap();
     let request_chatgpt_account_id = request.headers.get("chatgpt-account-id").unwrap();
     let request_body = request.body_json::<serde_json::Value>().unwrap();
 
     assert_eq!(
-        request_session_id.to_str().unwrap(),
+        request_conversation_id.to_str().unwrap(),
         conversation_id.to_string()
     );
     assert_eq!(request_originator.to_str().unwrap(), "codex_cli_rs");
@@ -967,7 +967,7 @@ async fn history_dedupes_streamed_and_final_messages_across_turns() {
     assert_eq!(requests.len(), 3, "expected 3 requests (one per turn)");
 
     // Replace full-array compare with tail-only raw JSON compare using a single hard-coded value.
-    let r3_tail_expected = serde_json::json!([
+    let r3_tail_expected = json!([
         {
             "type": "message",
             "role": "user",

codex-rs/core/tests/suite/prompt_caching.rs

@@ -17,6 +17,7 @@ use core_test_support::load_default_config_for_test;
 use core_test_support::load_sse_fixture_with_id;
 use core_test_support::wait_for_event;
 use tempfile::TempDir;
+use uuid::Uuid;
 use wiremock::Mock;
 use wiremock::MockServer;
 use wiremock::ResponseTemplate;
@@ -269,7 +270,7 @@ async fn prefixes_context_and_instructions_once_and_consistently_across_requests
     let requests = server.received_requests().await.unwrap();
     assert_eq!(requests.len(), 2, "expected two POST requests");
 
-    let shell = default_user_shell().await;
+    let shell = default_user_shell(Uuid::new_v4(), codex_home.path()).await;
 
     let expected_env_text = format!(
         r#"<environment_context>

codex-rs/core/tests/suite/seatbelt.rs

@@ -159,6 +159,41 @@ async fn read_only_forbids_all_writes() {
         .await;
 }
 
+/// Verify that user lookups via `pwd.getpwuid(os.getuid())` work under the
+/// seatbelt sandbox. Prior to allowing the necessary mach‑lookup for
+/// OpenDirectory libinfo, this would fail with `KeyError: getpwuid(): uid not found`.
+#[tokio::test]
+async fn python_getpwuid_works_under_seatbelt() {
+    if std::env::var(CODEX_SANDBOX_ENV_VAR) == Ok("seatbelt".to_string()) {
+        eprintln!("{CODEX_SANDBOX_ENV_VAR} is set to 'seatbelt', skipping test.");
+        return;
+    }
+
+    // ReadOnly is sufficient here since we are only exercising user lookup.
+    let policy = SandboxPolicy::ReadOnly;
+
+    let mut child = spawn_command_under_seatbelt(
+        vec![
+            "python3".to_string(),
+            "-c".to_string(),
+            // Print the passwd struct; success implies lookup worked.
+            "import pwd, os; print(pwd.getpwuid(os.getuid()))".to_string(),
+        ],
+        &policy,
+        std::env::current_dir().expect("should be able to get current dir"),
+        StdioPolicy::RedirectForShellTool,
+        HashMap::new(),
+    )
+    .await
+    .expect("should be able to spawn python under seatbelt");
+
+    let status = child
+        .wait()
+        .await
+        .expect("should be able to wait for child process");
+    assert!(status.success(), "python exited with {status:?}");
+}
+
 #[expect(clippy::expect_used)]
 fn create_test_scenario(tmp: &TempDir) -> TestScenario {
     let repo_parent = tmp.path().to_path_buf();

codex-rs/core/tests/unexpected_status_no_retry.rs

@@ -0,0 +1,88 @@
+use std::time::Duration;
+
+use codex_core::ConversationManager;
+use codex_core::ModelProviderInfo;
+use codex_core::WireApi;
+use codex_core::protocol::EventMsg;
+use codex_core::protocol::InputItem;
+use codex_core::protocol::Op;
+use codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR;
+use codex_login::CodexAuth;
+use core_test_support::load_default_config_for_test;
+use core_test_support::wait_for_event_with_timeout;
+use serde_json::json;
+use tempfile::TempDir;
+use wiremock::Mock;
+use wiremock::MockServer;
+use wiremock::ResponseTemplate;
+use wiremock::matchers::method;
+use wiremock::matchers::path;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fails_fast_on_unexpected_status() {
+    if std::env::var(CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR).is_ok() {
+        println!(
+            "Skipping test because it cannot execute when network is disabled in a Codex sandbox."
+        );
+        return;
+    }
+
+    let server = MockServer::start().await;
+
+    let err_body = json!({
+        "error": {"message": "bad request"}
+    });
+    let tmpl = ResponseTemplate::new(400)
+        .insert_header("content-type", "application/json")
+        .set_body_string(err_body.to_string());
+
+    Mock::given(method("POST"))
+        .and(path("/v1/responses"))
+        .respond_with(tmpl)
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let provider = ModelProviderInfo {
+        name: "openai".into(),
+        base_url: Some(format!("{}/v1", server.uri())),
+        env_key: Some("PATH".into()),
+        env_key_instructions: None,
+        wire_api: WireApi::Responses,
+        query_params: None,
+        http_headers: None,
+        env_http_headers: None,
+        request_max_retries: Some(0),
+        stream_max_retries: Some(3),
+        stream_idle_timeout_ms: Some(2000),
+        requires_openai_auth: false,
+    };
+
+    let home = TempDir::new().unwrap();
+    let mut config = load_default_config_for_test(&home);
+    config.model_provider = provider;
+
+    let conversation_manager =
+        ConversationManager::with_auth(CodexAuth::from_api_key("Test API Key"));
+    let codex = conversation_manager
+        .new_conversation(config)
+        .await
+        .unwrap()
+        .conversation;
+
+    codex
+        .submit(Op::UserInput {
+            items: vec![InputItem::Text {
+                text: "hello".into(),
+            }],
+        })
+        .await
+        .unwrap();
+
+    wait_for_event_with_timeout(
+        &codex,
+        |ev| matches!(ev, EventMsg::Error(_)),
+        Duration::from_secs(5),
+    )
+    .await;
+}

codex-rs/exec/Cargo.toml

@@ -25,7 +25,6 @@ codex-common = { path = "../common", features = [
     "sandbox_summary",
 ] }
 codex-core = { path = "../core" }
-codex-login = { path = "../login" }
 codex-ollama = { path = "../ollama" }
 codex-protocol = { path = "../protocol" }
 owo-colors = "4.2.0"

codex-rs/exec/src/event_processor_with_human_output.rs

@@ -26,6 +26,7 @@ use codex_core::protocol::TurnAbortReason;
 use codex_core::protocol::TurnDiffEvent;
 use codex_core::protocol::WebSearchBeginEvent;
 use codex_core::protocol::WebSearchEndEvent;
+use codex_protocol::num_format::format_with_separators;
 use owo_colors::OwoColorize;
 use owo_colors::Style;
 use shlex::try_join;
@@ -189,8 +190,14 @@ impl EventProcessor for EventProcessorWithHumanOutput {
                 }
                 return CodexStatus::InitiateShutdown;
             }
-            EventMsg::TokenCount(token_usage) => {
-                ts_println!(self, "tokens used: {}", token_usage.blended_total());
+            EventMsg::TokenCount(ev) => {
+                if let Some(usage_info) = ev.info {
+                    ts_println!(
+                        self,
+                        "tokens used: {}",
+                        format_with_separators(usage_info.total_token_usage.blended_total())
+                    );
+                }
             }
             EventMsg::AgentMessageDelta(AgentMessageDeltaEvent { delta }) => {
                 if !self.answer_started {
@@ -511,7 +518,7 @@ impl EventProcessor for EventProcessorWithHumanOutput {
             }
             EventMsg::SessionConfigured(session_configured_event) => {
                 let SessionConfiguredEvent {
-                    session_id,
+                    session_id: conversation_id,
                     model,
                     history_log_id: _,
                     history_entry_count: _,
@@ -522,7 +529,7 @@ impl EventProcessor for EventProcessorWithHumanOutput {
                     self,
                     "{} {}",
                     "codex session".style(self.magenta).style(self.bold),
-                    session_id.to_string().style(self.dimmed)
+                    conversation_id.to_string().style(self.dimmed)
                 );
 
                 ts_println!(self, "model: {}", model);

codex-rs/linux-sandbox/Cargo.toml

@@ -15,9 +15,7 @@ path = "src/lib.rs"
 workspace = true
 
 [target.'cfg(target_os = "linux")'.dependencies]
-anyhow = "1"
 clap = { version = "4", features = ["derive"] }
-codex-common = { path = "../common", features = ["cli"] }
 codex-core = { path = "../core" }
 landlock = "0.4.1"
 libc = "0.2.175"

codex-rs/login/Cargo.toml

@@ -17,7 +17,6 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"
 tempfile = "3"
-thiserror = "2.0.16"
 tiny_http = "0.12"
 tokio = { version = "1", features = [
     "io-std",
@@ -31,5 +30,4 @@ urlencoding = "2.1"
 webbrowser = "1.0"
 
 [dev-dependencies]
-pretty_assertions = "1.4.1"
 tempfile = "3"

codex-rs/mcp-server/Cargo.toml

@@ -26,7 +26,6 @@ schemars = "0.8.22"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 shlex = "1.3.0"
-strum_macros = "0.27.2"
 tokio = { version = "1", features = [
     "io-std",
     "macros",
@@ -44,5 +43,4 @@ assert_cmd = "2"
 mcp_test_support = { path = "tests/common" }
 pretty_assertions = "1.4.1"
 tempfile = "3"
-tokio-test = "0.4"
 wiremock = "0.6"

codex-rs/mcp-server/src/codex_message_processor.rs

@@ -1,8 +1,3 @@
-use std::collections::HashMap;
-use std::path::PathBuf;
-use std::sync::Arc;
-use std::time::Duration;
-
 use crate::error_code::INTERNAL_ERROR_CODE;
 use crate::error_code::INVALID_REQUEST_ERROR_CODE;
 use crate::json_to_toml::json_to_toml;
@@ -14,11 +9,13 @@ use codex_core::ConversationManager;
 use codex_core::Cursor as RolloutCursor;
 use codex_core::NewConversation;
 use codex_core::RolloutRecorder;
+use codex_core::SessionMeta;
 use codex_core::auth::CLIENT_ID;
 use codex_core::config::Config;
 use codex_core::config::ConfigOverrides;
 use codex_core::config::ConfigToml;
 use codex_core::config::load_config_as_toml;
+use codex_core::default_client::get_codex_user_agent;
 use codex_core::exec::ExecParams;
 use codex_core::exec_env::create_env;
 use codex_core::get_platform_sandbox;
@@ -48,6 +45,7 @@ use codex_protocol::mcp_protocol::ExecArbitraryCommandResponse;
 use codex_protocol::mcp_protocol::ExecCommandApprovalParams;
 use codex_protocol::mcp_protocol::ExecCommandApprovalResponse;
 use codex_protocol::mcp_protocol::ExecOneOffCommandParams;
+use codex_protocol::mcp_protocol::GetUserAgentResponse;
 use codex_protocol::mcp_protocol::GetUserSavedConfigResponse;
 use codex_protocol::mcp_protocol::GitDiffToRemoteResponse;
 use codex_protocol::mcp_protocol::InputItem as WireInputItem;
@@ -68,8 +66,16 @@ use codex_protocol::mcp_protocol::SendUserTurnParams;
 use codex_protocol::mcp_protocol::SendUserTurnResponse;
 use codex_protocol::mcp_protocol::ServerNotification;
 use codex_protocol::mcp_protocol::UserSavedConfig;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::InputMessageKind;
+use codex_protocol::protocol::USER_MESSAGE_BEGIN;
 use mcp_types::JSONRPCErrorError;
 use mcp_types::RequestId;
+use std::collections::HashMap;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
 use tokio::sync::Mutex;
 use tokio::sync::oneshot;
 use tracing::error;
@@ -99,7 +105,7 @@ pub(crate) struct CodexMessageProcessor {
     conversation_listeners: HashMap<Uuid, oneshot::Sender<()>>,
     active_login: Arc<Mutex<Option<ActiveLogin>>>,
     // Queue of pending interrupt requests per conversation. We reply when TurnAborted arrives.
-    pending_interrupts: Arc<Mutex<HashMap<Uuid, Vec<RequestId>>>>,
+    pending_interrupts: Arc<Mutex<HashMap<ConversationId, Vec<RequestId>>>>,
 }
 
 impl CodexMessageProcessor {
@@ -169,6 +175,9 @@ impl CodexMessageProcessor {
             ClientRequest::GetUserSavedConfig { request_id } => {
                 self.get_user_saved_config(request_id).await;
             }
+            ClientRequest::GetUserAgent { request_id } => {
+                self.get_user_agent(request_id).await;
+            }
             ClientRequest::ExecOneOffCommand { request_id, params } => {
                 self.exec_one_off_command(request_id, params).await;
             }
@@ -384,6 +393,12 @@ impl CodexMessageProcessor {
         self.outgoing.send_response(request_id, response).await;
     }
 
+    async fn get_user_agent(&self, request_id: RequestId) {
+        let user_agent = get_codex_user_agent(Some(&self.config.responses_originator_header));
+        let response = GetUserAgentResponse { user_agent };
+        self.outgoing.send_response(request_id, response).await;
+    }
+
     async fn get_user_saved_config(&self, request_id: RequestId) {
         let toml_value = match load_config_as_toml(&self.config.codex_home) {
             Ok(val) => val,
@@ -511,7 +526,7 @@ impl CodexMessageProcessor {
                     ..
                 } = conversation_id;
                 let response = NewConversationResponse {
-                    conversation_id: ConversationId(conversation_id),
+                    conversation_id,
                     model: session_configured.model,
                 };
                 self.outgoing.send_response(request_id, response).await;
@@ -559,16 +574,11 @@ impl CodexMessageProcessor {
             }
         };
 
-        // Build summaries
-        let mut items: Vec<ConversationSummary> = Vec::new();
-        for it in page.items.into_iter() {
-            let (timestamp, preview) = extract_ts_and_preview(&it.head);
-            items.push(ConversationSummary {
-                path: it.path,
-                preview,
-                timestamp,
-            });
-        }
+        let items = page
+            .items
+            .into_iter()
+            .filter_map(|it| extract_conversation_summary(it.path, &it.head))
+            .collect();
 
         // Encode next_cursor as a plain string
         let next_cursor = match page.next_cursor {
@@ -622,19 +632,29 @@ impl CodexMessageProcessor {
                 session_configured,
                 ..
             }) => {
-                let event = codex_core::protocol::Event {
+                let event = Event {
                     id: "".to_string(),
-                    msg: codex_core::protocol::EventMsg::SessionConfigured(
-                        session_configured.clone(),
-                    ),
+                    msg: EventMsg::SessionConfigured(session_configured.clone()),
                 };
                 self.outgoing.send_event_as_notification(&event, None).await;
+                let initial_messages = session_configured.initial_messages.map(|msgs| {
+                    msgs.into_iter()
+                        .filter(|event| {
+                            // Don't send non-plain user messages (like user instructions
+                            // or environment context) back so they don't get rendered.
+                            if let EventMsg::UserMessage(user_message) = event {
+                                return matches!(user_message.kind, Some(InputMessageKind::Plain));
+                            }
+                            true
+                        })
+                        .collect()
+                });
 
                 // Reply with conversation id + model and initial messages (when present)
                 let response = codex_protocol::mcp_protocol::ResumeConversationResponse {
-                    conversation_id: ConversationId(conversation_id),
+                    conversation_id,
                     model: session_configured.model.clone(),
-                    initial_messages: session_configured.initial_messages.clone(),
+                    initial_messages,
                 };
                 self.outgoing.send_response(request_id, response).await;
             }
@@ -656,7 +676,7 @@ impl CodexMessageProcessor {
         } = params;
         let Ok(conversation) = self
             .conversation_manager
-            .get_conversation(conversation_id.0)
+            .get_conversation(conversation_id)
             .await
         else {
             let error = JSONRPCErrorError {
@@ -704,7 +724,7 @@ impl CodexMessageProcessor {
 
         let Ok(conversation) = self
             .conversation_manager
-            .get_conversation(conversation_id.0)
+            .get_conversation(conversation_id)
             .await
         else {
             let error = JSONRPCErrorError {
@@ -750,7 +770,7 @@ impl CodexMessageProcessor {
         let InterruptConversationParams { conversation_id } = params;
         let Ok(conversation) = self
             .conversation_manager
-            .get_conversation(conversation_id.0)
+            .get_conversation(conversation_id)
             .await
         else {
             let error = JSONRPCErrorError {
@@ -765,7 +785,7 @@ impl CodexMessageProcessor {
         // Record the pending interrupt so we can reply when TurnAborted arrives.
         {
             let mut map = self.pending_interrupts.lock().await;
-            map.entry(conversation_id.0).or_default().push(request_id);
+            map.entry(conversation_id).or_default().push(request_id);
         }
 
         // Submit the interrupt; we'll respond upon TurnAborted.
@@ -780,12 +800,12 @@ impl CodexMessageProcessor {
         let AddConversationListenerParams { conversation_id } = params;
         let Ok(conversation) = self
             .conversation_manager
-            .get_conversation(conversation_id.0)
+            .get_conversation(conversation_id)
             .await
         else {
             let error = JSONRPCErrorError {
                 code: INVALID_REQUEST_ERROR_CODE,
-                message: format!("conversation not found: {}", conversation_id.0),
+                message: format!("conversation not found: {conversation_id}"),
                 data: None,
             };
             self.outgoing.send_error(request_id, error).await;
@@ -822,11 +842,11 @@ impl CodexMessageProcessor {
                         let mut params = match serde_json::to_value(event.clone()) {
                             Ok(serde_json::Value::Object(map)) => map,
                             Ok(_) => {
-                                tracing::error!("event did not serialize to an object");
+                                error!("event did not serialize to an object");
                                 continue;
                             }
                             Err(err) => {
-                                tracing::error!("failed to serialize event: {err}");
+                                error!("failed to serialize event: {err}");
                                 continue;
                             }
                         };
@@ -898,7 +918,7 @@ async fn apply_bespoke_event_handling(
     conversation_id: ConversationId,
     conversation: Arc<CodexConversation>,
     outgoing: Arc<OutgoingMessageSender>,
-    pending_interrupts: Arc<Mutex<HashMap<Uuid, Vec<RequestId>>>>,
+    pending_interrupts: Arc<Mutex<HashMap<ConversationId, Vec<RequestId>>>>,
 ) {
     let Event { id: event_id, msg } = event;
     match msg {
@@ -951,7 +971,7 @@ async fn apply_bespoke_event_handling(
         EventMsg::TurnAborted(turn_aborted_event) => {
             let pending = {
                 let mut map = pending_interrupts.lock().await;
-                map.remove(&conversation_id.0).unwrap_or_default()
+                map.remove(&conversation_id).unwrap_or_default()
             };
             if !pending.is_empty() {
                 let response = InterruptConversationResponse {
@@ -1009,7 +1029,7 @@ fn derive_config_from_params(
 
 async fn on_patch_approval_response(
     event_id: String,
-    receiver: tokio::sync::oneshot::Receiver<mcp_types::Result>,
+    receiver: oneshot::Receiver<mcp_types::Result>,
     codex: Arc<CodexConversation>,
 ) {
     let response = receiver.await;
@@ -1051,14 +1071,14 @@ async fn on_patch_approval_response(
 
 async fn on_exec_approval_response(
     event_id: String,
-    receiver: tokio::sync::oneshot::Receiver<mcp_types::Result>,
+    receiver: oneshot::Receiver<mcp_types::Result>,
     conversation: Arc<CodexConversation>,
 ) {
     let response = receiver.await;
     let value = match response {
         Ok(value) => value,
         Err(err) => {
-            tracing::error!("request failed: {err:?}");
+            error!("request failed: {err:?}");
             return;
         }
     };
@@ -1085,37 +1105,99 @@ async fn on_exec_approval_response(
     }
 }
 
-fn extract_ts_and_preview(head: &[serde_json::Value]) -> (Option<String>, String) {
-    let ts = head
-        .first()
-        .and_then(|v| v.get("timestamp"))
-        .and_then(|v| v.as_str())
-        .map(|s| s.to_string());
-    let preview = find_first_user_text(head).unwrap_or_default();
-    (ts, preview)
+fn extract_conversation_summary(
+    path: PathBuf,
+    head: &[serde_json::Value],
+) -> Option<ConversationSummary> {
+    let session_meta = match head.first() {
+        Some(first_line) => match serde_json::from_value::<SessionMeta>(first_line.clone()) {
+            Ok(session_meta) => session_meta,
+            Err(..) => return None,
+        },
+        None => return None,
+    };
+
+    let preview = head
+        .iter()
+        .filter_map(|value| serde_json::from_value::<ResponseItem>(value.clone()).ok())
+        .find_map(|item| match item {
+            ResponseItem::Message { content, .. } => {
+                content.into_iter().find_map(|content| match content {
+                    ContentItem::InputText { text } => {
+                        match InputMessageKind::from(("user", &text)) {
+                            InputMessageKind::Plain => Some(text),
+                            _ => None,
+                        }
+                    }
+                    _ => None,
+                })
+            }
+            _ => None,
+        })?;
+
+    let preview = match preview.find(USER_MESSAGE_BEGIN) {
+        Some(idx) => preview[idx + USER_MESSAGE_BEGIN.len()..].trim(),
+        None => preview.as_str(),
+    };
+
+    let timestamp = if session_meta.timestamp.is_empty() {
+        None
+    } else {
+        Some(session_meta.timestamp.clone())
+    };
+
+    Some(ConversationSummary {
+        conversation_id: session_meta.id,
+        timestamp,
+        path,
+        preview: preview.to_string(),
+    })
 }
 
-fn find_first_user_text(head: &[serde_json::Value]) -> Option<String> {
-    use codex_core::protocol::InputMessageKind;
-    for v in head.iter() {
-        let t = v.get("type").and_then(|x| x.as_str()).unwrap_or("");
-        if t != "message" {
-            continue;
-        }
-        if v.get("role").and_then(|x| x.as_str()) != Some("user") {
-            continue;
-        }
-        if let Some(arr) = v.get("content").and_then(|c| c.as_array()) {
-            for c in arr.iter() {
-                if let (Some("input_text"), Some(txt)) =
-                    (c.get("type").and_then(|t| t.as_str()), c.get("text"))
-                    && let Some(s) = txt.as_str()
-                    && matches!(InputMessageKind::from(("user", s)), InputMessageKind::Plain)
-                {
-                    return Some(s.to_string());
-                }
-            }
-        }
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    #[test]
+    fn extract_conversation_summary_prefers_plain_user_messages() {
+        let conversation_id =
+            ConversationId(Uuid::parse_str("3f941c35-29b3-493b-b0a4-e25800d9aeb0").unwrap());
+        let timestamp = Some("2025-09-05T16:53:11.850Z".to_string());
+        let path = PathBuf::from("rollout.jsonl");
+
+        let head = vec![
+            json!({
+                "id": conversation_id.0,
+                "timestamp": timestamp,
+            }),
+            json!({
+                "type": "message",
+                "role": "user",
+                "content": [{
+                    "type": "input_text",
+                    "text": "<user_instructions>\n<AGENTS.md contents>\n</user_instructions>".to_string(),
+                }],
+            }),
+            json!({
+                "type": "message",
+                "role": "user",
+                "content": [{
+                    "type": "input_text",
+                    "text": format!("<prior context> {USER_MESSAGE_BEGIN}Count to 5"),
+                }],
+            }),
+        ];
+
+        let summary = extract_conversation_summary(path.clone(), &head).expect("summary");
+
+        assert_eq!(summary.conversation_id, conversation_id);
+        assert_eq!(
+            summary.timestamp,
+            Some("2025-09-05T16:53:11.850Z".to_string())
+        );
+        assert_eq!(summary.path, path);
+        assert_eq!(summary.preview, "Count to 5");
     }
-    None
 }

codex-rs/mcp-server/src/codex_tool_config.rs

@@ -181,8 +181,8 @@ impl CodexToolCallParam {
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct CodexToolCallReplyParam {
-    /// The *session id* for this conversation.
-    pub session_id: String,
+    /// The conversation id for this Codex session.
+    pub conversation_id: String,
 
     /// The *next user prompt* to continue the Codex conversation.
     pub prompt: String,
@@ -213,7 +213,8 @@ pub(crate) fn create_tool_for_codex_tool_call_reply_param() -> Tool {
         input_schema: tool_input_schema,
         output_schema: None,
         description: Some(
-            "Continue a Codex session by providing the session id and prompt.".to_string(),
+            "Continue a Codex conversation by providing the conversation id and prompt."
+                .to_string(),
         ),
         annotations: None,
     }
@@ -308,21 +309,21 @@ mod tests {
         let tool = create_tool_for_codex_tool_call_reply_param();
         let tool_json = serde_json::to_value(&tool).expect("tool serializes");
         let expected_tool_json = serde_json::json!({
-          "description": "Continue a Codex session by providing the session id and prompt.",
+          "description": "Continue a Codex conversation by providing the conversation id and prompt.",
           "inputSchema": {
             "properties": {
+              "conversationId": {
+                "description": "The conversation id for this Codex session.",
+                "type": "string"
+              },
               "prompt": {
                 "description": "The *next user prompt* to continue the Codex conversation.",
                 "type": "string"
               },
-              "sessionId": {
-                "description": "The *session id* for this conversation.",
-                "type": "string"
-              },
             },
             "required": [
+              "conversationId",
               "prompt",
-              "sessionId",
             ],
             "type": "object",
           },

codex-rs/mcp-server/src/codex_tool_runner.rs

@@ -5,6 +5,10 @@
 use std::collections::HashMap;
 use std::sync::Arc;
 
+use crate::exec_approval::handle_exec_approval_request;
+use crate::outgoing_message::OutgoingMessageSender;
+use crate::outgoing_message::OutgoingNotificationMeta;
+use crate::patch_approval::handle_patch_approval_request;
 use codex_core::CodexConversation;
 use codex_core::ConversationManager;
 use codex_core::NewConversation;
@@ -18,18 +22,13 @@ use codex_core::protocol::InputItem;
 use codex_core::protocol::Op;
 use codex_core::protocol::Submission;
 use codex_core::protocol::TaskCompleteEvent;
+use codex_protocol::mcp_protocol::ConversationId;
 use mcp_types::CallToolResult;
 use mcp_types::ContentBlock;
 use mcp_types::RequestId;
 use mcp_types::TextContent;
 use serde_json::json;
 use tokio::sync::Mutex;
-use uuid::Uuid;
-
-use crate::exec_approval::handle_exec_approval_request;
-use crate::outgoing_message::OutgoingMessageSender;
-use crate::outgoing_message::OutgoingNotificationMeta;
-use crate::patch_approval::handle_patch_approval_request;
 
 pub(crate) const INVALID_PARAMS_ERROR_CODE: i64 = -32602;
 
@@ -43,7 +42,7 @@ pub async fn run_codex_tool_session(
     config: CodexConfig,
     outgoing: Arc<OutgoingMessageSender>,
     conversation_manager: Arc<ConversationManager>,
-    running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, Uuid>>>,
+    running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, ConversationId>>>,
 ) {
     let NewConversation {
         conversation_id,
@@ -119,13 +118,13 @@ pub async fn run_codex_tool_session_reply(
     outgoing: Arc<OutgoingMessageSender>,
     request_id: RequestId,
     prompt: String,
-    running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, Uuid>>>,
-    session_id: Uuid,
+    running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, ConversationId>>>,
+    conversation_id: ConversationId,
 ) {
     running_requests_id_to_codex_uuid
         .lock()
         .await
-        .insert(request_id.clone(), session_id);
+        .insert(request_id.clone(), conversation_id);
     if let Err(e) = conversation
         .submit(Op::UserInput {
             items: vec![InputItem::Text { text: prompt }],
@@ -154,7 +153,7 @@ async fn run_codex_tool_session_inner(
     codex: Arc<CodexConversation>,
     outgoing: Arc<OutgoingMessageSender>,
     request_id: RequestId,
-    running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, Uuid>>>,
+    running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, ConversationId>>>,
 ) {
     let request_id_str = match &request_id {
         RequestId::String(s) => s.clone(),

codex-rs/mcp-server/src/message_processor.rs

@@ -9,6 +9,7 @@ use crate::codex_tool_config::create_tool_for_codex_tool_call_reply_param;
 use crate::error_code::INVALID_REQUEST_ERROR_CODE;
 use crate::outgoing_message::OutgoingMessageSender;
 use codex_protocol::mcp_protocol::ClientRequest;
+use codex_protocol::mcp_protocol::ConversationId;
 
 use codex_core::AuthManager;
 use codex_core::ConversationManager;
@@ -41,7 +42,7 @@ pub(crate) struct MessageProcessor {
     initialized: bool,
     codex_linux_sandbox_exe: Option<PathBuf>,
     conversation_manager: Arc<ConversationManager>,
-    running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, Uuid>>>,
+    running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, ConversationId>>>,
 }
 
 impl MessageProcessor {
@@ -436,7 +437,10 @@ impl MessageProcessor {
         tracing::info!("tools/call -> params: {:?}", arguments);
 
         // parse arguments
-        let CodexToolCallReplyParam { session_id, prompt } = match arguments {
+        let CodexToolCallReplyParam {
+            conversation_id,
+            prompt,
+        } = match arguments {
             Some(json_val) => match serde_json::from_value::<CodexToolCallReplyParam>(json_val) {
                 Ok(params) => params,
                 Err(e) => {
@@ -457,12 +461,12 @@ impl MessageProcessor {
             },
             None => {
                 tracing::error!(
-                    "Missing arguments for codex-reply tool-call; the `session_id` and `prompt` fields are required."
+                    "Missing arguments for codex-reply tool-call; the `conversation_id` and `prompt` fields are required."
                 );
                 let result = CallToolResult {
                     content: vec![ContentBlock::TextContent(TextContent {
                         r#type: "text".to_owned(),
-                        text: "Missing arguments for codex-reply tool-call; the `session_id` and `prompt` fields are required.".to_owned(),
+                        text: "Missing arguments for codex-reply tool-call; the `conversation_id` and `prompt` fields are required.".to_owned(),
                         annotations: None,
                     })],
                     is_error: Some(true),
@@ -473,14 +477,14 @@ impl MessageProcessor {
                 return;
             }
         };
-        let session_id = match Uuid::parse_str(&session_id) {
-            Ok(id) => id,
+        let conversation_id = match Uuid::parse_str(&conversation_id) {
+            Ok(id) => ConversationId::from(id),
             Err(e) => {
-                tracing::error!("Failed to parse session_id: {e}");
+                tracing::error!("Failed to parse conversation_id: {e}");
                 let result = CallToolResult {
                     content: vec![ContentBlock::TextContent(TextContent {
                         r#type: "text".to_owned(),
-                        text: format!("Failed to parse session_id: {e}"),
+                        text: format!("Failed to parse conversation_id: {e}"),
                         annotations: None,
                     })],
                     is_error: Some(true),
@@ -496,14 +500,18 @@ impl MessageProcessor {
         let outgoing = self.outgoing.clone();
         let running_requests_id_to_codex_uuid = self.running_requests_id_to_codex_uuid.clone();
 
-        let codex = match self.conversation_manager.get_conversation(session_id).await {
+        let codex = match self
+            .conversation_manager
+            .get_conversation(conversation_id)
+            .await
+        {
             Ok(c) => c,
             Err(_) => {
-                tracing::warn!("Session not found for session_id: {session_id}");
+                tracing::warn!("Session not found for conversation_id: {conversation_id}");
                 let result = CallToolResult {
                     content: vec![ContentBlock::TextContent(TextContent {
                         r#type: "text".to_owned(),
-                        text: format!("Session not found for session_id: {session_id}"),
+                        text: format!("Session not found for conversation_id: {conversation_id}"),
                         annotations: None,
                     })],
                     is_error: Some(true),
@@ -528,7 +536,7 @@ impl MessageProcessor {
                     request_id,
                     prompt,
                     running_requests_id_to_codex_uuid,
-                    session_id,
+                    conversation_id,
                 )
                 .await;
             }
@@ -564,24 +572,28 @@ impl MessageProcessor {
             RequestId::Integer(i) => i.to_string(),
         };
 
-        // Obtain the session_id while holding the first lock, then release.
-        let session_id = {
+        // Obtain the conversation id while holding the first lock, then release.
+        let conversation_id = {
             let map_guard = self.running_requests_id_to_codex_uuid.lock().await;
             match map_guard.get(&request_id) {
-                Some(id) => *id, // Uuid is Copy
+                Some(id) => *id,
                 None => {
                     tracing::warn!("Session not found for request_id: {}", request_id_string);
                     return;
                 }
             }
         };
-        tracing::info!("session_id: {session_id}");
+        tracing::info!("conversation_id: {conversation_id}");
 
         // Obtain the Codex conversation from the server.
-        let codex_arc = match self.conversation_manager.get_conversation(session_id).await {
+        let codex_arc = match self
+            .conversation_manager
+            .get_conversation(conversation_id)
+            .await
+        {
             Ok(c) => c,
             Err(_) => {
-                tracing::warn!("Session not found for session_id: {session_id}");
+                tracing::warn!("Session not found for conversation_id: {conversation_id}");
                 return;
             }
         };

codex-rs/mcp-server/src/outgoing_message.rs

@@ -258,6 +258,7 @@ pub(crate) struct OutgoingError {
 mod tests {
     use codex_core::protocol::EventMsg;
     use codex_core::protocol::SessionConfiguredEvent;
+    use codex_protocol::mcp_protocol::ConversationId;
     use codex_protocol::mcp_protocol::LoginChatGptCompleteNotification;
     use pretty_assertions::assert_eq;
     use serde_json::json;
@@ -270,10 +271,11 @@ mod tests {
         let (outgoing_tx, mut outgoing_rx) = mpsc::unbounded_channel::<OutgoingMessage>();
         let outgoing_message_sender = OutgoingMessageSender::new(outgoing_tx);
 
+        let conversation_id = ConversationId::new();
         let event = Event {
             id: "1".to_string(),
             msg: EventMsg::SessionConfigured(SessionConfiguredEvent {
-                session_id: Uuid::new_v4(),
+                session_id: conversation_id,
                 model: "gpt-4o".to_string(),
                 history_log_id: 1,
                 history_entry_count: 1000,
@@ -302,8 +304,9 @@ mod tests {
         let (outgoing_tx, mut outgoing_rx) = mpsc::unbounded_channel::<OutgoingMessage>();
         let outgoing_message_sender = OutgoingMessageSender::new(outgoing_tx);
 
+        let conversation_id = ConversationId::new();
         let session_configured_event = SessionConfiguredEvent {
-            session_id: Uuid::new_v4(),
+            session_id: conversation_id,
             model: "gpt-4o".to_string(),
             history_log_id: 1,
             history_entry_count: 1000,

codex-rs/mcp-server/tests/common/Cargo.toml

@@ -9,20 +9,16 @@ path = "lib.rs"
 [dependencies]
 anyhow = "1"
 assert_cmd = "2"
-codex-core = { path = "../../../core" }
 codex-mcp-server = { path = "../.." }
 codex-protocol = { path = "../../../protocol" }
 mcp-types = { path = "../../../mcp-types" }
 pretty_assertions = "1.4.1"
 serde = { version = "1" }
 serde_json = "1"
-shlex = "1.3.0"
-tempfile = "3"
 tokio = { version = "1", features = [
     "io-std",
     "macros",
     "process",
     "rt-multi-thread",
 ] }
-uuid = { version = "1", features = ["serde", "v4"] }
 wiremock = "0.6"

codex-rs/mcp-server/tests/common/mcp_process.rs

@@ -247,6 +247,11 @@ impl McpProcess {
         self.send_request("getUserSavedConfig", None).await
     }
 
+    /// Send a `getUserAgent` JSON-RPC request.
+    pub async fn send_get_user_agent_request(&mut self) -> anyhow::Result<i64> {
+        self.send_request("getUserAgent", None).await
+    }
+
     /// Send a `listConversations` JSON-RPC request.
     pub async fn send_list_conversations_request(
         &mut self,

codex-rs/mcp-server/tests/suite/list_resume.rs

@@ -142,7 +142,7 @@ async fn test_list_and_resume_conversations() {
     } = to_response::<ResumeConversationResponse>(resume_resp)
         .expect("deserialize resumeConversation response");
     // conversation id should be a valid UUID
-    let _ = uuid::Uuid::from_bytes(conversation_id.0.into_bytes());
+    let _: uuid::Uuid = conversation_id.into();
 }
 
 fn create_fake_rollout(codex_home: &Path, filename_ts: &str, meta_rfc3339: &str, preview: &str) {
@@ -157,7 +157,7 @@ fn create_fake_rollout(codex_home: &Path, filename_ts: &str, meta_rfc3339: &str,
     let file_path = dir.join(format!("rollout-{filename_ts}-{uuid}.jsonl"));
     let mut lines = Vec::new();
     // Meta line with timestamp
-    lines.push(json!({"timestamp": meta_rfc3339}).to_string());
+    lines.push(json!({"timestamp": meta_rfc3339, "id": uuid}).to_string());
     // Minimal user message entry as a persisted response item
     lines.push(
         json!({

codex-rs/mcp-server/tests/suite/mod.rs

@@ -8,3 +8,4 @@ mod interrupt;
 mod list_resume;
 mod login;
 mod send_message;
+mod user_agent;

codex-rs/mcp-server/tests/suite/user_agent.rs

@@ -0,0 +1,45 @@
+use codex_core::default_client::DEFAULT_ORIGINATOR;
+use codex_core::default_client::get_codex_user_agent;
+use codex_protocol::mcp_protocol::GetUserAgentResponse;
+use mcp_test_support::McpProcess;
+use mcp_test_support::to_response;
+use mcp_types::JSONRPCResponse;
+use mcp_types::RequestId;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+use tokio::time::timeout;
+
+const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn get_user_agent_returns_current_codex_user_agent() {
+    let codex_home = TempDir::new().unwrap_or_else(|err| panic!("create tempdir: {err}"));
+
+    let mut mcp = McpProcess::new(codex_home.path())
+        .await
+        .expect("spawn mcp process");
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize())
+        .await
+        .expect("initialize timeout")
+        .expect("initialize request");
+
+    let request_id = mcp
+        .send_get_user_agent_request()
+        .await
+        .expect("send getUserAgent");
+    let response: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await
+    .expect("getUserAgent timeout")
+    .expect("getUserAgent response");
+
+    let received: GetUserAgentResponse =
+        to_response(response).expect("deserialize getUserAgent response");
+    let expected = GetUserAgentResponse {
+        user_agent: get_codex_user_agent(Some(DEFAULT_ORIGINATOR)),
+    };
+
+    assert_eq!(received, expected);
+}

codex-rs/mcp-types/Cargo.toml

@@ -9,4 +9,4 @@ workspace = true
 [dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-ts-rs = { version = "11", features = ["serde-json-impl"] }
+ts-rs = { version = "11", features = ["serde-json-impl", "no-serde-warnings"] }

codex-rs/ollama/Cargo.toml

@@ -24,9 +24,7 @@ tokio = { version = "1", features = [
     "rt-multi-thread",
     "signal",
 ] }
-toml = "0.9.5"
 tracing = { version = "0.1.41", features = ["log"] }
 wiremock = "0.6"
 
 [dev-dependencies]
-tempfile = "3"

codex-rs/protocol-ts/src/lib.rs

@@ -20,34 +20,25 @@ pub fn generate_ts(out_dir: &Path, prettier: Option<&Path>) -> Result<()> {
     codex_protocol::mcp_protocol::InputItem::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::ClientRequest::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::ServerRequest::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::NewConversationParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::NewConversationResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::AddConversationListenerParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::AddConversationSubscriptionResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::RemoveConversationListenerParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::RemoveConversationSubscriptionResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::SendUserMessageParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::SendUserMessageResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::SendUserTurnParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::SendUserTurnResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::InterruptConversationParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::InterruptConversationResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::GitDiffToRemoteParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::GitDiffToRemoteResponse::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::LoginChatGptResponse::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::LoginChatGptCompleteNotification::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::CancelLoginChatGptParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::CancelLoginChatGptResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::LogoutChatGptParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::LogoutChatGptResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::GetAuthStatusParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::GetAuthStatusResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::ApplyPatchApprovalParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::ApplyPatchApprovalResponse::export_all_to(out_dir)?;
-    codex_protocol::mcp_protocol::ExecCommandApprovalParams::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::ExecCommandApprovalResponse::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::GetUserSavedConfigResponse::export_all_to(out_dir)?;
+    codex_protocol::mcp_protocol::GetUserAgentResponse::export_all_to(out_dir)?;
     codex_protocol::mcp_protocol::ServerNotification::export_all_to(out_dir)?;
+    codex_protocol::mcp_protocol::ListConversationsResponse::export_all_to(out_dir)?;
+    codex_protocol::mcp_protocol::ResumeConversationResponse::export_all_to(out_dir)?;
 
     generate_index_ts(out_dir)?;
 

codex-rs/protocol/Cargo.toml

@@ -12,17 +12,23 @@ workspace = true
 
 [dependencies]
 base64 = "0.22.1"
+icu_decimal = "2.0.0"
+icu_locale_core = "2.0.0"
 mcp-types = { path = "../mcp-types" }
 mime_guess = "2.0.5"
 serde = { version = "1", features = ["derive"] }
-serde_bytes = "0.11"
 serde_json = "1"
 serde_with = { version = "3.14.0", features = ["macros", "base64"] }
 strum = "0.27.2"
 strum_macros = "0.27.2"
+sys-locale = "0.3.2"
 tracing = "0.1.41"
-ts-rs = { version = "11", features = ["uuid-impl", "serde-json-impl"] }
+ts-rs = { version = "11", features = ["uuid-impl", "serde-json-impl", "no-serde-warnings"] }
 uuid = { version = "1", features = ["serde", "v4"] }
 
 [dev-dependencies]
 pretty_assertions = "1.4.1"
+
+[package.metadata.cargo-shear]
+# Required because the not imported as strum_macros in non-nightly builds.
+ignored = ["strum"]

codex-rs/protocol/src/custom_prompts.rs

@@ -1,8 +1,9 @@
 use serde::Deserialize;
 use serde::Serialize;
 use std::path::PathBuf;
+use ts_rs::TS;
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+#[derive(Serialize, Deserialize, Debug, Clone, TS)]
 pub struct CustomPrompt {
     pub name: String,
     pub path: PathBuf,

codex-rs/protocol/src/lib.rs

@@ -3,6 +3,7 @@ pub mod custom_prompts;
 pub mod mcp_protocol;
 pub mod message_history;
 pub mod models;
+pub mod num_format;
 pub mod parse_command;
 pub mod plan_tool;
 pub mod protocol;

codex-rs/protocol/src/mcp_protocol.rs

@@ -19,16 +19,40 @@ use strum_macros::Display;
 use ts_rs::TS;
 use uuid::Uuid;
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, TS)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, TS, Hash)]
 #[ts(type = "string")]
 pub struct ConversationId(pub Uuid);
 
+impl ConversationId {
+    pub fn new() -> Self {
+        Self(Uuid::new_v4())
+    }
+}
+
+impl Default for ConversationId {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl Display for ConversationId {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{}", self.0)
     }
 }
 
+impl From<Uuid> for ConversationId {
+    fn from(value: Uuid) -> Self {
+        Self(value)
+    }
+}
+
+impl From<ConversationId> for Uuid {
+    fn from(value: ConversationId) -> Self {
+        value.0
+    }
+}
+
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, TS)]
 #[ts(type = "string")]
 pub struct GitSha(pub String);
@@ -119,6 +143,10 @@ pub enum ClientRequest {
         #[serde(rename = "id")]
         request_id: RequestId,
     },
+    GetUserAgent {
+        #[serde(rename = "id")]
+        request_id: RequestId,
+    },
     /// Execute a command (argv vector) under the server's sandbox.
     ExecOneOffCommand {
         #[serde(rename = "id")]
@@ -177,7 +205,7 @@ pub struct NewConversationResponse {
     pub model: String,
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+#[derive(Serialize, Deserialize, Debug, Clone, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct ResumeConversationResponse {
     pub conversation_id: ConversationId,
@@ -200,6 +228,7 @@ pub struct ListConversationsParams {
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct ConversationSummary {
+    pub conversation_id: ConversationId,
     pub path: PathBuf,
     pub preview: String,
     /// RFC3339 timestamp string for the session start, if available.
@@ -321,6 +350,12 @@ pub struct GetAuthStatusResponse {
     pub auth_token: Option<String>,
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, TS)]
+#[serde(rename_all = "camelCase")]
+pub struct GetUserAgentResponse {
+    pub user_agent: String,
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct GetUserSavedConfigResponse {
@@ -603,4 +638,10 @@ mod tests {
             serde_json::to_value(&request).unwrap(),
         );
     }
+
+    #[test]
+    fn test_conversation_id_default_is_not_zeroes() {
+        let id = ConversationId::default();
+        assert_ne!(id.0, Uuid::nil());
+    }
 }

codex-rs/protocol/src/message_history.rs

@@ -1,9 +1,10 @@
 use serde::Deserialize;
 use serde::Serialize;
+use ts_rs::TS;
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+#[derive(Serialize, Deserialize, Debug, Clone, TS)]
 pub struct HistoryEntry {
-    pub session_id: String,
+    pub conversation_id: String,
     pub ts: u64,
     pub text: String,
 }

codex-rs/protocol/src/models.rs

@@ -6,10 +6,11 @@ use serde::Deserialize;
 use serde::Deserializer;
 use serde::Serialize;
 use serde::ser::Serializer;
+use ts_rs::TS;
 
 use crate::protocol::InputItem;
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum ResponseInputItem {
     Message {
@@ -30,7 +31,7 @@ pub enum ResponseInputItem {
     },
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum ContentItem {
     InputText { text: String },
@@ -38,7 +39,7 @@ pub enum ContentItem {
     OutputText { text: String },
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum ResponseItem {
     Message {
@@ -159,7 +160,7 @@ impl From<ResponseInputItem> for ResponseItem {
     }
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 #[serde(rename_all = "snake_case")]
 pub enum LocalShellStatus {
     Completed,
@@ -167,13 +168,13 @@ pub enum LocalShellStatus {
     Incomplete,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum LocalShellAction {
     Exec(LocalShellExecAction),
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 pub struct LocalShellExecAction {
     pub command: Vec<String>,
     pub timeout_ms: Option<u64>,
@@ -182,7 +183,7 @@ pub struct LocalShellExecAction {
     pub user: Option<String>,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum WebSearchAction {
     Search {
@@ -192,13 +193,13 @@ pub enum WebSearchAction {
     Other,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum ReasoningItemReasoningSummary {
     SummaryText { text: String },
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum ReasoningItemContent {
     ReasoningText { text: String },
@@ -242,7 +243,7 @@ impl From<Vec<InputItem>> for ResponseInputItem {
 
 /// If the `name` of a `ResponseItem::FunctionCall` is either `container.exec`
 /// or shell`, the `arguments` field should deserialize to this struct.
-#[derive(Deserialize, Debug, Clone, PartialEq)]
+#[derive(Deserialize, Debug, Clone, PartialEq, TS)]
 pub struct ShellToolCallParams {
     pub command: Vec<String>,
     pub workdir: Option<String>,
@@ -256,7 +257,7 @@ pub struct ShellToolCallParams {
     pub justification: Option<String>,
 }
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, TS)]
 pub struct FunctionCallOutputPayload {
     pub content: String,
     pub success: Option<bool>,

codex-rs/protocol/src/num_format.rs

@@ -0,0 +1,98 @@
+use std::sync::OnceLock;
+
+use icu_decimal::DecimalFormatter;
+use icu_decimal::input::Decimal;
+use icu_decimal::options::DecimalFormatterOptions;
+use icu_locale_core::Locale;
+
+fn make_local_formatter() -> Option<DecimalFormatter> {
+    let loc: Locale = sys_locale::get_locale()?.parse().ok()?;
+    DecimalFormatter::try_new(loc.into(), DecimalFormatterOptions::default()).ok()
+}
+
+fn make_en_us_formatter() -> DecimalFormatter {
+    #![allow(clippy::expect_used)]
+    let loc: Locale = "en-US".parse().expect("en-US wasn't a valid locale");
+    DecimalFormatter::try_new(loc.into(), DecimalFormatterOptions::default())
+        .expect("en-US wasn't a valid locale")
+}
+
+fn formatter() -> &'static DecimalFormatter {
+    static FORMATTER: OnceLock<DecimalFormatter> = OnceLock::new();
+    FORMATTER.get_or_init(|| make_local_formatter().unwrap_or_else(make_en_us_formatter))
+}
+
+/// Format a u64 with locale-aware digit separators (e.g. "12345" -> "12,345"
+/// for en-US).
+pub fn format_with_separators(n: u64) -> String {
+    formatter().format(&Decimal::from(n)).to_string()
+}
+
+fn format_si_suffix_with_formatter(n: u64, formatter: &DecimalFormatter) -> String {
+    if n < 1000 {
+        return formatter.format(&Decimal::from(n)).to_string();
+    }
+
+    // Format `n / scale` with the requested number of fractional digits.
+    let format_scaled = |n: u64, scale: u64, frac_digits: u32| -> String {
+        let value = n as f64 / scale as f64;
+        let scaled: u64 = (value * 10f64.powi(frac_digits as i32)).round() as u64;
+        let mut dec = Decimal::from(scaled);
+        dec.multiply_pow10(-(frac_digits as i16));
+        formatter.format(&dec).to_string()
+    };
+
+    const UNITS: [(u64, &str); 3] = [(1_000, "K"), (1_000_000, "M"), (1_000_000_000, "G")];
+    let f = n as f64;
+    for &(scale, suffix) in &UNITS {
+        if (100.0 * f / scale as f64).round() < 1000.0 {
+            return format!("{}{}", format_scaled(n, scale, 2), suffix);
+        } else if (10.0 * f / scale as f64).round() < 1000.0 {
+            return format!("{}{}", format_scaled(n, scale, 1), suffix);
+        } else if (f / scale as f64).round() < 1000.0 {
+            return format!("{}{}", format_scaled(n, scale, 0), suffix);
+        }
+    }
+
+    // Above 1000G, keep whole‑G precision.
+    format!(
+        "{}G",
+        format_with_separators(((n as f64) / 1e9).round() as u64)
+    )
+}
+
+/// Format token counts to 3 significant figures, using base-10 SI suffixes.
+///
+/// Examples (en-US):
+///   - 999 -> "999"
+///   - 1200 -> "1.20K"
+///   - 123456789 -> "123M"
+pub fn format_si_suffix(n: u64) -> String {
+    format_si_suffix_with_formatter(n, formatter())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn kmg() {
+        let formatter = make_en_us_formatter();
+        let fmt = |n: u64| format_si_suffix_with_formatter(n, &formatter);
+        assert_eq!(fmt(0), "0");
+        assert_eq!(fmt(999), "999");
+        assert_eq!(fmt(1_000), "1.00K");
+        assert_eq!(fmt(1_200), "1.20K");
+        assert_eq!(fmt(10_000), "10.0K");
+        assert_eq!(fmt(100_000), "100K");
+        assert_eq!(fmt(999_500), "1.00M");
+        assert_eq!(fmt(1_000_000), "1.00M");
+        assert_eq!(fmt(1_234_000), "1.23M");
+        assert_eq!(fmt(12_345_678), "12.3M");
+        assert_eq!(fmt(999_950_000), "1.00G");
+        assert_eq!(fmt(1_000_000_000), "1.00G");
+        assert_eq!(fmt(1_234_000_000), "1.23G");
+        // Above 1000G we keep whole‑G precision (no higher unit supported here).
+        assert_eq!(fmt(1_234_000_000_000), "1,234G");
+    }
+}

codex-rs/protocol/src/parse_command.rs

@@ -1,7 +1,8 @@
 use serde::Deserialize;
 use serde::Serialize;
+use ts_rs::TS;
 
-#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum ParsedCommand {
     Read {

codex-rs/protocol/src/plan_tool.rs

@@ -1,8 +1,9 @@
 use serde::Deserialize;
 use serde::Serialize;
+use ts_rs::TS;
 
 // Types for the TODO tool arguments matching codex-vscode/todo-mcp/src/main.rs
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, TS)]
 #[serde(rename_all = "snake_case")]
 pub enum StepStatus {
     Pending,
@@ -10,14 +11,14 @@ pub enum StepStatus {
     Completed,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, TS)]
 #[serde(deny_unknown_fields)]
 pub struct PlanItemArg {
     pub step: String,
     pub status: StepStatus,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, TS)]
 #[serde(deny_unknown_fields)]
 pub struct UpdatePlanArgs {
     #[serde(default)]

codex-rs/protocol/src/protocol.rs

@@ -10,7 +10,15 @@ use std::path::PathBuf;
 use std::str::FromStr;
 use std::time::Duration;
 
+use crate::config_types::ReasoningEffort as ReasoningEffortConfig;
+use crate::config_types::ReasoningSummary as ReasoningSummaryConfig;
 use crate::custom_prompts::CustomPrompt;
+use crate::mcp_protocol::ConversationId;
+use crate::message_history::HistoryEntry;
+use crate::models::ResponseItem;
+use crate::num_format::format_with_separators;
+use crate::parse_command::ParsedCommand;
+use crate::plan_tool::UpdatePlanArgs;
 use mcp_types::CallToolResult;
 use mcp_types::Tool as McpTool;
 use serde::Deserialize;
@@ -18,14 +26,6 @@ use serde::Serialize;
 use serde_with::serde_as;
 use strum_macros::Display;
 use ts_rs::TS;
-use uuid::Uuid;
-
-use crate::config_types::ReasoningEffort as ReasoningEffortConfig;
-use crate::config_types::ReasoningSummary as ReasoningSummaryConfig;
-use crate::message_history::HistoryEntry;
-use crate::models::ResponseItem;
-use crate::parse_command::ParsedCommand;
-use crate::plan_tool::UpdatePlanArgs;
 
 /// Open/close tags for special user-input blocks. Used across crates to avoid
 /// duplicated hardcoded strings.
@@ -33,6 +33,7 @@ pub const USER_INSTRUCTIONS_OPEN_TAG: &str = "<user_instructions>";
 pub const USER_INSTRUCTIONS_CLOSE_TAG: &str = "</user_instructions>";
 pub const ENVIRONMENT_CONTEXT_OPEN_TAG: &str = "<environment_context>";
 pub const ENVIRONMENT_CONTEXT_CLOSE_TAG: &str = "</environment_context>";
+pub const USER_MESSAGE_BEGIN: &str = "## My request for Codex:";
 
 /// Submission Queue Entry - requests from user
 #[derive(Debug, Clone, Deserialize, Serialize)]
@@ -404,7 +405,7 @@ pub struct Event {
 }
 
 /// Response event from the agent
-#[derive(Debug, Clone, Deserialize, Serialize, Display)]
+#[derive(Debug, Clone, Deserialize, Serialize, Display, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 #[strum(serialize_all = "snake_case")]
 pub enum EventMsg {
@@ -417,9 +418,9 @@ pub enum EventMsg {
     /// Agent has completed all actions
     TaskComplete(TaskCompleteEvent),
 
-    /// Token count event, sent periodically to report the number of tokens
-    /// used in the current session.
-    TokenCount(TokenUsage),
+    /// Usage update for the current session, including totals and last turn.
+    /// Optional means unknown — UIs should not display when `None`.
+    TokenCount(TokenCountEvent),
 
     /// Agent text output message
     AgentMessage(AgentMessageEvent),
@@ -503,30 +504,72 @@ pub enum EventMsg {
 
 // Individual event payload types matching each `EventMsg` variant.
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct ErrorEvent {
     pub message: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct TaskCompleteEvent {
     pub last_agent_message: Option<String>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct TaskStartedEvent {
     pub model_context_window: Option<u64>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize, Default)]
+#[derive(Debug, Clone, Deserialize, Serialize, Default, TS)]
 pub struct TokenUsage {
     pub input_tokens: u64,
-    pub cached_input_tokens: Option<u64>,
+    pub cached_input_tokens: u64,
     pub output_tokens: u64,
-    pub reasoning_output_tokens: Option<u64>,
+    pub reasoning_output_tokens: u64,
     pub total_tokens: u64,
 }
 
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
+pub struct TokenUsageInfo {
+    pub total_token_usage: TokenUsage,
+    pub last_token_usage: TokenUsage,
+    pub model_context_window: Option<u64>,
+}
+
+impl TokenUsageInfo {
+    pub fn new_or_append(
+        info: &Option<TokenUsageInfo>,
+        last: &Option<TokenUsage>,
+        model_context_window: Option<u64>,
+    ) -> Option<Self> {
+        if info.is_none() && last.is_none() {
+            return None;
+        }
+
+        let mut info = match info {
+            Some(info) => info.clone(),
+            None => Self {
+                total_token_usage: TokenUsage::default(),
+                last_token_usage: TokenUsage::default(),
+                model_context_window,
+            },
+        };
+        if let Some(last) = last {
+            info.append_last_usage(last);
+        }
+        Some(info)
+    }
+
+    pub fn append_last_usage(&mut self, last: &TokenUsage) {
+        self.total_token_usage.add_assign(last);
+        self.last_token_usage = last.clone();
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
+pub struct TokenCountEvent {
+    pub info: Option<TokenUsageInfo>,
+}
+
 // Includes prompts, tools and space to call compact.
 const BASELINE_TOKENS: u64 = 12000;
 
@@ -536,7 +579,7 @@ impl TokenUsage {
     }
 
     pub fn cached_input(&self) -> u64 {
-        self.cached_input_tokens.unwrap_or(0)
+        self.cached_input_tokens
     }
 
     pub fn non_cached_input(&self) -> u64 {
@@ -554,7 +597,7 @@ impl TokenUsage {
     /// This will be off for the current turn and pending function calls.
     pub fn tokens_in_context_window(&self) -> u64 {
         self.total_tokens
-            .saturating_sub(self.reasoning_output_tokens.unwrap_or(0))
+            .saturating_sub(self.reasoning_output_tokens)
     }
 
     /// Estimate the remaining user-controllable percentage of the model's context window.
@@ -579,6 +622,15 @@ impl TokenUsage {
         let remaining = effective_window.saturating_sub(used);
         ((remaining as f32 / effective_window as f32) * 100.0).clamp(0.0, 100.0) as u8
     }
+
+    /// In-place element-wise sum of token counts.
+    pub fn add_assign(&mut self, other: &TokenUsage) {
+        self.input_tokens += other.input_tokens;
+        self.cached_input_tokens += other.cached_input_tokens;
+        self.output_tokens += other.output_tokens;
+        self.reasoning_output_tokens += other.reasoning_output_tokens;
+        self.total_tokens += other.total_tokens;
+    }
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize)]
@@ -595,31 +647,39 @@ impl From<TokenUsage> for FinalOutput {
 impl fmt::Display for FinalOutput {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let token_usage = &self.token_usage;
+
         write!(
             f,
             "Token usage: total={} input={}{} output={}{}",
-            token_usage.blended_total(),
-            token_usage.non_cached_input(),
+            format_with_separators(token_usage.blended_total()),
+            format_with_separators(token_usage.non_cached_input()),
             if token_usage.cached_input() > 0 {
-                format!(" (+ {} cached)", token_usage.cached_input())
+                format!(
+                    " (+ {} cached)",
+                    format_with_separators(token_usage.cached_input())
+                )
             } else {
                 String::new()
             },
-            token_usage.output_tokens,
-            token_usage
-                .reasoning_output_tokens
-                .map(|r| format!(" (reasoning {r})"))
-                .unwrap_or_default()
+            format_with_separators(token_usage.output_tokens),
+            if token_usage.reasoning_output_tokens > 0 {
+                format!(
+                    " (reasoning {})",
+                    format_with_separators(token_usage.reasoning_output_tokens)
+                )
+            } else {
+                String::new()
+            }
         )
     }
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct AgentMessageEvent {
     pub message: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 #[serde(rename_all = "snake_case")]
 pub enum InputMessageKind {
     /// Plain user text (default)
@@ -630,7 +690,7 @@ pub enum InputMessageKind {
     EnvironmentContext,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct UserMessageEvent {
     pub message: String,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -660,35 +720,35 @@ where
     }
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct AgentMessageDeltaEvent {
     pub delta: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct AgentReasoningEvent {
     pub text: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct AgentReasoningRawContentEvent {
     pub text: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct AgentReasoningRawContentDeltaEvent {
     pub delta: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct AgentReasoningSectionBreakEvent {}
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct AgentReasoningDeltaEvent {
     pub delta: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct McpInvocation {
     /// Name of the MCP server as defined in the config.
     pub server: String,
@@ -698,18 +758,19 @@ pub struct McpInvocation {
     pub arguments: Option<serde_json::Value>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct McpToolCallBeginEvent {
     /// Identifier so this can be paired with the McpToolCallEnd event.
     pub call_id: String,
     pub invocation: McpInvocation,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct McpToolCallEndEvent {
     /// Identifier for the corresponding McpToolCallBegin that finished.
     pub call_id: String,
     pub invocation: McpInvocation,
+    #[ts(type = "string")]
     pub duration: Duration,
     /// Result of the tool call. Note this could be an error.
     pub result: Result<CallToolResult, String>,
@@ -724,12 +785,12 @@ impl McpToolCallEndEvent {
     }
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct WebSearchBeginEvent {
     pub call_id: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct WebSearchEndEvent {
     pub call_id: String,
     pub query: String,
@@ -737,13 +798,13 @@ pub struct WebSearchEndEvent {
 
 /// Response payload for `Op::GetHistory` containing the current session's
 /// in-memory transcript.
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct ConversationHistoryResponseEvent {
-    pub conversation_id: Uuid,
+    pub conversation_id: ConversationId,
     pub entries: Vec<ResponseItem>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct ExecCommandBeginEvent {
     /// Identifier so this can be paired with the ExecCommandEnd event.
     pub call_id: String,
@@ -754,7 +815,7 @@ pub struct ExecCommandBeginEvent {
     pub parsed_cmd: Vec<ParsedCommand>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct ExecCommandEndEvent {
     /// Identifier for the ExecCommandBegin that finished.
     pub call_id: String,
@@ -768,12 +829,13 @@ pub struct ExecCommandEndEvent {
     /// The command's exit code.
     pub exit_code: i32,
     /// The duration of the command execution.
+    #[ts(type = "string")]
     pub duration: Duration,
     /// Formatted output from the command, as seen by the model.
     pub formatted_output: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, TS)]
 #[serde(rename_all = "snake_case")]
 pub enum ExecOutputStream {
     Stdout,
@@ -781,7 +843,7 @@ pub enum ExecOutputStream {
 }
 
 #[serde_as]
-#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, TS)]
 pub struct ExecCommandOutputDeltaEvent {
     /// Identifier for the ExecCommandBegin that produced this chunk.
     pub call_id: String,
@@ -789,10 +851,11 @@ pub struct ExecCommandOutputDeltaEvent {
     pub stream: ExecOutputStream,
     /// Raw bytes from the stream (may not be valid UTF-8).
     #[serde_as(as = "serde_with::base64::Base64")]
+    #[ts(type = "string")]
     pub chunk: Vec<u8>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct ExecApprovalRequestEvent {
     /// Identifier for the associated exec call, if available.
     pub call_id: String,
@@ -805,7 +868,7 @@ pub struct ExecApprovalRequestEvent {
     pub reason: Option<String>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct ApplyPatchApprovalRequestEvent {
     /// Responses API call id for the associated patch apply call, if available.
     pub call_id: String,
@@ -818,17 +881,17 @@ pub struct ApplyPatchApprovalRequestEvent {
     pub grant_root: Option<PathBuf>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct BackgroundEventEvent {
     pub message: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct StreamErrorEvent {
     pub message: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct PatchApplyBeginEvent {
     /// Identifier so this can be paired with the PatchApplyEnd event.
     pub call_id: String,
@@ -838,7 +901,7 @@ pub struct PatchApplyBeginEvent {
     pub changes: HashMap<PathBuf, FileChange>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct PatchApplyEndEvent {
     /// Identifier for the PatchApplyBegin that finished.
     pub call_id: String,
@@ -850,12 +913,12 @@ pub struct PatchApplyEndEvent {
     pub success: bool,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct TurnDiffEvent {
     pub unified_diff: String,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct GetHistoryEntryResponseEvent {
     pub offset: usize,
     pub log_id: u64,
@@ -865,22 +928,22 @@ pub struct GetHistoryEntryResponseEvent {
 }
 
 /// Response payload for `Op::ListMcpTools`.
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct McpListToolsResponseEvent {
     /// Fully qualified tool name -> tool definition.
     pub tools: std::collections::HashMap<String, McpTool>,
 }
 
 /// Response payload for `Op::ListCustomPrompts`.
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct ListCustomPromptsResponseEvent {
     pub custom_prompts: Vec<CustomPrompt>,
 }
 
-#[derive(Debug, Default, Clone, Deserialize, Serialize)]
+#[derive(Debug, Default, Clone, Deserialize, Serialize, TS)]
 pub struct SessionConfiguredEvent {
-    /// Unique id for this session.
-    pub session_id: Uuid,
+    /// Name left as session_id instead of conversation_id for backwards compatibility.
+    pub session_id: ConversationId,
 
     /// Tell the client what model is being queried.
     pub model: String,
@@ -934,7 +997,7 @@ pub enum FileChange {
     },
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct Chunk {
     /// 1-based line index of the first line in the original file
     pub orig_index: u32,
@@ -942,7 +1005,7 @@ pub struct Chunk {
     pub inserted_lines: Vec<String>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, TS)]
 pub struct TurnAbortedEvent {
     pub reason: TurnAbortReason,
 }
@@ -962,11 +1025,11 @@ mod tests {
     /// amount of nesting.
     #[test]
     fn serialize_event() {
-        let session_id: Uuid = uuid::uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");
+        let conversation_id = ConversationId(uuid::uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8"));
         let event = Event {
             id: "1234".to_string(),
             msg: EventMsg::SessionConfigured(SessionConfiguredEvent {
-                session_id,
+                session_id: conversation_id,
                 model: "codex-mini-latest".to_string(),
                 history_log_id: 0,
                 history_entry_count: 0,

codex-rs/scripts/create_github_release

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+
+import argparse
+import base64
+import json
+import re
+import subprocess
+import sys
+
+
+REPO = "openai/codex"
+BRANCH_REF = "heads/main"
+CARGO_TOML_PATH = "codex-rs/Cargo.toml"
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Publish a tagged Codex release.")
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="Print the version that would be used and exit before making changes.",
+    )
+
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument(
+        "--publish-alpha",
+        action="store_true",
+        help="Publish the next alpha release for the upcoming minor version.",
+    )
+    group.add_argument(
+        "--publish-release",
+        action="store_true",
+        help="Publish the next stable release by bumping the minor version.",
+    )
+    return parser.parse_args(argv[1:])
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+    try:
+        version = determine_version(args)
+        print(f"Publishing version {version}")
+        if args.dry_run:
+            return 0
+
+        print("Fetching branch head...")
+        base_commit = get_branch_head()
+        print(f"Base commit: {base_commit}")
+        print("Fetching commit tree...")
+        base_tree = get_commit_tree(base_commit)
+        print(f"Base tree: {base_tree}")
+        print("Fetching Cargo.toml...")
+        current_contents = fetch_file_contents(base_commit)
+        print("Updating version...")
+        updated_contents = replace_version(current_contents, version)
+        print("Creating blob...")
+        blob_sha = create_blob(updated_contents)
+        print(f"Blob SHA: {blob_sha}")
+        print("Creating tree...")
+        tree_sha = create_tree(base_tree, blob_sha)
+        print(f"Tree SHA: {tree_sha}")
+        print("Creating commit...")
+        commit_sha = create_commit(version, tree_sha, base_commit)
+        print(f"Commit SHA: {commit_sha}")
+        print("Creating tag...")
+        tag_sha = create_tag(version, commit_sha)
+        print(f"Tag SHA: {tag_sha}")
+        print("Creating tag ref...")
+        create_tag_ref(version, tag_sha)
+        print("Done.")
+    except ReleaseError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+class ReleaseError(RuntimeError):
+    pass
+
+
+def run_gh_api(endpoint: str, *, method: str = "GET", payload: dict | None = None) -> dict:
+    print(f"Running gh api {method} {endpoint}")
+    command = [
+        "gh",
+        "api",
+        endpoint,
+        "--method",
+        method,
+        "-H",
+        "Accept: application/vnd.github+json",
+    ]
+    json_payload = None
+    if payload is not None:
+        json_payload = json.dumps(payload)
+        print(f"Payload: {json_payload}")
+        command.extend(["-H", "Content-Type: application/json", "--input", "-"])
+    result = subprocess.run(command, text=True, capture_output=True, input=json_payload)
+    if result.returncode != 0:
+        message = result.stderr.strip() or result.stdout.strip() or "gh api call failed"
+        raise ReleaseError(message)
+    try:
+        return json.loads(result.stdout or "{}")
+    except json.JSONDecodeError as error:
+        raise ReleaseError("Failed to parse response from gh api.") from error
+
+
+def get_branch_head() -> str:
+    response = run_gh_api(f"/repos/{REPO}/git/refs/{BRANCH_REF}")
+    try:
+        return response["object"]["sha"]
+    except KeyError as error:
+        raise ReleaseError("Unable to determine branch head.") from error
+
+
+def get_commit_tree(commit_sha: str) -> str:
+    response = run_gh_api(f"/repos/{REPO}/git/commits/{commit_sha}")
+    try:
+        return response["tree"]["sha"]
+    except KeyError as error:
+        raise ReleaseError("Commit response missing tree SHA.") from error
+
+
+def fetch_file_contents(ref_sha: str) -> str:
+    response = run_gh_api(f"/repos/{REPO}/contents/{CARGO_TOML_PATH}?ref={ref_sha}")
+    try:
+        encoded_content = response["content"].replace("\n", "")
+        encoding = response.get("encoding", "")
+    except KeyError as error:
+        raise ReleaseError("Failed to fetch Cargo.toml contents.") from error
+
+    if encoding != "base64":
+        raise ReleaseError(f"Unexpected Cargo.toml encoding: {encoding}")
+
+    try:
+        return base64.b64decode(encoded_content).decode("utf-8")
+    except (ValueError, UnicodeDecodeError) as error:
+        raise ReleaseError("Failed to decode Cargo.toml contents.") from error
+
+
+def replace_version(contents: str, version: str) -> str:
+    updated, matches = re.subn(
+        r'^version = "[^"]+"', f'version = "{version}"', contents, count=1, flags=re.MULTILINE
+    )
+    if matches != 1:
+        raise ReleaseError("Unable to update version in Cargo.toml.")
+    return updated
+
+
+def create_blob(content: str) -> str:
+    response = run_gh_api(
+        f"/repos/{REPO}/git/blobs",
+        method="POST",
+        payload={"content": content, "encoding": "utf-8"},
+    )
+    try:
+        return response["sha"]
+    except KeyError as error:
+        raise ReleaseError("Blob creation response missing SHA.") from error
+
+
+def create_tree(base_tree_sha: str, blob_sha: str) -> str:
+    response = run_gh_api(
+        f"/repos/{REPO}/git/trees",
+        method="POST",
+        payload={
+            "base_tree": base_tree_sha,
+            "tree": [
+                {
+                    "path": CARGO_TOML_PATH,
+                    "mode": "100644",
+                    "type": "blob",
+                    "sha": blob_sha,
+                }
+            ],
+        },
+    )
+    try:
+        return response["sha"]
+    except KeyError as error:
+        raise ReleaseError("Tree creation response missing SHA.") from error
+
+
+def create_commit(version: str, tree_sha: str, parent_sha: str) -> str:
+    response = run_gh_api(
+        f"/repos/{REPO}/git/commits",
+        method="POST",
+        payload={
+            "message": f"Release {version}",
+            "tree": tree_sha,
+            "parents": [parent_sha],
+        },
+    )
+    try:
+        return response["sha"]
+    except KeyError as error:
+        raise ReleaseError("Commit creation response missing SHA.") from error
+
+
+def create_tag(version: str, commit_sha: str) -> str:
+    tag_name = f"rust-v{version}"
+    response = run_gh_api(
+        f"/repos/{REPO}/git/tags",
+        method="POST",
+        payload={
+            "tag": tag_name,
+            "message": f"Release {version}",
+            "object": commit_sha,
+            "type": "commit",
+        },
+    )
+    try:
+        return response["sha"]
+    except KeyError as error:
+        raise ReleaseError("Tag creation response missing SHA.") from error
+
+
+def create_tag_ref(version: str, tag_sha: str) -> None:
+    tag_ref = f"refs/tags/rust-v{version}"
+    run_gh_api(
+        f"/repos/{REPO}/git/refs",
+        method="POST",
+        payload={"ref": tag_ref, "sha": tag_sha},
+    )
+
+
+def determine_version(args: argparse.Namespace) -> str:
+    latest_version = get_latest_release_version()
+    major, minor, patch = parse_semver(latest_version)
+    next_minor_version = format_version(major, minor + 1, patch)
+
+    if args.publish_release:
+        return next_minor_version
+
+    alpha_prefix = f"{next_minor_version}-alpha."
+    releases = list_releases()
+    highest_alpha = 0
+    found_alpha = False
+    for release in releases:
+        tag = release.get("tag_name", "")
+        candidate = strip_tag_prefix(tag)
+        if candidate and candidate.startswith(alpha_prefix):
+            suffix = candidate[len(alpha_prefix) :]
+            try:
+                alpha_number = int(suffix)
+            except ValueError:
+                continue
+            highest_alpha = max(highest_alpha, alpha_number)
+            found_alpha = True
+
+    if found_alpha:
+        return f"{alpha_prefix}{highest_alpha + 1}"
+    return f"{alpha_prefix}1"
+
+
+def get_latest_release_version() -> str:
+    response = run_gh_api(f"/repos/{REPO}/releases/latest")
+    tag = response.get("tag_name")
+    version = strip_tag_prefix(tag)
+    if not version:
+        raise ReleaseError("Latest release tag has unexpected format.")
+    return version
+
+
+def list_releases() -> list[dict]:
+    response = run_gh_api(f"/repos/{REPO}/releases?per_page=100")
+    if not isinstance(response, list):
+        raise ReleaseError("Unexpected response when listing releases.")
+    return response
+
+
+def strip_tag_prefix(tag: str | None) -> str | None:
+    if not tag:
+        return None
+    prefix = "rust-v"
+    if not tag.startswith(prefix):
+        return None
+    return tag[len(prefix) :]
+
+
+def parse_semver(version: str) -> tuple[int, int, int]:
+    parts = version.split(".")
+    if len(parts) != 3:
+        raise ReleaseError(f"Unexpected version format: {version}")
+    try:
+        return int(parts[0]), int(parts[1]), int(parts[2])
+    except ValueError as error:
+        raise ReleaseError(f"Version components must be integers: {version}") from error
+
+
+def format_version(major: int, minor: int, patch: int) -> str:
+    return f"{major}.{minor}.{patch}"
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

codex-rs/scripts/create_github_release.sh

@@ -1,64 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-
-# By default, this script uses a version based on the current date and time.
-# If you want to specify a version, pass it as the first argument. Example:
-#
-#     ./scripts/create_github_release.sh 0.1.0-alpha.4
-#
-# The value will be used to update the `version` field in `Cargo.toml`.
-
-# Change to the root of the Cargo workspace.
-cd "$(dirname "${BASH_SOURCE[0]}")/.."
-
-# Cancel if there are uncommitted changes.
-if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
-  echo "ERROR: You have uncommitted or untracked changes." >&2
-  exit 1
-fi
-
-# Fail if in a detached HEAD state.
-CURRENT_BRANCH=$(git symbolic-ref --short -q HEAD 2>/dev/null || true)
-if [ -z "${CURRENT_BRANCH:-}" ]; then
-  echo "ERROR: Could not determine the current branch (detached HEAD?)." >&2
-  echo "       Please run this script from a checked-out branch." >&2
-  exit 1
-fi
-
-# Ensure we are on the 'main' branch before proceeding.
-if [ "${CURRENT_BRANCH}" != "main" ]; then
-  echo "ERROR: Releases must be created from the 'main' branch (current: '${CURRENT_BRANCH}')." >&2
-  echo "       Please switch to 'main' and try again." >&2
-  exit 1
-fi
-
-# Ensure the current local commit on 'main' is present on 'origin/main'.
-# This guarantees we only create releases from commits that are already on
-# the canonical repository (https://github.com/openai/codex).
-if ! git fetch --quiet origin main; then
-  echo "ERROR: Failed to fetch 'origin/main'. Ensure the 'origin' remote is configured and reachable." >&2
-  exit 1
-fi
-
-if ! git merge-base --is-ancestor HEAD origin/main; then
-  echo "ERROR: Your local 'main' HEAD commit is not present on 'origin/main'." >&2
-  echo "       Please push your commits first (git push origin main) or check out a commit on 'origin/main'." >&2
-  exit 1
-fi
-
-# Create a new branch for the release and make a commit with the new version.
-if [ $# -ge 1 ]; then
-  VERSION="$1"
-else
-  VERSION=$(printf '0.0.%d' "$(date +%y%m%d%H%M)")
-fi
-TAG="rust-v$VERSION"
-git checkout -b "$TAG"
-perl -i -pe "s/^version = \".*\"/version = \"$VERSION\"/" Cargo.toml
-git add Cargo.toml
-git commit -m "Release $VERSION"
-git tag -a "$TAG" -m "Release $VERSION"
-git push origin "refs/tags/$TAG"
-
-git checkout "$CURRENT_BRANCH"

codex-rs/tui/Cargo.toml

@@ -44,7 +44,7 @@ crossterm = { version = "0.28.1", features = [
     "event-stream",
 ] }
 diffy = "0.4.2"
-image = { version = "^0.25.6", default-features = false, features = [
+image = { version = "^0.25.8", default-features = false, features = [
     "jpeg",
     "png",
 ] }
@@ -59,9 +59,7 @@ ratatui = { version = "0.29.0", features = [
     "unstable-rendered-line-info",
     "unstable-widget-ref",
 ] }
-ratatui-image = "8.0.0"
 regex-lite = "0.1"
-reqwest = { version = "0.12", features = ["json"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = { version = "1", features = ["preserve_order"] }
 shlex = "1.3.0"
@@ -81,12 +79,10 @@ tokio-stream = "0.1.17"
 tracing = { version = "0.1.41", features = ["log"] }
 tracing-appender = "0.2.3"
 tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
-tui-input = "0.14.0"
 tui-markdown = "0.3.3"
 unicode-segmentation = "1.12.0"
 unicode-width = "0.1"
 url = "2"
-uuid = "1"
 pathdiff = "0.2"
 
 [target.'cfg(unix)'.dependencies]
@@ -100,7 +96,7 @@ arboard = "3"
 
 [dev-dependencies]
 chrono = { version = "0.4", features = ["serde"] }
-insta = "1.43.1"
+insta = "1.43.2"
 pretty_assertions = "1"
 rand = "0.9"
 vt100 = "0.16.2"

codex-rs/tui/src/app_backtrack.rs

@@ -4,23 +4,25 @@ use crate::pager_overlay::Overlay;
 use crate::tui;
 use crate::tui::TuiEvent;
 use codex_core::protocol::ConversationHistoryResponseEvent;
+use codex_protocol::mcp_protocol::ConversationId;
 use color_eyre::eyre::Result;
 use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
 use crossterm::event::KeyEventKind;
+
 /// Aggregates all backtrack-related state used by the App.
 #[derive(Default)]
 pub(crate) struct BacktrackState {
     /// True when Esc has primed backtrack mode in the main view.
     pub(crate) primed: bool,
     /// Session id of the base conversation to fork from.
-    pub(crate) base_id: Option<uuid::Uuid>,
+    pub(crate) base_id: Option<ConversationId>,
     /// Current step count (Nth last user message).
     pub(crate) count: usize,
     /// True when the transcript overlay is showing a backtrack preview.
     pub(crate) overlay_preview_active: bool,
     /// Pending fork request: (base_id, drop_count, prefill).
-    pub(crate) pending: Option<(uuid::Uuid, usize, String)>,
+    pub(crate) pending: Option<(ConversationId, usize, String)>,
 }
 
 impl App {
@@ -91,7 +93,7 @@ impl App {
     pub(crate) fn request_backtrack(
         &mut self,
         prefill: String,
-        base_id: uuid::Uuid,
+        base_id: ConversationId,
         drop_last_messages: usize,
     ) {
         self.backtrack.pending = Some((base_id, drop_last_messages, prefill));
@@ -135,7 +137,7 @@ impl App {
     fn prime_backtrack(&mut self) {
         self.backtrack.primed = true;
         self.backtrack.count = 0;
-        self.backtrack.base_id = self.chat_widget.session_id();
+        self.backtrack.base_id = self.chat_widget.conversation_id();
         self.chat_widget.show_esc_backtrack_hint();
     }
 
@@ -151,7 +153,7 @@ impl App {
     /// When overlay is already open, begin preview mode and select latest user message.
     fn begin_overlay_backtrack_preview(&mut self, tui: &mut tui::Tui) {
         self.backtrack.primed = true;
-        self.backtrack.base_id = self.chat_widget.session_id();
+        self.backtrack.base_id = self.chat_widget.conversation_id();
         self.backtrack.overlay_preview_active = true;
         let sel = self.compute_backtrack_selection(tui, 1);
         self.apply_backtrack_selection(sel);

codex-rs/tui/src/bottom_pane/bottom_pane_view.rs

@@ -19,7 +19,7 @@ pub(crate) trait BottomPaneView {
 
     /// Handle Ctrl-C while this view is active.
     fn on_ctrl_c(&mut self, _pane: &mut BottomPane) -> CancellationEvent {
-        CancellationEvent::Ignored
+        CancellationEvent::NotHandled
     }
 
     /// Return the desired height of the view.

codex-rs/tui/src/bottom_pane/chat_composer.rs

@@ -1,4 +1,5 @@
-use codex_core::protocol::TokenUsage;
+use codex_core::protocol::TokenUsageInfo;
+use codex_protocol::num_format::format_si_suffix;
 use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
 use crossterm::event::KeyEventKind;
@@ -63,12 +64,6 @@ struct AttachedImage {
     path: PathBuf,
 }
 
-struct TokenUsageInfo {
-    total_token_usage: TokenUsage,
-    last_token_usage: TokenUsage,
-    model_context_window: Option<u64>,
-}
-
 pub(crate) struct ChatComposer {
     textarea: TextArea,
     textarea_state: RefCell<TextAreaState>,
@@ -85,6 +80,7 @@ pub(crate) struct ChatComposer {
     has_focus: bool,
     attached_images: Vec<AttachedImage>,
     placeholder_text: String,
+    is_task_running: bool,
     // Non-bracketed paste burst tracker.
     paste_burst: PasteBurst,
     // When true, disables paste-burst logic and inserts characters immediately.
@@ -125,6 +121,7 @@ impl ChatComposer {
             has_focus: has_input_focus,
             attached_images: Vec::new(),
             placeholder_text,
+            is_task_running: false,
             paste_burst: PasteBurst::default(),
             disable_paste_burst: false,
             custom_prompts: Vec::new(),
@@ -166,17 +163,8 @@ impl ChatComposer {
     /// Update the cached *context-left* percentage and refresh the placeholder
     /// text. The UI relies on the placeholder to convey the remaining
     /// context when the composer is empty.
-    pub(crate) fn set_token_usage(
-        &mut self,
-        total_token_usage: TokenUsage,
-        last_token_usage: TokenUsage,
-        model_context_window: Option<u64>,
-    ) {
-        self.token_usage_info = Some(TokenUsageInfo {
-            total_token_usage,
-            last_token_usage,
-            model_context_window,
-        });
+    pub(crate) fn set_token_usage(&mut self, token_info: Option<TokenUsageInfo>) {
+        self.token_usage_info = token_info;
     }
 
     /// Record the history metadata advertised by `SessionConfiguredEvent` so
@@ -1220,6 +1208,10 @@ impl ChatComposer {
         self.has_focus = has_focus;
     }
 
+    pub fn set_task_running(&mut self, running: bool) {
+        self.is_task_running = running;
+    }
+
     pub(crate) fn set_esc_backtrack_hint(&mut self, show: bool) {
         self.esc_backtrack_hint = show;
     }
@@ -1244,11 +1236,16 @@ impl WidgetRef for ChatComposer {
             ActivePopup::None => {
                 let bottom_line_rect = popup_rect;
                 let mut hint: Vec<Span<'static>> = if self.ctrl_c_quit_hint {
+                    let ctrl_c_followup = if self.is_task_running {
+                        " to interrupt"
+                    } else {
+                        " to quit"
+                    };
                     vec![
                         " ".into(),
                         key_hint::ctrl('C'),
                         " again".into(),
-                        " to quit".into(),
+                        ctrl_c_followup.into(),
                     ]
                 } else {
                     let newline_hint_key = if self.use_shift_enter_hint {
@@ -1280,8 +1277,11 @@ impl WidgetRef for ChatComposer {
                     let token_usage = &token_usage_info.total_token_usage;
                     hint.push("   ".into());
                     hint.push(
-                        Span::from(format!("{} tokens used", token_usage.blended_total()))
-                            .style(Style::default().add_modifier(Modifier::DIM)),
+                        Span::from(format!(
+                            "{} tokens used",
+                            format_si_suffix(token_usage.blended_total())
+                        ))
+                        .style(Style::default().add_modifier(Modifier::DIM)),
                     );
                     let last_token_usage = &token_usage_info.last_token_usage;
                     if let Some(context_window) = token_usage_info.model_context_window {
@@ -1290,11 +1290,16 @@ impl WidgetRef for ChatComposer {
                         } else {
                             100
                         };
+                        let context_style = if percent_remaining < 20 {
+                            Style::default().fg(Color::Yellow)
+                        } else {
+                            Style::default().add_modifier(Modifier::DIM)
+                        };
                         hint.push("   ".into());
-                        hint.push(
-                            Span::from(format!("{percent_remaining}% context left"))
-                                .style(Style::default().add_modifier(Modifier::DIM)),
-                        );
+                        hint.push(Span::styled(
+                            format!("{percent_remaining}% context left"),
+                            context_style,
+                        ));
                     }
                 }
 

codex-rs/tui/src/bottom_pane/mod.rs

@@ -5,7 +5,7 @@ use crate::app_event_sender::AppEventSender;
 use crate::tui::FrameRequester;
 use crate::user_approval_widget::ApprovalRequest;
 use bottom_pane_view::BottomPaneView;
-use codex_core::protocol::TokenUsage;
+use codex_core::protocol::TokenUsageInfo;
 use codex_file_search::FileMatch;
 use crossterm::event::KeyEvent;
 use ratatui::buffer::Buffer;
@@ -30,8 +30,8 @@ mod textarea;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum CancellationEvent {
-    Ignored,
     Handled,
+    NotHandled,
 }
 
 pub(crate) use chat_composer::ChatComposer;
@@ -195,7 +195,15 @@ impl BottomPane {
     pub(crate) fn on_ctrl_c(&mut self) -> CancellationEvent {
         let mut view = match self.active_view.take() {
             Some(view) => view,
-            None => return CancellationEvent::Ignored,
+            None => {
+                return if self.composer_is_empty() {
+                    CancellationEvent::NotHandled
+                } else {
+                    self.set_composer_text(String::new());
+                    self.show_ctrl_c_quit_hint();
+                    CancellationEvent::Handled
+                };
+            }
         };
 
         let event = view.on_ctrl_c(self);
@@ -208,7 +216,7 @@ impl BottomPane {
                 }
                 self.show_ctrl_c_quit_hint();
             }
-            CancellationEvent::Ignored => {
+            CancellationEvent::NotHandled => {
                 self.active_view = Some(view);
             }
         }
@@ -267,6 +275,7 @@ impl BottomPane {
         }
     }
 
+    #[cfg(test)]
     pub(crate) fn ctrl_c_quit_hint_visible(&self) -> bool {
         self.ctrl_c_quit_hint
     }
@@ -289,6 +298,7 @@ impl BottomPane {
 
     pub fn set_task_running(&mut self, running: bool) {
         self.is_task_running = running;
+        self.composer.set_task_running(running);
 
         if running {
             if self.status.is_none() {
@@ -358,14 +368,8 @@ impl BottomPane {
 
     /// Update the *context-window remaining* indicator in the composer. This
     /// is forwarded directly to the underlying `ChatComposer`.
-    pub(crate) fn set_token_usage(
-        &mut self,
-        total_token_usage: TokenUsage,
-        last_token_usage: TokenUsage,
-        model_context_window: Option<u64>,
-    ) {
-        self.composer
-            .set_token_usage(total_token_usage, last_token_usage, model_context_window);
+    pub(crate) fn set_token_usage(&mut self, token_info: Option<TokenUsageInfo>) {
+        self.composer.set_token_usage(token_info);
         self.request_redraw();
     }
 
@@ -510,7 +514,7 @@ mod tests {
         let tx = AppEventSender::new(tx_raw);
         let mut pane = BottomPane::new(BottomPaneParams {
             app_event_tx: tx,
-            frame_requester: crate::tui::FrameRequester::test_dummy(),
+            frame_requester: FrameRequester::test_dummy(),
             has_input_focus: true,
             enhanced_keys_supported: false,
             placeholder_text: "Ask Codex to do anything".to_string(),
@@ -519,7 +523,7 @@ mod tests {
         pane.push_approval_request(exec_request());
         assert_eq!(CancellationEvent::Handled, pane.on_ctrl_c());
         assert!(pane.ctrl_c_quit_hint_visible());
-        assert_eq!(CancellationEvent::Ignored, pane.on_ctrl_c());
+        assert_eq!(CancellationEvent::NotHandled, pane.on_ctrl_c());
     }
 
     // live ring removed; related tests deleted.
@@ -530,7 +534,7 @@ mod tests {
         let tx = AppEventSender::new(tx_raw);
         let mut pane = BottomPane::new(BottomPaneParams {
             app_event_tx: tx,
-            frame_requester: crate::tui::FrameRequester::test_dummy(),
+            frame_requester: FrameRequester::test_dummy(),
             has_input_focus: true,
             enhanced_keys_supported: false,
             placeholder_text: "Ask Codex to do anything".to_string(),
@@ -561,7 +565,7 @@ mod tests {
         let tx = AppEventSender::new(tx_raw);
         let mut pane = BottomPane::new(BottomPaneParams {
             app_event_tx: tx.clone(),
-            frame_requester: crate::tui::FrameRequester::test_dummy(),
+            frame_requester: FrameRequester::test_dummy(),
             has_input_focus: true,
             enhanced_keys_supported: false,
             placeholder_text: "Ask Codex to do anything".to_string(),
@@ -589,7 +593,7 @@ mod tests {
 
         // Render and ensure the top row includes the Working header and a composer line below.
         // Give the animation thread a moment to tick.
-        std::thread::sleep(std::time::Duration::from_millis(120));
+        std::thread::sleep(Duration::from_millis(120));
         let area = Rect::new(0, 0, 40, 6);
         let mut buf = Buffer::empty(area);
         (&pane).render_ref(area, &mut buf);
@@ -629,7 +633,7 @@ mod tests {
         let tx = AppEventSender::new(tx_raw);
         let mut pane = BottomPane::new(BottomPaneParams {
             app_event_tx: tx,
-            frame_requester: crate::tui::FrameRequester::test_dummy(),
+            frame_requester: FrameRequester::test_dummy(),
             has_input_focus: true,
             enhanced_keys_supported: false,
             placeholder_text: "Ask Codex to do anything".to_string(),
@@ -660,7 +664,7 @@ mod tests {
         let tx = AppEventSender::new(tx_raw);
         let mut pane = BottomPane::new(BottomPaneParams {
             app_event_tx: tx,
-            frame_requester: crate::tui::FrameRequester::test_dummy(),
+            frame_requester: FrameRequester::test_dummy(),
             has_input_focus: true,
             enhanced_keys_supported: false,
             placeholder_text: "Ask Codex to do anything".to_string(),
@@ -711,7 +715,7 @@ mod tests {
         let tx = AppEventSender::new(tx_raw);
         let mut pane = BottomPane::new(BottomPaneParams {
             app_event_tx: tx,
-            frame_requester: crate::tui::FrameRequester::test_dummy(),
+            frame_requester: FrameRequester::test_dummy(),
             has_input_focus: true,
             enhanced_keys_supported: false,
             placeholder_text: "Ask Codex to do anything".to_string(),

codex-rs/tui/src/chatwidget.rs

@@ -29,6 +29,7 @@ use codex_core::protocol::PatchApplyBeginEvent;
 use codex_core::protocol::StreamErrorEvent;
 use codex_core::protocol::TaskCompleteEvent;
 use codex_core::protocol::TokenUsage;
+use codex_core::protocol::TokenUsageInfo;
 use codex_core::protocol::TurnAbortReason;
 use codex_core::protocol::TurnDiffEvent;
 use codex_core::protocol::UserMessageEvent;
@@ -84,7 +85,7 @@ use codex_core::protocol::AskForApproval;
 use codex_core::protocol::SandboxPolicy;
 use codex_core::protocol_config_types::ReasoningEffort as ReasoningEffortConfig;
 use codex_file_search::FileMatch;
-use uuid::Uuid;
+use codex_protocol::mcp_protocol::ConversationId;
 
 // Track information about an in-flight exec command.
 struct RunningCommand {
@@ -109,8 +110,7 @@ pub(crate) struct ChatWidget {
     active_exec_cell: Option<ExecCell>,
     config: Config,
     initial_user_message: Option<UserMessage>,
-    total_token_usage: TokenUsage,
-    last_token_usage: TokenUsage,
+    token_info: Option<TokenUsageInfo>,
     // Stream lifecycle controller
     stream: StreamController,
     running_commands: HashMap<String, RunningCommand>,
@@ -121,7 +121,7 @@ pub(crate) struct ChatWidget {
     reasoning_buffer: String,
     // Accumulates full reasoning content for transcript-only recording
     full_reasoning_buffer: String,
-    session_id: Option<Uuid>,
+    conversation_id: Option<ConversationId>,
     frame_requester: FrameRequester,
     // Whether to include the initial welcome banner on session configured
     show_welcome_banner: bool,
@@ -163,7 +163,7 @@ impl ChatWidget {
     fn on_session_configured(&mut self, event: codex_core::protocol::SessionConfiguredEvent) {
         self.bottom_pane
             .set_history_metadata(event.history_log_id, event.history_entry_count);
-        self.session_id = Some(event.session_id);
+        self.conversation_id = Some(event.session_id);
         let initial_messages = event.initial_messages.clone();
         if let Some(messages) = initial_messages {
             self.replay_initial_messages(messages);
@@ -259,16 +259,10 @@ impl ChatWidget {
         self.maybe_send_next_queued_input();
     }
 
-    fn on_token_count(&mut self, token_usage: TokenUsage) {
-        self.total_token_usage = add_token_usage(&self.total_token_usage, &token_usage);
-        self.last_token_usage = token_usage;
-        self.bottom_pane.set_token_usage(
-            self.total_token_usage.clone(),
-            self.last_token_usage.clone(),
-            self.config.model_context_window,
-        );
+    pub(crate) fn set_token_info(&mut self, info: Option<TokenUsageInfo>) {
+        self.bottom_pane.set_token_usage(info.clone());
+        self.token_info = info;
     }
-
     /// Finalize any active exec as failed, push an error message into history,
     /// and stop/clear running UI state.
     fn finalize_turn_with_error_message(&mut self, message: String) {
@@ -659,15 +653,14 @@ impl ChatWidget {
                 initial_prompt.unwrap_or_default(),
                 initial_images,
             ),
-            total_token_usage: TokenUsage::default(),
-            last_token_usage: TokenUsage::default(),
+            token_info: None,
             stream: StreamController::new(config),
             running_commands: HashMap::new(),
             task_complete_pending: false,
             interrupts: InterruptManager::new(),
             reasoning_buffer: String::new(),
             full_reasoning_buffer: String::new(),
-            session_id: None,
+            conversation_id: None,
             queued_user_messages: VecDeque::new(),
             show_welcome_banner: true,
             suppress_session_configured_redraw: false,
@@ -712,15 +705,14 @@ impl ChatWidget {
                 initial_prompt.unwrap_or_default(),
                 initial_images,
             ),
-            total_token_usage: TokenUsage::default(),
-            last_token_usage: TokenUsage::default(),
+            token_info: None,
             stream: StreamController::new(config),
             running_commands: HashMap::new(),
             task_complete_pending: false,
             interrupts: InterruptManager::new(),
             reasoning_buffer: String::new(),
             full_reasoning_buffer: String::new(),
-            session_id: None,
+            conversation_id: None,
             queued_user_messages: VecDeque::new(),
             show_welcome_banner: false,
             suppress_session_configured_redraw: true,
@@ -1050,7 +1042,7 @@ impl ChatWidget {
             EventMsg::AgentReasoningSectionBreak(_) => self.on_reasoning_section_break(),
             EventMsg::TaskStarted(_) => self.on_task_started(),
             EventMsg::TaskComplete(TaskCompleteEvent { .. }) => self.on_task_complete(),
-            EventMsg::TokenCount(token_usage) => self.on_token_count(token_usage),
+            EventMsg::TokenCount(ev) => self.set_token_info(ev.info),
             EventMsg::Error(ErrorEvent { message }) => self.on_error(message),
             EventMsg::TurnAborted(ev) => match ev.reason {
                 TurnAbortReason::Interrupted => {
@@ -1157,10 +1149,17 @@ impl ChatWidget {
     }
 
     pub(crate) fn add_status_output(&mut self) {
+        let default_usage;
+        let usage_ref = if let Some(ti) = &self.token_info {
+            &ti.total_token_usage
+        } else {
+            default_usage = TokenUsage::default();
+            &default_usage
+        };
         self.add_to_history(history_cell::new_status_output(
             &self.config,
-            &self.total_token_usage,
-            &self.session_id,
+            usage_ref,
+            &self.conversation_id,
         ));
     }
 
@@ -1289,15 +1288,17 @@ impl ChatWidget {
 
     /// Handle Ctrl-C key press.
     fn on_ctrl_c(&mut self) {
-        if self.bottom_pane.on_ctrl_c() == CancellationEvent::Ignored {
-            if self.bottom_pane.is_task_running() {
-                self.submit_op(Op::Interrupt);
-            } else if self.bottom_pane.ctrl_c_quit_hint_visible() {
-                self.submit_op(Op::Shutdown);
-            } else {
-                self.bottom_pane.show_ctrl_c_quit_hint();
-            }
+        if self.bottom_pane.on_ctrl_c() == CancellationEvent::Handled {
+            return;
         }
+
+        if self.bottom_pane.is_task_running() {
+            self.bottom_pane.show_ctrl_c_quit_hint();
+            self.submit_op(Op::Interrupt);
+            return;
+        }
+
+        self.submit_op(Op::Shutdown);
     }
 
     pub(crate) fn composer_is_empty(&self) -> bool {
@@ -1352,12 +1353,15 @@ impl ChatWidget {
         self.submit_user_message(text.into());
     }
 
-    pub(crate) fn token_usage(&self) -> &TokenUsage {
-        &self.total_token_usage
+    pub(crate) fn token_usage(&self) -> TokenUsage {
+        self.token_info
+            .as_ref()
+            .map(|ti| ti.total_token_usage.clone())
+            .unwrap_or_default()
     }
 
-    pub(crate) fn session_id(&self) -> Option<Uuid> {
-        self.session_id
+    pub(crate) fn conversation_id(&self) -> Option<ConversationId> {
+        self.conversation_id
     }
 
     /// Return a reference to the widget's current config (includes any
@@ -1367,12 +1371,8 @@ impl ChatWidget {
     }
 
     pub(crate) fn clear_token_usage(&mut self) {
-        self.total_token_usage = TokenUsage::default();
-        self.bottom_pane.set_token_usage(
-            self.total_token_usage.clone(),
-            self.last_token_usage.clone(),
-            self.config.model_context_window,
-        );
+        self.token_info = None;
+        self.bottom_pane.set_token_usage(None);
     }
 
     pub fn cursor_pos(&self, area: Rect) -> Option<(u16, u16)> {
@@ -1405,34 +1405,6 @@ const EXAMPLE_PROMPTS: [&str; 6] = [
     "Improve documentation in @filename",
 ];
 
-fn add_token_usage(current_usage: &TokenUsage, new_usage: &TokenUsage) -> TokenUsage {
-    let cached_input_tokens = match (
-        current_usage.cached_input_tokens,
-        new_usage.cached_input_tokens,
-    ) {
-        (Some(current), Some(new)) => Some(current + new),
-        (Some(current), None) => Some(current),
-        (None, Some(new)) => Some(new),
-        (None, None) => None,
-    };
-    let reasoning_output_tokens = match (
-        current_usage.reasoning_output_tokens,
-        new_usage.reasoning_output_tokens,
-    ) {
-        (Some(current), Some(new)) => Some(current + new),
-        (Some(current), None) => Some(current),
-        (None, Some(new)) => Some(new),
-        (None, None) => None,
-    };
-    TokenUsage {
-        input_tokens: current_usage.input_tokens + new_usage.input_tokens,
-        cached_input_tokens,
-        output_tokens: current_usage.output_tokens + new_usage.output_tokens,
-        reasoning_output_tokens,
-        total_tokens: current_usage.total_tokens + new_usage.total_tokens,
-    }
-}
-
 // Extract the first bold (Markdown) element in the form **...** from `s`.
 // Returns the inner text if found; otherwise `None`.
 fn extract_first_bold(s: &str) -> Option<String> {

codex-rs/tui/src/chatwidget/tests.rs

@@ -25,6 +25,7 @@ use codex_core::protocol::PatchApplyEndEvent;
 use codex_core::protocol::StreamErrorEvent;
 use codex_core::protocol::TaskCompleteEvent;
 use codex_core::protocol::TaskStartedEvent;
+use codex_protocol::mcp_protocol::ConversationId;
 use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
 use crossterm::event::KeyModifiers;
@@ -35,11 +36,10 @@ use std::io::BufRead;
 use std::io::BufReader;
 use std::path::PathBuf;
 use tokio::sync::mpsc::unbounded_channel;
-use uuid::Uuid;
 
 fn test_config() -> Config {
     // Use base defaults to avoid depending on host state.
-    codex_core::config::Config::load_from_base_config_with_overrides(
+    Config::load_from_base_config_with_overrides(
         ConfigToml::default(),
         ConfigOverrides::default(),
         std::env::temp_dir(),
@@ -79,7 +79,7 @@ fn final_answer_without_newline_is_flushed_immediately() {
     // Set up a VT100 test terminal to capture ANSI visual output
     let width: u16 = 80;
     let height: u16 = 2000;
-    let viewport = ratatui::layout::Rect::new(0, height - 1, width, 1);
+    let viewport = Rect::new(0, height - 1, width, 1);
     let backend = ratatui::backend::TestBackend::new(width, height);
     let mut terminal = crate::custom_terminal::Terminal::with_options(backend)
         .expect("failed to construct terminal");
@@ -132,13 +132,15 @@ fn final_answer_without_newline_is_flushed_immediately() {
 fn resumed_initial_messages_render_history() {
     let (mut chat, mut rx, _ops) = make_chatwidget_manual();
 
+    let conversation_id = ConversationId::new();
+
     let configured = codex_core::protocol::SessionConfiguredEvent {
-        session_id: Uuid::nil(),
+        session_id: conversation_id,
         model: "test-model".to_string(),
         history_log_id: 0,
         history_entry_count: 0,
         initial_messages: Some(vec![
-            EventMsg::UserMessage(codex_core::protocol::UserMessageEvent {
+            EventMsg::UserMessage(UserMessageEvent {
                 message: "hello from user".to_string(),
                 kind: Some(InputMessageKind::Plain),
             }),
@@ -175,6 +177,10 @@ fn resumed_initial_messages_render_history() {
     );
 }
 
+#[cfg_attr(
+    target_os = "macos",
+    ignore = "system configuration APIs are blocked under macOS seatbelt"
+)]
 #[tokio::test(flavor = "current_thread")]
 async fn helpers_are_available_and_do_not_panic() {
     let (tx_raw, _rx) = unbounded_channel::<AppEvent>();
@@ -185,7 +191,7 @@ async fn helpers_are_available_and_do_not_panic() {
     )));
     let init = ChatWidgetInit {
         config: cfg,
-        frame_requester: crate::tui::FrameRequester::test_dummy(),
+        frame_requester: FrameRequester::test_dummy(),
         app_event_tx: tx,
         initial_prompt: None,
         initial_images: Vec::new(),
@@ -208,7 +214,7 @@ fn make_chatwidget_manual() -> (
     let cfg = test_config();
     let bottom = BottomPane::new(BottomPaneParams {
         app_event_tx: app_event_tx.clone(),
-        frame_requester: crate::tui::FrameRequester::test_dummy(),
+        frame_requester: FrameRequester::test_dummy(),
         has_input_focus: true,
         enhanced_keys_supported: false,
         placeholder_text: "Ask Codex to do anything".to_string(),
@@ -221,18 +227,17 @@ fn make_chatwidget_manual() -> (
         active_exec_cell: None,
         config: cfg.clone(),
         initial_user_message: None,
-        total_token_usage: TokenUsage::default(),
-        last_token_usage: TokenUsage::default(),
+        token_info: None,
         stream: StreamController::new(cfg),
         running_commands: HashMap::new(),
         task_complete_pending: false,
         interrupts: InterruptManager::new(),
         reasoning_buffer: String::new(),
         full_reasoning_buffer: String::new(),
-        session_id: None,
-        frame_requester: crate::tui::FrameRequester::test_dummy(),
+        conversation_id: None,
+        frame_requester: FrameRequester::test_dummy(),
         show_welcome_banner: true,
-        queued_user_messages: std::collections::VecDeque::new(),
+        queued_user_messages: VecDeque::new(),
         suppress_session_configured_redraw: false,
     };
     (widget, rx, op_rx)
@@ -368,11 +373,10 @@ fn begin_exec(chat: &mut ChatWidget, call_id: &str, raw_cmd: &str) {
     // Build the full command vec and parse it using core's parser,
     // then convert to protocol variants for the event payload.
     let command = vec!["bash".to_string(), "-lc".to_string(), raw_cmd.to_string()];
-    let parsed_cmd: Vec<codex_protocol::parse_command::ParsedCommand> =
-        codex_core::parse_command::parse_command(&command)
-            .into_iter()
-            .map(Into::into)
-            .collect();
+    let parsed_cmd: Vec<ParsedCommand> = codex_core::parse_command::parse_command(&command)
+        .into_iter()
+        .map(Into::into)
+        .collect();
     chat.handle_codex_event(Event {
         id: call_id.to_string(),
         msg: EventMsg::ExecCommandBegin(ExecCommandBeginEvent {
@@ -413,7 +417,7 @@ fn active_blob(chat: &ChatWidget) -> String {
     lines_to_single_string(&lines)
 }
 
-fn open_fixture(name: &str) -> std::fs::File {
+fn open_fixture(name: &str) -> File {
     // 1) Prefer fixtures within this crate
     {
         let mut p = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
@@ -621,7 +625,7 @@ async fn binary_size_transcript_snapshot() {
     // Set up a VT100 test terminal to capture ANSI visual output
     let width: u16 = 80;
     let height: u16 = 2000;
-    let viewport = ratatui::layout::Rect::new(0, height - 1, width, 1);
+    let viewport = Rect::new(0, height - 1, width, 1);
     let backend = ratatui::backend::TestBackend::new(width, height);
     let mut terminal = crate::custom_terminal::Terminal::with_options(backend)
         .expect("failed to construct terminal");
@@ -806,7 +810,7 @@ fn approval_modal_exec_snapshot() {
     // Build a chat widget with manual channels to avoid spawning the agent.
     let (mut chat, _rx, _op_rx) = make_chatwidget_manual();
     // Ensure policy allows surfacing approvals explicitly (not strictly required for direct event).
-    chat.config.approval_policy = codex_core::protocol::AskForApproval::OnRequest;
+    chat.config.approval_policy = AskForApproval::OnRequest;
     // Inject an exec approval request to display the approval modal.
     let ev = ExecApprovalRequestEvent {
         call_id: "call-approve-cmd".into(),
@@ -836,7 +840,7 @@ fn approval_modal_exec_snapshot() {
 #[test]
 fn approval_modal_exec_without_reason_snapshot() {
     let (mut chat, _rx, _op_rx) = make_chatwidget_manual();
-    chat.config.approval_policy = codex_core::protocol::AskForApproval::OnRequest;
+    chat.config.approval_policy = AskForApproval::OnRequest;
 
     let ev = ExecApprovalRequestEvent {
         call_id: "call-approve-cmd-noreason".into(),
@@ -862,10 +866,10 @@ fn approval_modal_exec_without_reason_snapshot() {
 #[test]
 fn approval_modal_patch_snapshot() {
     let (mut chat, _rx, _op_rx) = make_chatwidget_manual();
-    chat.config.approval_policy = codex_core::protocol::AskForApproval::OnRequest;
+    chat.config.approval_policy = AskForApproval::OnRequest;
 
     // Build a small changeset and a reason/grant_root to exercise the prompt text.
-    let mut changes = std::collections::HashMap::new();
+    let mut changes = HashMap::new();
     changes.insert(
         PathBuf::from("README.md"),
         FileChange::Add {
@@ -911,7 +915,7 @@ fn interrupt_restores_queued_messages_into_composer() {
     chat.handle_codex_event(Event {
         id: "turn-1".into(),
         msg: EventMsg::TurnAborted(codex_core::protocol::TurnAbortedEvent {
-            reason: codex_core::protocol::TurnAbortReason::Interrupted,
+            reason: TurnAbortReason::Interrupted,
         }),
     });
 
@@ -1345,7 +1349,7 @@ fn apply_patch_full_flow_integration_like() {
 fn apply_patch_untrusted_shows_approval_modal() {
     let (mut chat, _rx, _op_rx) = make_chatwidget_manual();
     // Ensure approval policy is untrusted (OnRequest)
-    chat.config.approval_policy = codex_core::protocol::AskForApproval::OnRequest;
+    chat.config.approval_policy = AskForApproval::OnRequest;
 
     // Simulate a patch approval request from backend
     let mut changes = HashMap::new();
@@ -1364,8 +1368,8 @@ fn apply_patch_untrusted_shows_approval_modal() {
     });
 
     // Render and ensure the approval modal title is present
-    let area = ratatui::layout::Rect::new(0, 0, 80, 12);
-    let mut buf = ratatui::buffer::Buffer::empty(area);
+    let area = Rect::new(0, 0, 80, 12);
+    let mut buf = Buffer::empty(area);
     (&chat).render_ref(area, &mut buf);
 
     let mut contains_title = false;
@@ -1390,7 +1394,7 @@ fn apply_patch_request_shows_diff_summary() {
     let (mut chat, mut rx, _op_rx) = make_chatwidget_manual();
 
     // Ensure we are in OnRequest so an approval is surfaced
-    chat.config.approval_policy = codex_core::protocol::AskForApproval::OnRequest;
+    chat.config.approval_policy = AskForApproval::OnRequest;
 
     // Simulate backend asking to apply a patch adding two lines to README.md
     let mut changes = HashMap::new();
@@ -1692,7 +1696,7 @@ fn chatwidget_exec_and_status_layout_vt100_snapshot() {
     let width: u16 = 80;
     let ui_height: u16 = chat.desired_height(width);
     let vt_height: u16 = 40;
-    let viewport = ratatui::layout::Rect::new(0, vt_height - ui_height, width, ui_height);
+    let viewport = Rect::new(0, vt_height - ui_height, width, ui_height);
 
     // Use TestBackend for the terminal (no real ANSI emitted by drawing),
     // but capture VT100 escape stream for history insertion with a separate writer.
@@ -1707,7 +1711,7 @@ fn chatwidget_exec_and_status_layout_vt100_snapshot() {
     }
 
     // 2) Render the ChatWidget UI into an off-screen buffer using WidgetRef directly
-    let mut ui_buf = ratatui::buffer::Buffer::empty(viewport);
+    let mut ui_buf = Buffer::empty(viewport);
     (&chat).render_ref(viewport, &mut ui_buf);
 
     // 3) Build VT100 visual from the captured ANSI

codex-rs/tui/src/clipboard_paste.rs

@@ -49,34 +49,60 @@ pub struct PastedImageInfo {
 /// Capture image from system clipboard, encode to PNG, and return bytes + info.
 #[cfg(not(target_os = "android"))]
 pub fn paste_image_as_png() -> Result<(Vec<u8>, PastedImageInfo), PasteImageError> {
+    let _span = tracing::debug_span!("paste_image_as_png").entered();
     tracing::debug!("attempting clipboard image read");
     let mut cb = arboard::Clipboard::new()
         .map_err(|e| PasteImageError::ClipboardUnavailable(e.to_string()))?;
-    let img = cb
-        .get_image()
-        .map_err(|e| PasteImageError::NoImage(e.to_string()))?;
-    let w = img.width as u32;
-    let h = img.height as u32;
+    // Sometimes images on the clipboard come as files (e.g. when copy/pasting from
+    // Finder), sometimes they come as image data (e.g. when pasting from Chrome).
+    // Accept both, and prefer files if both are present.
+    let files = cb
+        .get()
+        .file_list()
+        .map_err(|e| PasteImageError::ClipboardUnavailable(e.to_string()));
+    let dyn_img = if let Some(img) = files
+        .unwrap_or_default()
+        .into_iter()
+        .find_map(|f| image::open(f).ok())
+    {
+        tracing::debug!(
+            "clipboard image opened from file: {}x{}",
+            img.width(),
+            img.height()
+        );
+        img
+    } else {
+        let _span = tracing::debug_span!("get_image").entered();
+        let img = cb
+            .get_image()
+            .map_err(|e| PasteImageError::NoImage(e.to_string()))?;
+        let w = img.width as u32;
+        let h = img.height as u32;
+        tracing::debug!("clipboard image opened from image: {}x{}", w, h);
+
+        let Some(rgba_img) = image::RgbaImage::from_raw(w, h, img.bytes.into_owned()) else {
+            return Err(PasteImageError::EncodeFailed("invalid RGBA buffer".into()));
+        };
+
+        image::DynamicImage::ImageRgba8(rgba_img)
+    };
 
     let mut png: Vec<u8> = Vec::new();
-    let Some(rgba_img) = image::RgbaImage::from_raw(w, h, img.bytes.into_owned()) else {
-        return Err(PasteImageError::EncodeFailed("invalid RGBA buffer".into()));
-    };
-    let dyn_img = image::DynamicImage::ImageRgba8(rgba_img);
-    tracing::debug!("clipboard image decoded RGBA {w}x{h}");
     {
+        let span =
+            tracing::debug_span!("encode_image", byte_length = tracing::field::Empty).entered();
         let mut cursor = std::io::Cursor::new(&mut png);
         dyn_img
             .write_to(&mut cursor, image::ImageFormat::Png)
             .map_err(|e| PasteImageError::EncodeFailed(e.to_string()))?;
+        span.record("byte_length", png.len());
     }
 
-    tracing::debug!("clipboard image encoded to PNG ({}) bytes", png.len());
     Ok((
         png,
         PastedImageInfo {
-            width: w,
-            height: h,
+            width: dyn_img.width(),
+            height: dyn_img.height(),
             encoded_format: EncodedImageFormat::Png,
         },
     ))

codex-rs/tui/src/history_cell.rs

@@ -27,6 +27,8 @@ use codex_core::protocol::McpInvocation;
 use codex_core::protocol::SandboxPolicy;
 use codex_core::protocol::SessionConfiguredEvent;
 use codex_core::protocol::TokenUsage;
+use codex_protocol::mcp_protocol::ConversationId;
+use codex_protocol::num_format::format_with_separators;
 use codex_protocol::parse_command::ParsedCommand;
 use image::DynamicImage;
 use image::ImageReader;
@@ -49,7 +51,6 @@ use std::time::Duration;
 use std::time::Instant;
 use tracing::error;
 use unicode_width::UnicodeWidthStr;
-use uuid::Uuid;
 
 #[derive(Clone, Debug)]
 pub(crate) struct CommandOutput {
@@ -821,7 +822,7 @@ pub(crate) fn new_completed_mcp_tool_call(
 pub(crate) fn new_status_output(
     config: &Config,
     usage: &TokenUsage,
-    session_id: &Option<Uuid>,
+    session_id: &Option<ConversationId>,
 ) -> PlainHistoryCell {
     let mut lines: Vec<Line<'static>> = Vec::new();
     lines.push("/status".magenta().into());
@@ -964,23 +965,22 @@ pub(crate) fn new_status_output(
     // Input: <input> [+ <cached> cached]
     let mut input_line_spans: Vec<Span<'static>> = vec![
         "  • Input: ".into(),
-        usage.non_cached_input().to_string().into(),
+        format_with_separators(usage.non_cached_input()).into(),
     ];
-    if let Some(cached) = usage.cached_input_tokens
-        && cached > 0
-    {
+    if usage.cached_input_tokens > 0 {
+        let cached = usage.cached_input_tokens;
         input_line_spans.push(format!(" (+ {cached} cached)").into());
     }
     lines.push(Line::from(input_line_spans));
     // Output: <output>
     lines.push(Line::from(vec![
         "  • Output: ".into(),
-        usage.output_tokens.to_string().into(),
+        format_with_separators(usage.output_tokens).into(),
     ]));
     // Total: <total>
     lines.push(Line::from(vec![
         "  • Total: ".into(),
-        usage.blended_total().to_string().into(),
+        format_with_separators(usage.blended_total()).into(),
     ]));
 
     PlainHistoryCell { lines }
@@ -1178,13 +1178,14 @@ pub(crate) fn new_proposed_command(command: &[String]) -> PlainHistoryCell {
     let mut lines: Vec<Line<'static>> = Vec::new();
     lines.push(Line::from(vec!["• ".into(), "Proposed Command".bold()]));
 
-    let cmd_lines: Vec<Line<'static>> = cmd
-        .lines()
-        .map(|part| Line::from(part.to_string()))
-        .collect();
+    let highlighted_lines = crate::render::highlight::highlight_bash_to_lines(&cmd);
     let initial_prefix: Span<'static> = "  └ ".dim();
     let subsequent_prefix: Span<'static> = "    ".into();
-    lines.extend(prefix_lines(cmd_lines, initial_prefix, subsequent_prefix));
+    lines.extend(prefix_lines(
+        highlighted_lines,
+        initial_prefix,
+        subsequent_prefix,
+    ));
 
     PlainHistoryCell { lines }
 }

codex-rs/tui/src/lib.rs

@@ -217,6 +217,7 @@ pub async fn run_main(
     let file_layer = tracing_subscriber::fmt::layer()
         .with_writer(non_blocking)
         .with_target(false)
+        .with_span_events(tracing_subscriber::fmt::format::FmtSpan::CLOSE)
         .with_filter(env_filter());
 
     if cli.oss {

codex-rs/tui/src/resume_picker.rs

@@ -8,7 +8,6 @@ use codex_core::ConversationItem;
 use codex_core::ConversationsPage;
 use codex_core::Cursor;
 use codex_core::RolloutRecorder;
-use codex_core::protocol::InputMessageKind;
 use color_eyre::eyre::Result;
 use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
@@ -24,6 +23,10 @@ use crate::text_formatting::truncate_text;
 use crate::tui::FrameRequester;
 use crate::tui::Tui;
 use crate::tui::TuiEvent;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::InputMessageKind;
+use codex_protocol::protocol::USER_MESSAGE_BEGIN;
 
 const PAGE_SIZE: usize = 25;
 
@@ -273,7 +276,7 @@ fn head_to_row(item: &ConversationItem) -> Option<Row> {
         ts = Some(parsed.with_timezone(&Utc));
     }
 
-    let preview = find_first_user_text(&item.head)?;
+    let preview = preview_from_head(&item.head)?;
     let preview = preview.trim().to_string();
     if preview.is_empty() {
         return None;
@@ -285,37 +288,42 @@ fn head_to_row(item: &ConversationItem) -> Option<Row> {
     })
 }
 
-/// Return the first plain user text from the JSONL `head` of a rollout.
-///
-/// Strategy: scan for the first `{ type: "message", role: "user" }` entry and
-/// then return the first `content` item where `{ type: "input_text" }` that is
-/// classified as `InputMessageKind::Plain` (i.e., not wrapped in
-/// `<user_instructions>` or `<environment_context>` tags).
-fn find_first_user_text(head: &[serde_json::Value]) -> Option<String> {
-    for v in head.iter() {
-        let t = v.get("type").and_then(|x| x.as_str()).unwrap_or("");
-        if t != "message" {
-            continue;
-        }
-        if v.get("role").and_then(|x| x.as_str()) != Some("user") {
-            continue;
-        }
-        if let Some(arr) = v.get("content").and_then(|c| c.as_array()) {
-            for c in arr.iter() {
-                if let (Some("input_text"), Some(txt)) =
-                    (c.get("type").and_then(|t| t.as_str()), c.get("text"))
-                    && let Some(s) = txt.as_str()
-                {
-                    // Skip XML-wrapped user_instructions/environment_context blocks and
-                    // return the first plain user text we find.
-                    if matches!(InputMessageKind::from(("user", s)), InputMessageKind::Plain) {
-                        return Some(s.to_string());
-                    }
+fn preview_from_head(head: &[serde_json::Value]) -> Option<String> {
+    head.iter()
+        .filter_map(|value| serde_json::from_value::<ResponseItem>(value.clone()).ok())
+        .find_map(|item| match item {
+            ResponseItem::Message { content, .. } => {
+                // Find the actual user message (as opposed to user instructions or ide context)
+                let preview = content
+                    .into_iter()
+                    .filter_map(|content| match content {
+                        ContentItem::InputText { text }
+                            if matches!(
+                                InputMessageKind::from(("user", text.as_str())),
+                                InputMessageKind::Plain
+                            ) =>
+                        {
+                            // Strip ide context.
+                            let text = match text.find(USER_MESSAGE_BEGIN) {
+                                Some(idx) => {
+                                    text[idx + USER_MESSAGE_BEGIN.len()..].trim().to_string()
+                                }
+                                None => text,
+                            };
+                            Some(text)
+                        }
+                        _ => None,
+                    })
+                    .collect::<String>();
+
+                if preview.is_empty() {
+                    None
+                } else {
+                    Some(preview)
                 }
             }
-        }
-    }
-    None
+            _ => None,
+        })
 }
 
 fn draw_picker(tui: &mut Tui, state: &PickerState) -> std::io::Result<()> {
@@ -452,31 +460,26 @@ mod tests {
     }
 
     #[test]
-    fn skips_user_instructions_and_env_context() {
+    fn preview_uses_first_message_input_text() {
         let head = vec![
             json!({ "timestamp": "2025-01-01T00:00:00Z" }),
             json!({
                 "type": "message",
                 "role": "user",
                 "content": [
-                    { "type": "input_text", "text": "<user_instructions>hi</user_instructions>" }
+                    { "type": "input_text", "text": "<user_instructions>hi</user_instructions>" },
+                    { "type": "input_text", "text": "real question" },
+                    { "type": "input_image", "image_url": "ignored" }
                 ]
             }),
             json!({
                 "type": "message",
                 "role": "user",
-                "content": [
-                    { "type": "input_text", "text": "<environment_context>cwd</environment_context>" }
-                ]
-            }),
-            json!({
-                "type": "message",
-                "role": "user",
-                "content": [ { "type": "input_text", "text": "real question" } ]
+                "content": [ { "type": "input_text", "text": "later text" } ]
             }),
         ];
-        let first = find_first_user_text(&head);
-        assert_eq!(first.as_deref(), Some("real question"));
+        let preview = preview_from_head(&head);
+        assert_eq!(preview.as_deref(), Some("real question"));
     }
 
     #[test]

docs/config.md

@@ -6,9 +6,12 @@ Codex supports several mechanisms for setting config values:
 - Config-specific command-line flags, such as `--model o3` (highest precedence).
 - A generic `-c`/`--config` flag that takes a `key=value` pair, such as `--config model="o3"`.
   - The key can contain dots to set a value deeper than the root, e.g. `--config model_providers.openai.wire_api="chat"`.
-  - Values can contain objects, such as `--config shell_environment_policy.include_only=["PATH", "HOME", "USER"]`.
-  - For consistency with `config.toml`, values are in TOML format rather than JSON format, so use `{a = 1, b = 2}` rather than `{"a": 1, "b": 2}`.
-  - If `value` cannot be parsed as a valid TOML value, it is treated as a string value. This means that both `-c model="o3"` and `-c model=o3` are equivalent.
+  - For consistency with `config.toml`, values are a string in TOML format rather than JSON format, so use `key='{a = 1, b = 2}'` rather than `key='{"a": 1, "b": 2}'`.
+    - The quotes around the value are necessary, as without them your shell would split the config argument on spaces, resulting in `codex` receiving `-c key={a` with (invalid) additional arguments `=`, `1,`, `b`, `=`, `2}`.
+  - Values can contain any TOML object, such as `--config shell_environment_policy.include_only='["PATH", "HOME", "USER"]'`.
+  - If `value` cannot be parsed as a valid TOML value, it is treated as a string value. This means that `-c model='"o3"'` and `-c model=o3` are equivalent.
+    - In the first case, the value is the TOML string `"o3"`, while in the second the value is `o3`, which is not valid TOML and therefore treated as the TOML string `"o3"`.
+    - Because quotes are interpreted by one's shell, `-c key="true"` will be correctly interpreted in TOML as `key = true` (a boolean) and not `key = "true"` (a string). If for some reason you needed the string `"true"`, you would need to use `-c key='"true"'` (note the two sets of quotes).
 - The `$CODEX_HOME/config.toml` configuration file where the `CODEX_HOME` environment value defaults to `~/.codex`. (Note `CODEX_HOME` will also be where logs and other Codex-related information are stored.)
 
 Both the `--config` flag and the `config.toml` file support the following options:
@@ -334,6 +337,8 @@ Defines the list of MCP servers that Codex can consult for tool use. Currently,
 
 **Note:** Codex may cache the list of tools and resources from an MCP server so that Codex can include this information in context at startup without spawning all the servers. This is designed to save resources by loading MCP servers lazily.
 
+Each server may set `startup_timeout_ms` to adjust how long Codex waits for it to start and respond to a tools listing. The default is `10_000` (10 seconds).
+
 This config option is comparable to how Claude and Cursor define `mcpServers` in their respective JSON config files, though because Codex uses TOML for its config language, the format is slightly different. For example, the following config in JSON:
 
 ```json
@@ -358,6 +363,8 @@ Should be represented as follows in `~/.codex/config.toml`:
 command = "npx"
 args = ["-y", "mcp-server"]
 env = { "API_KEY" = "value" }
+# Optional: override the default 10s startup timeout
+startup_timeout_ms = 20_000
 ```
 
 ## shell_environment_policy
@@ -574,6 +581,7 @@ Options that are specific to the TUI.
 | `mcp_servers.<id>.command` | string | MCP server launcher command. |
 | `mcp_servers.<id>.args` | array<string> | MCP server args. |
 | `mcp_servers.<id>.env` | map<string,string> | MCP server env vars. |
+| `mcp_servers.<id>.startup_timeout_ms` | number | Startup timeout in milliseconds (default: 10_000). Timeout is applied both for initializing MCP server and initially listing tools. |
 | `model_providers.<id>.name` | string | Display name. |
 | `model_providers.<id>.base_url` | string | API base URL. |
 | `model_providers.<id>.env_key` | string | Env var for API key. |

docs/release_management.md

@@ -8,16 +8,23 @@ Currently, we made Codex binaries available in three places:
 
 # Cutting a Release
 
-Currently, choosing the version number for the next release is a manual process. In general, just go to https://github.com/openai/codex/releases/latest and see what the latest release is and increase the minor version by `1`, so if the current release is `0.20.0`, then the next release should be `0.21.0`.
+Run the `codex-rs/scripts/create_github_release` script in the repository to publish a new release. The script will choose the appropriate version number depending on the type of release you are creating.
 
-Assuming you are trying to publish `0.21.0`, first you would run:
+To cut a new alpha release from `main` (feel free to cut alphas liberally):
 
-```shell
-VERSION=0.21.0
-./codex-rs/scripts/create_github_release.sh "$VERSION"
+```
+./codex-rs/scripts/create_github_release --publish-alpha
 ```
 
-This will kick off a GitHub Action to build the release, so go to https://github.com/openai/codex/actions/workflows/rust-release.yml to find the corresponding workflow. (Note: we should automate finding the workflow URL with `gh`.)
+To cut a new _public_ release from `main` (which requires more caution), run:
+
+```
+./codex-rs/scripts/create_github_release --publish-release
+```
+
+TIP: Add the `--dry-run` flag to report the next version number for the respective release and exit.
+
+Running the publishing script will kick off a GitHub Action to build the release, so go to https://github.com/openai/codex/actions/workflows/rust-release.yml to find the corresponding workflow. (Note: we should automate finding the workflow URL with `gh`.)
 
 When the workflow finishes, the GitHub Release is "done," but you still have to consider npm and Homebrew.