From 232db0613a70301e36981c42e859d670a17f68f3 Mon Sep 17 00:00:00 2001 From: Ruslan Nigmatullin Date: Mon, 6 Apr 2026 20:17:08 -0700 Subject: [PATCH 1/3] app-server: Fix compilation of a test in mcp_resource (#16972) --- codex-rs/app-server/tests/suite/v2/mcp_resource.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/codex-rs/app-server/tests/suite/v2/mcp_resource.rs b/codex-rs/app-server/tests/suite/v2/mcp_resource.rs index db5ddfa9b2..0a38f3b37e 100644 --- a/codex-rs/app-server/tests/suite/v2/mcp_resource.rs +++ b/codex-rs/app-server/tests/suite/v2/mcp_resource.rs @@ -15,7 +15,7 @@ use codex_app_server_protocol::McpResourceReadResponse; use codex_app_server_protocol::RequestId; use codex_app_server_protocol::ThreadStartParams; use codex_app_server_protocol::ThreadStartResponse; -use codex_login::AuthCredentialsStoreMode; +use codex_config::types::AuthCredentialsStoreMode; use core_test_support::responses; use pretty_assertions::assert_eq; use rmcp::handler::server::ServerHandler; From 4bb507d2c4fb978bd6ccc1ad65d467d532fc3b15 Mon Sep 17 00:00:00 2001 From: pakrym-oai Date: Mon, 6 Apr 2026 20:26:21 -0700 Subject: [PATCH 2/3] Make AGENTS.md discovery FS-aware (#15826) ## Summary - make AGENTS.md discovery and loading fully FS-aware and remove the non-FS discover helper - migrate remote-aware codex-core tests to use TestEnv workspace setup instead of syncing a local workspace copy - add AGENTS.md corner-case coverage, including directory fallbacks and remote-aware integration coverage ## Testing - cargo test -p codex-core project_doc -- --nocapture - cargo test -p codex-core hierarchical_agents -- --nocapture - cargo test -p codex-core agents_md -- --nocapture - cargo test -p codex-tui status -- --nocapture - cargo test -p codex-tui-app-server status -- --nocapture - just fix - just fmt - just bazel-lock-update - just bazel-lock-check - just argument-comment-lint - remote Linux executor tests in progress via scripts/test-remote-env.sh --- codex-rs/Cargo.lock | 1 + codex-rs/core/src/codex.rs | 12 +- codex-rs/core/src/codex_tests.rs | 8 +- codex-rs/core/src/project_doc.rs | 111 +++++++++------ codex-rs/core/src/project_doc_tests.rs | 125 ++++++++++++++++- codex-rs/core/tests/common/test_codex.rs | 118 ++++++++++------ codex-rs/core/tests/common/test_codex_exec.rs | 1 + codex-rs/core/tests/suite/agents_md.rs | 130 ++++++++++++++++++ .../core/tests/suite/hierarchical_agents.rs | 34 +++-- codex-rs/core/tests/suite/mod.rs | 1 + codex-rs/core/tests/suite/remote_env.rs | 11 +- codex-rs/exec-server/src/lib.rs | 1 + codex-rs/exec-server/src/local_file_system.rs | 5 + .../exec-server/src/remote_file_system.rs | 4 + codex-rs/exec-server/src/rpc.rs | 8 ++ .../src/server/file_system_handler.rs | 5 +- codex-rs/tui/Cargo.toml | 1 + codex-rs/tui/src/chatwidget.rs | 15 ++ codex-rs/tui/src/status/card.rs | 34 ++++- codex-rs/tui/src/status/helpers.rs | 90 ++++++------ codex-rs/tui/src/status/mod.rs | 1 + 21 files changed, 545 insertions(+), 171 deletions(-) create mode 100644 codex-rs/core/tests/suite/agents_md.rs diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lock index d1b1e5eb9c..3578fd8c63 100644 --- a/codex-rs/Cargo.lock +++ b/codex-rs/Cargo.lock @@ -2794,6 +2794,7 @@ dependencies = [ "codex-cloud-requirements", "codex-config", "codex-core", + "codex-exec-server", "codex-features", "codex-feedback", "codex-file-search", diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs index 4bf309c902..423c62848a 100644 --- a/codex-rs/core/src/codex.rs +++ b/codex-rs/core/src/codex.rs @@ -536,7 +536,11 @@ impl Codex { config.startup_warnings.push(message); } - let user_instructions = get_user_instructions(&config).await; + let environment = environment_manager + .current() + .await + .map_err(|err| CodexErr::Fatal(format!("failed to create environment: {err}")))?; + let user_instructions = get_user_instructions(&config, environment.as_deref()).await; let exec_policy = if crate::guardian::is_guardian_reviewer_source(&session_source) { // Guardian review should rely on the built-in shell safety checks, @@ -664,12 +668,12 @@ impl Codex { agent_status_tx.clone(), conversation_history, session_source_clone, - environment_manager, skills_manager, plugins_manager, mcp_manager.clone(), skills_watcher, agent_control, + environment, ) .await .map_err(|e| { @@ -1518,12 +1522,12 @@ impl Session { agent_status: watch::Sender, initial_history: InitialHistory, session_source: SessionSource, - environment_manager: Arc, skills_manager: Arc, plugins_manager: Arc, mcp_manager: Arc, skills_watcher: Arc, agent_control: AgentControl, + environment: Option>, ) -> anyhow::Result> { debug!( "Configuring session: model={}; provider={:?}", @@ -1963,7 +1967,7 @@ impl Session { code_mode_service: crate::tools::code_mode::CodeModeService::new( config.js_repl_node_path.clone(), ), - environment: environment_manager.current().await?, + environment, }; services .model_client diff --git a/codex-rs/core/src/codex_tests.rs b/codex-rs/core/src/codex_tests.rs index 88a8902f85..cf7c23be90 100644 --- a/codex-rs/core/src/codex_tests.rs +++ b/codex-rs/core/src/codex_tests.rs @@ -2612,14 +2612,16 @@ async fn session_new_fails_when_zsh_fork_enabled_without_zsh_path() { agent_status_tx, InitialHistory::New, SessionSource::Exec, - Arc::new(codex_exec_server::EnvironmentManager::new( - /*exec_server_url*/ None, - )), skills_manager, plugins_manager, mcp_manager, Arc::new(SkillsWatcher::noop()), AgentControl::default(), + Some(Arc::new( + codex_exec_server::Environment::create(/*exec_server_url*/ None) + .await + .expect("create environment"), + )), ) .await; diff --git a/codex-rs/core/src/project_doc.rs b/codex-rs/core/src/project_doc.rs index 1b72f64610..236c25a3c5 100644 --- a/codex-rs/core/src/project_doc.rs +++ b/codex-rs/core/src/project_doc.rs @@ -21,10 +21,12 @@ use crate::config_loader::default_project_root_markers; use crate::config_loader::merge_toml_values; use crate::config_loader::project_root_markers_from_config; use codex_app_server_protocol::ConfigLayerSource; +use codex_exec_server::Environment; +use codex_exec_server::ExecutorFileSystem; use codex_features::Feature; +use codex_utils_absolute_path::AbsolutePathBuf; use dunce::canonicalize as normalize_path; -use std::path::PathBuf; -use tokio::io::AsyncReadExt; +use std::io; use toml::Value as TomlValue; use tracing::error; @@ -76,8 +78,19 @@ fn render_js_repl_instructions(config: &Config) -> Option { /// Combines `Config::instructions` and `AGENTS.md` (if present) into a single /// string of instructions. -pub(crate) async fn get_user_instructions(config: &Config) -> Option { - let project_docs = read_project_docs(config).await; +pub(crate) async fn get_user_instructions( + config: &Config, + environment: Option<&Environment>, +) -> Option { + let fs = environment?.get_filesystem(); + get_user_instructions_with_fs(config, fs.as_ref()).await +} + +pub(crate) async fn get_user_instructions_with_fs( + config: &Config, + fs: &dyn ExecutorFileSystem, +) -> Option { + let project_docs = read_project_docs_with_fs(config, fs).await; let mut output = String::new(); @@ -125,14 +138,25 @@ pub(crate) async fn get_user_instructions(config: &Config) -> Option { /// concatenation of all discovered docs. If no documentation file is found the /// function returns `Ok(None)`. Unexpected I/O failures bubble up as `Err` so /// callers can decide how to handle them. -pub async fn read_project_docs(config: &Config) -> std::io::Result> { +pub async fn read_project_docs( + config: &Config, + environment: &Environment, +) -> io::Result> { + let fs = environment.get_filesystem(); + read_project_docs_with_fs(config, fs.as_ref()).await +} + +async fn read_project_docs_with_fs( + config: &Config, + fs: &dyn ExecutorFileSystem, +) -> io::Result> { let max_total = config.project_doc_max_bytes; if max_total == 0 { return Ok(None); } - let paths = discover_project_doc_paths(config)?; + let paths = discover_project_doc_paths(config, fs).await?; if paths.is_empty() { return Ok(None); } @@ -145,16 +169,22 @@ pub async fn read_project_docs(config: &Config) -> std::io::Result f, - Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue, - Err(e) => return Err(e), - }; + match fs.get_metadata(&p).await { + Ok(metadata) if !metadata.is_file => continue, + Ok(_) => {} + Err(err) if err.kind() == io::ErrorKind::NotFound => continue, + Err(err) => return Err(err), + } - let size = file.metadata().await?.len(); - let mut reader = tokio::io::BufReader::new(file).take(remaining); - let mut data: Vec = Vec::new(); - reader.read_to_end(&mut data).await?; + let mut data = match fs.read_file(&p).await { + Ok(data) => data, + Err(err) if err.kind() == io::ErrorKind::NotFound => continue, + Err(err) => return Err(err), + }; + let size = data.len() as u64; + if size > remaining { + data.truncate(remaining as usize); + } if size > remaining { tracing::warn!( @@ -183,10 +213,17 @@ pub async fn read_project_docs(config: &Config) -> std::io::Result std::io::Result> { - let mut dir = config.cwd.to_path_buf(); +pub async fn discover_project_doc_paths( + config: &Config, + fs: &dyn ExecutorFileSystem, +) -> io::Result> { + if config.project_doc_max_bytes == 0 { + return Ok(Vec::new()); + } + + let mut dir = config.cwd.clone(); if let Ok(canon) = normalize_path(&dir) { - dir = canon; + dir = AbsolutePathBuf::try_from(canon)?; } let mut merged = TomlValue::Table(toml::map::Map::new()); @@ -211,14 +248,14 @@ pub fn discover_project_doc_paths(config: &Config) -> std::io::Result true, - Err(e) if e.kind() == std::io::ErrorKind::NotFound => false, - Err(e) => return Err(e), + Err(err) if err.kind() == io::ErrorKind::NotFound => false, + Err(err) => return Err(err), }; if marker_exists { - project_root = Some(ancestor.to_path_buf()); + project_root = Some(AbsolutePathBuf::try_from(ancestor.to_path_buf())?); break; } } @@ -228,11 +265,11 @@ pub fn discover_project_doc_paths(config: &Config) -> std::io::Result = if let Some(root) = project_root { + let search_dirs: Vec = if let Some(root) = project_root { let mut dirs = Vec::new(); - let mut cursor = dir.as_path(); + let mut cursor = dir.clone(); loop { - dirs.push(cursor.to_path_buf()); + dirs.push(cursor.clone()); if cursor == root { break; } @@ -247,29 +284,25 @@ pub fn discover_project_doc_paths(config: &Config) -> std::io::Result = Vec::new(); + let mut found: Vec = Vec::new(); let candidate_filenames = candidate_filenames(config); for d in search_dirs { for name in &candidate_filenames { - let candidate = d.join(name); - match std::fs::symlink_metadata(&candidate) { - Ok(md) => { - let ft = md.file_type(); - // Allow regular files and symlinks; opening will later fail for dangling links. - if ft.is_file() || ft.is_symlink() { - found.push(candidate); - break; - } + let candidate = d.join(name)?; + match fs.get_metadata(&candidate).await { + Ok(md) if md.is_file => { + found.push(candidate); + break; } - Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue, - Err(e) => return Err(e), + Ok(_) => {} + Err(err) if err.kind() == io::ErrorKind::NotFound => continue, + Err(err) => return Err(err), } } } Ok(found) } - fn candidate_filenames<'a>(config: &'a Config) -> Vec<&'a str> { let mut names: Vec<&'a str> = Vec::with_capacity(2 + config.project_doc_fallback_filenames.len()); diff --git a/codex-rs/core/src/project_doc_tests.rs b/codex-rs/core/src/project_doc_tests.rs index 9f4d9c5286..be9cb44b28 100644 --- a/codex-rs/core/src/project_doc_tests.rs +++ b/codex-rs/core/src/project_doc_tests.rs @@ -1,12 +1,23 @@ use super::*; use crate::config::ConfigBuilder; +use codex_exec_server::LOCAL_FS; use codex_features::Feature; +use codex_utils_absolute_path::AbsolutePathBuf; use core_test_support::PathBufExt; use core_test_support::TempDirExt; +use pretty_assertions::assert_eq; use std::fs; use std::path::PathBuf; use tempfile::TempDir; +async fn get_user_instructions(config: &Config) -> Option { + super::get_user_instructions_with_fs(config, LOCAL_FS.as_ref()).await +} + +async fn discover_project_doc_paths(config: &Config) -> std::io::Result> { + super::discover_project_doc_paths(config, LOCAL_FS.as_ref()).await +} + /// Helper that returns a `Config` pointing at `root` and using `limit` as /// the maximum number of bytes to embed from AGENTS.md. The caller can /// optionally specify a custom `instructions` string – when `None` the @@ -85,6 +96,16 @@ async fn no_doc_file_returns_none() { assert!(res.is_none(), "Expected None when AGENTS.md is absent"); } +#[tokio::test] +async fn no_environment_returns_none() { + let tmp = tempfile::tempdir().expect("tempdir"); + let config = make_config(&tmp, /*limit*/ 4096, Some("user instructions")).await; + + let res = super::get_user_instructions(&config, /*environment*/ None).await; + + assert_eq!(res, None); +} + /// Small file within the byte-limit is returned unmodified. #[tokio::test] async fn doc_smaller_than_limit_is_returned() { @@ -161,6 +182,18 @@ async fn zero_byte_limit_disables_docs() { ); } +#[tokio::test] +async fn zero_byte_limit_disables_discovery() { + let tmp = tempfile::tempdir().expect("tempdir"); + fs::write(tmp.path().join("AGENTS.md"), "something").unwrap(); + + let discovery = + discover_project_doc_paths(&make_config(&tmp, /*limit*/ 0, /*instructions*/ None).await) + .await + .expect("discover paths"); + assert_eq!(discovery, Vec::::new()); +} + #[tokio::test] async fn js_repl_instructions_are_appended_when_enabled() { let tmp = tempfile::tempdir().expect("tempdir"); @@ -293,11 +326,18 @@ async fn project_root_markers_are_honored_for_agents_discovery() { .await; cfg.cwd = nested.abs(); - let discovery = discover_project_doc_paths(&cfg).expect("discover paths"); - let expected_parent = - dunce::canonicalize(root.path().join("AGENTS.md")).expect("canonical parent doc path"); - let expected_child = - dunce::canonicalize(cfg.cwd.as_path().join("AGENTS.md")).expect("canonical child doc path"); + let discovery = discover_project_doc_paths(&cfg) + .await + .expect("discover paths"); + let expected_parent = AbsolutePathBuf::try_from( + dunce::canonicalize(root.path().join("AGENTS.md")).expect("canonical parent doc path"), + ) + .expect("absolute parent doc path"); + let expected_child = AbsolutePathBuf::try_from( + dunce::canonicalize(cfg.cwd.join("AGENTS.md").expect("absolute child doc path")) + .expect("canonical child doc path"), + ) + .expect("absolute child doc path"); assert_eq!(discovery.len(), 2); assert_eq!(discovery[0], expected_parent); assert_eq!(discovery[1], expected_child); @@ -321,7 +361,9 @@ async fn agents_local_md_preferred() { assert_eq!(res, "local"); - let discovery = discover_project_doc_paths(&cfg).expect("discover paths"); + let discovery = discover_project_doc_paths(&cfg) + .await + .expect("discover paths"); assert_eq!(discovery.len(), 1); assert_eq!( discovery[0].file_name().unwrap().to_string_lossy(), @@ -371,7 +413,9 @@ async fn agents_md_preferred_over_fallbacks() { assert_eq!(res, "primary"); - let discovery = discover_project_doc_paths(&cfg).expect("discover paths"); + let discovery = discover_project_doc_paths(&cfg) + .await + .expect("discover paths"); assert_eq!(discovery.len(), 1); assert!( discovery[0] @@ -382,6 +426,73 @@ async fn agents_md_preferred_over_fallbacks() { ); } +#[tokio::test] +async fn agents_md_directory_is_ignored() { + let tmp = tempfile::tempdir().expect("tempdir"); + fs::create_dir(tmp.path().join("AGENTS.md")).unwrap(); + + let cfg = make_config(&tmp, /*limit*/ 4096, /*instructions*/ None).await; + + let res = get_user_instructions(&cfg).await; + assert_eq!(res, None); + + let discovery = discover_project_doc_paths(&cfg) + .await + .expect("discover paths"); + assert_eq!(discovery, Vec::::new()); +} + +#[cfg(unix)] +#[tokio::test] +async fn agents_md_special_file_is_ignored() { + use std::ffi::CString; + use std::os::unix::ffi::OsStrExt; + + let tmp = tempfile::tempdir().expect("tempdir"); + let path = tmp.path().join("AGENTS.md"); + let c_path = CString::new(path.as_os_str().as_bytes()).expect("path without nul"); + // SAFETY: `c_path` is a valid, nul-terminated path and `mkfifo` does not + // retain the pointer after the call. + let rc = unsafe { libc::mkfifo(c_path.as_ptr(), 0o644) }; + assert_eq!(rc, 0); + + let cfg = make_config(&tmp, /*limit*/ 4096, /*instructions*/ None).await; + + let res = get_user_instructions(&cfg).await; + assert_eq!(res, None); + + let discovery = discover_project_doc_paths(&cfg) + .await + .expect("discover paths"); + assert_eq!(discovery, Vec::::new()); +} + +#[tokio::test] +async fn override_directory_falls_back_to_agents_md_file() { + let tmp = tempfile::tempdir().expect("tempdir"); + fs::create_dir(tmp.path().join(LOCAL_PROJECT_DOC_FILENAME)).unwrap(); + fs::write(tmp.path().join(DEFAULT_PROJECT_DOC_FILENAME), "primary").unwrap(); + + let cfg = make_config(&tmp, /*limit*/ 4096, /*instructions*/ None).await; + + let res = get_user_instructions(&cfg) + .await + .expect("AGENTS.md should be used when override is a directory"); + assert_eq!(res, "primary"); + + let discovery = discover_project_doc_paths(&cfg) + .await + .expect("discover paths"); + assert_eq!(discovery.len(), 1); + assert_eq!( + discovery[0] + .file_name() + .expect("file name") + .to_string_lossy(), + DEFAULT_PROJECT_DOC_FILENAME + ); +} + #[tokio::test] async fn skills_are_not_appended_to_project_doc() { let tmp = tempfile::tempdir().expect("tempdir"); diff --git a/codex-rs/core/tests/common/test_codex.rs b/codex-rs/core/tests/common/test_codex.rs index 10957fd9f0..bffd0cbfd6 100644 --- a/codex-rs/core/tests/common/test_codex.rs +++ b/codex-rs/core/tests/common/test_codex.rs @@ -1,3 +1,4 @@ +use std::future::Future; use std::mem::swap; use std::path::Path; use std::path::PathBuf; @@ -34,12 +35,12 @@ use codex_protocol::protocol::SessionConfiguredEvent; use codex_protocol::protocol::SessionSource; use codex_protocol::user_input::UserInput; use codex_utils_absolute_path::AbsolutePathBuf; +use futures::future::BoxFuture; use serde_json::Value; use tempfile::TempDir; use wiremock::MockServer; use crate::PathBufExt; -use crate::PathExt; use crate::RemoteEnvConfig; use crate::TempDirExt; use crate::get_remote_test_env; @@ -55,6 +56,8 @@ use wiremock::matchers::path_regex; type ConfigMutator = dyn FnOnce(&mut Config) + Send; type PreBuildHook = dyn FnOnce(&Path) + Send + 'static; +type WorkspaceSetup = dyn FnOnce(AbsolutePathBuf, Arc) -> BoxFuture<'static, Result<()>> + + Send; const TEST_MODEL_WITH_EXPERIMENTAL_TOOLS: &str = "test-gpt-5.1-codex"; const REMOTE_EXEC_SERVER_START_TIMEOUT: Duration = Duration::from_secs(5); const REMOTE_EXEC_SERVER_POLL_INTERVAL: Duration = Duration::from_millis(25); @@ -97,24 +100,28 @@ impl RemoteExecServerProcess { #[derive(Debug)] pub struct TestEnv { environment: codex_exec_server::Environment, - cwd: PathBuf, - _local_cwd_temp_dir: Option, + cwd: AbsolutePathBuf, + local_cwd_temp_dir: Option>, _remote_exec_server_process: Option, } impl TestEnv { pub async fn local() -> Result { - let local_cwd_temp_dir = TempDir::new()?; - let cwd = local_cwd_temp_dir.path().to_path_buf(); + let local_cwd_temp_dir = Arc::new(TempDir::new()?); + let cwd = local_cwd_temp_dir.abs(); let environment = codex_exec_server::Environment::create(/*exec_server_url*/ None).await?; Ok(Self { environment, cwd, - _local_cwd_temp_dir: Some(local_cwd_temp_dir), + local_cwd_temp_dir: Some(local_cwd_temp_dir), _remote_exec_server_process: None, }) } + pub fn cwd(&self) -> &AbsolutePathBuf { + &self.cwd + } + pub fn environment(&self) -> &codex_exec_server::Environment { &self.environment } @@ -122,6 +129,10 @@ impl TestEnv { pub fn exec_server_url(&self) -> Option<&str> { self.environment.exec_server_url() } + + fn local_cwd_temp_dir(&self) -> Option> { + self.local_cwd_temp_dir.clone() + } } pub async fn test_env() -> Result { @@ -134,16 +145,13 @@ pub async fn test_env() -> Result { let cwd = remote_aware_cwd_path(); environment .get_filesystem() - .create_directory( - &absolute_path(&cwd)?, - CreateDirectoryOptions { recursive: true }, - ) + .create_directory(&cwd, CreateDirectoryOptions { recursive: true }) .await?; - remote_process.process.register_cleanup_path(&cwd); + remote_process.process.register_cleanup_path(cwd.as_path()); Ok(TestEnv { environment, cwd, - _local_cwd_temp_dir: None, + local_cwd_temp_dir: None, _remote_exec_server_process: Some(remote_process.process), }) } @@ -201,11 +209,12 @@ echo $!" }) } -fn remote_aware_cwd_path() -> PathBuf { +fn remote_aware_cwd_path() -> AbsolutePathBuf { PathBuf::from(format!( "/tmp/codex-core-test-cwd-{}", remote_exec_server_instance_id() )) + .abs() } fn wait_for_remote_listen_url(container_name: &str, stdout_path: &str) -> Result { @@ -299,10 +308,6 @@ fn docker_command_capture_stdout(args: [&str; N]) -> Result Result { - Ok(path.abs()) -} - /// A collection of different ways the model can output an apply_patch call #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub enum ApplyPatchModelOutput { @@ -326,6 +331,7 @@ pub struct TestCodexBuilder { config_mutators: Vec>, auth: CodexAuth, pre_build_hooks: Vec>, + workspace_setups: Vec>, home: Option>, user_shell_override: Option, } @@ -359,6 +365,16 @@ impl TestCodexBuilder { self } + pub fn with_workspace_setup(mut self, setup: F) -> Self + where + F: FnOnce(AbsolutePathBuf, Arc) -> Fut + Send + 'static, + Fut: Future> + Send + 'static, + { + self.workspace_setups + .push(Box::new(move |cwd, fs| Box::pin(setup(cwd, fs)))); + self + } + pub fn with_home(mut self, home: Arc) -> Self { self.home = Some(home); self @@ -382,25 +398,24 @@ impl TestCodexBuilder { Some(home) => home, None => Arc::new(TempDir::new()?), }; - Box::pin(self.build_with_home(server, home, /*resume_from*/ None)).await + let base_url = format!("{}/v1", server.uri()); + let test_env = TestEnv::local().await?; + Box::pin(self.build_with_home_and_base_url(base_url, home, /*resume_from*/ None, test_env)) + .await } pub async fn build_remote_aware( &mut self, server: &wiremock::MockServer, ) -> anyhow::Result { - let test_env = test_env().await?; let home = match self.home.clone() { Some(home) => home, None => Arc::new(TempDir::new()?), }; let base_url = format!("{}/v1", server.uri()); - let cwd = test_env.cwd.to_path_buf(); - self.config_mutators.push(Box::new(move |config| { - config.cwd = cwd.abs(); - })); - let (config, cwd) = self.prepare_config(base_url, &home).await?; - Box::pin(self.build_from_config(config, cwd, home, /*resume_from*/ None, test_env)).await + let test_env = test_env().await?; + Box::pin(self.build_with_home_and_base_url(base_url, home, /*resume_from*/ None, test_env)) + .await } pub async fn build_with_streaming_server( @@ -412,10 +427,12 @@ impl TestCodexBuilder { Some(home) => home, None => Arc::new(TempDir::new()?), }; + let test_env = TestEnv::local().await?; Box::pin(self.build_with_home_and_base_url( format!("{base_url}/v1"), home, /*resume_from*/ None, + test_env, )) .await } @@ -435,7 +452,9 @@ impl TestCodexBuilder { config.model_provider.supports_websockets = true; config.experimental_realtime_ws_model = Some("realtime-test-model".to_string()); })); - Box::pin(self.build_with_home_and_base_url(base_url, home, /*resume_from*/ None)).await + let test_env = TestEnv::local().await?; + Box::pin(self.build_with_home_and_base_url(base_url, home, /*resume_from*/ None, test_env)) + .await } pub async fn resume( @@ -443,19 +462,10 @@ impl TestCodexBuilder { server: &wiremock::MockServer, home: Arc, rollout_path: PathBuf, - ) -> anyhow::Result { - Box::pin(self.build_with_home(server, home, Some(rollout_path))).await - } - - async fn build_with_home( - &mut self, - server: &wiremock::MockServer, - home: Arc, - resume_from: Option, ) -> anyhow::Result { let base_url = format!("{}/v1", server.uri()); - let (config, cwd) = self.prepare_config(base_url, &home).await?; - Box::pin(self.build_from_config(config, cwd, home, resume_from, TestEnv::local().await?)) + let test_env = TestEnv::local().await?; + Box::pin(self.build_with_home_and_base_url(base_url, home, Some(rollout_path), test_env)) .await } @@ -464,10 +474,30 @@ impl TestCodexBuilder { base_url: String, home: Arc, resume_from: Option, + test_env: TestEnv, ) -> anyhow::Result { - let (config, cwd) = self.prepare_config(base_url, &home).await?; - Box::pin(self.build_from_config(config, cwd, home, resume_from, TestEnv::local().await?)) - .await + let (config, fallback_cwd) = self + .prepare_config(base_url, &home, test_env.cwd().clone()) + .await?; + let environment_manager = Arc::new(codex_exec_server::EnvironmentManager::new( + test_env.exec_server_url().map(str::to_owned), + )); + let file_system = test_env.environment().get_filesystem(); + let mut workspace_setups = vec![]; + swap(&mut self.workspace_setups, &mut workspace_setups); + for setup in workspace_setups { + setup(config.cwd.clone(), Arc::clone(&file_system)).await?; + } + let cwd = test_env.local_cwd_temp_dir().unwrap_or(fallback_cwd); + Box::pin(self.build_from_config( + config, + cwd, + home, + resume_from, + test_env, + environment_manager, + )) + .await } async fn build_from_config( @@ -477,11 +507,9 @@ impl TestCodexBuilder { home: Arc, resume_from: Option, test_env: TestEnv, + environment_manager: Arc, ) -> anyhow::Result { let auth = self.auth.clone(); - let environment_manager = Arc::new(codex_exec_server::EnvironmentManager::new( - test_env.exec_server_url().map(str::to_owned), - )); let thread_manager = if config.model_catalog.is_some() { ThreadManager::new( &config, @@ -553,6 +581,7 @@ impl TestCodexBuilder { &mut self, base_url: String, home: &TempDir, + cwd_override: AbsolutePathBuf, ) -> anyhow::Result<(Config, Arc)> { let model_provider = ModelProviderInfo { base_url: Some(base_url), @@ -563,7 +592,7 @@ impl TestCodexBuilder { }; let cwd = Arc::new(TempDir::new()?); let mut config = load_default_config_for_test(home).await; - config.cwd = cwd.abs(); + config.cwd = cwd_override; config.model_provider = model_provider; for hook in self.pre_build_hooks.drain(..) { hook(home.path()); @@ -897,6 +926,7 @@ pub fn test_codex() -> TestCodexBuilder { config_mutators: vec![], auth: CodexAuth::from_api_key("dummy"), pre_build_hooks: vec![], + workspace_setups: vec![], home: None, user_shell_override: None, } diff --git a/codex-rs/core/tests/common/test_codex_exec.rs b/codex-rs/core/tests/common/test_codex_exec.rs index 5fe47018a6..ad32bcb025 100644 --- a/codex-rs/core/tests/common/test_codex_exec.rs +++ b/codex-rs/core/tests/common/test_codex_exec.rs @@ -17,6 +17,7 @@ impl TestCodexExecBuilder { ); cmd.current_dir(self.cwd.path()) .env("CODEX_HOME", self.home.path()) + .env("CODEX_SQLITE_HOME", self.home.path()) .env(CODEX_API_KEY_ENV_VAR, "dummy"); cmd } diff --git a/codex-rs/core/tests/suite/agents_md.rs b/codex-rs/core/tests/suite/agents_md.rs new file mode 100644 index 0000000000..7fbcc0703c --- /dev/null +++ b/codex-rs/core/tests/suite/agents_md.rs @@ -0,0 +1,130 @@ +use anyhow::Result; +use codex_exec_server::CreateDirectoryOptions; +use core_test_support::responses::ev_completed; +use core_test_support::responses::ev_response_created; +use core_test_support::responses::mount_sse_once; +use core_test_support::responses::sse; +use core_test_support::responses::start_mock_server; +use core_test_support::test_codex::TestCodexBuilder; +use core_test_support::test_codex::test_codex; + +async fn agents_instructions(mut builder: TestCodexBuilder) -> Result { + let server = start_mock_server().await; + let resp_mock = mount_sse_once( + &server, + sse(vec![ev_response_created("resp1"), ev_completed("resp1")]), + ) + .await; + + let test = builder.build_remote_aware(&server).await?; + test.submit_turn("hello").await?; + + let request = resp_mock.single_request(); + request + .message_input_texts("user") + .into_iter() + .find(|text| text.starts_with("# AGENTS.md instructions for ")) + .ok_or_else(|| anyhow::anyhow!("instructions message not found")) +} + +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn agents_override_is_preferred_over_agents_md() -> Result<()> { + let instructions = + agents_instructions(test_codex().with_workspace_setup(|cwd, fs| async move { + let agents_md = cwd.join("AGENTS.md").expect("absolute AGENTS.md path"); + let override_md = cwd + .join("AGENTS.override.md") + .expect("absolute AGENTS.override.md path"); + fs.write_file(&agents_md, b"base doc".to_vec()).await?; + fs.write_file(&override_md, b"override doc".to_vec()) + .await?; + Ok::<(), anyhow::Error>(()) + })) + .await?; + + assert!( + instructions.contains("override doc"), + "expected AGENTS.override.md contents: {instructions}" + ); + assert!( + !instructions.contains("base doc"), + "expected AGENTS.md to be ignored when override exists: {instructions}" + ); + + Ok(()) +} + +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn configured_fallback_is_used_when_agents_candidate_is_directory() -> Result<()> { + let instructions = agents_instructions( + test_codex() + .with_config(|config| { + config.project_doc_fallback_filenames = vec!["WORKFLOW.md".to_string()]; + }) + .with_workspace_setup(|cwd, fs| async move { + let agents_dir = cwd.join("AGENTS.md").expect("absolute AGENTS.md path"); + let fallback = cwd.join("WORKFLOW.md").expect("absolute WORKFLOW.md path"); + fs.create_directory(&agents_dir, CreateDirectoryOptions { recursive: true }) + .await?; + fs.write_file(&fallback, b"fallback doc".to_vec()).await?; + Ok::<(), anyhow::Error>(()) + }), + ) + .await?; + + assert!( + instructions.contains("fallback doc"), + "expected fallback doc contents: {instructions}" + ); + + Ok(()) +} + +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn agents_docs_are_concatenated_from_project_root_to_cwd() -> Result<()> { + let instructions = agents_instructions( + test_codex() + .with_config(|config| { + config.cwd = config + .cwd + .join("nested/workspace") + .expect("absolute nested workspace path"); + }) + .with_workspace_setup(|cwd, fs| async move { + let nested = cwd.clone(); + let root = nested + .parent() + .and_then(|parent| parent.parent()) + .expect("nested workspace should have a project root ancestor"); + let root_agents = root + .join("AGENTS.md") + .expect("absolute root AGENTS.md path"); + let git_marker = root.join(".git").expect("absolute .git path"); + let nested_agents = nested + .join("AGENTS.md") + .expect("absolute nested AGENTS.md path"); + + fs.create_directory(&nested, CreateDirectoryOptions { recursive: true }) + .await?; + fs.write_file(&root_agents, b"root doc".to_vec()).await?; + fs.write_file(&git_marker, b"gitdir: /tmp/mock-git-dir\n".to_vec()) + .await?; + fs.write_file(&nested_agents, b"child doc".to_vec()).await?; + Ok::<(), anyhow::Error>(()) + }), + ) + .await?; + + let root_pos = instructions + .find("root doc") + .expect("expected root doc in AGENTS instructions"); + let child_pos = instructions + .find("child doc") + .expect("expected child doc in AGENTS instructions"); + assert!( + root_pos < child_pos, + "expected root doc before child doc: {instructions}" + ); + + Ok(()) +} diff --git a/codex-rs/core/tests/suite/hierarchical_agents.rs b/codex-rs/core/tests/suite/hierarchical_agents.rs index 8a3fadfbb0..bddc1a5276 100644 --- a/codex-rs/core/tests/suite/hierarchical_agents.rs +++ b/codex-rs/core/tests/suite/hierarchical_agents.rs @@ -18,21 +18,22 @@ async fn hierarchical_agents_appends_to_project_doc_in_user_instructions() { ) .await; - let mut builder = test_codex().with_config(|config| { - config - .features - .enable(Feature::ChildAgentsMd) - .expect("test config should allow feature update"); - std::fs::write( + let mut builder = test_codex() + .with_config(|config| { config - .cwd - .join("AGENTS.md") - .expect("absolute AGENTS.md path"), - "be nice", - ) - .expect("write AGENTS.md"); - }); - let test = builder.build(&server).await.expect("build test codex"); + .features + .enable(Feature::ChildAgentsMd) + .expect("test config should allow feature update"); + }) + .with_workspace_setup(|cwd, fs| async move { + let agents_md = cwd.join("AGENTS.md").expect("absolute AGENTS.md path"); + fs.write_file(&agents_md, b"be nice".to_vec()).await?; + Ok::<(), anyhow::Error>(()) + }); + let test = builder + .build_remote_aware(&server) + .await + .expect("build test codex"); test.submit_turn("hello").await.expect("submit turn"); @@ -73,7 +74,10 @@ async fn hierarchical_agents_emits_when_no_project_doc() { .enable(Feature::ChildAgentsMd) .expect("test config should allow feature update"); }); - let test = builder.build(&server).await.expect("build test codex"); + let test = builder + .build_remote_aware(&server) + .await + .expect("build test codex"); test.submit_turn("hello").await.expect("submit turn"); diff --git a/codex-rs/core/tests/suite/mod.rs b/codex-rs/core/tests/suite/mod.rs index 4d58537e02..78dcf748a3 100644 --- a/codex-rs/core/tests/suite/mod.rs +++ b/codex-rs/core/tests/suite/mod.rs @@ -74,6 +74,7 @@ pub static CODEX_ALIASES_TEMP_DIR: Option = { mod abort_tasks; mod agent_jobs; mod agent_websocket; +mod agents_md; mod apply_patch_cli; #[cfg(not(target_os = "windows"))] mod approvals; diff --git a/codex-rs/core/tests/suite/remote_env.rs b/codex-rs/core/tests/suite/remote_env.rs index 0dd7718d3a..4cd9568a58 100644 --- a/codex-rs/core/tests/suite/remote_env.rs +++ b/codex-rs/core/tests/suite/remote_env.rs @@ -1,6 +1,6 @@ use anyhow::Result; use codex_exec_server::RemoveOptions; -use codex_utils_absolute_path::AbsolutePathBuf; +use core_test_support::PathBufExt; use core_test_support::get_remote_test_env; use core_test_support::test_codex::test_env; use pretty_assertions::assert_eq; @@ -17,8 +17,7 @@ async fn remote_test_env_can_connect_and_use_filesystem() -> Result<()> { let test_env = test_env().await?; let file_system = test_env.environment().get_filesystem(); - let file_path = remote_test_file_path(); - let file_path_abs = absolute_path(file_path.clone())?; + let file_path_abs = remote_test_file_path().abs(); let payload = b"remote-test-env-ok".to_vec(); file_system @@ -39,12 +38,6 @@ async fn remote_test_env_can_connect_and_use_filesystem() -> Result<()> { Ok(()) } - -fn absolute_path(path: PathBuf) -> Result { - AbsolutePathBuf::try_from(path.clone()) - .map_err(|err| anyhow::anyhow!("invalid absolute path {}: {err}", path.display())) -} - fn remote_test_file_path() -> PathBuf { let nanos = match SystemTime::now().duration_since(UNIX_EPOCH) { Ok(duration) => duration.as_nanos(), diff --git a/codex-rs/exec-server/src/lib.rs b/codex-rs/exec-server/src/lib.rs index ab27ab2397..88378da9ee 100644 --- a/codex-rs/exec-server/src/lib.rs +++ b/codex-rs/exec-server/src/lib.rs @@ -41,6 +41,7 @@ pub use file_system::FileMetadata; pub use file_system::FileSystemResult; pub use file_system::ReadDirectoryEntry; pub use file_system::RemoveOptions; +pub use local_file_system::LOCAL_FS; pub use process::ExecBackend; pub use process::ExecProcess; pub use process::StartedExecProcess; diff --git a/codex-rs/exec-server/src/local_file_system.rs b/codex-rs/exec-server/src/local_file_system.rs index fba7efa306..69ab9d64b0 100644 --- a/codex-rs/exec-server/src/local_file_system.rs +++ b/codex-rs/exec-server/src/local_file_system.rs @@ -3,6 +3,8 @@ use codex_utils_absolute_path::AbsolutePathBuf; use std::path::Component; use std::path::Path; use std::path::PathBuf; +use std::sync::Arc; +use std::sync::LazyLock; use std::time::SystemTime; use std::time::UNIX_EPOCH; use tokio::io; @@ -17,6 +19,9 @@ use crate::RemoveOptions; const MAX_READ_FILE_BYTES: u64 = 512 * 1024 * 1024; +pub static LOCAL_FS: LazyLock> = + LazyLock::new(|| -> Arc { Arc::new(LocalFileSystem) }); + #[derive(Clone, Default)] pub(crate) struct LocalFileSystem; diff --git a/codex-rs/exec-server/src/remote_file_system.rs b/codex-rs/exec-server/src/remote_file_system.rs index 27e4fee911..7da10b0e50 100644 --- a/codex-rs/exec-server/src/remote_file_system.rs +++ b/codex-rs/exec-server/src/remote_file_system.rs @@ -23,6 +23,7 @@ use crate::ReadDirectoryEntry; use crate::RemoveOptions; const INVALID_REQUEST_ERROR_CODE: i64 = -32600; +const NOT_FOUND_ERROR_CODE: i64 = -32004; #[derive(Clone)] pub(crate) struct RemoteFileSystem { @@ -151,6 +152,9 @@ impl ExecutorFileSystem for RemoteFileSystem { fn map_remote_error(error: ExecServerError) -> io::Error { match error { + ExecServerError::Server { code, message } if code == NOT_FOUND_ERROR_CODE => { + io::Error::new(io::ErrorKind::NotFound, message) + } ExecServerError::Server { code, message } if code == INVALID_REQUEST_ERROR_CODE => { io::Error::new(io::ErrorKind::InvalidInput, message) } diff --git a/codex-rs/exec-server/src/rpc.rs b/codex-rs/exec-server/src/rpc.rs index f2d725e69c..bf7cb27a5a 100644 --- a/codex-rs/exec-server/src/rpc.rs +++ b/codex-rs/exec-server/src/rpc.rs @@ -356,6 +356,14 @@ pub(crate) fn invalid_params(message: String) -> JSONRPCErrorError { } } +pub(crate) fn not_found(message: String) -> JSONRPCErrorError { + JSONRPCErrorError { + code: -32004, + data: None, + message, + } +} + pub(crate) fn internal_error(message: String) -> JSONRPCErrorError { JSONRPCErrorError { code: -32603, diff --git a/codex-rs/exec-server/src/server/file_system_handler.rs b/codex-rs/exec-server/src/server/file_system_handler.rs index 2e4e1592d1..2f6c679dcc 100644 --- a/codex-rs/exec-server/src/server/file_system_handler.rs +++ b/codex-rs/exec-server/src/server/file_system_handler.rs @@ -26,6 +26,7 @@ use crate::RemoveOptions; use crate::local_file_system::LocalFileSystem; use crate::rpc::internal_error; use crate::rpc::invalid_request; +use crate::rpc::not_found; #[derive(Clone, Default)] pub(crate) struct FileSystemHandler { @@ -153,7 +154,9 @@ impl FileSystemHandler { } fn map_fs_error(err: io::Error) -> JSONRPCErrorError { - if err.kind() == io::ErrorKind::InvalidInput { + if err.kind() == io::ErrorKind::NotFound { + not_found(err.to_string()) + } else if err.kind() == io::ErrorKind::InvalidInput { invalid_request(err.to_string()) } else { internal_error(err.to_string()) diff --git a/codex-rs/tui/Cargo.toml b/codex-rs/tui/Cargo.toml index 8c68de0da6..713a5b38ae 100644 --- a/codex-rs/tui/Cargo.toml +++ b/codex-rs/tui/Cargo.toml @@ -33,6 +33,7 @@ codex-chatgpt = { workspace = true } codex-cloud-requirements = { workspace = true } codex-config = { workspace = true } codex-core = { workspace = true } +codex-exec-server = { workspace = true } codex-features = { workspace = true } codex-feedback = { workspace = true } codex-file-search = { workspace = true } diff --git a/codex-rs/tui/src/chatwidget.rs b/codex-rs/tui/src/chatwidget.rs index 786911f158..f942308aa7 100644 --- a/codex-rs/tui/src/chatwidget.rs +++ b/codex-rs/tui/src/chatwidget.rs @@ -7303,6 +7303,8 @@ impl ChatWidget { .values() .cloned() .collect(); + let config = self.config.clone(); + let frame_requester = self.frame_requester.clone(); let (cell, handle) = crate::status::new_status_output_with_rate_limits_handle( &self.config, self.status_account_display.as_ref(), @@ -7317,8 +7319,21 @@ impl ChatWidget { self.model_display_name(), collaboration_mode, reasoning_effort_override, + "".to_string(), refreshing_rate_limits, ); + let agents_summary_handle = handle.clone(); + tokio::spawn(async move { + let agents_summary = match crate::status::discover_agents_summary(&config).await { + Ok(summary) => summary, + Err(err) => { + tracing::warn!(error = %err, "failed to discover project docs for /status"); + "".to_string() + } + }; + agents_summary_handle.finish_agents_summary_discovery(agents_summary); + frame_requester.schedule_frame(); + }); if let Some(request_id) = request_id { self.refreshing_status_outputs.push((request_id, handle)); } diff --git a/codex-rs/tui/src/status/card.rs b/codex-rs/tui/src/status/card.rs index 781f4ae311..a737262139 100644 --- a/codex-rs/tui/src/status/card.rs +++ b/codex-rs/tui/src/status/card.rs @@ -28,7 +28,6 @@ use super::format::line_display_width; use super::format::push_label; use super::format::truncate_line_to_width; use super::helpers::compose_account_display; -use super::helpers::compose_agents_summary; use super::helpers::compose_model_display; use super::helpers::format_directory_display; use super::helpers::format_tokens_compact; @@ -68,10 +67,20 @@ struct StatusRateLimitState { #[derive(Debug, Clone)] pub(crate) struct StatusHistoryHandle { + agents_summary: Arc>, rate_limit_state: Arc>, } impl StatusHistoryHandle { + pub(crate) fn finish_agents_summary_discovery(&self, agents_summary: String) { + #[expect(clippy::expect_used)] + let mut current = self + .agents_summary + .write() + .expect("status history agents summary state poisoned"); + *current = agents_summary; + } + pub(crate) fn finish_rate_limit_refresh( &self, rate_limits: &[RateLimitSnapshotDisplay], @@ -98,7 +107,7 @@ struct StatusHistoryCell { model_details: Vec, directory: PathBuf, permissions: String, - agents_summary: String, + agents_summary: Arc>, collaboration_mode: Option, model_provider: Option, account: Option, @@ -177,6 +186,7 @@ pub(crate) fn new_status_output_with_rate_limits( model_name, collaboration_mode, reasoning_effort_override, + "".to_string(), refreshing_rate_limits, ) .0 @@ -197,6 +207,7 @@ pub(crate) fn new_status_output_with_rate_limits_handle( model_name: &str, collaboration_mode: Option<&str>, reasoning_effort_override: Option>, + agents_summary: String, refreshing_rate_limits: bool, ) -> (CompositeHistoryCell, StatusHistoryHandle) { let command = PlainHistoryCell::new(vec!["/status".magenta().into()]); @@ -214,6 +225,7 @@ pub(crate) fn new_status_output_with_rate_limits_handle( model_name, collaboration_mode, reasoning_effort_override, + agents_summary, refreshing_rate_limits, ); @@ -239,6 +251,7 @@ impl StatusHistoryCell { model_name: &str, collaboration_mode: Option<&str>, reasoning_effort_override: Option>, + agents_summary: String, refreshing_rate_limits: bool, ) -> (Self, StatusHistoryHandle) { let mut config_entries = vec![ @@ -302,7 +315,6 @@ impl StatusHistoryCell { } else { format!("Custom ({sandbox}, {approval})") }; - let agents_summary = compose_agents_summary(config); let model_provider = format_model_provider(config); let account = compose_account_display(account_display); let session_id = session_id.as_ref().map(std::string::ToString::to_string); @@ -333,6 +345,7 @@ impl StatusHistoryCell { rate_limits, refreshing_rate_limits, })); + let agents_summary = Arc::new(RwLock::new(agents_summary)); ( Self { @@ -340,7 +353,6 @@ impl StatusHistoryCell { model_details, directory: config.cwd.to_path_buf(), permissions, - agents_summary, collaboration_mode: collaboration_mode.map(ToString::to_string), model_provider, account, @@ -348,9 +360,13 @@ impl StatusHistoryCell { session_id, forked_from, token_usage, + agents_summary: agents_summary.clone(), rate_limit_state: rate_limit_state.clone(), }, - StatusHistoryHandle { rate_limit_state }, + StatusHistoryHandle { + agents_summary, + rate_limit_state, + }, ) } @@ -564,6 +580,12 @@ impl HistoryCell for StatusHistoryCell { .rate_limit_state .read() .expect("status history rate-limit state poisoned"); + #[expect(clippy::expect_used)] + let agents_summary = self + .agents_summary + .read() + .expect("status history agents summary state poisoned") + .clone(); if self.model_provider.is_some() { push_label(&mut labels, &mut seen, "Model provider"); @@ -625,7 +647,7 @@ impl HistoryCell for StatusHistoryCell { } lines.push(formatter.line("Directory", vec![Span::from(directory_value)])); lines.push(formatter.line("Permissions", vec![Span::from(self.permissions.clone())])); - lines.push(formatter.line("Agents.md", vec![Span::from(self.agents_summary.clone())])); + lines.push(formatter.line("Agents.md", vec![Span::from(agents_summary)])); if let Some(account_value) = account_value { lines.push(formatter.line("Account", vec![Span::from(account_value)])); diff --git a/codex-rs/tui/src/status/helpers.rs b/codex-rs/tui/src/status/helpers.rs index 7813094c35..9f4c8f793b 100644 --- a/codex-rs/tui/src/status/helpers.rs +++ b/codex-rs/tui/src/status/helpers.rs @@ -5,7 +5,10 @@ use chrono::DateTime; use chrono::Local; use codex_core::config::Config; use codex_core::project_doc::discover_project_doc_paths; +use codex_exec_server::LOCAL_FS; use codex_protocol::account::PlanType; +use codex_utils_absolute_path::AbsolutePathBuf; +use std::io; use std::path::Path; use unicode_width::UnicodeWidthStr; @@ -33,51 +36,52 @@ pub(crate) fn compose_model_display( (model_name.to_string(), details) } -pub(crate) fn compose_agents_summary(config: &Config) -> String { - match discover_project_doc_paths(config) { - Ok(paths) => { - let mut rels: Vec = Vec::new(); - for p in paths { - let file_name = p - .file_name() - .map(|name| name.to_string_lossy().to_string()) - .unwrap_or_else(|| "".to_string()); - let display = if let Some(parent) = p.parent() { - if parent == config.cwd.as_path() { - file_name.clone() - } else { - let mut cur = config.cwd.as_path(); - let mut ups = 0usize; - let mut reached = false; - while let Some(c) = cur.parent() { - if cur == parent { - reached = true; - break; - } - cur = c; - ups += 1; - } - if reached { - let up = format!("..{}", std::path::MAIN_SEPARATOR); - format!("{}{}", up.repeat(ups), file_name) - } else if let Ok(stripped) = p.strip_prefix(&config.cwd) { - normalize_agents_display_path(stripped) - } else { - normalize_agents_display_path(&p) - } - } - } else { - normalize_agents_display_path(&p) - }; - rels.push(display); - } - if rels.is_empty() { - "".to_string() +pub(crate) async fn discover_agents_summary(config: &Config) -> io::Result { + let paths = discover_project_doc_paths(config, LOCAL_FS.as_ref()).await?; + Ok(compose_agents_summary(config, &paths)) +} + +pub(crate) fn compose_agents_summary(config: &Config, paths: &[AbsolutePathBuf]) -> String { + let mut rels: Vec = Vec::new(); + for p in paths { + let file_name = p + .file_name() + .map(|name| name.to_string_lossy().to_string()) + .unwrap_or_else(|| "".to_string()); + let display = if let Some(parent) = p.parent() { + if parent.as_path() == config.cwd.as_path() { + file_name.clone() } else { - rels.join(", ") + let mut cur = config.cwd.as_path(); + let mut ups = 0usize; + let mut reached = false; + while let Some(c) = cur.parent() { + if cur == parent.as_path() { + reached = true; + break; + } + cur = c; + ups += 1; + } + if reached { + let up = format!("..{}", std::path::MAIN_SEPARATOR); + format!("{}{}", up.repeat(ups), file_name) + } else if let Ok(stripped) = p.strip_prefix(&config.cwd) { + normalize_agents_display_path(stripped) + } else { + normalize_agents_display_path(p) + } } - } - Err(_) => "".to_string(), + } else { + normalize_agents_display_path(p) + }; + rels.push(display); + } + + if rels.is_empty() { + "".to_string() + } else { + rels.join(", ") } } diff --git a/codex-rs/tui/src/status/mod.rs b/codex-rs/tui/src/status/mod.rs index e09955a6a6..1781104efd 100644 --- a/codex-rs/tui/src/status/mod.rs +++ b/codex-rs/tui/src/status/mod.rs @@ -19,6 +19,7 @@ pub(crate) use card::new_status_output; #[cfg(test)] pub(crate) use card::new_status_output_with_rate_limits; pub(crate) use card::new_status_output_with_rate_limits_handle; +pub(crate) use helpers::discover_agents_summary; pub(crate) use helpers::format_directory_display; pub(crate) use helpers::format_tokens_compact; pub(crate) use helpers::plan_type_display_name; From 24c598e8a9efdd7b9de2dd8c935f7204c1c7c414 Mon Sep 17 00:00:00 2001 From: Ahmed Ibrahim Date: Mon, 6 Apr 2026 21:10:19 -0700 Subject: [PATCH 3/3] Honor null thread instructions (#16964) - Treat explicit null thread instructions as a blank-slate override while preserving omitted-field fallback behavior. - Preserve null through rollout resume/fork and keep explicit empty strings distinct. - Add app-server v2 start/fork coverage for the tri-state instruction params. --- .../schema/typescript/v2/ThreadForkParams.ts | 2 +- .../typescript/v2/ThreadResumeParams.ts | 2 +- .../schema/typescript/v2/ThreadStartParams.ts | 2 +- .../app-server-protocol/src/protocol/v2.rs | 77 ++++++++- .../app-server/src/codex_message_processor.rs | 11 +- .../app-server/tests/suite/v2/thread_fork.rs | 149 ++++++++++++++++++ .../app-server/tests/suite/v2/turn_start.rs | 97 ++++++++++++ codex-rs/codex-api/src/common.rs | 6 +- codex-rs/codex-api/tests/clients.rs | 4 +- codex-rs/core/src/client.rs | 13 +- codex-rs/core/src/client_common.rs | 17 +- codex-rs/core/src/client_common_tests.rs | 8 +- codex-rs/core/src/codex.rs | 54 ++++--- codex-rs/core/src/codex_tests.rs | 28 ++-- codex-rs/core/src/compact_remote.rs | 15 +- codex-rs/core/src/config/mod.rs | 13 +- codex-rs/core/src/config_loader/tests.rs | 4 +- codex-rs/core/src/guardian/review_session.rs | 2 +- codex-rs/core/src/memories/phase1.rs | 4 +- codex-rs/core/src/session_startup_prewarm.rs | 4 +- codex-rs/core/src/tasks/review.rs | 2 +- .../core/src/tools/handlers/agent_jobs.rs | 2 +- .../src/tools/handlers/multi_agents/spawn.rs | 6 +- .../src/tools/handlers/multi_agents_common.rs | 5 +- .../src/tools/handlers/multi_agents_tests.rs | 8 +- .../tools/handlers/multi_agents_v2/spawn.rs | 6 +- codex-rs/core/tests/suite/client.rs | 43 ++++- .../core/tests/suite/client_websockets.rs | 4 +- codex-rs/core/tests/suite/compact_remote.rs | 2 +- codex-rs/core/tests/suite/personality.rs | 2 +- .../core/tests/suite/rollout_list_find.rs | 2 +- .../suite/stream_error_allows_next_turn.rs | 2 +- codex-rs/mcp-server/src/codex_tool_config.rs | 4 +- codex-rs/protocol/src/lib.rs | 1 + codex-rs/protocol/src/protocol.rs | 12 +- codex-rs/protocol/src/serde_helpers.rs | 23 +++ codex-rs/rollout/src/recorder.rs | 4 +- codex-rs/rollout/src/recorder_tests.rs | 4 +- codex-rs/rollout/src/tests.rs | 7 +- 39 files changed, 550 insertions(+), 101 deletions(-) create mode 100644 codex-rs/protocol/src/serde_helpers.rs diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts index a7ba311803..952da565a6 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts @@ -27,7 +27,7 @@ model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier * Override where approval requests are routed for review on this thread * and subsequent turns. */ -approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, ephemeral?: boolean, /** +approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null | null, developerInstructions?: string | null | null, ephemeral?: boolean, /** * If true, persist additional rollout EventMsg variants required to * reconstruct a richer thread history on subsequent resume/fork/read. */ diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts index 770344de8e..fcde0ae502 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts @@ -36,7 +36,7 @@ model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier * Override where approval requests are routed for review on this thread * and subsequent turns. */ -approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, /** +approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null | null, developerInstructions?: string | null | null, personality?: Personality | null, /** * If true, persist additional rollout EventMsg variants required to * reconstruct a richer thread history on subsequent resume/fork/read. */ diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts index 61f501ad60..c7b27823f6 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts @@ -12,7 +12,7 @@ export type ThreadStartParams = {model?: string | null, modelProvider?: string | * Override where approval requests are routed for review on this thread * and subsequent turns. */ -approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, serviceName?: string | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, ephemeral?: boolean | null, /** +approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, serviceName?: string | null, baseInstructions?: string | null | null, developerInstructions?: string | null | null, personality?: Personality | null, ephemeral?: boolean | null, /** * If true, opt into emitting raw Responses API items on the event stream. * This is for internal use only (e.g. Codex Cloud). */ diff --git a/codex-rs/app-server-protocol/src/protocol/v2.rs b/codex-rs/app-server-protocol/src/protocol/v2.rs index 61b7db45e2..3562d9cda6 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2.rs +++ b/codex-rs/app-server-protocol/src/protocol/v2.rs @@ -2603,10 +2603,22 @@ pub struct ThreadStartParams { pub config: Option>, #[ts(optional = nullable)] pub service_name: Option, + #[serde( + default, + deserialize_with = "super::serde_helpers::deserialize_double_option", + serialize_with = "super::serde_helpers::serialize_double_option", + skip_serializing_if = "Option::is_none" + )] #[ts(optional = nullable)] - pub base_instructions: Option, + pub base_instructions: Option>, + #[serde( + default, + deserialize_with = "super::serde_helpers::deserialize_double_option", + serialize_with = "super::serde_helpers::serialize_double_option", + skip_serializing_if = "Option::is_none" + )] #[ts(optional = nullable)] - pub developer_instructions: Option, + pub developer_instructions: Option>, #[ts(optional = nullable)] pub personality: Option, #[ts(optional = nullable)] @@ -2721,10 +2733,22 @@ pub struct ThreadResumeParams { pub sandbox: Option, #[ts(optional = nullable)] pub config: Option>, + #[serde( + default, + deserialize_with = "super::serde_helpers::deserialize_double_option", + serialize_with = "super::serde_helpers::serialize_double_option", + skip_serializing_if = "Option::is_none" + )] #[ts(optional = nullable)] - pub base_instructions: Option, + pub base_instructions: Option>, + #[serde( + default, + deserialize_with = "super::serde_helpers::deserialize_double_option", + serialize_with = "super::serde_helpers::serialize_double_option", + skip_serializing_if = "Option::is_none" + )] #[ts(optional = nullable)] - pub developer_instructions: Option, + pub developer_instructions: Option>, #[ts(optional = nullable)] pub personality: Option, /// If true, persist additional rollout EventMsg variants required to @@ -2798,10 +2822,22 @@ pub struct ThreadForkParams { pub sandbox: Option, #[ts(optional = nullable)] pub config: Option>, + #[serde( + default, + deserialize_with = "super::serde_helpers::deserialize_double_option", + serialize_with = "super::serde_helpers::serialize_double_option", + skip_serializing_if = "Option::is_none" + )] #[ts(optional = nullable)] - pub base_instructions: Option, + pub base_instructions: Option>, + #[serde( + default, + deserialize_with = "super::serde_helpers::deserialize_double_option", + serialize_with = "super::serde_helpers::serialize_double_option", + skip_serializing_if = "Option::is_none" + )] #[ts(optional = nullable)] - pub developer_instructions: Option, + pub developer_instructions: Option>, #[serde(default, skip_serializing_if = "std::ops::Not::not")] pub ephemeral: bool, /// If true, persist additional rollout EventMsg variants required to @@ -8325,6 +8361,35 @@ mod tests { assert_eq!(serialized_without_override.get("serviceTier"), None); } + #[test] + fn thread_start_params_preserve_explicit_null_instructions() { + let params: ThreadStartParams = serde_json::from_value(json!({ + "baseInstructions": null, + "developerInstructions": null, + })) + .expect("params should deserialize"); + assert_eq!(params.base_instructions, Some(None)); + assert_eq!(params.developer_instructions, Some(None)); + + let serialized = serde_json::to_value(¶ms).expect("params should serialize"); + assert_eq!( + serialized.get("baseInstructions"), + Some(&serde_json::Value::Null) + ); + assert_eq!( + serialized.get("developerInstructions"), + Some(&serde_json::Value::Null) + ); + + let serialized_without_override = + serde_json::to_value(ThreadStartParams::default()).expect("params should serialize"); + assert_eq!(serialized_without_override.get("baseInstructions"), None); + assert_eq!( + serialized_without_override.get("developerInstructions"), + None + ); + } + #[test] fn turn_start_params_preserve_explicit_null_service_tier() { let params: TurnStartParams = serde_json::from_value(json!({ diff --git a/codex-rs/app-server/src/codex_message_processor.rs b/codex-rs/app-server/src/codex_message_processor.rs index 920fcbeceb..91641898d1 100644 --- a/codex-rs/app-server/src/codex_message_processor.rs +++ b/codex-rs/app-server/src/codex_message_processor.rs @@ -2473,8 +2473,8 @@ impl CodexMessageProcessor { approval_policy: Option, approvals_reviewer: Option, sandbox: Option, - base_instructions: Option, - developer_instructions: Option, + base_instructions: Option>, + developer_instructions: Option>, personality: Option, ) -> ConfigOverrides { ConfigOverrides { @@ -4363,6 +4363,13 @@ impl CodexMessageProcessor { developer_instructions, /*personality*/ None, ); + if typesafe_overrides.base_instructions.is_none() + && let Ok(history) = RolloutRecorder::get_rollout_history(&rollout_path).await + && let Some(base_instructions) = history.get_base_instructions() + { + typesafe_overrides.base_instructions = + Some(base_instructions.map(|base_instructions| base_instructions.text)); + } typesafe_overrides.ephemeral = ephemeral.then_some(true); // Derive a Config using the same logic as new conversation, honoring overrides if provided. let cloud_requirements = self.current_cloud_requirements(); diff --git a/codex-rs/app-server/tests/suite/v2/thread_fork.rs b/codex-rs/app-server/tests/suite/v2/thread_fork.rs index 9907fc4b1d..b4e80d7816 100644 --- a/codex-rs/app-server/tests/suite/v2/thread_fork.rs +++ b/codex-rs/app-server/tests/suite/v2/thread_fork.rs @@ -26,6 +26,8 @@ use codex_app_server_protocol::TurnStatus; use codex_app_server_protocol::UserInput; use codex_config::types::AuthCredentialsStoreMode; use codex_login::REFRESH_TOKEN_URL_OVERRIDE_ENV_VAR; +use core_test_support::responses; +use core_test_support::skip_if_no_network; use pretty_assertions::assert_eq; use serde_json::Value; use serde_json::json; @@ -183,6 +185,153 @@ async fn thread_fork_creates_new_thread_and_emits_started() -> Result<()> { Ok(()) } +#[tokio::test] +async fn thread_fork_honors_explicit_null_thread_instructions() -> Result<()> { + skip_if_no_network!(Ok(())); + + let server = responses::start_mock_server().await; + let body = responses::sse(vec![ + responses::ev_response_created("resp-1"), + responses::ev_assistant_message("msg-1", "Done"), + responses::ev_completed("resp-1"), + ]); + let response_mock = + responses::mount_sse_sequence(&server, vec![body.clone(), body.clone(), body]).await; + + let codex_home = TempDir::new()?; + create_config_toml(codex_home.path(), &server.uri())?; + + let conversation_id = create_fake_rollout( + codex_home.path(), + "2025-01-05T12-00-00", + "2025-01-05T12:00:00Z", + "Saved user message", + Some("mock_provider"), + /*git_info*/ None, + )?; + + let mut mcp = McpProcess::new(codex_home.path()).await?; + timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??; + + let disabled_instruction_config = json!({ + "include_permissions_instructions": false, + "include_apps_instructions": false, + "include_environment_context": false, + "features.apps": false, + "features.plugins": false, + "features.codex_hooks": false, + "skills.bundled.enabled": false, + }); + + let fork_params = [ + ( + json!({ + "threadId": conversation_id.clone(), + "config": disabled_instruction_config.clone(), + }), + /*expect_instructions*/ true, + ), + ( + json!({ + "threadId": conversation_id.clone(), + "config": disabled_instruction_config.clone(), + "baseInstructions": null, + "developerInstructions": null, + }), + /*expect_instructions*/ false, + ), + ]; + + let mut forked_thread_ids = Vec::new(); + for (params, _expect_instructions) in fork_params { + let fork_id = mcp.send_raw_request("thread/fork", Some(params)).await?; + let fork_resp: JSONRPCResponse = timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_response_message(RequestId::Integer(fork_id)), + ) + .await??; + let ThreadForkResponse { thread, .. } = to_response::(fork_resp)?; + forked_thread_ids.push(thread.id.clone()); + + let turn_id = mcp + .send_turn_start_request(TurnStartParams { + thread_id: thread.id, + input: vec![UserInput::Text { + text: "continue".to_string(), + text_elements: Vec::new(), + }], + ..Default::default() + }) + .await?; + let turn_resp: JSONRPCResponse = timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_response_message(RequestId::Integer(turn_id)), + ) + .await??; + let _: TurnStartResponse = to_response::(turn_resp)?; + timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_notification_message("turn/completed"), + ) + .await??; + } + + let refork_id = mcp + .send_raw_request( + "thread/fork", + Some(json!({ + "threadId": forked_thread_ids[1].clone(), + "config": disabled_instruction_config.clone(), + })), + ) + .await?; + let refork_resp: JSONRPCResponse = timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_response_message(RequestId::Integer(refork_id)), + ) + .await??; + let ThreadForkResponse { thread, .. } = to_response::(refork_resp)?; + let turn_id = mcp + .send_turn_start_request(TurnStartParams { + thread_id: thread.id, + input: vec![UserInput::Text { + text: "continue again".to_string(), + text_elements: Vec::new(), + }], + ..Default::default() + }) + .await?; + let turn_resp: JSONRPCResponse = timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_response_message(RequestId::Integer(turn_id)), + ) + .await??; + let _: TurnStartResponse = to_response::(turn_resp)?; + timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_notification_message("turn/completed"), + ) + .await??; + + let requests = response_mock.requests(); + assert_eq!(requests.len(), 3); + for (request, expect_instructions) in requests.into_iter().zip([true, false, false]) { + let payload = request.body_json(); + assert_eq!( + payload.get("instructions").is_some(), + expect_instructions, + "unexpected instructions field in payload: {payload:?}" + ); + let developer_texts = request.message_input_texts("developer"); + assert!( + developer_texts.iter().all(|text| !text.is_empty()), + "did not expect empty developer instruction messages: {developer_texts:?}" + ); + } + + Ok(()) +} + #[tokio::test] async fn thread_fork_tracks_thread_initialized_analytics() -> Result<()> { let server = create_mock_responses_server_repeating_assistant("Done").await; diff --git a/codex-rs/app-server/tests/suite/v2/turn_start.rs b/codex-rs/app-server/tests/suite/v2/turn_start.rs index 59591dd0d1..e8f3e1df2c 100644 --- a/codex-rs/app-server/tests/suite/v2/turn_start.rs +++ b/codex-rs/app-server/tests/suite/v2/turn_start.rs @@ -152,6 +152,103 @@ async fn turn_start_sends_originator_header() -> Result<()> { Ok(()) } +#[tokio::test] +async fn turn_start_honors_explicit_null_thread_instructions() -> Result<()> { + skip_if_no_network!(Ok(())); + + let server = responses::start_mock_server().await; + let body = responses::sse(vec![ + responses::ev_response_created("resp-1"), + responses::ev_assistant_message("msg-1", "Done"), + responses::ev_completed("resp-1"), + ]); + let response_mock = responses::mount_sse_sequence(&server, vec![body.clone(), body]).await; + + let codex_home = TempDir::new()?; + create_config_toml(codex_home.path(), &server.uri(), "never", &BTreeMap::new())?; + + let mut mcp = McpProcess::new(codex_home.path()).await?; + timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??; + + let disabled_instruction_config = json!({ + "include_permissions_instructions": false, + "include_apps_instructions": false, + "include_environment_context": false, + "features.apps": false, + "features.plugins": false, + "features.codex_hooks": false, + "skills.bundled.enabled": false, + }); + + let thread_start_params = [ + ( + json!({ + "model": "mock-model", + "config": disabled_instruction_config.clone(), + }), + /*expect_instructions*/ true, + ), + ( + json!({ + "model": "mock-model", + "config": disabled_instruction_config.clone(), + "baseInstructions": null, + "developerInstructions": null, + }), + /*expect_instructions*/ false, + ), + ]; + + for (params, _expect_instructions) in thread_start_params { + let thread_req = mcp.send_raw_request("thread/start", Some(params)).await?; + let thread_resp: JSONRPCResponse = timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_response_message(RequestId::Integer(thread_req)), + ) + .await??; + let ThreadStartResponse { thread, .. } = to_response::(thread_resp)?; + + let turn_req = mcp + .send_turn_start_request(TurnStartParams { + thread_id: thread.id, + input: vec![V2UserInput::Text { + text: "Hello".to_string(), + text_elements: Vec::new(), + }], + ..Default::default() + }) + .await?; + timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_response_message(RequestId::Integer(turn_req)), + ) + .await??; + timeout( + DEFAULT_READ_TIMEOUT, + mcp.read_stream_until_notification_message("turn/completed"), + ) + .await??; + } + + let requests = response_mock.requests(); + assert_eq!(requests.len(), 2); + for (request, expect_instructions) in requests.into_iter().zip([true, false]) { + let payload = request.body_json(); + assert_eq!( + payload.get("instructions").is_some(), + expect_instructions, + "unexpected instructions field in payload: {payload:?}" + ); + let developer_texts = request.message_input_texts("developer"); + assert!( + developer_texts.iter().all(|text| !text.is_empty()), + "did not expect empty developer instruction messages: {developer_texts:?}" + ); + } + + Ok(()) +} + #[tokio::test] async fn turn_start_emits_user_message_item_with_text_elements() -> Result<()> { let responses = vec![create_final_assistant_message_sse_response("Done")?]; diff --git a/codex-rs/codex-api/src/common.rs b/codex-rs/codex-api/src/common.rs index 39fb976e67..a2a2c1d478 100644 --- a/codex-rs/codex-api/src/common.rs +++ b/codex-rs/codex-api/src/common.rs @@ -153,7 +153,8 @@ impl From for OpenAiVerbosity { #[derive(Debug, Serialize, Clone, PartialEq)] pub struct ResponsesApiRequest { pub model: String, - pub instructions: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub instructions: Option, pub input: Vec, pub tools: Vec, pub tool_choice: String, @@ -196,7 +197,8 @@ impl From<&ResponsesApiRequest> for ResponseCreateWsRequest { #[derive(Debug, Serialize)] pub struct ResponseCreateWsRequest { pub model: String, - pub instructions: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub instructions: Option, #[serde(skip_serializing_if = "Option::is_none")] pub previous_response_id: Option, pub input: Vec, diff --git a/codex-rs/codex-api/tests/clients.rs b/codex-rs/codex-api/tests/clients.rs index ba0f416788..2f3bc17e2c 100644 --- a/codex-rs/codex-api/tests/clients.rs +++ b/codex-rs/codex-api/tests/clients.rs @@ -266,7 +266,7 @@ async fn streaming_client_retries_on_transport_error() -> Result<()> { let request = ResponsesApiRequest { model: "gpt-test".into(), - instructions: "Say hi".into(), + instructions: Some("Say hi".into()), input: Vec::new(), tools: Vec::new(), tool_choice: "auto".into(), @@ -302,7 +302,7 @@ async fn azure_default_store_attaches_ids_and_headers() -> Result<()> { let request = ResponsesApiRequest { model: "gpt-test".into(), - instructions: "Say hi".into(), + instructions: Some("Say hi".into()), input: vec![ResponseItem::Message { id: Some("msg_1".into()), role: "user".into(), diff --git a/codex-rs/core/src/client.rs b/codex-rs/core/src/client.rs index d77e36870a..b77dda2b75 100644 --- a/codex-rs/core/src/client.rs +++ b/codex-rs/core/src/client.rs @@ -399,7 +399,11 @@ impl ModelClient { ApiCompactClient::new(transport, client_setup.api_provider, client_setup.api_auth) .with_telemetry(Some(request_telemetry)); - let instructions = prompt.base_instructions.text.clone(); + let instructions = prompt + .base_instructions + .as_ref() + .map(|base_instructions| base_instructions.text.clone()) + .unwrap_or_default(); let input = prompt.get_formatted_input(); let tools = create_tools_json_for_responses_api(&prompt.tools)?; let reasoning = Self::build_reasoning(model_info, effort, summary); @@ -755,7 +759,10 @@ impl ModelClientSession { summary: ReasoningSummaryConfig, service_tier: Option, ) -> Result { - let instructions = &prompt.base_instructions.text; + let instructions = prompt + .base_instructions + .as_ref() + .map(|base_instructions| base_instructions.text.clone()); let input = prompt.get_formatted_input(); let tools = create_tools_json_for_responses_api(&prompt.tools)?; let default_reasoning_effort = model_info.default_reasoning_level; @@ -794,7 +801,7 @@ impl ModelClientSession { let prompt_cache_key = Some(self.client.state.conversation_id.to_string()); let request = ResponsesApiRequest { model: model_info.slug.clone(), - instructions: instructions.clone(), + instructions, input, tools, tool_choice: "auto".to_string(), diff --git a/codex-rs/core/src/client_common.rs b/codex-rs/core/src/client_common.rs index cb50ccac39..828839ae77 100644 --- a/codex-rs/core/src/client_common.rs +++ b/codex-rs/core/src/client_common.rs @@ -23,7 +23,7 @@ pub const REVIEW_EXIT_INTERRUPTED_TMPL: &str = include_str!("../templates/review/exit_interrupted.xml"); /// API request payload for a single model turn -#[derive(Default, Debug, Clone)] +#[derive(Debug, Clone)] pub struct Prompt { /// Conversation context input items. pub input: Vec, @@ -35,7 +35,7 @@ pub struct Prompt { /// Whether parallel tool calls are permitted for this prompt. pub(crate) parallel_tool_calls: bool, - pub base_instructions: BaseInstructions, + pub base_instructions: Option, /// Optionally specify the personality of the model. pub personality: Option, @@ -44,6 +44,19 @@ pub struct Prompt { pub output_schema: Option, } +impl Default for Prompt { + fn default() -> Self { + Self { + input: Vec::new(), + tools: Vec::new(), + parallel_tool_calls: false, + base_instructions: Some(BaseInstructions::default()), + personality: None, + output_schema: None, + } + } +} + impl Prompt { pub(crate) fn get_formatted_input(&self) -> Vec { let mut input = self.input.clone(); diff --git a/codex-rs/core/src/client_common_tests.rs b/codex-rs/core/src/client_common_tests.rs index 16a37796ad..968703046e 100644 --- a/codex-rs/core/src/client_common_tests.rs +++ b/codex-rs/core/src/client_common_tests.rs @@ -14,7 +14,7 @@ fn serializes_text_verbosity_when_set() { let tools: Vec = vec![]; let req = ResponsesApiRequest { model: "gpt-5.1".to_string(), - instructions: "i".to_string(), + instructions: Some("i".to_string()), input, tools, tool_choice: "auto".to_string(), @@ -57,7 +57,7 @@ fn serializes_text_schema_with_strict_format() { let req = ResponsesApiRequest { model: "gpt-5.1".to_string(), - instructions: "i".to_string(), + instructions: Some("i".to_string()), input, tools, tool_choice: "auto".to_string(), @@ -94,7 +94,7 @@ fn omits_text_when_not_set() { let tools: Vec = vec![]; let req = ResponsesApiRequest { model: "gpt-5.1".to_string(), - instructions: "i".to_string(), + instructions: Some("i".to_string()), input, tools, tool_choice: "auto".to_string(), @@ -116,7 +116,7 @@ fn omits_text_when_not_set() { fn serializes_flex_service_tier_when_set() { let req = ResponsesApiRequest { model: "gpt-5.1".to_string(), - instructions: "i".to_string(), + instructions: Some("i".to_string()), input: vec![], tools: vec![], tool_choice: "auto".to_string(), diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs index 423c62848a..237b77e38d 100644 --- a/codex-rs/core/src/codex.rs +++ b/codex-rs/core/src/codex.rs @@ -581,11 +581,15 @@ impl Codex { let model_info = models_manager .get_model_info(model.as_str(), &config.to_models_manager_config()) .await; - let base_instructions = config - .base_instructions - .clone() - .or_else(|| conversation_history.get_base_instructions().map(|s| s.text)) - .unwrap_or_else(|| model_info.get_model_instructions(config.personality)); + let base_instructions = match config.base_instructions.clone() { + Some(base_instructions) => base_instructions, + None => conversation_history + .get_base_instructions() + .map(|base_instructions| { + base_instructions.map(|base_instructions| base_instructions.text) + }) + .unwrap_or_else(|| Some(model_info.get_model_instructions(config.personality))), + }; // Respect thread-start tools. When missing (resumed/forked threads), read from the db // first, then fall back to rollout-file tools. @@ -1106,7 +1110,7 @@ pub(crate) struct SessionConfiguration { personality: Option, /// Base instructions for the session. - base_instructions: String, + base_instructions: Option, /// Compact prompt override. compact_prompt: Option, @@ -1545,9 +1549,10 @@ impl Session { conversation_id, forked_from_id, session_source, - BaseInstructions { - text: session_configuration.base_instructions.clone(), - }, + session_configuration + .base_instructions + .clone() + .map(|text| BaseInstructions { text }), session_configuration.dynamic_tools.clone(), if session_configuration.persist_extended_history { EventPersistenceMode::Extended @@ -2109,8 +2114,9 @@ impl Session { )); } } - sess.schedule_startup_prewarm(session_configuration.base_instructions.clone()) - .await; + if let Some(base_instructions) = session_configuration.base_instructions.clone() { + sess.schedule_startup_prewarm(base_instructions).await; + } let session_start_source = match &initial_history { InitialHistory::Resumed(_) => codex_hooks::SessionStartSource::Resume, InitialHistory::New | InitialHistory::Forked(_) => { @@ -2212,11 +2218,13 @@ impl Session { state.history.estimate_token_count(turn_context) } - pub(crate) async fn get_base_instructions(&self) -> BaseInstructions { + pub(crate) async fn get_base_instructions(&self) -> Option { let state = self.state.lock().await; - BaseInstructions { - text: state.session_configuration.base_instructions.clone(), - } + state + .session_configuration + .base_instructions + .clone() + .map(|text| BaseInstructions { text }) } // Merges connector IDs into the session-level explicit connector selection. @@ -3620,7 +3628,11 @@ impl Session { state.reference_context_item(), state.previous_turn_settings(), state.session_configuration.collaboration_mode.clone(), - state.session_configuration.base_instructions.clone(), + state + .session_configuration + .base_instructions + .clone() + .unwrap_or_default(), state.session_configuration.session_source.clone(), ) }; @@ -3861,7 +3873,13 @@ impl Session { pub(crate) async fn recompute_token_usage(&self, turn_context: &TurnContext) { let history = self.clone_history().await; - let base_instructions = self.get_base_instructions().await; + let empty_base_instructions = BaseInstructions { + text: String::new(), + }; + let base_instructions = self + .get_base_instructions() + .await + .unwrap_or(empty_base_instructions); let Some(estimated_total_tokens) = history.estimate_token_count_with_base_instructions(&base_instructions) else { @@ -6555,7 +6573,7 @@ pub(crate) fn build_prompt( input: Vec, router: &ToolRouter, turn_context: &TurnContext, - base_instructions: BaseInstructions, + base_instructions: Option, ) -> Prompt { let deferred_dynamic_tools = turn_context .dynamic_tools diff --git a/codex-rs/core/src/codex_tests.rs b/codex-rs/core/src/codex_tests.rs index cf7c23be90..b0437edbfe 100644 --- a/codex-rs/core/src/codex_tests.rs +++ b/codex-rs/core/src/codex_tests.rs @@ -591,11 +591,15 @@ async fn get_base_instructions_no_user_content() { { let mut state = session.state.lock().await; - state.session_configuration.base_instructions = model_info.base_instructions.clone(); + state.session_configuration.base_instructions = + Some(model_info.base_instructions.clone()); } let base_instructions = session.get_base_instructions().await; - assert_eq!(base_instructions.text, model_info.base_instructions); + assert_eq!( + base_instructions.expect("base instructions").text, + model_info.base_instructions + ); } } @@ -1091,7 +1095,7 @@ async fn recompute_token_usage_uses_session_base_instructions() { let override_instructions = "SESSION_OVERRIDE_INSTRUCTIONS_ONLY".repeat(120); { let mut state = session.state.lock().await; - state.session_configuration.base_instructions = override_instructions.clone(); + state.session_configuration.base_instructions = Some(override_instructions.clone()); } let item = user_message("hello"); @@ -1855,7 +1859,7 @@ async fn set_rate_limits_retains_previous_credits() { base_instructions: config .base_instructions .clone() - .unwrap_or_else(|| model_info.get_model_instructions(config.personality)), + .unwrap_or_else(|| Some(model_info.get_model_instructions(config.personality))), compact_prompt: config.compact_prompt.clone(), approval_policy: config.permissions.approval_policy.clone(), approvals_reviewer: config.approvals_reviewer, @@ -1957,7 +1961,7 @@ async fn set_rate_limits_updates_plan_type_when_present() { base_instructions: config .base_instructions .clone() - .unwrap_or_else(|| model_info.get_model_instructions(config.personality)), + .unwrap_or_else(|| Some(model_info.get_model_instructions(config.personality))), compact_prompt: config.compact_prompt.clone(), approval_policy: config.permissions.approval_policy.clone(), approvals_reviewer: config.approvals_reviewer, @@ -2222,7 +2226,7 @@ async fn attach_rollout_recorder(session: &Arc) -> PathBuf { ThreadId::default(), /*forked_from_id*/ None, SessionSource::Exec, - BaseInstructions::default(), + Some(BaseInstructions::default()), Vec::new(), EventPersistenceMode::Limited, ), @@ -2306,7 +2310,7 @@ pub(crate) async fn make_session_configuration_for_tests() -> SessionConfigurati base_instructions: config .base_instructions .clone() - .unwrap_or_else(|| model_info.get_model_instructions(config.personality)), + .unwrap_or_else(|| Some(model_info.get_model_instructions(config.personality))), compact_prompt: config.compact_prompt.clone(), approval_policy: config.permissions.approval_policy.clone(), approvals_reviewer: config.approvals_reviewer, @@ -2572,7 +2576,7 @@ async fn session_new_fails_when_zsh_fork_enabled_without_zsh_path() { base_instructions: config .base_instructions .clone() - .unwrap_or_else(|| model_info.get_model_instructions(config.personality)), + .unwrap_or_else(|| Some(model_info.get_model_instructions(config.personality))), compact_prompt: config.compact_prompt.clone(), approval_policy: config.permissions.approval_policy.clone(), approvals_reviewer: config.approvals_reviewer, @@ -2675,7 +2679,7 @@ pub(crate) async fn make_session_and_context() -> (Session, TurnContext) { base_instructions: config .base_instructions .clone() - .unwrap_or_else(|| model_info.get_model_instructions(config.personality)), + .unwrap_or_else(|| Some(model_info.get_model_instructions(config.personality))), compact_prompt: config.compact_prompt.clone(), approval_policy: config.permissions.approval_policy.clone(), approvals_reviewer: config.approvals_reviewer, @@ -3515,7 +3519,7 @@ pub(crate) async fn make_session_and_context_with_dynamic_tools_and_rx( base_instructions: config .base_instructions .clone() - .unwrap_or_else(|| model_info.get_model_instructions(config.personality)), + .unwrap_or_else(|| Some(model_info.get_model_instructions(config.personality))), compact_prompt: config.compact_prompt.clone(), approval_policy: config.permissions.approval_policy.clone(), approvals_reviewer: config.approvals_reviewer, @@ -4264,7 +4268,7 @@ async fn record_context_updates_and_set_reference_context_item_persists_baseline ThreadId::default(), /*forked_from_id*/ None, SessionSource::Exec, - BaseInstructions::default(), + Some(BaseInstructions::default()), Vec::new(), EventPersistenceMode::Limited, ), @@ -4361,7 +4365,7 @@ async fn record_context_updates_and_set_reference_context_item_persists_full_rei ThreadId::default(), /*forked_from_id*/ None, SessionSource::Exec, - BaseInstructions::default(), + Some(BaseInstructions::default()), Vec::new(), EventPersistenceMode::Limited, ), diff --git a/codex-rs/core/src/compact_remote.rs b/codex-rs/core/src/compact_remote.rs index 5bc7944d28..640ca3c1f8 100644 --- a/codex-rs/core/src/compact_remote.rs +++ b/codex-rs/core/src/compact_remote.rs @@ -76,10 +76,16 @@ async fn run_remote_compact_task_inner_impl( .await; let mut history = sess.clone_history().await; let base_instructions = sess.get_base_instructions().await; + let token_count_base_instructions = + base_instructions + .clone() + .unwrap_or_else(|| BaseInstructions { + text: String::new(), + }); let deleted_items = trim_function_call_history_to_fit_context_window( &mut history, turn_context.as_ref(), - &base_instructions, + &token_count_base_instructions, ); if deleted_items > 0 { info!( @@ -127,8 +133,13 @@ async fn run_remote_compact_task_inner_impl( ) .or_else(|err| async { let total_usage_breakdown = sess.get_total_token_usage_breakdown().await; + let base_instruction_text = prompt + .base_instructions + .as_ref() + .map(|base_instructions| base_instructions.text.as_str()) + .unwrap_or(""); let compact_request_log_data = - build_compact_request_log_data(&prompt.input, &prompt.base_instructions.text); + build_compact_request_log_data(&prompt.input, base_instruction_text); log_remote_compact_failure( turn_context, &compact_request_log_data, diff --git a/codex-rs/core/src/config/mod.rs b/codex-rs/core/src/config/mod.rs index 3c2d80464e..20d3dd2f1b 100644 --- a/codex-rs/core/src/config/mod.rs +++ b/codex-rs/core/src/config/mod.rs @@ -243,7 +243,7 @@ pub struct Config { pub user_instructions: Option, /// Base instructions override. - pub base_instructions: Option, + pub base_instructions: Option>, /// Developer instructions override injected as a separate message. pub developer_instructions: Option, @@ -687,7 +687,7 @@ impl Config { model_context_window: self.model_context_window, model_auto_compact_token_limit: self.model_auto_compact_token_limit, tool_output_token_limit: self.tool_output_token_limit, - base_instructions: self.base_instructions.clone(), + base_instructions: self.base_instructions.clone().flatten(), personality_enabled: self.features.enabled(Feature::Personality), model_supports_reasoning_summaries: self.model_supports_reasoning_summaries, model_catalog: self.model_catalog.clone(), @@ -1200,8 +1200,8 @@ pub struct ConfigOverrides { pub js_repl_node_path: Option, pub js_repl_node_module_dirs: Option>, pub zsh_path: Option, - pub base_instructions: Option, - pub developer_instructions: Option, + pub base_instructions: Option>, + pub developer_instructions: Option>, pub personality: Option, pub compact_prompt: Option, pub include_apply_patch_tool: Option, @@ -1760,8 +1760,9 @@ impl Config { .or(cfg.model_instructions_file.as_ref()); let file_base_instructions = Self::try_read_non_empty_file(model_instructions_path, "model instructions file")?; - let base_instructions = base_instructions.or(file_base_instructions); - let developer_instructions = developer_instructions.or(cfg.developer_instructions); + let base_instructions = base_instructions.or_else(|| file_base_instructions.map(Some)); + let developer_instructions = + developer_instructions.unwrap_or_else(|| cfg.developer_instructions.clone()); let include_permissions_instructions = config_profile .include_permissions_instructions .or(cfg.include_permissions_instructions) diff --git a/codex-rs/core/src/config_loader/tests.rs b/codex-rs/core/src/config_loader/tests.rs index 7978f37ec8..629730cbf2 100644 --- a/codex-rs/core/src/config_loader/tests.rs +++ b/codex-rs/core/src/config_loader/tests.rs @@ -905,7 +905,7 @@ model_instructions_file = "child.txt" .await?; assert_eq!( - config.base_instructions.as_deref(), + config.base_instructions.as_ref().and_then(Option::as_deref), Some("child instructions") ); @@ -941,7 +941,7 @@ async fn cli_override_model_instructions_file_sets_base_instructions() -> std::i .await?; assert_eq!( - config.base_instructions.as_deref(), + config.base_instructions.as_ref().and_then(Option::as_deref), Some("cli override instructions") ); diff --git a/codex-rs/core/src/guardian/review_session.rs b/codex-rs/core/src/guardian/review_session.rs index bc24974c82..368b812e56 100644 --- a/codex-rs/core/src/guardian/review_session.rs +++ b/codex-rs/core/src/guardian/review_session.rs @@ -137,7 +137,7 @@ impl GuardianReviewSessionReuseKey { model_reasoning_summary: spawn_config.model_reasoning_summary, permissions: spawn_config.permissions.clone(), developer_instructions: spawn_config.developer_instructions.clone(), - base_instructions: spawn_config.base_instructions.clone(), + base_instructions: spawn_config.base_instructions.clone().flatten(), user_instructions: spawn_config.user_instructions.clone(), compact_prompt: spawn_config.compact_prompt.clone(), cwd: spawn_config.cwd.to_path_buf(), diff --git a/codex-rs/core/src/memories/phase1.rs b/codex-rs/core/src/memories/phase1.rs index 37cb0e9f48..0b8cdcdad5 100644 --- a/codex-rs/core/src/memories/phase1.rs +++ b/codex-rs/core/src/memories/phase1.rs @@ -336,9 +336,9 @@ mod job { }], tools: Vec::new(), parallel_tool_calls: false, - base_instructions: BaseInstructions { + base_instructions: Some(BaseInstructions { text: phase_one::PROMPT.to_string(), - }, + }), personality: None, output_schema: Some(output_schema()), }; diff --git a/codex-rs/core/src/session_startup_prewarm.rs b/codex-rs/core/src/session_startup_prewarm.rs index 397ffc949c..708401aedd 100644 --- a/codex-rs/core/src/session_startup_prewarm.rs +++ b/codex-rs/core/src/session_startup_prewarm.rs @@ -217,9 +217,9 @@ async fn schedule_startup_prewarm_inner( Vec::new(), startup_router.as_ref(), startup_turn_context.as_ref(), - BaseInstructions { + Some(BaseInstructions { text: base_instructions, - }, + }), ); let startup_turn_metadata_header = startup_turn_context .turn_metadata_state diff --git a/codex-rs/core/src/tasks/review.rs b/codex-rs/core/src/tasks/review.rs index a1cc071108..834cf20b4b 100644 --- a/codex-rs/core/src/tasks/review.rs +++ b/codex-rs/core/src/tasks/review.rs @@ -112,7 +112,7 @@ async fn start_review_conversation( let _ = sub_agent_config.features.disable(Feature::Collab); // Set explicit review rubric for the sub-agent - sub_agent_config.base_instructions = Some(crate::REVIEW_PROMPT.to_string()); + sub_agent_config.base_instructions = Some(Some(crate::REVIEW_PROMPT.to_string())); sub_agent_config.permissions.approval_policy = Constrained::allow_only(AskForApproval::Never); let model = config diff --git a/codex-rs/core/src/tools/handlers/agent_jobs.rs b/codex-rs/core/src/tools/handlers/agent_jobs.rs index fe30f3d750..837b654edc 100644 --- a/codex-rs/core/src/tools/handlers/agent_jobs.rs +++ b/codex-rs/core/src/tools/handlers/agent_jobs.rs @@ -535,7 +535,7 @@ async fn build_runner_options( let max_concurrency = normalize_concurrency(requested_concurrency, turn.config.agent_max_threads); let base_instructions = session.get_base_instructions().await; - let spawn_config = build_agent_spawn_config(&base_instructions, turn.as_ref())?; + let spawn_config = build_agent_spawn_config(base_instructions.as_ref(), turn.as_ref())?; Ok(JobRunnerOptions { max_concurrency, spawn_config, diff --git a/codex-rs/core/src/tools/handlers/multi_agents/spawn.rs b/codex-rs/core/src/tools/handlers/multi_agents/spawn.rs index 8e4bfb5b59..a2482ea6a9 100644 --- a/codex-rs/core/src/tools/handlers/multi_agents/spawn.rs +++ b/codex-rs/core/src/tools/handlers/multi_agents/spawn.rs @@ -59,8 +59,10 @@ impl ToolHandler for Handler { .into(), ) .await; - let mut config = - build_agent_spawn_config(&session.get_base_instructions().await, turn.as_ref())?; + let mut config = build_agent_spawn_config( + session.get_base_instructions().await.as_ref(), + turn.as_ref(), + )?; apply_requested_spawn_agent_model_overrides( &session, turn.as_ref(), diff --git a/codex-rs/core/src/tools/handlers/multi_agents_common.rs b/codex-rs/core/src/tools/handlers/multi_agents_common.rs index 2078c229b9..4205c4bb43 100644 --- a/codex-rs/core/src/tools/handlers/multi_agents_common.rs +++ b/codex-rs/core/src/tools/handlers/multi_agents_common.rs @@ -201,11 +201,12 @@ pub(crate) fn parse_collab_input( /// skipping this helper and cloning stale config state directly can send the child agent out with /// the wrong provider or runtime policy. pub(crate) fn build_agent_spawn_config( - base_instructions: &BaseInstructions, + base_instructions: Option<&BaseInstructions>, turn: &TurnContext, ) -> Result { let mut config = build_agent_shared_config(turn)?; - config.base_instructions = Some(base_instructions.text.clone()); + config.base_instructions = + Some(base_instructions.map(|base_instructions| base_instructions.text.clone())); Ok(config) } diff --git a/codex-rs/core/src/tools/handlers/multi_agents_tests.rs b/codex-rs/core/src/tools/handlers/multi_agents_tests.rs index eab43f899c..03f4b0780b 100644 --- a/codex-rs/core/src/tools/handlers/multi_agents_tests.rs +++ b/codex-rs/core/src/tools/handlers/multi_agents_tests.rs @@ -3209,9 +3209,9 @@ async fn build_agent_spawn_config_uses_turn_context_values() { .set(AskForApproval::OnRequest) .expect("approval policy set"); - let config = build_agent_spawn_config(&base_instructions, &turn).expect("spawn config"); + let config = build_agent_spawn_config(Some(&base_instructions), &turn).expect("spawn config"); let mut expected = (*turn.config).clone(); - expected.base_instructions = Some(base_instructions.text); + expected.base_instructions = Some(Some(base_instructions.text)); expected.model = Some(turn.model_info.slug.clone()); expected.model_provider = turn.provider.clone(); expected.model_reasoning_effort = turn.reasoning_effort; @@ -3247,7 +3247,7 @@ async fn build_agent_spawn_config_preserves_base_user_instructions() { text: "base".to_string(), }; - let config = build_agent_spawn_config(&base_instructions, &turn).expect("spawn config"); + let config = build_agent_spawn_config(Some(&base_instructions), &turn).expect("spawn config"); assert_eq!(config.user_instructions, base_config.user_instructions); } @@ -3256,7 +3256,7 @@ async fn build_agent_spawn_config_preserves_base_user_instructions() { async fn build_agent_resume_config_clears_base_instructions() { let (_session, mut turn) = make_session_and_context().await; let mut base_config = (*turn.config).clone(); - base_config.base_instructions = Some("caller-base".to_string()); + base_config.base_instructions = Some(Some("caller-base".to_string())); turn.config = Arc::new(base_config); turn.approval_policy .set(AskForApproval::OnRequest) diff --git a/codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs b/codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs index 77c48af9e6..a1cdb121d1 100644 --- a/codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs +++ b/codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs @@ -68,8 +68,10 @@ impl ToolHandler for Handler { .into(), ) .await; - let mut config = - build_agent_spawn_config(&session.get_base_instructions().await, turn.as_ref())?; + let mut config = build_agent_spawn_config( + session.get_base_instructions().await.as_ref(), + turn.as_ref(), + )?; apply_requested_spawn_agent_model_overrides( &session, turn.as_ref(), diff --git a/codex-rs/core/tests/suite/client.rs b/codex-rs/core/tests/suite/client.rs index 8e719460e5..cb97e4a3b3 100644 --- a/codex-rs/core/tests/suite/client.rs +++ b/codex-rs/core/tests/suite/client.rs @@ -921,7 +921,7 @@ async fn includes_base_instructions_override_in_request() { let mut builder = test_codex() .with_auth(CodexAuth::from_api_key("Test API Key")) .with_config(|config| { - config.base_instructions = Some("test instructions".to_string()); + config.base_instructions = Some(Some("test instructions".to_string())); }); let codex = builder .build(&server) @@ -953,6 +953,47 @@ async fn includes_base_instructions_override_in_request() { ); } +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn omits_explicit_null_base_instructions_from_request() { + skip_if_no_network!(); + // Mock server + let server = MockServer::start().await; + let resp_mock = mount_sse_once( + &server, + sse(vec![ev_response_created("resp1"), ev_completed("resp1")]), + ) + .await; + + let mut builder = test_codex() + .with_auth(CodexAuth::from_api_key("Test API Key")) + .with_config(|config| { + config.base_instructions = Some(None); + }); + let codex = builder + .build(&server) + .await + .expect("create new conversation") + .codex; + + codex + .submit(Op::UserInput { + items: vec![UserInput::Text { + text: "hello".into(), + text_elements: Vec::new(), + }], + final_output_json_schema: None, + }) + .await + .unwrap(); + + wait_for_event(&codex, |ev| matches!(ev, EventMsg::TurnComplete(_))).await; + + let request = resp_mock.single_request(); + let request_body = request.body_json(); + + assert_eq!(request_body.get("instructions"), None); +} + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] async fn chatgpt_auth_sends_correct_request() { skip_if_no_network!(); diff --git a/codex-rs/core/tests/suite/client_websockets.rs b/codex-rs/core/tests/suite/client_websockets.rs index d348d4a022..0a1195a11b 100755 --- a/codex-rs/core/tests/suite/client_websockets.rs +++ b/codex-rs/core/tests/suite/client_websockets.rs @@ -1654,9 +1654,9 @@ fn prompt_with_input(input: Vec) -> Prompt { fn prompt_with_input_and_instructions(input: Vec, instructions: &str) -> Prompt { let mut prompt = prompt_with_input(input); - prompt.base_instructions = BaseInstructions { + prompt.base_instructions = Some(BaseInstructions { text: instructions.to_string(), - }; + }); prompt } diff --git a/codex-rs/core/tests/suite/compact_remote.rs b/codex-rs/core/tests/suite/compact_remote.rs index 0069c5fb86..dd99e0f391 100644 --- a/codex-rs/core/tests/suite/compact_remote.rs +++ b/codex-rs/core/tests/suite/compact_remote.rs @@ -869,7 +869,7 @@ async fn remote_compact_trim_estimate_uses_session_base_instructions() -> Result let override_base_instructions = override_base_instructions.clone(); move |config| { config.model_context_window = Some(override_context_window); - config.base_instructions = Some(override_base_instructions); + config.base_instructions = Some(Some(override_base_instructions)); } }), ) diff --git a/codex-rs/core/tests/suite/personality.rs b/codex-rs/core/tests/suite/personality.rs index 172738ffd1..8a0cbdcb63 100644 --- a/codex-rs/core/tests/suite/personality.rs +++ b/codex-rs/core/tests/suite/personality.rs @@ -66,7 +66,7 @@ async fn base_instructions_override_disables_personality_template() { .enable(Feature::Personality) .expect("test config should allow feature update"); config.personality = Some(Personality::Friendly); - config.base_instructions = Some("override instructions".to_string()); + config.base_instructions = Some(Some("override instructions".to_string())); let model_info = codex_core::test_support::construct_model_info_offline("gpt-5.2-codex", &config); diff --git a/codex-rs/core/tests/suite/rollout_list_find.rs b/codex-rs/core/tests/suite/rollout_list_find.rs index 7445a4ba05..93edd1621a 100644 --- a/codex-rs/core/tests/suite/rollout_list_find.rs +++ b/codex-rs/core/tests/suite/rollout_list_find.rs @@ -173,7 +173,7 @@ async fn find_locates_rollout_file_written_by_recorder() -> std::io::Result<()> thread_id, /*forked_from_id*/ None, SessionSource::Exec, - BaseInstructions::default(), + Some(BaseInstructions::default()), Vec::new(), EventPersistenceMode::Limited, ), diff --git a/codex-rs/core/tests/suite/stream_error_allows_next_turn.rs b/codex-rs/core/tests/suite/stream_error_allows_next_turn.rs index 19d9d27cf7..c5aa57ce74 100644 --- a/codex-rs/core/tests/suite/stream_error_allows_next_turn.rs +++ b/codex-rs/core/tests/suite/stream_error_allows_next_turn.rs @@ -84,7 +84,7 @@ async fn continue_after_stream_error() { let TestCodex { codex, .. } = test_codex() .with_config(move |config| { - config.base_instructions = Some("You are a helpful assistant".to_string()); + config.base_instructions = Some(Some("You are a helpful assistant".to_string())); config.model_provider = provider; }) .build(&server) diff --git a/codex-rs/mcp-server/src/codex_tool_config.rs b/codex-rs/mcp-server/src/codex_tool_config.rs index f83fd4fd5a..341f0ac4b2 100644 --- a/codex-rs/mcp-server/src/codex_tool_config.rs +++ b/codex-rs/mcp-server/src/codex_tool_config.rs @@ -179,8 +179,8 @@ impl CodexToolCallParam { codex_self_exe: arg0_paths.codex_self_exe.clone(), codex_linux_sandbox_exe: arg0_paths.codex_linux_sandbox_exe.clone(), main_execve_wrapper_exe: arg0_paths.main_execve_wrapper_exe.clone(), - base_instructions, - developer_instructions, + base_instructions: base_instructions.map(Some), + developer_instructions: developer_instructions.map(Some), compact_prompt, ..Default::default() }; diff --git a/codex-rs/protocol/src/lib.rs b/codex-rs/protocol/src/lib.rs index de580de6f3..e78bfe6e45 100644 --- a/codex-rs/protocol/src/lib.rs +++ b/codex-rs/protocol/src/lib.rs @@ -23,4 +23,5 @@ pub mod plan_tool; pub mod protocol; pub mod request_permissions; pub mod request_user_input; +mod serde_helpers; pub mod user_input; diff --git a/codex-rs/protocol/src/protocol.rs b/codex-rs/protocol/src/protocol.rs index 7116878b47..05926a9544 100644 --- a/codex-rs/protocol/src/protocol.rs +++ b/codex-rs/protocol/src/protocol.rs @@ -48,6 +48,8 @@ use crate::plan_tool::UpdatePlanArgs; use crate::request_permissions::RequestPermissionsEvent; use crate::request_permissions::RequestPermissionsResponse; use crate::request_user_input::RequestUserInputResponse; +use crate::serde_helpers::deserialize_double_option; +use crate::serde_helpers::serialize_double_option; use crate::user_input::UserInput; use codex_git_utils::GitSha; use codex_utils_absolute_path::AbsolutePathBuf; @@ -2332,7 +2334,7 @@ impl InitialHistory { } } - pub fn get_base_instructions(&self) -> Option { + pub fn get_base_instructions(&self) -> Option> { // TODO: SessionMeta should (in theory) always be first in the history, so we can probably only check the first item? match self { InitialHistory::New => None, @@ -2540,7 +2542,13 @@ pub struct SessionMeta { /// base_instructions for the session. This *should* always be present when creating a new session, /// but may be missing for older sessions. If not present, fall back to rendering the base_instructions /// from ModelsManager. - pub base_instructions: Option, + #[serde( + default, + deserialize_with = "deserialize_double_option", + serialize_with = "serialize_double_option", + skip_serializing_if = "Option::is_none" + )] + pub base_instructions: Option>, #[serde(skip_serializing_if = "Option::is_none")] pub dynamic_tools: Option>, #[serde(skip_serializing_if = "Option::is_none")] diff --git a/codex-rs/protocol/src/serde_helpers.rs b/codex-rs/protocol/src/serde_helpers.rs new file mode 100644 index 0000000000..0e35ebdba7 --- /dev/null +++ b/codex-rs/protocol/src/serde_helpers.rs @@ -0,0 +1,23 @@ +use serde::Deserialize; +use serde::Deserializer; +use serde::Serialize; +use serde::Serializer; + +pub fn deserialize_double_option<'de, T, D>(deserializer: D) -> Result>, D::Error> +where + T: Deserialize<'de>, + D: Deserializer<'de>, +{ + serde_with::rust::double_option::deserialize(deserializer) +} + +pub fn serialize_double_option( + value: &Option>, + serializer: S, +) -> Result +where + T: Serialize, + S: Serializer, +{ + serde_with::rust::double_option::serialize(value, serializer) +} diff --git a/codex-rs/rollout/src/recorder.rs b/codex-rs/rollout/src/recorder.rs index f39c38af60..aa7b485b0c 100644 --- a/codex-rs/rollout/src/recorder.rs +++ b/codex-rs/rollout/src/recorder.rs @@ -81,7 +81,7 @@ pub enum RolloutRecorderParams { conversation_id: ThreadId, forked_from_id: Option, source: SessionSource, - base_instructions: BaseInstructions, + base_instructions: Option, dynamic_tools: Vec, event_persistence_mode: EventPersistenceMode, }, @@ -110,7 +110,7 @@ impl RolloutRecorderParams { conversation_id: ThreadId, forked_from_id: Option, source: SessionSource, - base_instructions: BaseInstructions, + base_instructions: Option, dynamic_tools: Vec, event_persistence_mode: EventPersistenceMode, ) -> Self { diff --git a/codex-rs/rollout/src/recorder_tests.rs b/codex-rs/rollout/src/recorder_tests.rs index 163c8a1ee8..6ee55672e7 100644 --- a/codex-rs/rollout/src/recorder_tests.rs +++ b/codex-rs/rollout/src/recorder_tests.rs @@ -73,7 +73,7 @@ async fn recorder_materializes_only_after_explicit_persist() -> std::io::Result< thread_id, /*forked_from_id*/ None, SessionSource::Exec, - BaseInstructions::default(), + Some(BaseInstructions::default()), Vec::new(), EventPersistenceMode::Limited, ), @@ -166,7 +166,7 @@ async fn metadata_irrelevant_events_touch_state_db_updated_at() -> std::io::Resu thread_id, /*forked_from_id*/ None, SessionSource::Cli, - BaseInstructions::default(), + Some(BaseInstructions::default()), Vec::new(), EventPersistenceMode::Limited, ), diff --git a/codex-rs/rollout/src/tests.rs b/codex-rs/rollout/src/tests.rs index e647a54cd4..aeda089a25 100644 --- a/codex-rs/rollout/src/tests.rs +++ b/codex-rs/rollout/src/tests.rs @@ -977,7 +977,7 @@ async fn test_get_thread_contents() { } #[tokio::test] -async fn test_base_instructions_missing_in_meta_defaults_to_null() { +async fn test_base_instructions_missing_in_meta_stays_missing() { let temp = TempDir::new().unwrap(); let home = temp.path(); @@ -1011,10 +1011,7 @@ async fn test_base_instructions_missing_in_meta_defaults_to_null() { .await .expect("session meta head"); let first = head.first().expect("first head entry"); - assert_eq!( - first.get("base_instructions"), - Some(&serde_json::Value::Null) - ); + assert_eq!(first.get("base_instructions"), None); } #[tokio::test]