diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json index b2f88d3344..0af7d8d481 100644 --- a/codex-rs/core/config.schema.json +++ b/codex-rs/core/config.schema.json @@ -53,6 +53,13 @@ "format": "uint", "minimum": 1.0, "type": "integer" + }, + "nickname_pool": { + "description": "Global fallback nickname candidates for spawned agent threads.\n\nExample: ```toml [agents] nickname_pool = [\"Scout\", \"Builder\", \"Reviewer\"] ```", + "items": { + "type": "string" + }, + "type": "array" } }, "type": "object" diff --git a/codex-rs/core/src/agent/control.rs b/codex-rs/core/src/agent/control.rs index eaee6e9857..31c5371874 100644 --- a/codex-rs/core/src/agent/control.rs +++ b/codex-rs/core/src/agent/control.rs @@ -54,6 +54,10 @@ fn agent_nickname_candidates( return candidates; } + if !config.agent_nickname_pool.is_empty() { + return config.agent_nickname_pool.clone(); + } + default_agent_nickname_list() .into_iter() .map(ToOwned::to_owned) diff --git a/codex-rs/core/src/agent/control_tests.rs b/codex-rs/core/src/agent/control_tests.rs index 26819309a7..e2e41efb39 100644 --- a/codex-rs/core/src/agent/control_tests.rs +++ b/codex-rs/core/src/agent/control_tests.rs @@ -961,6 +961,94 @@ async fn spawn_thread_subagent_uses_role_specific_nickname_candidates() { assert_eq!(agent_nickname, Some("Atlas".to_string())); } +#[tokio::test] +async fn spawn_thread_subagent_uses_global_nickname_pool_when_role_has_no_candidates() { + let mut harness = AgentControlHarness::new().await; + harness.config.agent_nickname_pool = vec!["Scout".to_string()]; + harness.config.agent_roles.insert( + "researcher".to_string(), + AgentRoleConfig { + description: Some("Research role".to_string()), + config_file: None, + nickname_candidates: None, + }, + ); + let (parent_thread_id, _parent_thread) = harness.start_thread().await; + + let child_thread_id = harness + .control + .spawn_agent( + harness.config.clone(), + text_input("hello child"), + Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn { + parent_thread_id, + depth: 1, + agent_nickname: None, + agent_role: Some("researcher".to_string()), + })), + ) + .await + .expect("child spawn should succeed"); + + let child_thread = harness + .manager + .get_thread(child_thread_id) + .await + .expect("child thread should be registered"); + let snapshot = child_thread.config_snapshot().await; + + let SessionSource::SubAgent(SubAgentSource::ThreadSpawn { agent_nickname, .. }) = + snapshot.session_source + else { + panic!("expected thread-spawn sub-agent source"); + }; + assert_eq!(agent_nickname, Some("Scout".to_string())); +} + +#[tokio::test] +async fn spawn_thread_subagent_prefers_role_candidates_over_global_nickname_pool() { + let mut harness = AgentControlHarness::new().await; + harness.config.agent_nickname_pool = vec!["Scout".to_string()]; + harness.config.agent_roles.insert( + "researcher".to_string(), + AgentRoleConfig { + description: Some("Research role".to_string()), + config_file: None, + nickname_candidates: Some(vec!["Atlas".to_string()]), + }, + ); + let (parent_thread_id, _parent_thread) = harness.start_thread().await; + + let child_thread_id = harness + .control + .spawn_agent( + harness.config.clone(), + text_input("hello child"), + Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn { + parent_thread_id, + depth: 1, + agent_nickname: None, + agent_role: Some("researcher".to_string()), + })), + ) + .await + .expect("child spawn should succeed"); + + let child_thread = harness + .manager + .get_thread(child_thread_id) + .await + .expect("child thread should be registered"); + let snapshot = child_thread.config_snapshot().await; + + let SessionSource::SubAgent(SubAgentSource::ThreadSpawn { agent_nickname, .. }) = + snapshot.session_source + else { + panic!("expected thread-spawn sub-agent source"); + }; + assert_eq!(agent_nickname, Some("Atlas".to_string())); +} + #[tokio::test] async fn resume_thread_subagent_restores_stored_nickname_and_role() { let (home, mut config) = test_config().await; diff --git a/codex-rs/core/src/config/agent_roles.rs b/codex-rs/core/src/config/agent_roles.rs index c527435e92..cc0d3cf2d1 100644 --- a/codex-rs/core/src/config/agent_roles.rs +++ b/codex-rs/core/src/config/agent_roles.rs @@ -441,6 +441,47 @@ fn normalize_agent_role_nickname_candidates( Ok(Some(normalized_candidates)) } +pub(crate) fn normalize_agent_nickname_pool( + field_label: &str, + nickname_pool: Option<&[String]>, +) -> std::io::Result>> { + let Some(nickname_pool) = nickname_pool else { + return Ok(None); + }; + + let mut normalized_candidates = Vec::with_capacity(nickname_pool.len()); + let mut seen_candidates = BTreeSet::new(); + + for nickname in nickname_pool { + let normalized_nickname = nickname.trim(); + if normalized_nickname.is_empty() { + continue; + } + + if !normalized_nickname + .chars() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, ' ' | '-' | '_')) + { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + format!( + "{field_label} may only contain ASCII letters, digits, spaces, hyphens, and underscores" + ), + )); + } + + if seen_candidates.insert(normalized_nickname.to_owned()) { + normalized_candidates.push(normalized_nickname.to_owned()); + } + } + + if normalized_candidates.is_empty() { + Ok(None) + } else { + Ok(Some(normalized_candidates)) + } +} + fn discover_agent_roles_in_dir( agents_dir: &Path, declared_role_files: &BTreeSet, diff --git a/codex-rs/core/src/config/config_tests.rs b/codex-rs/core/src/config/config_tests.rs index ee856664dd..aea4cd380f 100644 --- a/codex-rs/core/src/config/config_tests.rs +++ b/codex-rs/core/src/config/config_tests.rs @@ -107,6 +107,23 @@ persistence = "none" history_no_persistence_cfg.history ); + let agents_with_nickname_pool = r#" +[agents] +nickname_pool = ["Scout", "Builder", "Reviewer"] +"#; + let agents_with_nickname_pool_cfg = toml::from_str::(agents_with_nickname_pool) + .expect("TOML deserialization should succeed"); + assert_eq!( + agents_with_nickname_pool_cfg + .agents + .and_then(|agents| agents.nickname_pool), + Some(vec![ + "Scout".to_string(), + "Builder".to_string(), + "Reviewer".to_string() + ]) + ); + let memories = r#" [memories] no_memories_if_mcp_or_web_search = true @@ -1579,6 +1596,109 @@ profile = "project" Ok(()) } +#[tokio::test] +async fn user_agents_nickname_pool_is_used_without_project_override() -> std::io::Result<()> { + let codex_home = TempDir::new()?; + let workspace = TempDir::new()?; + let workspace_key = workspace.path().to_string_lossy().replace('\\', "\\\\"); + std::fs::write( + codex_home.path().join(CONFIG_TOML_FILE), + format!( + r#" +[agents] +nickname_pool = [" Scout ", "", "Builder", "Scout", " ", "Reviewer"] + +[projects."{workspace_key}"] +trust_level = "trusted" +"#, + ), + )?; + + let config = ConfigBuilder::default() + .codex_home(codex_home.path().to_path_buf()) + .fallback_cwd(Some(workspace.path().to_path_buf())) + .build() + .await?; + + assert_eq!( + config.agent_nickname_pool, + vec![ + "Scout".to_string(), + "Builder".to_string(), + "Reviewer".to_string() + ] + ); + + Ok(()) +} + +#[tokio::test] +async fn project_agents_nickname_pool_overrides_user_pool() -> std::io::Result<()> { + let codex_home = TempDir::new()?; + let workspace = TempDir::new()?; + let workspace_key = workspace.path().to_string_lossy().replace('\\', "\\\\"); + std::fs::write( + codex_home.path().join(CONFIG_TOML_FILE), + format!( + r#" +[agents] +nickname_pool = ["Scout", "Builder"] + +[projects."{workspace_key}"] +trust_level = "trusted" +"#, + ), + )?; + let project_config_dir = workspace.path().join(".codex"); + std::fs::create_dir_all(&project_config_dir)?; + std::fs::write( + project_config_dir.join(CONFIG_TOML_FILE), + r#" +[agents] +nickname_pool = ["Reviewer"] +"#, + )?; + + let config = ConfigBuilder::default() + .codex_home(codex_home.path().to_path_buf()) + .fallback_cwd(Some(workspace.path().to_path_buf())) + .build() + .await?; + + assert_eq!(config.agent_nickname_pool, vec!["Reviewer".to_string()]); + + Ok(()) +} + +#[tokio::test] +async fn empty_agents_nickname_pool_preserves_default_behavior() -> std::io::Result<()> { + let codex_home = TempDir::new()?; + let workspace = TempDir::new()?; + let workspace_key = workspace.path().to_string_lossy().replace('\\', "\\\\"); + std::fs::write( + codex_home.path().join(CONFIG_TOML_FILE), + format!( + r#" +[agents] +nickname_pool = ["", " "] + +[projects."{workspace_key}"] +trust_level = "trusted" +"#, + ), + )?; + + let config = ConfigBuilder::default() + .codex_home(codex_home.path().to_path_buf()) + .fallback_cwd(Some(workspace.path().to_path_buf())) + .build() + .await?; + + assert!(config.agent_nickname_pool.is_empty()); + + Ok(()) +} + #[test] fn profile_sandbox_mode_overrides_base() -> std::io::Result<()> { let codex_home = TempDir::new()?; @@ -3064,6 +3184,7 @@ fn load_config_rejects_missing_agent_role_config_file() -> std::io::Result<()> { max_threads: None, max_depth: None, job_max_runtime_seconds: None, + nickname_pool: None, roles: BTreeMap::from([( "researcher".to_string(), AgentRoleToml { @@ -3929,6 +4050,7 @@ fn load_config_normalizes_agent_role_nickname_candidates() -> std::io::Result<() max_threads: None, max_depth: None, job_max_runtime_seconds: None, + nickname_pool: None, roles: BTreeMap::from([( "researcher".to_string(), AgentRoleToml { @@ -3970,6 +4092,7 @@ fn load_config_rejects_empty_agent_role_nickname_candidates() -> std::io::Result max_threads: None, max_depth: None, job_max_runtime_seconds: None, + nickname_pool: None, roles: BTreeMap::from([( "researcher".to_string(), AgentRoleToml { @@ -4005,6 +4128,7 @@ fn load_config_rejects_duplicate_agent_role_nickname_candidates() -> std::io::Re max_threads: None, max_depth: None, job_max_runtime_seconds: None, + nickname_pool: None, roles: BTreeMap::from([( "researcher".to_string(), AgentRoleToml { @@ -4040,6 +4164,7 @@ fn load_config_rejects_unsafe_agent_role_nickname_candidates() -> std::io::Resul max_threads: None, max_depth: None, job_max_runtime_seconds: None, + nickname_pool: None, roles: BTreeMap::from([( "researcher".to_string(), AgentRoleToml { @@ -4284,6 +4409,7 @@ fn test_precedence_fixture_with_o3_profile() -> std::io::Result<()> { tool_output_token_limit: None, agent_max_threads: DEFAULT_AGENT_MAX_THREADS, agent_max_depth: DEFAULT_AGENT_MAX_DEPTH, + agent_nickname_pool: Vec::new(), agent_roles: BTreeMap::new(), memories: MemoriesConfig::default(), agent_job_max_runtime_seconds: DEFAULT_AGENT_JOB_MAX_RUNTIME_SECONDS, @@ -4425,6 +4551,7 @@ fn test_precedence_fixture_with_gpt3_profile() -> std::io::Result<()> { tool_output_token_limit: None, agent_max_threads: DEFAULT_AGENT_MAX_THREADS, agent_max_depth: DEFAULT_AGENT_MAX_DEPTH, + agent_nickname_pool: Vec::new(), agent_roles: BTreeMap::new(), memories: MemoriesConfig::default(), agent_job_max_runtime_seconds: DEFAULT_AGENT_JOB_MAX_RUNTIME_SECONDS, @@ -4564,6 +4691,7 @@ fn test_precedence_fixture_with_zdr_profile() -> std::io::Result<()> { tool_output_token_limit: None, agent_max_threads: DEFAULT_AGENT_MAX_THREADS, agent_max_depth: DEFAULT_AGENT_MAX_DEPTH, + agent_nickname_pool: Vec::new(), agent_roles: BTreeMap::new(), memories: MemoriesConfig::default(), agent_job_max_runtime_seconds: DEFAULT_AGENT_JOB_MAX_RUNTIME_SECONDS, @@ -4689,6 +4817,7 @@ fn test_precedence_fixture_with_gpt5_profile() -> std::io::Result<()> { tool_output_token_limit: None, agent_max_threads: DEFAULT_AGENT_MAX_THREADS, agent_max_depth: DEFAULT_AGENT_MAX_DEPTH, + agent_nickname_pool: Vec::new(), agent_roles: BTreeMap::new(), memories: MemoriesConfig::default(), agent_job_max_runtime_seconds: DEFAULT_AGENT_JOB_MAX_RUNTIME_SECONDS, diff --git a/codex-rs/core/src/config/mod.rs b/codex-rs/core/src/config/mod.rs index a1f270458a..320e07861e 100644 --- a/codex-rs/core/src/config/mod.rs +++ b/codex-rs/core/src/config/mod.rs @@ -417,6 +417,9 @@ pub struct Config { /// Maximum nesting depth allowed for spawned agent threads. pub agent_max_depth: i32, + /// Global fallback nickname candidates for spawned agent threads. + pub agent_nickname_pool: Vec, + /// User-defined role declarations keyed by role name. pub agent_roles: BTreeMap, @@ -1666,6 +1669,15 @@ pub struct AgentsToml { #[schemars(range(min = 1))] pub job_max_runtime_seconds: Option, + /// Global fallback nickname candidates for spawned agent threads. + /// + /// Example: + /// ```toml + /// [agents] + /// nickname_pool = ["Scout", "Builder", "Reviewer"] + /// ``` + pub nickname_pool: Option>, + /// User-defined role declarations keyed by role name. /// /// Example: @@ -2442,6 +2454,13 @@ impl Config { "agents.job_max_runtime_seconds must fit within a 64-bit signed integer", )); } + let agent_nickname_pool = agent_roles::normalize_agent_nickname_pool( + "agents.nickname_pool", + cfg.agents + .as_ref() + .and_then(|agents| agents.nickname_pool.as_deref()), + )? + .unwrap_or_default(); let background_terminal_max_timeout = cfg .background_terminal_max_timeout .unwrap_or(DEFAULT_MAX_BACKGROUND_TERMINAL_TIMEOUT_MS) @@ -2707,6 +2726,7 @@ impl Config { tool_output_token_limit: cfg.tool_output_token_limit, agent_max_threads, agent_max_depth, + agent_nickname_pool, agent_roles, memories: cfg.memories.unwrap_or_default().into(), agent_job_max_runtime_seconds,