Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Parallelize instruction refresh and tool preparation (#47458)

Henry Levy0a2eb4696c26
diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rs
index b977bb16f6..bd0c2da1e3 100644
--- a/codex-rs/core/src/session/mod.rs
+++ b/codex-rs/core/src/session/mod.rs
@@ -3820,52 +3820,55 @@ impl Session {
);
let session_telemetry = settings.telemetry(&turn_context.session_telemetry);
let environments = environments.or_cancel(cancellation_token).await?;
- let (loaded_agents_md, warnings) = self
- .services
- .agents_md_manager
- .refresh(&turn_context.config, &environments)
- .or_cancel(cancellation_token)
- .await?;
- self.emit_instruction_warnings(warnings).await;
- let loaded_agents_md = loaded_agents_md?;
- let selected_capability_roots = self
- .resolve_selected_capability_roots_for_step(&environments)
- .await;
- let ready_selected_capability_roots =
- Self::ready_selected_capability_roots(&selected_capability_roots);
- let executor_capability_discovery = self
- .executor_capability_discovery_for_step(
- &turn_context.config,
- &ready_selected_capability_roots,
- &environments,
- )
- .or_cancel(cancellation_token)
- .await?;
- let extension_data = codex_extension_api::ExtensionData::new(turn_context.sub_id.clone());
- extension_data.insert(selected_capability_roots.clone());
- if let Some(discovery) = &executor_capability_discovery {
- extension_data.insert(discovery.as_ref().clone());
- if !discovery.sandbox_contexts().is_empty() {
- extension_data.insert(discovery.sandbox_contexts().clone());
+ // Keep both preparation futures off caller stacks while they are live together.
+ let load_agents_md = Box::pin(async {
+ let (loaded_agents_md, warnings) = self
+ .services
+ .agents_md_manager
+ .refresh(&turn_context.config, &environments)
+ .or_cancel(cancellation_token)
+ .await?;
+ self.emit_instruction_warnings(warnings).await;
+ loaded_agents_md
+ });
+ let prepare_tools = Box::pin(async {
+ let selected_capability_roots = self
+ .resolve_selected_capability_roots_for_step(&environments)
+ .await;
+ let ready_selected_capability_roots =
+ Self::ready_selected_capability_roots(&selected_capability_roots);
+ let executor_capability_discovery = self
+ .executor_capability_discovery_for_step(
+ &turn_context.config,
+ &ready_selected_capability_roots,
+ &environments,
+ )
+ .await;
+ let extension_data =
+ codex_extension_api::ExtensionData::new(turn_context.sub_id.clone());
+ extension_data.insert(selected_capability_roots.clone());
+ if let Some(discovery) = &executor_capability_discovery {
+ extension_data.insert(discovery.as_ref().clone());
+ if !discovery.sandbox_contexts().is_empty() {
+ extension_data.insert(discovery.sandbox_contexts().clone());
+ }
+ } else if !turn_context
+ .permission_profile_for_environments(&environments)
+ .file_system_sandbox_policy()
+ .has_full_disk_read_access()
+ {
+ let sandbox_contexts = environments
+ .turn_environments()
+ .map(|environment| {
+ (
+ environment.selection.environment_id.clone(),
+ environment.sandbox_context(/*additional_permissions*/ None),
+ )
+ })
+ .collect::<HashMap<_, _>>();
+ extension_data.insert(sandbox_contexts);
}
- } else if !turn_context
- .permission_profile_for_environments(&environments)
- .file_system_sandbox_policy()
- .has_full_disk_read_access()
- {
- let sandbox_contexts = environments
- .turn_environments()
- .map(|environment| {
- (
- environment.selection.environment_id.clone(),
- environment.sandbox_context(/*additional_permissions*/ None),
- )
- })
- .collect::<HashMap<_, _>>();
- extension_data.insert(sandbox_contexts);
- }
- let (mcp, prepared_recommendations) = async {
- tokio::join!(
+ let (mcp, prepared_recommendations) = tokio::join!(
// MCP refresh can be large; keep it off the sampling request's stack.
Box::pin(self.mcp_runtime_for_step(
turn_context.as_ref(),
@@ -3874,34 +3877,52 @@ impl Session {
required_plugins,
)),
turn::prepare_tool_recommendations(self.as_ref(), turn_context.as_ref()),
+ );
+ let mut selected_plugins = self
+ .services
+ .thread_extension_data
+ .get::<codex_extension_api::SelectedPluginSnapshot>()
+ .map(|snapshot| snapshot.as_ref().clone())
+ .unwrap_or_default();
+ selected_plugins.plugins.retain(|plugin| {
+ ready_selected_capability_roots
+ .iter()
+ .any(|root| root.id == plugin.selected_root_id)
+ });
+ extension_data.insert(selected_plugins.clone());
+ let tool_router = turn::built_tools(
+ self.as_ref(),
+ turn_context.as_ref(),
+ &settings.model_info,
+ &environments,
+ &mcp,
+ &extension_data,
+ prepared_recommendations,
)
- }
- .or_cancel(cancellation_token)
- .await?;
- let mut selected_plugins = self
- .services
- .thread_extension_data
- .get::<codex_extension_api::SelectedPluginSnapshot>()
- .map(|snapshot| snapshot.as_ref().clone())
- .unwrap_or_default();
- selected_plugins.plugins.retain(|plugin| {
- ready_selected_capability_roots
- .iter()
- .any(|root| root.id == plugin.selected_root_id)
+ .await?;
+ Ok::<_, CodexErr>((
+ selected_capability_roots,
+ executor_capability_discovery,
+ mcp,
+ tool_router,
+ selected_plugins,
+ ))
});
- extension_data.insert(selected_plugins.clone());
+ // Returned warnings must finish delivery even if tools fail or preparation is cancelled.
+ let (loaded_agents_md, prepared_tools) =
+ tokio::join!(load_agents_md, prepare_tools.or_cancel(cancellation_token));
+ let loaded_agents_md = loaded_agents_md?;
+ if cancellation_token.is_cancelled() {
+ return Err(CodexErr::TurnAborted);
+ }
+ let (
+ selected_capability_roots,
+ executor_capability_discovery,
+ mcp,
+ tool_router,
+ selected_plugins,
+ ) = prepared_tools??;
turn_context.extension_data.insert(selected_plugins);
- let tool_router = turn::built_tools(
- self.as_ref(),
- turn_context.as_ref(),
- &settings.model_info,
- &environments,
- &mcp,
- &extension_data,
- prepared_recommendations,
- )
- .or_cancel(cancellation_token)
- .await??;
Ok(Arc::new(StepContext {
settings,
token_budget,
diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rs
index 1a14903b62..2ece63f87a 100644
--- a/codex-rs/core/src/session/tests.rs
+++ b/codex-rs/core/src/session/tests.rs
@@ -8918,6 +8918,94 @@ pub(crate) async fn make_session_and_context_with_rx() -> (
make_session_and_context_with_dynamic_tools_and_rx(Vec::new()).await
}
+#[tokio::test]
+async fn cancelled_step_capture_finishes_warning_delivery() {
+ struct WarningProvider {
+ warnings: std::sync::Mutex<Vec<String>>,
+ }
+
+ impl codex_extension_api::ThreadInstructionsProvider for WarningProvider {
+ fn load_thread_instructions(&self) -> codex_extension_api::LoadInstructionsFuture<'_> {
+ Box::pin(async {
+ codex_extension_api::LoadedUserInstructions {
+ instructions: None,
+ warnings: std::mem::take(&mut *self.warnings.lock().expect("warnings")),
+ }
+ })
+ }
+ }
+
+ let warnings = vec![
+ "first provider warning".to_string(),
+ "second provider warning".to_string(),
+ ];
+ let warning_fields = |event: Event| match event.msg {
+ EventMsg::Warning(warning) => (event.id, warning.message),
+ other => panic!("expected a warning, got {other:?}"),
+ };
+ let (mut session, mut turn) = make_session_and_context().await;
+ Arc::make_mut(&mut turn.config).project_doc_max_bytes = 0;
+ session.services.agents_md_manager = Arc::new(AgentsMdManager::new(SessionInstructions {
+ thread_provider: Some(Arc::new(WarningProvider {
+ warnings: std::sync::Mutex::new(warnings.clone()),
+ })),
+ ..Default::default()
+ }));
+ attach_thread_persistence(&mut session).await;
+ let (tx, rx) = async_channel::bounded(/*cap*/ 1);
+ session.tx_event = tx;
+ let session = Arc::new(session);
+ let turn = Arc::new(turn);
+ let cancellation = CancellationToken::new();
+ let mut capture = Box::pin(tokio::task::unconstrained(
+ session.capture_step_context(Arc::clone(&turn), &cancellation),
+ ));
+ let first_warning = tokio::select! {
+ _ = &mut capture => panic!("capture must wait to deliver both warnings"),
+ event = timeout(Duration::from_secs(5), rx.recv()) => {
+ event.expect("first warning arrives").expect("event channel open")
+ }
+ };
+ assert_eq!(
+ warning_fields(first_warning.clone()),
+ (INITIAL_SUBMIT_ID.to_owned(), warnings[0].clone()),
+ );
+
+ // Keep the second warning blocked while cancellation is observed.
+ session
+ .tx_event
+ .try_send(first_warning.clone())
+ .expect("fill event channel");
+ cancellation.cancel();
+ assert!(futures::poll!(capture.as_mut()).is_pending());
+ assert_eq!(
+ warning_fields(rx.recv().await.expect("release event delivery")),
+ warning_fields(first_warning),
+ );
+ let Err(error) = capture.await else {
+ panic!("cancelled step cannot be published");
+ };
+ assert!(matches!(error.details(), CodexErrorDetails::TurnAborted));
+ assert_eq!(
+ warning_fields(
+ rx.try_recv()
+ .expect("second warning delivered before returning")
+ ),
+ (INITIAL_SUBMIT_ID.to_owned(), warnings[1].clone()),
+ );
+ assert!(
+ turn.extension_data
+ .get::<codex_extension_api::SelectedPluginSnapshot>()
+ .is_none()
+ );
+
+ session
+ .capture_step_context(turn, &CancellationToken::new())
+ .await
+ .expect("next capture succeeds without repeating consumed warnings");
+ assert!(rx.is_empty());
+}
+
#[tokio::test]
async fn refresh_mcp_servers_uses_latest_state_for_existing_turns() {
let (session, turn_context) = make_session_and_context().await;
diff --git a/codex-rs/core/tests/suite/agents_md_refresh.rs b/codex-rs/core/tests/suite/agents_md_refresh.rs
index 3155f6a14d..807ccecaa9 100644
--- a/codex-rs/core/tests/suite/agents_md_refresh.rs
+++ b/codex-rs/core/tests/suite/agents_md_refresh.rs
@@ -1,11 +1,206 @@
-//! Exercises global-instruction refreshes through real turns and provider reads.
+//! Exercises instruction refreshes and concurrent step preparation through real turns.
use super::*;
+use codex_extension_api::ExtensionData;
+use codex_extension_api::ExtensionFuture;
+use codex_extension_api::ExtensionRegistryBuilder;
+use codex_extension_api::SelectedPluginSnapshot;
+use codex_extension_api::ToolContributor;
+use codex_extension_api::TurnErrorInput;
+use codex_extension_api::TurnLifecycleContributor;
+use codex_extension_api::TurnStartInput;
+use codex_extension_api::TurnStopInput;
+use codex_protocol::dynamic_tools::DynamicToolFunctionSpec;
+use codex_protocol::dynamic_tools::DynamicToolSpec;
use codex_protocol::request_user_input::RequestUserInputAnswer;
use codex_protocol::request_user_input::RequestUserInputResponse;
+use codex_tools::ToolCall;
+use codex_tools::ToolExecutor;
use pretty_assertions::assert_eq;
use std::collections::HashMap;
use tokio::sync::Notify;
+use tokio::sync::oneshot;
+
+struct StepPreparationObserver {
+ instructions: RecordingThreadInstructionsProvider,
+ tools_ready: Mutex<Option<oneshot::Sender<()>>>,
+ waiting_for_tools: Mutex<Option<oneshot::Receiver<()>>>,
+ published_plugins: Mutex<Vec<(&'static str, bool)>>,
+}
+
+impl StepPreparationObserver {
+ fn record_plugins(&self, phase: &'static str, turn_store: &ExtensionData) {
+ self.published_plugins
+ .lock()
+ .expect("plugin observations")
+ .push((phase, turn_store.get::<SelectedPluginSnapshot>().is_some()));
+ }
+}
+
+impl ThreadInstructionsProvider for StepPreparationObserver {
+ fn load_thread_instructions(&self) -> LoadInstructionsFuture<'_> {
+ let ready = self
+ .waiting_for_tools
+ .lock()
+ .expect("instruction gate")
+ .take();
+ Box::pin(async move {
+ if let Some(ready) = ready {
+ ready.await.expect("tool preparation must complete");
+ }
+ self.instructions.load_thread_instructions().await
+ })
+ }
+}
+
+impl ToolContributor for StepPreparationObserver {
+ fn tools(
+ &self,
+ _session_store: &ExtensionData,
+ _thread_store: &ExtensionData,
+ ) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {
+ if let Some(ready) = self.tools_ready.lock().expect("tool gate").take() {
+ ready
+ .send(())
+ .expect("instruction refresh must remain live");
+ }
+ Vec::new()
+ }
+}
+
+impl TurnLifecycleContributor for StepPreparationObserver {
+ fn on_turn_start<'a>(&'a self, input: TurnStartInput<'a>) -> ExtensionFuture<'a, ()> {
+ Box::pin(async move { self.record_plugins("start", input.turn_store) })
+ }
+
+ fn on_turn_error<'a>(&'a self, input: TurnErrorInput<'a>) -> ExtensionFuture<'a, ()> {
+ Box::pin(async move { self.record_plugins("error", input.turn_store) })
+ }
+
+ fn on_turn_stop<'a>(&'a self, input: TurnStopInput<'a>) -> ExtensionFuture<'a, ()> {
+ Box::pin(async move { self.record_plugins("stop", input.turn_store) })
+ }
+}
+
+#[derive(Clone, Copy)]
+enum PreparationOutcome {
+ Success,
+ ToolCollision,
+ InstructionError,
+ BothErrors,
+}
+
+#[test_case::test_case(PreparationOutcome::Success; "publish after both branches succeed")]
+#[test_case::test_case(PreparationOutcome::ToolCollision; "warning survives tool failure")]
+#[test_case::test_case(PreparationOutcome::InstructionError; "instruction error prevents publication")]
+#[test_case::test_case(PreparationOutcome::BothErrors; "instruction error takes precedence")]
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn concurrent_preparation_preserves_warnings_errors_and_plugin_publication(
+ outcome: PreparationOutcome,
+) -> Result<()> {
+ let server = start_mock_server().await;
+ let request = mount_sse_once(&server, responses::sse_completed("prepared")).await;
+ let observer = Arc::new(StepPreparationObserver {
+ instructions: RecordingThreadInstructionsProvider::with_text(TASK_USER_INSTRUCTIONS),
+ tools_ready: Mutex::default(),
+ waiting_for_tools: Mutex::default(),
+ published_plugins: Mutex::default(),
+ });
+ let mut extensions = ExtensionRegistryBuilder::new();
+ extensions.tool_contributor(observer.clone());
+ extensions.turn_lifecycle_contributor(observer.clone());
+ let mut builder = test_codex()
+ .with_extensions(Arc::new(extensions.build()))
+ .with_config(|config| {
+ config.tool_registry.error_on_tool_collisions = true;
+ config.update_plan_enabled = true;
+ });
+ let test = builder.build_with_auto_env(&server).await?;
+ let succeeds = matches!(outcome, PreparationOutcome::Success);
+ let dynamic_tools = if matches!(
+ outcome,
+ PreparationOutcome::ToolCollision | PreparationOutcome::BothErrors
+ ) {
+ vec![DynamicToolSpec::Function(DynamicToolFunctionSpec {
+ name: "update_plan".to_string(),
+ description: "Collides with the built-in planning tool.".to_string(),
+ input_schema: json!({"type": "object", "properties": {}}),
+ defer_loading: false,
+ })]
+ } else {
+ Vec::new()
+ };
+ let thread = test
+ .thread_manager
+ .start_thread(StartThreadOptions {
+ environments: Some(vec![test.executor_environment().selection().clone()]),
+ dynamic_tools,
+ thread_instructions_provider: Some(observer.clone()),
+ ..StartThreadOptions::new(test.config.clone())
+ })
+ .await?
+ .thread;
+ observer
+ .instructions
+ .set_warnings(vec![PROVIDER_WARNING.to_string()]);
+ if matches!(
+ outcome,
+ PreparationOutcome::InstructionError | PreparationOutcome::BothErrors
+ ) {
+ observer.instructions.set_instructions(Some(Instructions {
+ text: "x".repeat(approx_bytes_for_tokens(/*tokens*/ 10_001)),
+ source: None,
+ }));
+ }
+ // The provider finishes only once the other branch has reached tool construction.
+ // A tool collision must not cancel the provider or hide its warning/error.
+ let (tools_ready, waiting_for_tools) = oneshot::channel();
+ *observer.tools_ready.lock().expect("tool gate") = Some(tools_ready);
+ *observer.waiting_for_tools.lock().expect("instruction gate") = Some(waiting_for_tools);
+ thread
+ .start_or_steer_turn(TurnInputRequest::user_input(vec![UserInput::Text {
+ text: "prepare instructions and tools".to_string(),
+ text_elements: Vec::new(),
+ }]))
+ .await?;
+ let mut notices = Vec::new();
+ wait_for_event(&thread, |event| {
+ match event {
+ EventMsg::Warning(warning) => notices.push(("warning", warning.message.clone())),
+ EventMsg::Error(error) => notices.push(("error", error.message.clone())),
+ _ => {}
+ }
+ matches!(event, EventMsg::TurnComplete(_))
+ })
+ .await;
+ let mut expected_notices = vec![("warning", PROVIDER_WARNING.to_string())];
+ let mut expected_publication = vec![("start", false)];
+ match outcome {
+ PreparationOutcome::Success => {}
+ PreparationOutcome::ToolCollision => {
+ expected_notices.push(("error", "duplicate tool: functions.update_plan".to_string()));
+ expected_publication.push(("error", false));
+ }
+ PreparationOutcome::InstructionError | PreparationOutcome::BothErrors => {
+ expected_notices.push((
+ "error",
+ "thread instructions exceed the limit of 10000 estimated tokens (10001 estimated tokens provided)".to_string(),
+ ));
+ expected_publication.push(("error", false));
+ }
+ }
+ expected_publication.push(("stop", succeeds));
+ assert_eq!(notices, expected_notices);
+ assert_eq!(
+ *observer
+ .published_plugins
+ .lock()
+ .expect("plugin observations"),
+ expected_publication
+ );
+ assert_eq!(request.requests().len(), usize::from(succeeds));
+ Ok(())
+}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn failed_global_read_keeps_instructions_until_recovery() -> Result<()> {