Repository navigation
feat: fork thread multi agent #12499
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
b6d6011
e8de9b8
1befa18
c449d6b
b1f25d0
aa078d0
f5ff85e
435ca4e
6055f14
eb86090
d4e1d38
4d9b1ab
4077f1c
d077c5b
4f6c59e
2236e58
1e864b4
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,11 +4,16 @@ use crate::agent::status::is_final; | |
| use crate::error::CodexErr; | ||
| use crate::error::Result as CodexResult; | ||
| use crate::find_thread_path_by_id_str; | ||
| use crate::rollout::RolloutRecorder; | ||
| use crate::session_prefix::format_subagent_notification_message; | ||
| use crate::state_db; | ||
| use crate::thread_manager::ThreadManagerState; | ||
| use codex_protocol::ThreadId; | ||
| use codex_protocol::models::FunctionCallOutputPayload; | ||
| use codex_protocol::models::ResponseItem; | ||
| use codex_protocol::protocol::InitialHistory; | ||
| use codex_protocol::protocol::Op; | ||
| use codex_protocol::protocol::RolloutItem; | ||
| use codex_protocol::protocol::SessionSource; | ||
| use codex_protocol::protocol::SubAgentSource; | ||
| use codex_protocol::protocol::TokenUsage; | ||
|
|
@@ -18,6 +23,12 @@ use std::sync::Weak; | |
| use tokio::sync::watch; | ||
|
|
||
| const AGENT_NAMES: &str = include_str!("agent_names.txt"); | ||
| const FORKED_SPAWN_AGENT_OUTPUT_MESSAGE: &str = "You are the newly spawned agent. The prior conversation history was forked from your parent agent. Treat the next user message as your new task, and use the forked history only as background context."; | ||
|
|
||
| #[derive(Clone, Debug, Default)] | ||
| pub(crate) struct SpawnAgentOptions { | ||
| pub(crate) fork_parent_spawn_call_id: Option<String>, | ||
| } | ||
|
|
||
| fn agent_nickname_list() -> Vec<&'static str> { | ||
| AGENT_NAMES | ||
|
|
@@ -57,6 +68,17 @@ impl AgentControl { | |
| config: crate::config::Config, | ||
| items: Vec<UserInput>, | ||
| session_source: Option<SessionSource>, | ||
| ) -> CodexResult<ThreadId> { | ||
| self.spawn_agent_with_options(config, items, session_source, SpawnAgentOptions::default()) | ||
| .await | ||
| } | ||
|
|
||
| pub(crate) async fn spawn_agent_with_options( | ||
| &self, | ||
| config: crate::config::Config, | ||
| items: Vec<UserInput>, | ||
| session_source: Option<SessionSource>, | ||
| options: SpawnAgentOptions, | ||
| ) -> CodexResult<ThreadId> { | ||
| let state = self.upgrade()?; | ||
| let mut reservation = self.state.reserve_spawn_slot(config.agent_max_threads)?; | ||
|
|
@@ -82,9 +104,75 @@ impl AgentControl { | |
| // The same `AgentControl` is sent to spawn the thread. | ||
| let new_thread = match session_source { | ||
| Some(session_source) => { | ||
| state | ||
| .spawn_new_thread_with_source(config, self.clone(), session_source, false, None) | ||
| .await? | ||
| if let Some(call_id) = options.fork_parent_spawn_call_id.as_ref() { | ||
| let SessionSource::SubAgent(SubAgentSource::ThreadSpawn { | ||
| parent_thread_id, | ||
| .. | ||
| }) = session_source.clone() | ||
| else { | ||
| return Err(CodexErr::Fatal( | ||
| "spawn_agent fork requires a thread-spawn session source".to_string(), | ||
| )); | ||
| }; | ||
| let parent_thread = state.get_thread(parent_thread_id).await.ok(); | ||
| if let Some(parent_thread) = parent_thread.as_ref() { | ||
| // `record_conversation_items` only queues rollout writes asynchronously. | ||
| // Flush/materialize the live parent before snapshotting JSONL for a fork. | ||
| parent_thread | ||
| .codex | ||
| .session | ||
| .ensure_rollout_materialized() | ||
| .await; | ||
| parent_thread.codex.session.flush_rollout().await; | ||
| } | ||
| let rollout_path = parent_thread | ||
| .as_ref() | ||
| .and_then(|parent_thread| parent_thread.rollout_path()) | ||
| .or(find_thread_path_by_id_str( | ||
| config.codex_home.as_path(), | ||
| &parent_thread_id.to_string(), | ||
| ) | ||
| .await?) | ||
|
jif-oai marked this conversation as resolved.
Resolved
|
||
| .ok_or_else(|| { | ||
| CodexErr::Fatal(format!( | ||
| "parent thread rollout unavailable for fork: {parent_thread_id}" | ||
| )) | ||
| })?; | ||
|
Comment on lines
+136
to
+140
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Forking hard-requires a rollout file path and returns Useful? React with 👍 / 👎.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. won't do |
||
| let mut forked_rollout_items = | ||
| RolloutRecorder::get_rollout_history(&rollout_path) | ||
| .await? | ||
| .get_rollout_items(); | ||
|
jif-oai marked this conversation as resolved.
Resolved
|
||
| let mut output = FunctionCallOutputPayload::from_text( | ||
| FORKED_SPAWN_AGENT_OUTPUT_MESSAGE.to_string(), | ||
| ); | ||
| output.success = Some(true); | ||
| forked_rollout_items.push(RolloutItem::ResponseItem( | ||
| ResponseItem::FunctionCallOutput { | ||
| call_id: call_id.clone(), | ||
| output, | ||
| }, | ||
| )); | ||
| let initial_history = InitialHistory::Forked(forked_rollout_items); | ||
| state | ||
| .fork_thread_with_source( | ||
| config, | ||
| initial_history, | ||
| self.clone(), | ||
| session_source, | ||
| false, | ||
| ) | ||
| .await? | ||
| } else { | ||
| state | ||
| .spawn_new_thread_with_source( | ||
| config, | ||
| self.clone(), | ||
| session_source, | ||
| false, | ||
| None, | ||
| ) | ||
| .await? | ||
| } | ||
| } | ||
| None => state.spawn_new_thread(config, self.clone()).await?, | ||
| }; | ||
|
|
@@ -421,6 +509,21 @@ mod tests { | |
| }) | ||
| } | ||
|
|
||
| /// Returns true when any message item contains `needle` in a text span. | ||
| fn history_contains_text(history_items: &[ResponseItem], needle: &str) -> bool { | ||
|
jif-oai marked this conversation as resolved.
Resolved
|
||
| history_items.iter().any(|item| { | ||
| let ResponseItem::Message { content, .. } = item else { | ||
| return false; | ||
| }; | ||
| content.iter().any(|content_item| match content_item { | ||
| ContentItem::InputText { text } | ContentItem::OutputText { text } => { | ||
| text.contains(needle) | ||
| } | ||
| ContentItem::InputImage { .. } => false, | ||
| }) | ||
| }) | ||
| } | ||
|
|
||
| async fn wait_for_subagent_notification(parent_thread: &Arc<CodexThread>) -> bool { | ||
| let wait = async { | ||
| loop { | ||
|
|
@@ -673,6 +776,242 @@ mod tests { | |
| assert_eq!(captured, Some(expected)); | ||
| } | ||
|
|
||
| #[tokio::test] | ||
| async fn spawn_agent_can_fork_parent_thread_history() { | ||
| let harness = AgentControlHarness::new().await; | ||
| let (parent_thread_id, parent_thread) = harness.start_thread().await; | ||
| parent_thread | ||
| .inject_user_message_without_turn("parent seed context".to_string()) | ||
| .await; | ||
| let turn_context = parent_thread.codex.session.new_default_turn().await; | ||
| let parent_spawn_call_id = "spawn-call-history".to_string(); | ||
| let parent_spawn_call = ResponseItem::FunctionCall { | ||
| id: None, | ||
| name: "spawn_agent".to_string(), | ||
| arguments: "{}".to_string(), | ||
| call_id: parent_spawn_call_id.clone(), | ||
| }; | ||
| parent_thread | ||
| .codex | ||
| .session | ||
| .record_conversation_items(turn_context.as_ref(), &[parent_spawn_call]) | ||
| .await; | ||
| parent_thread | ||
| .codex | ||
| .session | ||
| .ensure_rollout_materialized() | ||
| .await; | ||
| parent_thread.codex.session.flush_rollout().await; | ||
|
|
||
| let child_thread_id = harness | ||
| .control | ||
| .spawn_agent_with_options( | ||
| harness.config.clone(), | ||
| text_input("child task"), | ||
| Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn { | ||
| parent_thread_id, | ||
| depth: 1, | ||
| agent_nickname: None, | ||
| agent_role: None, | ||
| })), | ||
| SpawnAgentOptions { | ||
| fork_parent_spawn_call_id: Some(parent_spawn_call_id), | ||
| }, | ||
| ) | ||
| .await | ||
| .expect("forked spawn should succeed"); | ||
|
|
||
| let child_thread = harness | ||
| .manager | ||
| .get_thread(child_thread_id) | ||
| .await | ||
| .expect("child thread should be registered"); | ||
| assert_ne!(child_thread_id, parent_thread_id); | ||
| let history = child_thread.codex.session.clone_history().await; | ||
| assert!(history_contains_text( | ||
| history.raw_items(), | ||
| "parent seed context" | ||
| )); | ||
|
|
||
| let expected = ( | ||
| child_thread_id, | ||
| Op::UserInput { | ||
| items: vec![UserInput::Text { | ||
| text: "child task".to_string(), | ||
| text_elements: Vec::new(), | ||
| }], | ||
| final_output_json_schema: None, | ||
| }, | ||
| ); | ||
| let captured = harness | ||
| .manager | ||
| .captured_ops() | ||
| .into_iter() | ||
| .find(|entry| *entry == expected); | ||
| assert_eq!(captured, Some(expected)); | ||
|
|
||
| let _ = harness | ||
| .control | ||
| .shutdown_agent(child_thread_id) | ||
| .await | ||
| .expect("child shutdown should submit"); | ||
| let _ = parent_thread | ||
| .submit(Op::Shutdown {}) | ||
| .await | ||
| .expect("parent shutdown should submit"); | ||
| } | ||
|
|
||
| #[tokio::test] | ||
| async fn spawn_agent_fork_injects_output_for_parent_spawn_call() { | ||
| let harness = AgentControlHarness::new().await; | ||
| let (parent_thread_id, parent_thread) = harness.start_thread().await; | ||
| let turn_context = parent_thread.codex.session.new_default_turn().await; | ||
| let parent_spawn_call_id = "spawn-call-1".to_string(); | ||
| let parent_spawn_call = ResponseItem::FunctionCall { | ||
| id: None, | ||
| name: "spawn_agent".to_string(), | ||
| arguments: "{}".to_string(), | ||
| call_id: parent_spawn_call_id.clone(), | ||
| }; | ||
| parent_thread | ||
| .codex | ||
| .session | ||
| .record_conversation_items(turn_context.as_ref(), &[parent_spawn_call]) | ||
| .await; | ||
| parent_thread | ||
| .codex | ||
| .session | ||
| .ensure_rollout_materialized() | ||
| .await; | ||
| parent_thread.codex.session.flush_rollout().await; | ||
|
|
||
| let child_thread_id = harness | ||
| .control | ||
| .spawn_agent_with_options( | ||
| harness.config.clone(), | ||
| text_input("child task"), | ||
| Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn { | ||
| parent_thread_id, | ||
| depth: 1, | ||
| agent_nickname: None, | ||
| agent_role: None, | ||
| })), | ||
| SpawnAgentOptions { | ||
| fork_parent_spawn_call_id: Some(parent_spawn_call_id.clone()), | ||
| }, | ||
| ) | ||
| .await | ||
| .expect("forked spawn should succeed"); | ||
|
|
||
| let child_thread = harness | ||
| .manager | ||
| .get_thread(child_thread_id) | ||
| .await | ||
| .expect("child thread should be registered"); | ||
| let history = child_thread.codex.session.clone_history().await; | ||
| let injected_output = history.raw_items().iter().find_map(|item| match item { | ||
| ResponseItem::FunctionCallOutput { call_id, output } | ||
| if call_id == &parent_spawn_call_id => | ||
| { | ||
| Some(output) | ||
| } | ||
| _ => None, | ||
| }); | ||
| let injected_output = | ||
| injected_output.expect("forked child should contain synthetic tool output"); | ||
| assert_eq!( | ||
| injected_output.text_content(), | ||
| Some(FORKED_SPAWN_AGENT_OUTPUT_MESSAGE) | ||
| ); | ||
| assert_eq!(injected_output.success, Some(true)); | ||
|
|
||
| let _ = harness | ||
| .control | ||
| .shutdown_agent(child_thread_id) | ||
| .await | ||
| .expect("child shutdown should submit"); | ||
| let _ = parent_thread | ||
| .submit(Op::Shutdown {}) | ||
| .await | ||
| .expect("parent shutdown should submit"); | ||
| } | ||
|
|
||
| #[tokio::test] | ||
| async fn spawn_agent_fork_flushes_parent_rollout_before_loading_history() { | ||
| let harness = AgentControlHarness::new().await; | ||
| let (parent_thread_id, parent_thread) = harness.start_thread().await; | ||
| let turn_context = parent_thread.codex.session.new_default_turn().await; | ||
| let parent_spawn_call_id = "spawn-call-unflushed".to_string(); | ||
| let parent_spawn_call = ResponseItem::FunctionCall { | ||
| id: None, | ||
| name: "spawn_agent".to_string(), | ||
| arguments: "{}".to_string(), | ||
| call_id: parent_spawn_call_id.clone(), | ||
| }; | ||
| parent_thread | ||
| .codex | ||
| .session | ||
| .record_conversation_items(turn_context.as_ref(), &[parent_spawn_call]) | ||
| .await; | ||
|
|
||
| let child_thread_id = harness | ||
| .control | ||
| .spawn_agent_with_options( | ||
| harness.config.clone(), | ||
| text_input("child task"), | ||
| Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn { | ||
| parent_thread_id, | ||
| depth: 1, | ||
| agent_nickname: None, | ||
| agent_role: None, | ||
| })), | ||
| SpawnAgentOptions { | ||
| fork_parent_spawn_call_id: Some(parent_spawn_call_id.clone()), | ||
| }, | ||
| ) | ||
| .await | ||
| .expect("forked spawn should flush parent rollout before loading history"); | ||
|
|
||
| let child_thread = harness | ||
| .manager | ||
| .get_thread(child_thread_id) | ||
| .await | ||
| .expect("child thread should be registered"); | ||
| let history = child_thread.codex.session.clone_history().await; | ||
|
|
||
| let mut parent_call_index = None; | ||
| let mut injected_output_index = None; | ||
| for (idx, item) in history.raw_items().iter().enumerate() { | ||
| match item { | ||
| ResponseItem::FunctionCall { call_id, .. } if call_id == &parent_spawn_call_id => { | ||
| parent_call_index = Some(idx); | ||
| } | ||
| ResponseItem::FunctionCallOutput { call_id, .. } | ||
| if call_id == &parent_spawn_call_id => | ||
| { | ||
| injected_output_index = Some(idx); | ||
| } | ||
| _ => {} | ||
| } | ||
| } | ||
|
|
||
| let parent_call_index = | ||
| parent_call_index.expect("forked child should include the parent spawn_agent call"); | ||
| let injected_output_index = injected_output_index | ||
| .expect("forked child should include synthetic output for the parent spawn_agent call"); | ||
| assert!(parent_call_index < injected_output_index); | ||
|
|
||
| let _ = harness | ||
| .control | ||
| .shutdown_agent(child_thread_id) | ||
| .await | ||
| .expect("child shutdown should submit"); | ||
| let _ = parent_thread | ||
| .submit(Op::Shutdown {}) | ||
| .await | ||
| .expect("parent shutdown should submit"); | ||
| } | ||
|
|
||
| #[tokio::test] | ||
| async fn spawn_agent_respects_max_threads_limit() { | ||
| let max_threads = 1usize; | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.