enable-resume (#3537)

Adding the ability to resume conversations.
we have one verb `resume`. 

Behavior:

`tui`:
`codex resume`: opens session picker
`codex resume --last`: continue last message
`codex resume <session id>`: continue conversation with `session id`

`exec`:
`codex resume --last`: continue last conversation
`codex resume <session id>`: continue conversation with `session id`

Implementation:
- I added a function to find the path in `~/.codex/sessions/` with a
`UUID`. This is helpful in resuming with session id.
- Added the above mentioned flags
- Added lots of testing

codex-rs/exec/Cargo.toml

@@ -46,4 +46,6 @@ core_test_support = { path = "../core/tests/common" }
 libc = "0.2"
 predicates = "3"
 tempfile = "3.13.0"
+uuid = "1"
+walkdir = "2"
 wiremock = "0.6"

codex-rs/exec/src/cli.rs

@@ -6,6 +6,10 @@ use std::path::PathBuf;
 #[derive(Parser, Debug)]
 #[command(version)]
 pub struct Cli {
+    /// Action to perform. If omitted, runs a new non-interactive session.
+    #[command(subcommand)]
+    pub command: Option<Command>,
+
     /// Optional image(s) to attach to the initial prompt.
     #[arg(long = "image", short = 'i', value_name = "FILE", value_delimiter = ',', num_args = 1..)]
     pub images: Vec<PathBuf>,
@@ -69,6 +73,28 @@ pub struct Cli {
     pub prompt: Option<String>,
 }
 
+#[derive(Debug, clap::Subcommand)]
+pub enum Command {
+    /// Resume a previous session by id or pick the most recent with --last.
+    Resume(ResumeArgs),
+}
+
+#[derive(Parser, Debug)]
+pub struct ResumeArgs {
+    /// Conversation/session id (UUID). When provided, resumes this session.
+    /// If omitted, use --last to pick the most recent recorded session.
+    #[arg(value_name = "SESSION_ID")]
+    pub session_id: Option<String>,
+
+    /// Resume the most recent recorded session (newest) without specifying an id.
+    #[arg(long = "last", default_value_t = false, conflicts_with = "session_id")]
+    pub last: bool,
+
+    /// Prompt to send after resuming the session. If `-` is used, read from stdin.
+    #[arg(value_name = "PROMPT")]
+    pub prompt: Option<String>,
+}
+
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, ValueEnum)]
 #[value(rename_all = "kebab-case")]
 pub enum Color {

codex-rs/exec/src/lib.rs

@@ -30,11 +30,14 @@ use tracing::error;
 use tracing::info;
 use tracing_subscriber::EnvFilter;
 
+use crate::cli::Command as ExecCommand;
 use crate::event_processor::CodexStatus;
 use crate::event_processor::EventProcessor;
+use codex_core::find_conversation_path_by_id_str;
 
 pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()> {
     let Cli {
+        command,
         images,
         model: model_cli_arg,
         oss,
@@ -51,8 +54,15 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
         config_overrides,
     } = cli;
 
-    // Determine the prompt based on CLI arg and/or stdin.
-    let prompt = match prompt {
+    // Determine the prompt source (parent or subcommand) and read from stdin if needed.
+    let prompt_arg = match &command {
+        // Allow prompt before the subcommand by falling back to the parent-level prompt
+        // when the Resume subcommand did not provide its own prompt.
+        Some(ExecCommand::Resume(args)) => args.prompt.clone().or(prompt),
+        None => prompt,
+    };
+
+    let prompt = match prompt_arg {
         Some(p) if p != "-" => p,
         // Either `-` was passed or no positional arg.
         maybe_dash => {
@@ -190,11 +200,29 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
 
     let conversation_manager =
         ConversationManager::new(AuthManager::shared(config.codex_home.clone()));
+
+    // Handle resume subcommand by resolving a rollout path and using explicit resume API.
     let NewConversation {
         conversation_id: _,
         conversation,
         session_configured,
-    } = conversation_manager.new_conversation(config).await?;
+    } = if let Some(ExecCommand::Resume(args)) = command {
+        let resume_path = resolve_resume_path(&config, &args).await?;
+
+        if let Some(path) = resume_path {
+            conversation_manager
+                .resume_conversation_from_rollout(
+                    config.clone(),
+                    path,
+                    AuthManager::shared(config.codex_home.clone()),
+                )
+                .await?
+        } else {
+            conversation_manager.new_conversation(config).await?
+        }
+    } else {
+        conversation_manager.new_conversation(config).await?
+    };
     info!("Codex initialized with event: {session_configured:?}");
 
     let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<Event>();
@@ -279,3 +307,23 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
 
     Ok(())
 }
+
+async fn resolve_resume_path(
+    config: &Config,
+    args: &crate::cli::ResumeArgs,
+) -> anyhow::Result<Option<PathBuf>> {
+    if args.last {
+        match codex_core::RolloutRecorder::list_conversations(&config.codex_home, 1, None).await {
+            Ok(page) => Ok(page.items.first().map(|it| it.path.clone())),
+            Err(e) => {
+                error!("Error listing conversations: {e}");
+                Ok(None)
+            }
+        }
+    } else if let Some(id_str) = args.session_id.as_deref() {
+        let path = find_conversation_path_by_id_str(&config.codex_home, id_str).await?;
+        Ok(path)
+    } else {
+        Ok(None)
+    }
+}

codex-rs/exec/tests/fixtures/cli_responses_fixture.sse

@@ -0,0 +1,10 @@
+event: response.created
+data: {"type":"response.created","response":{"id":"resp1"}}
+
+event: response.output_item.done
+data: {"type":"response.output_item.done","item":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"fixture hello"}]}}
+
+event: response.completed
+data: {"type":"response.completed","response":{"id":"resp1","output":[]}}
+
+

codex-rs/exec/tests/suite/mod.rs

@@ -1,4 +1,5 @@
 // Aggregates all former standalone integration tests as modules.
 mod apply_patch;
 mod common;
+mod resume;
 mod sandbox;

codex-rs/exec/tests/suite/resume.rs

@@ -0,0 +1,267 @@
+#![allow(clippy::unwrap_used, clippy::expect_used)]
+use anyhow::Context;
+use assert_cmd::prelude::*;
+use serde_json::Value;
+use std::process::Command;
+use tempfile::TempDir;
+use uuid::Uuid;
+use walkdir::WalkDir;
+
+/// Utility: scan the sessions dir for a rollout file that contains `marker`
+/// in any response_item.message.content entry. Returns the absolute path.
+fn find_session_file_containing_marker(
+    sessions_dir: &std::path::Path,
+    marker: &str,
+) -> Option<std::path::PathBuf> {
+    for entry in WalkDir::new(sessions_dir) {
+        let entry = match entry {
+            Ok(e) => e,
+            Err(_) => continue,
+        };
+        if !entry.file_type().is_file() {
+            continue;
+        }
+        if !entry.file_name().to_string_lossy().ends_with(".jsonl") {
+            continue;
+        }
+        let path = entry.path();
+        let Ok(content) = std::fs::read_to_string(path) else {
+            continue;
+        };
+        // Skip the first meta line and scan remaining JSONL entries.
+        let mut lines = content.lines();
+        if lines.next().is_none() {
+            continue;
+        }
+        for line in lines {
+            if line.trim().is_empty() {
+                continue;
+            }
+            let Ok(item): Result<Value, _> = serde_json::from_str(line) else {
+                continue;
+            };
+            if item.get("type").and_then(|t| t.as_str()) == Some("response_item")
+                && let Some(payload) = item.get("payload")
+                && payload.get("type").and_then(|t| t.as_str()) == Some("message")
+                && payload
+                    .get("content")
+                    .map(|c| c.to_string())
+                    .unwrap_or_default()
+                    .contains(marker)
+            {
+                return Some(path.to_path_buf());
+            }
+        }
+    }
+    None
+}
+
+/// Extract the conversation UUID from the first SessionMeta line in the rollout file.
+fn extract_conversation_id(path: &std::path::Path) -> String {
+    let content = std::fs::read_to_string(path).unwrap();
+    let mut lines = content.lines();
+    let meta_line = lines.next().expect("missing meta line");
+    let meta: Value = serde_json::from_str(meta_line).expect("invalid meta json");
+    meta.get("payload")
+        .and_then(|p| p.get("id"))
+        .and_then(|v| v.as_str())
+        .unwrap_or_default()
+        .to_string()
+}
+
+#[test]
+fn exec_resume_last_appends_to_existing_file() -> anyhow::Result<()> {
+    let home = TempDir::new()?;
+    let fixture = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures/cli_responses_fixture.sse");
+
+    // 1) First run: create a session with a unique marker in the content.
+    let marker = format!("resume-last-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    Command::cargo_bin("codex-exec")
+        .context("should find binary for codex-exec")?
+        .env("CODEX_HOME", home.path())
+        .env("OPENAI_API_KEY", "dummy")
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(env!("CARGO_MANIFEST_DIR"))
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    // Find the created session file containing the marker.
+    let sessions_dir = home.path().join("sessions");
+    let path = find_session_file_containing_marker(&sessions_dir, &marker)
+        .expect("no session file found after first run");
+
+    // 2) Second run: resume the most recent file with a new marker.
+    let marker2 = format!("resume-last-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+
+    let mut binding = assert_cmd::Command::cargo_bin("codex-exec")
+        .context("should find binary for codex-exec")?;
+    let cmd = binding
+        .env("CODEX_HOME", home.path())
+        .env("OPENAI_API_KEY", "dummy")
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(env!("CARGO_MANIFEST_DIR"))
+        .arg(&prompt2)
+        .arg("resume")
+        .arg("--last");
+    cmd.assert().success();
+
+    // Ensure the same file was updated and contains both markers.
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no resumed session file containing marker2");
+    assert_eq!(
+        resumed_path, path,
+        "resume --last should append to existing file"
+    );
+    let content = std::fs::read_to_string(&resumed_path)?;
+    assert!(content.contains(&marker));
+    assert!(content.contains(&marker2));
+    Ok(())
+}
+
+#[test]
+fn exec_resume_by_id_appends_to_existing_file() -> anyhow::Result<()> {
+    let home = TempDir::new()?;
+    let fixture = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures/cli_responses_fixture.sse");
+
+    // 1) First run: create a session
+    let marker = format!("resume-by-id-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    Command::cargo_bin("codex-exec")
+        .context("should find binary for codex-exec")?
+        .env("CODEX_HOME", home.path())
+        .env("OPENAI_API_KEY", "dummy")
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(env!("CARGO_MANIFEST_DIR"))
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    let sessions_dir = home.path().join("sessions");
+    let path = find_session_file_containing_marker(&sessions_dir, &marker)
+        .expect("no session file found after first run");
+    let session_id = extract_conversation_id(&path);
+    assert!(
+        !session_id.is_empty(),
+        "missing conversation id in meta line"
+    );
+
+    // 2) Resume by id
+    let marker2 = format!("resume-by-id-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+
+    let mut binding = assert_cmd::Command::cargo_bin("codex-exec")
+        .context("should find binary for codex-exec")?;
+    let cmd = binding
+        .env("CODEX_HOME", home.path())
+        .env("OPENAI_API_KEY", "dummy")
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(env!("CARGO_MANIFEST_DIR"))
+        .arg(&prompt2)
+        .arg("resume")
+        .arg(&session_id);
+    cmd.assert().success();
+
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no resumed session file containing marker2");
+    assert_eq!(
+        resumed_path, path,
+        "resume by id should append to existing file"
+    );
+    let content = std::fs::read_to_string(&resumed_path)?;
+    assert!(content.contains(&marker));
+    assert!(content.contains(&marker2));
+    Ok(())
+}
+
+#[test]
+fn exec_resume_preserves_cli_configuration_overrides() -> anyhow::Result<()> {
+    let home = TempDir::new()?;
+    let fixture = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures/cli_responses_fixture.sse");
+
+    let marker = format!("resume-config-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    Command::cargo_bin("codex-exec")
+        .context("should find binary for codex-exec")?
+        .env("CODEX_HOME", home.path())
+        .env("OPENAI_API_KEY", "dummy")
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("--sandbox")
+        .arg("workspace-write")
+        .arg("--model")
+        .arg("gpt-5")
+        .arg("-C")
+        .arg(env!("CARGO_MANIFEST_DIR"))
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    let sessions_dir = home.path().join("sessions");
+    let path = find_session_file_containing_marker(&sessions_dir, &marker)
+        .expect("no session file found after first run");
+
+    let marker2 = format!("resume-config-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+
+    let output = Command::cargo_bin("codex-exec")
+        .context("should find binary for codex-exec")?
+        .env("CODEX_HOME", home.path())
+        .env("OPENAI_API_KEY", "dummy")
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("--sandbox")
+        .arg("workspace-write")
+        .arg("--model")
+        .arg("gpt-5-high")
+        .arg("-C")
+        .arg(env!("CARGO_MANIFEST_DIR"))
+        .arg(&prompt2)
+        .arg("resume")
+        .arg("--last")
+        .output()
+        .context("resume run should succeed")?;
+
+    assert!(output.status.success(), "resume run failed: {output:?}");
+
+    let stdout = String::from_utf8(output.stdout)?;
+    assert!(
+        stdout.contains("model: gpt-5-high"),
+        "stdout missing model override: {stdout}"
+    );
+    assert!(
+        stdout.contains("sandbox: workspace-write"),
+        "stdout missing sandbox override: {stdout}"
+    );
+
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no resumed session file containing marker2");
+    assert_eq!(resumed_path, path, "resume should append to same file");
+
+    let content = std::fs::read_to_string(&resumed_path)?;
+    assert!(content.contains(&marker));
+    assert!(content.contains(&marker2));
+    Ok(())
+}