Lightweight coding agent that runs in your terminal
Rust
Honor explicit plugin mentions during MCP startup (#42406)
Matthew Zeng460b63e5f43c
diff --git a/codex-rs/app-server/tests/suite/v2/selected_capability_stack.rs b/codex-rs/app-server/tests/suite/v2/selected_capability_stack.rsindex 79c92d8600..cff3e76733 100644--- a/codex-rs/app-server/tests/suite/v2/selected_capability_stack.rs+++ b/codex-rs/app-server/tests/suite/v2/selected_capability_stack.rs@@ -5,12 +5,15 @@ use anyhow::Context;use anyhow::Result;use app_test_support::ChatGptAuthFixture;use app_test_support::TestAppServer;+use app_test_support::create_final_assistant_message_sse_response;+use app_test_support::create_request_user_input_sse_response;use app_test_support::to_response;use app_test_support::write_chatgpt_auth;use app_test_support::write_mock_responses_config_toml_with_chatgpt_base_url;use codex_app_server_protocol::AppInfo;use codex_app_server_protocol::CapabilityRootLocation;use codex_app_server_protocol::EnvironmentAddResponse;+use codex_app_server_protocol::EnvironmentInfoResponse;use codex_app_server_protocol::ListMcpServerStatusParams;use codex_app_server_protocol::ListMcpServerStatusResponse;use codex_app_server_protocol::RequestId;@@ -22,6 +25,9 @@ use codex_app_server_protocol::ThreadStartParams;use codex_app_server_protocol::ThreadStartResponse;use codex_app_server_protocol::TurnEnvironmentParams;use codex_app_server_protocol::TurnStartParams;+use codex_app_server_protocol::TurnStartResponse;+use codex_app_server_protocol::TurnSteerParams;+use codex_app_server_protocol::TurnSteerResponse;use codex_app_server_protocol::UserInput;use codex_config::types::AuthCredentialsStoreMode;use codex_exec_server::LOCAL_ENVIRONMENT_ID;@@ -64,6 +70,122 @@ const MCP_SERVER_NAME: &str = "executor_probe";const MCP_CALL_ID: &str = "selected-executor-mcp-call";const CONNECTOR_ID: &str = "calendar";+#[derive(Clone, Copy)]+enum PluginMention {+ Unmentioned,+ Link,+ Structured,+}++#[test_case(PluginMention::Unmentioned, false; "optional direct")]+#[test_case(PluginMention::Unmentioned, true; "optional batched")]+#[test_case(PluginMention::Link, false; "plugin link direct")]+#[test_case(PluginMention::Link, true; "plugin link batched")]+#[test_case(PluginMention::Structured, false; "structured mention direct")]+#[test_case(PluginMention::Structured, true; "structured mention batched")]+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn selected_plugin_mcp_startup_respects_explicit_mentions(+ mention: PluginMention,+ executor_capability_discovery: bool,+) -> Result<()> {+ let explicitly_mentioned = !matches!(mention, PluginMention::Unmentioned);+ let responses_server = responses::start_mock_server().await;+ let (apps_url, apps_server_handle) =+ start_apps_server_with_delays(Vec::new(), Vec::new(), Duration::ZERO, Duration::ZERO)+ .await?;+ let fixture = selected_capability_fixture(&responses_server.uri(), &apps_url)?;+ let config_path = fixture.codex_home.path().join("config.toml");+ let config = std::fs::read_to_string(&config_path)?.replace(+ "executor_capability_discovery = true",+ &format!("executor_capability_discovery = {executor_capability_discovery}"),+ );+ std::fs::write(config_path, config)?;+ let initialize_barrier = fixture.block_mcp_startup()?;+ let response_mock = responses::mount_sse_once(+ &responses_server,+ create_final_assistant_message_sse_response("Done")?,+ )+ .await;+ let mut app_server = TestAppServer::builder()+ .with_codex_home(fixture.codex_home.path())+ // This fixture owns environments.toml and selects its environments explicitly.+ .without_auto_env()+ .build()+ .await?;+ timeout(READ_TIMEOUT, app_server.initialize()).await??;+ let thread_id = start_thread(+ &mut app_server,+ fixture.selected_root,+ fixture.environment_cwd.clone(),+ )+ .await?;+ let mut exec_server =+ spawn_exec_server(fixture.codex_home.path(), &fixture.exec_server_url).await?;+ add_environment(&mut app_server, &fixture.exec_server_url).await?;++ let text_input = |text| UserInput::Text {+ text,+ text_elements: Vec::new(),+ };+ let input = match mention {+ PluginMention::Unmentioned => text_input("Answer without using tools".to_string()),+ PluginMention::Link => {+ text_input(format!("Use [@executor-demo](plugin://{PLUGIN_ID}) now"))+ }+ PluginMention::Structured => UserInput::Mention {+ name: PLUGIN_DISPLAY_NAME.to_string(),+ path: format!("plugin://{PLUGIN_ID}?app=com.example.editor"),+ },+ };+ let request_id = app_server+ .send_turn_start_request(TurnStartParams {+ thread_id,+ input: vec![input],+ environments: Some(vec![TurnEnvironmentParams {+ environment_id: LOCAL_ENVIRONMENT_ID.to_string(),+ cwd: fixture.environment_cwd.into(),+ runtime_workspace_roots: None,+ }]),+ ..Default::default()+ })+ .await?;+ timeout(+ READ_TIMEOUT,+ app_server.read_stream_until_response_message(RequestId::Integer(request_id)),+ )+ .await??;+ wait_for_pid_file(&fixture.pid_file).await?;+ if explicitly_mentioned {+ // An explicit mention must outwait the optional one-second grace.+ tokio::time::sleep(Duration::from_secs(3)).await;+ assert!(response_mock.requests().is_empty());+ std::fs::write(&initialize_barrier, "ready")?;+ }+ let turn_timeout = if explicitly_mentioned {+ READ_TIMEOUT+ } else {+ Duration::from_secs(5)+ };+ timeout(+ turn_timeout,+ app_server.read_stream_until_notification_message("turn/completed"),+ )+ .await??;+ let request = response_mock.single_request();+ assert_selected_skill_catalog_available(&request);+ assert_eq!(+ request+ .tool_by_name(&format!("mcp__{MCP_SERVER_NAME}"), "echo")+ .is_some(),+ explicitly_mentioned,+ );++ exec_server.kill().await?;+ apps_server_handle.abort();+ let _ = apps_server_handle.await;+ Ok(())+}+#[test_case(false; "direct selected root discovery")]#[test_case(true; "batched executor capability discovery")]#[tokio::test(flavor = "multi_thread", worker_threads = 2)]@@ -257,10 +379,11 @@ async fn selected_capability_stack_tracks_environment_availability_and_resume()add_environment(&mut app_server, &fixture.exec_server_url).await?;wait_for_selected_mcp_server(&mut app_server, &thread_id).await?;+ // A skill mention alone does not wait for MCP startup.run_turn(&mut app_server,&thread_id,- &format!("Use ${SKILL_NAME} and call its selected executor MCP"),+ &format!("Use ${SKILL_NAME} and call [${MCP_SERVER_NAME}](mcp://{MCP_SERVER_NAME})"),fixture.environment_cwd.clone(),).await?;@@ -322,7 +445,9 @@ async fn selected_capability_stack_tracks_environment_availability_and_resume()run_turn(&mut app_server,&thread_id,- &format!("Use ${SKILL_NAME} after reattaching the selected executor"),+ &format!(+ "Use ${SKILL_NAME} with [${MCP_SERVER_NAME}](mcp://{MCP_SERVER_NAME}) after reattaching the selected executor"+ ),fixture.environment_cwd,).await?;@@ -352,10 +477,44 @@ async fn selected_capability_stack_tracks_environment_availability_and_resume()Ok(())}+#[derive(Clone, Copy)]+enum MentionTiming {+ Unmentioned,+ Initial,+ InitialBeforeRestart,+ Steered,+}++#[derive(Clone, Copy)]+enum MentionTarget {+ Plugin,+ Server,+}++#[test_case(MentionTiming::Unmentioned, MentionTarget::Plugin; "without a mention")]+#[test_case(MentionTiming::Initial, MentionTarget::Plugin; "with an initial plugin mention")]+#[test_case(MentionTiming::InitialBeforeRestart, MentionTarget::Plugin; "with an initial plugin mention across a restart")]+#[test_case(MentionTiming::Steered, MentionTarget::Plugin; "with a steered plugin mention")]+#[test_case(MentionTiming::Initial, MentionTarget::Server; "with an initial server mention")]+#[test_case(MentionTiming::Steered, MentionTarget::Server; "with a steered server mention")]#[tokio::test(flavor = "multi_thread", worker_threads = 2)]-async fn selected_capabilities_become_available_between_samples_in_one_turn() -> Result<()> {+async fn selected_capabilities_become_available_between_samples_in_one_turn(+ mention_timing: MentionTiming,+ mention_target: MentionTarget,+) -> Result<()> {const USER_INPUT_CALL_ID: &str = "pause-for-environment";+ const MCP_USER_INPUT_CALL_ID: &str = "pause-for-mcp";+ let mention_link = match mention_target {+ MentionTarget::Plugin => format!("[@executor-demo](plugin://{PLUGIN_ID})"),+ MentionTarget::Server => format!("[${MCP_SERVER_NAME}](mcp://{MCP_SERVER_NAME})"),+ };+ let samples_before_attach = if matches!(mention_timing, MentionTiming::Steered) {+ 2+ } else {+ 1+ };+ let continue_answers = json!({ "answers": { "confirm_path": { "answers": ["yes"] } } });let responses_server = responses::start_mock_server().await;let (apps_url, apps_server_handle) = start_apps_server_with_delays(vec![AppInfo {@@ -381,33 +540,43 @@ async fn selected_capabilities_become_available_between_samples_in_one_turn() ->).await?;let fixture = selected_capability_fixture(&responses_server.uri(), &apps_url)?;+ let initialize_barrier = fixture.block_mcp_startup()?;+ let stop_hook_barrier = if matches!(mention_timing, MentionTiming::InitialBeforeRestart) {+ let barrier = fixture.codex_home.path().join("allow-stop-hook");+ let hook_path = fixture.codex_home.path().join("wait-for-stop.py");+ std::fs::write(+ &hook_path,+ "import json\nimport sys\nimport time\nfrom pathlib import Path\n\n\+ json.load(sys.stdin)\nwhile not Path(sys.argv[1]).exists():\n time.sleep(0.01)\n",+ )?;+ let command = toml::Value::String(format!(+ "python3 \"{}\" \"{}\"",+ hook_path.display(),+ barrier.display()+ ));+ std::fs::write(+ fixture.codex_home.path().join("requirements.toml"),+ format!(+ "[[hooks.Stop]]\n[[hooks.Stop.hooks]]\ntype = 'command'\ncommand = {command}\ntimeout = 60\n"+ ),+ )?;+ let config_path = fixture.codex_home.path().join("config.toml");+ let config = std::fs::read_to_string(&config_path)?+ .replace("[features]\n", "[features]\nhooks = true\n");+ std::fs::write(config_path, config)?;+ Some(barrier)+ } else {+ None+ };let response_mock = responses::mount_sse_sequence(&responses_server,vec![- responses::sse(vec![- responses::ev_response_created("environment-pending"),- responses::ev_function_call(- USER_INPUT_CALL_ID,- "request_user_input",- &json!({- "questions": [{- "id": "continue",- "header": "Continue",- "question": "Continue after the executor is attached?",- "options": [{- "label": "Yes (Recommended)",- "description": "Continue the same turn."- }, {- "label": "No",- "description": "Stop here."- }]- }],- "autoResolutionMs": 60_000- })- .to_string(),- ),- responses::ev_completed("environment-pending"),- ]),+ if stop_hook_barrier.is_some() {+ create_final_assistant_message_sse_response("Waiting for the executor")?+ } else {+ create_request_user_input_sse_response(USER_INPUT_CALL_ID)?+ },+ create_request_user_input_sse_response(MCP_USER_INPUT_CALL_ID)?,responses::sse(vec![responses::ev_response_created("environment-ready-call"),responses::ev_function_call_with_namespace(@@ -446,9 +615,16 @@ async fn selected_capabilities_become_available_between_samples_in_one_turn() ->.await?;let turn_start_id = app_server.send_turn_start_request(TurnStartParams {- thread_id,+ thread_id: thread_id.clone(),input: vec![UserInput::Text {- text: "Use the executor when it becomes ready.".to_string(),+ text: match mention_timing {+ MentionTiming::Unmentioned | MentionTiming::Steered => {+ "Use the executor when it becomes ready.".to_string()+ }+ MentionTiming::Initial | MentionTiming::InitialBeforeRestart => {+ format!("Use {mention_link} when its executor becomes ready.")+ }+ },text_elements: Vec::new(),}],environments: Some(vec![TurnEnvironmentParams {@@ -467,34 +643,145 @@ async fn selected_capabilities_become_available_between_samples_in_one_turn() ->..Default::default()}).await?;- timeout(+ let response = timeout(READ_TIMEOUT,app_server.read_stream_until_response_message(RequestId::Integer(turn_start_id)),).await??;+ let TurnStartResponse { turn } = to_response(response)?;- let request = timeout(READ_TIMEOUT, app_server.read_stream_until_request_message()).await??;- let ServerRequest::ToolRequestUserInput { request_id, .. } = request else {- panic!("expected request_user_input, got {request:?}");+ let request_id = if stop_hook_barrier.is_some() {+ // Steering during a successful Stop hook restarts run_turn in the same RegularTask.+ timeout(+ READ_TIMEOUT,+ app_server.read_stream_until_matching_notification(+ "Stop hook started",+ |notification| {+ notification.method == "hook/started"+ && notification.params.as_ref().is_some_and(|params| {+ params["turnId"] == turn.id && params["run"]["eventName"] == "stop"+ })+ },+ ),+ )+ .await??;+ None+ } else {+ let request =+ timeout(READ_TIMEOUT, app_server.read_stream_until_request_message()).await??;+ let ServerRequest::ToolRequestUserInput { request_id, .. } = request else {+ panic!("expected request_user_input, got {request:?}");+ };+ Some(request_id)};let requests = response_mock.requests();assert_eq!(1, requests.len());assert_selected_capabilities_absent(&requests[0]);+ if !matches!(mention_timing, MentionTiming::Unmentioned) {+ let steer_request_id = app_server+ .send_turn_steer_request(TurnSteerParams {+ thread_id,+ input: vec![UserInput::Text {+ text: if matches!(mention_timing, MentionTiming::Steered) {+ format!("Use {mention_link} now.")+ } else {+ "Continue with the requested tool when it becomes available.".to_string()+ },+ text_elements: Vec::new(),+ }],+ expected_turn_id: turn.id.clone(),+ ..Default::default()+ })+ .await?;+ let response = timeout(+ READ_TIMEOUT,+ app_server.read_stream_until_response_message(RequestId::Integer(steer_request_id)),+ )+ .await??;+ let response: TurnSteerResponse = to_response(response)?;+ assert_eq!(response, TurnSteerResponse { turn_id: turn.id });+ }+ let request_id = if matches!(mention_timing, MentionTiming::Steered) {+ // Consume the mention while the executor is absent, then sample once more.+ app_server+ .send_response(+ request_id.expect("steering pauses before attaching the executor"),+ continue_answers.clone(),+ )+ .await?;+ let request =+ timeout(READ_TIMEOUT, app_server.read_stream_until_request_message()).await??;+ let ServerRequest::ToolRequestUserInput { request_id, .. } = request else {+ panic!("expected request_user_input, got {request:?}");+ };+ let requests = response_mock.requests();+ assert_eq!(2, requests.len());+ assert_selected_capabilities_absent(&requests[1]);+ Some(request_id)+ } else {+ request_id+ };let mut exec_server =spawn_exec_server(fixture.codex_home.path(), &fixture.exec_server_url).await?;add_environment(&mut app_server, &fixture.exec_server_url).await?;- tokio::time::sleep(Duration::from_millis(200)).await;- app_server- .send_response(- request_id,- json!({- "answers": {- "continue": { "answers": ["yes"] }- }- }),- )- .await?;+ if let Some(request_id) = request_id {+ app_server+ .send_response(request_id, continue_answers.clone())+ .await?;+ }+ if let Some(stop_hook_barrier) = stop_hook_barrier {+ std::fs::write(stop_hook_barrier, "ready")?;+ }+ let mcp_pid = wait_for_pid_file(&fixture.pid_file).await?;+ if !matches!(mention_timing, MentionTiming::Unmentioned) {+ // An explicit mention must still require startup after the executor attaches.+ tokio::time::sleep(Duration::from_secs(3)).await;+ assert_eq!(+ response_mock.requests().len(),+ samples_before_attach,+ "the explicit mention must keep later samples waiting for MCP startup"+ );+ std::fs::write(&initialize_barrier, "ready")?;+ }+ let request_id = if matches!(mention_timing, MentionTiming::Steered) {+ None+ } else {+ let request =+ timeout(READ_TIMEOUT, app_server.read_stream_until_request_message()).await??;+ let ServerRequest::ToolRequestUserInput { request_id, .. } = request else {+ panic!("expected request_user_input, got {request:?}");+ };+ let requests = response_mock.requests();+ assert_eq!(2, requests.len());+ assert_selected_skill_catalog_available(&requests[1]);+ if matches!(mention_timing, MentionTiming::Unmentioned) {+ assert!(+ requests[1]+ .tool_by_name(&format!("mcp__{MCP_SERVER_NAME}"), "echo")+ .is_none()+ );+ std::fs::write(&initialize_barrier, "ready")?;+ } else {+ assert_selected_plugin_tools(&requests[1]);+ }+ Some(request_id)+ };+ timeout(+ READ_TIMEOUT,+ app_server.read_stream_until_matching_notification("selected MCP ready", |notification| {+ notification.method == "mcpServer/startupStatus/updated"+ && notification.params.as_ref().is_some_and(|params| {+ params["name"] == MCP_SERVER_NAME && params["status"] == "ready"+ })+ }),+ )+ .await??;+ if let Some(request_id) = request_id {+ app_server+ .send_response(request_id, continue_answers)+ .await?;+ }timeout(READ_TIMEOUT,app_server.read_stream_until_notification_message("turn/completed"),@@ -502,19 +789,21 @@ async fn selected_capabilities_become_available_between_samples_in_one_turn() ->.await??;let requests = response_mock.requests();- assert_eq!(3, requests.len());- assert_selected_skill_catalog_available(&requests[1]);- assert_selected_plugin_tools(&requests[1]);- assert_plugin_guidance_count(&requests[1], /*expected_count*/ 0);- assert_selected_plugin_tools(&requests[2]);- assert_plugin_guidance_count(&requests[2], /*expected_count*/ 0);- let output = requests[2].function_call_output(MCP_CALL_ID);+ assert_eq!(4, requests.len());+ for request in &requests[samples_before_attach..] {+ assert_selected_skill_catalog_available(request);+ assert_plugin_guidance_count(request, /*expected_count*/ 0);+ }+ for request in &requests[2..] {+ assert_selected_plugin_tools(request);+ }+ let output = requests[3].function_call_output(MCP_CALL_ID);let output = output["output"].as_str().expect("MCP function output should be text");assert!(output.contains("ECHOING: same turn"));assert!(output.contains(EXECUTOR_ENV_VALUE));- wait_for_pid_file(&fixture.pid_file).await?;+ assert_eq!(mcp_pid, wait_for_pid_file(&fixture.pid_file).await?);exec_server.kill().await?;apps_server_handle.abort();@@ -531,6 +820,20 @@ struct SelectedCapabilityFixture {environment_cwd: AbsolutePathBuf,}+impl SelectedCapabilityFixture {+ fn block_mcp_startup(&self) -> Result<std::path::PathBuf> {+ let initialize_barrier = self._plugin.path().join("allow-mcp-initialize");+ let mcp_config_path = self._plugin.path().join(".mcp.json");+ let mut mcp_config: serde_json::Value =+ serde_json::from_slice(&std::fs::read(&mcp_config_path)?)?;+ mcp_config["mcpServers"][MCP_SERVER_NAME]["env"]["MCP_TEST_INITIALIZE_BARRIER_FILE"] =+ json!(initialize_barrier);+ mcp_config["mcpServers"][MCP_SERVER_NAME]["startup_timeout_sec"] = json!(30);+ std::fs::write(mcp_config_path, serde_json::to_vec(&mcp_config)?)?;+ Ok(initialize_barrier)+ }+}+fn selected_capability_fixture(responses_server_uri: &str,apps_url: &str,@@ -799,6 +1102,19 @@ async fn add_environment(app_server: &mut TestAppServer, exec_server_url: &str)).await??;let _: EnvironmentAddResponse = to_response(response)?;+ // Wait for executor attachment, independently of plugin MCP startup.+ let request_id = app_server+ .send_raw_request(+ "environment/info",+ Some(json!({ "environmentId": EXECUTOR_ID })),+ )+ .await?;+ let response = timeout(+ READ_TIMEOUT,+ app_server.read_stream_until_response_message(RequestId::Integer(request_id)),+ )+ .await??;+ let _: EnvironmentInfoResponse = to_response(response)?;Ok(())}diff --git a/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs b/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rsindex 36ad04e173..616ec1729f 100644--- a/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs+++ b/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs@@ -1,3 +1,4 @@+use std::collections::HashSet;use std::sync::Arc;use std::sync::atomic::Ordering;use std::time::Instant;@@ -170,6 +171,7 @@ impl McpConnectionSet {config: Arc<crate::McpConfig>,plugins_available: bool,required_servers: &[String],+ required_plugins: &HashSet<String>,) -> McpBinding {let revision = self.tool_catalog_revision.read().await;let mut listed_tools = Vec::new();@@ -190,10 +192,13 @@ impl McpConnectionSet {let has_cached_tools = cached_tools.is_some();let must_wait_for_startup = (required&& (!view.connection.startup_is_dormant() || !has_cached_tools))- || self.is_selected_plugin_mcp_server(server_name)|| required_servers.iter().any(|required| required == server_name)+ || (self.is_selected_plugin_mcp_server(server_name)+ && self+ .plugin_id_for_mcp_server_name(server_name)+ .is_some_and(|plugin_id| required_plugins.contains(plugin_id)))|| (server_name == CODEX_APPS_MCP_SERVER_NAME && !has_cached_tools);if !must_wait_for_startup && has_cached_tools {return (server_name, view, cached_tools);diff --git a/codex-rs/codex-mcp/src/connection_manager_tests.rs b/codex-rs/codex-mcp/src/connection_manager_tests.rsindex 9c974ac466..0c0e57306e 100644--- a/codex-rs/codex-mcp/src/connection_manager_tests.rs+++ b/codex-rs/codex-mcp/src/connection_manager_tests.rs@@ -231,6 +231,7 @@ async fn capture_binding(manager: &Arc<McpConnectionSet>) -> McpBinding {Arc::new(config),/*plugins_available*/ false,/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),).await}@@ -2592,10 +2593,17 @@ async fn capture_binding_skips_pending_optional_servers_after_configured_shared_serde_json::from_value(serde_json::json!({ "command": "optional-plugin" })).expect("optional plugin MCP config"),));+ catalog.register(crate::McpServerRegistration::from_selected_plugin(+ "pending-selected".to_string(),+ crate::McpPluginAttribution::new("selected-plugin".to_string(), "Selected".to_string()),+ /*selection_order*/ 0,+ serde_json::from_value(serde_json::json!({ "command": "selected-plugin" }))+ .expect("selected plugin MCP config"),+ ));plugin_config.mcp_server_catalog = catalog.build();plugin_config.optional_mcp_startup_grace = Duration::from_millis(250);manager.tool_plugin_provenance = Arc::new(crate::tool_plugin_provenance(&plugin_config));- for server_name in ["pending-one", "pending-two"] {+ for server_name in ["pending-one", "pending-two", "pending-selected"] {manager.insert_test_client(server_name.to_string(),AsyncManagedClient {@@ -2613,19 +2621,34 @@ async fn capture_binding_skips_pending_optional_servers_after_configured_shared_);}+ let mut required_manager = McpConnectionSet::new_uninitialized(+ &approval_policy,+ &permission_profile,+ /*prefix_mcp_tool_names*/ true,+ );+ required_manager.tool_plugin_provenance = Arc::clone(&manager.tool_plugin_provenance);+ required_manager.insert_test_client(+ "pending-selected",+ manager.test_client("pending-selected").clone(),+ );+ required_manager.required_servers = vec!["pending-selected".to_string()];+let manager = Arc::new(manager);assert_eq!(manager.stable_catalog_revision().await, None);+ let started = tokio::time::Instant::now();let binding = tokio::time::timeout(Duration::from_millis(500),manager.capture_binding_with_metadata(Arc::new(plugin_config),/*plugins_available*/ false,/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),),).await.expect("all optional servers should share the configured startup grace");assert!(binding.tools().is_empty());+ assert_eq!(started.elapsed(), Duration::from_millis(250));let binding = tokio::time::timeout(Duration::from_millis(1), capture_binding(&manager)).await@@ -2651,17 +2674,52 @@ async fn capture_binding_skips_pending_optional_servers_after_configured_shared_"resource discovery must not wait for an omitted optional server");- let required_servers = vec!["pending-one".to_string()];- let binding = tokio::time::timeout(- Duration::from_millis(1),- manager.capture_binding_with_metadata(- Arc::new(crate::mcp::tests::test_mcp_config(std::env::temp_dir())),- /*plugins_available*/ false,- &required_servers,- ),- )- .await;- assert!(binding.is_err(), "explicitly requested servers must wait");+ for server_name in ["pending-one", "pending-selected"] {+ let required_servers = vec![server_name.to_string()];+ let binding = tokio::time::timeout(+ Duration::from_millis(1),+ manager.capture_binding_with_metadata(+ Arc::new(crate::mcp::tests::test_mcp_config(std::env::temp_dir())),+ /*plugins_available*/ false,+ &required_servers,+ /*required_plugins*/ &HashSet::new(),+ ),+ )+ .await;+ assert!(binding.is_err(), "explicitly requested servers must wait");+ }+ // A plugin mention must still require startup after the optional grace has elapsed.+ for (plugin_id, must_wait) in [+ ("selected-plugin", true),+ ("optional-plugin", false),+ ("selected-plugin-other", false),+ ] {+ let required_plugins = HashSet::from([plugin_id.to_string()]);+ let binding = tokio::time::timeout(+ Duration::from_millis(1),+ manager.capture_binding_with_metadata(+ Arc::new(crate::mcp::tests::test_mcp_config(std::env::temp_dir())),+ /*plugins_available*/ false,+ /*required_servers*/ &[],+ &required_plugins,+ ),+ )+ .await;+ assert_eq!(+ binding.is_err(),+ must_wait,+ "plugin requirement {plugin_id}"+ );+ }+ assert!(+ tokio::time::timeout(+ Duration::from_millis(1500),+ capture_binding(&Arc::new(required_manager)),+ )+ .await+ .is_err(),+ "configured-required selected plugin servers must wait beyond the optional grace"+ );}#[tokio::test(start_paused = true)]@@ -2690,6 +2748,7 @@ async fn capture_binding_waits_for_optional_startup_when_shared_grace_is_disableArc::new(config),/*plugins_available*/ false,/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),).await});@@ -2818,6 +2877,7 @@ async fn capture_binding_shares_optional_startup_grace_across_connection_sets()Arc::new(disabled_config),/*plugins_available*/ false,/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),),).await@@ -2845,6 +2905,7 @@ async fn capture_binding_shares_optional_startup_grace_across_connection_sets()Arc::new(updated_config),/*plugins_available*/ false,/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),),).awaitdiff --git a/codex-rs/codex-mcp/src/runtime.rs b/codex-rs/codex-mcp/src/runtime.rsindex dc30070e90..7a55d2cc52 100644--- a/codex-rs/codex-mcp/src/runtime.rs+++ b/codex-rs/codex-mcp/src/runtime.rs@@ -6,6 +6,7 @@//! [`crate::connection_manager`].use std::collections::HashMap;+use std::collections::HashSet;use std::path::PathBuf;use std::sync::Arc;use std::sync::Mutex;@@ -335,20 +336,29 @@ impl McpRuntime {/// Captures the latest published configuration and live client handles.pub async fn current_binding(&self) -> Option<Arc<McpBinding>> {- self.current_binding_with_required_servers(&[]).await+ self.current_binding_with_requirements(&[], &HashSet::new())+ .await}- /// Captures the latest runtime, waiting for servers explicitly required by this turn.- pub async fn current_binding_with_required_servers(+ /// Captures one runtime, waiting for explicitly required servers and selected plugins.+ /// Plugin IDs are resolved by the captured connection set, even if a refresh publishes later.+ pub async fn current_binding_with_requirements(&self,required_servers: &[String],+ required_plugins: &HashSet<String>,) -> Option<Arc<McpBinding>> {- Self::binding_from_published_runtime(self.current.load_full(), required_servers).await+ Self::binding_from_published_runtime(+ self.current.load_full(),+ required_servers,+ required_plugins,+ )+ .await}async fn binding_from_published_runtime(current: Arc<PublishedMcpRuntime>,required_servers: &[String],+ required_plugins: &HashSet<String>,) -> Option<Arc<McpBinding>> {let config = Arc::clone(current.config.as_ref()?);let stable_catalog_revision = current.connections.stable_catalog_revision().await;@@ -367,7 +377,12 @@ impl McpRuntime {let binding = Arc::new(current.connections- .capture_binding_with_metadata(config, current.plugins_available, required_servers)+ .capture_binding_with_metadata(+ config,+ current.plugins_available,+ required_servers,+ required_plugins,+ ).await,);if let Some(catalog_revision) = stable_catalog_revision@@ -445,7 +460,12 @@ impl McpRuntime {if !current.connections.wait_for_server_startup(server).await {return None;}- Self::binding_from_published_runtime(current, /*required_servers*/ &[]).await+ Self::binding_from_published_runtime(+ current,+ /*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),+ )+ .await}/// Returns the latest published configuration without waiting for clients.@@ -877,12 +897,14 @@ mod tests {let first = McpRuntime::binding_from_published_runtime(Arc::clone(&published),/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),).await.expect("first binding");let repeated = McpRuntime::binding_from_published_runtime(Arc::clone(&published),/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),).await.expect("repeated binding");@@ -893,10 +915,13 @@ mod tests {cached_binding: Mutex::new(None),..previous});- let refreshed =- McpRuntime::binding_from_published_runtime(republished, /*required_servers*/ &[])- .await- .expect("republished binding");+ let refreshed = McpRuntime::binding_from_published_runtime(+ republished,+ /*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),+ )+ .await+ .expect("republished binding");assert!(!Arc::ptr_eq(&first, &refreshed));}diff --git a/codex-rs/core/src/plugins/mentions.rs b/codex-rs/core/src/plugins/mentions.rsindex 13563806da..fb43b13130 100644--- a/codex-rs/core/src/plugins/mentions.rs+++ b/codex-rs/core/src/plugins/mentions.rs@@ -68,6 +68,19 @@ pub(crate) fn collect_explicit_plugin_mentions(return Vec::new();}+ // `config_name` stores the full plugin ID, not its display or mention name.+ let mentioned_plugin_ids = collect_explicit_plugin_ids(input);+ plugins+ .iter()+ .filter(|plugin| mentioned_plugin_ids.contains(plugin.config_name.as_str()))+ .cloned()+ .collect()+}++/// Collect exact IDs from explicit `plugin://` references, independently of display names.+///+/// Host plugins use `<plugin>@<marketplace>` IDs; selected roots may supply opaque IDs.+pub(crate) fn collect_explicit_plugin_ids(input: &[UserInput]) -> HashSet<String> {let messages = input.iter().filter_map(|item| match item {@@ -76,7 +89,7 @@ pub(crate) fn collect_explicit_plugin_mentions(}).collect::<Vec<String>>();- let mentioned_config_names: HashSet<String> = input+ input.iter().filter_map(|item| match item {UserInput::Mention { path, .. } => Some(path.clone()),@@ -89,16 +102,6 @@ pub(crate) fn collect_explicit_plugin_mentions().filter(|path| tool_kind_for_path(path.as_str()) == ToolMentionKind::Plugin).filter_map(|path| plugin_config_name_from_path(path.as_str()).map(str::to_string))- .collect();-- if mentioned_config_names.is_empty() {- return Vec::new();- }-- plugins- .iter()- .filter(|plugin| mentioned_config_names.contains(plugin.config_name.as_str()))- .cloned().collect()}diff --git a/codex-rs/core/src/plugins/mentions_tests.rs b/codex-rs/core/src/plugins/mentions_tests.rsindex 8184a41945..ee0747eeb5 100644--- a/codex-rs/core/src/plugins/mentions_tests.rs+++ b/codex-rs/core/src/plugins/mentions_tests.rs@@ -4,6 +4,7 @@ use codex_protocol::user_input::UserInput;use pretty_assertions::assert_eq;use super::collect_explicit_app_ids;+use super::collect_explicit_plugin_ids;use super::collect_explicit_plugin_mentions;use crate::plugins::PluginCapabilitySummary;@@ -77,35 +78,39 @@ fn collect_explicit_app_ids_ignores_non_app_paths() {#[test]fn collect_explicit_plugin_mentions_from_structured_paths() {+ let expected = plugin("sample@test", "Sample");let plugins = vec![- plugin("sample@test", "sample"),- plugin("other@test", "other"),+ expected.clone(),+ plugin("sample@other-marketplace", "Sample"),+ plugin("other@test", "alias"),];let mentioned = collect_explicit_plugin_mentions(&[UserInput::Mention {- name: "sample".to_string(),+ name: "alias".to_string(),path: "plugin://sample@test".to_string(),}],&plugins,);- assert_eq!(mentioned, vec![plugin("sample@test", "sample")]);+ assert_eq!(mentioned, vec![expected]);}#[test]fn collect_explicit_plugin_mentions_from_linked_text_mentions() {+ let expected = plugin("sample@test", "Sample");let plugins = vec![- plugin("sample@test", "sample"),- plugin("other@test", "other"),+ expected.clone(),+ plugin("sample@other-marketplace", "Sample"),+ plugin("other@test", "alias"),];let mentioned = collect_explicit_plugin_mentions(- &[text_input("use [@sample](plugin://sample@test)")],+ &[text_input("use [@alias](plugin://sample@test)")],&plugins,);- assert_eq!(mentioned, vec![plugin("sample@test", "sample")]);+ assert_eq!(mentioned, vec![expected]);}#[test]@@ -154,3 +159,19 @@ fn collect_explicit_plugin_mentions_ignores_dollar_linked_plugin_mentions() {assert_eq!(mentioned, Vec::<PluginCapabilitySummary>::new());}++#[test]+fn collect_explicit_plugin_ids_preserves_opaque_ids() {+ let input = [+ text_input("use [@same](plugin://selected-one)"),+ UserInput::Mention {+ name: "same".to_string(),+ path: "plugin://selected-two".to_string(),+ },+ ];++ assert_eq!(+ collect_explicit_plugin_ids(&input),+ HashSet::from(["selected-one".to_string(), "selected-two".to_string()]),+ );+}diff --git a/codex-rs/core/src/plugins/mod.rs b/codex-rs/core/src/plugins/mod.rsindex ca0e71ce4b..e47c8e28e6 100644--- a/codex-rs/core/src/plugins/mod.rs+++ b/codex-rs/core/src/plugins/mod.rs@@ -23,6 +23,7 @@ pub(crate) use render::render_explicit_plugin_instructions;pub(crate) use mentions::build_connector_slug_counts;pub(crate) use mentions::collect_explicit_app_ids;+pub(crate) use mentions::collect_explicit_plugin_ids;pub(crate) use mentions::collect_explicit_plugin_mentions;pub(crate) use mentions::collect_tool_mentions_from_messages;diff --git a/codex-rs/core/src/session/mcp.rs b/codex-rs/core/src/session/mcp.rsindex 46af2d336e..fb79de7d7b 100644--- a/codex-rs/core/src/session/mcp.rs+++ b/codex-rs/core/src/session/mcp.rs@@ -329,6 +329,7 @@ impl Session {turn_context: &TurnContext,selected_capability_roots: &[ResolvedSelectedCapabilityRoot],required_servers: &[String],+ required_plugins: &HashSet<String>,) -> Arc<codex_mcp::McpBinding> {let ready_selected_capability_roots =Self::ready_selected_capability_roots(selected_capability_roots);@@ -365,7 +366,7 @@ impl Session {if let Some(binding) = self.services.mcp_runtime- .current_binding_with_required_servers(&required_servers)+ .current_binding_with_requirements(&required_servers, required_plugins).await{return binding;diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rsindex 90fe56ec36..0cf192be81 100644--- a/codex-rs/core/src/session/mod.rs+++ b/codex-rs/core/src/session/mod.rs@@ -3459,6 +3459,7 @@ impl Session {turn_context,cancellation_token,/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),).await}@@ -3468,9 +3469,15 @@ impl Session {turn_context: Arc<TurnContext>,cancellation_token: &CancellationToken,required_servers: &[String],+ required_plugins: &HashSet<String>,) -> CodexResult<Arc<StepContext>> {let step_context = self- .capture_step_context_inner(turn_context, cancellation_token, required_servers)+ .capture_step_context_inner(+ turn_context,+ cancellation_token,+ required_servers,+ required_plugins,+ ).await?;self.set_last_known_step_context(&step_context).await;Ok(step_context)@@ -3487,6 +3494,7 @@ impl Session {turn_context,cancellation_token,/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),).await}@@ -3497,6 +3505,7 @@ impl Session {turn_context: Arc<TurnContext>,cancellation_token: &CancellationToken,required_servers: &[String],+ required_plugins: &HashSet<String>,) -> CodexResult<Arc<StepContext>> {// Capture once before asynchronous planning; all request consumers// retain this immutable settings version even if the turn is updated.@@ -3574,6 +3583,7 @@ impl Session {turn_context.as_ref(),&selected_capability_roots,required_servers,+ required_plugins,),turn::prepare_tool_recommendations(self.as_ref(), turn_context.as_ref()),)diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rsindex c1b00dfa26..ffac44c011 100644--- a/codex-rs/core/src/session/tests.rs+++ b/codex-rs/core/src/session/tests.rs@@ -9072,6 +9072,7 @@ async fn refresh_mcp_servers_uses_latest_state_for_existing_turns() {&turn_context,/*selected_capability_roots*/ &[],/*required_servers*/ &[],+ /*required_plugins*/ &HashSet::new(),).await;diff --git a/codex-rs/core/src/session/turn.rs b/codex-rs/core/src/session/turn.rsindex 72d97c082a..c49579cb22 100644--- a/codex-rs/core/src/session/turn.rs+++ b/codex-rs/core/src/session/turn.rs@@ -138,6 +138,13 @@ use tracing::warn;const POST_SAMPLING_TOKEN_ESTIMATE_TARGET: &str = "codex_core::post_sampling_token_estimate";+/// Explicit MCP startup requirements retained across restarts within one user turn.+#[derive(Default)]+pub(crate) struct McpStartupRequirements {+ required_servers: Vec<String>,+ required_plugins: HashSet<String>,+}+/// Takes initial turn input and runs a loop where, at each sampling request,/// the model replies with either:///@@ -156,6 +163,7 @@ pub(crate) async fn run_turn(sess: Arc<Session>,turn_context: Arc<TurnContext>,input: Vec<TurnInput>,+ mcp_startup_requirements: &mut McpStartupRequirements,prewarmed_client_session: Option<ModelClientSession>,cancellation_token: CancellationToken,) -> CodexResult<Option<String>> {@@ -192,7 +200,16 @@ pub(crate) async fn run_turn(}let user_input = turn_user_input(&input);- let (required_servers, mentioned_plugins) =+ let allow_plugin_mentions =+ !crate::guardian::is_basic_session_source(&turn_context.session_source);+ let McpStartupRequirements {+ required_servers,+ required_plugins,+ } = mcp_startup_requirements;+ if allow_plugin_mentions {+ required_plugins.extend(crate::plugins::collect_explicit_plugin_ids(&user_input));+ }+ let (input_required_servers, mentioned_plugins) =match required_mcp_servers_for_input(&sess, turn_context.as_ref(), &user_input).or_cancel(&cancellation_token).await@@ -205,12 +222,17 @@ pub(crate) async fn run_turn(}};+ required_servers.extend(input_required_servers);+ required_servers.sort_unstable();+ required_servers.dedup();+// run_turn owns the step used to seed context and make the first sampling request.let first_step_context = match sess.capture_step_context_with_required_mcp_servers(Arc::clone(&turn_context),&cancellation_token,- &required_servers,+ required_servers,+ required_plugins,).await{@@ -343,24 +365,38 @@ pub(crate) async fn run_turn(// Capture once so context, advertised tools, and tool calls share one request view.let step_context = match next_step_context.take() {- Some(step_context) => step_context,+ Some(step_context) if pending_input.is_empty() => step_context,None if pending_input.is_empty() => {- sess.capture_step_context(Arc::clone(&turn_context), &cancellation_token)- .await?+ sess.capture_step_context_with_required_mcp_servers(+ Arc::clone(&turn_context),+ &cancellation_token,+ required_servers,+ required_plugins,+ )+ .await?}- None => {+ Some(_) | None => {let pending_user_input = turn_user_input(&pending_input);- let (required_servers, _) = required_mcp_servers_for_input(+ if allow_plugin_mentions {+ required_plugins.extend(crate::plugins::collect_explicit_plugin_ids(+ &pending_user_input,+ ));+ }+ let (pending_required_servers, _) = required_mcp_servers_for_input(&sess,turn_context.as_ref(),&pending_user_input,).or_cancel(&cancellation_token).await?;+ required_servers.extend(pending_required_servers);+ required_servers.sort_unstable();+ required_servers.dedup();sess.capture_step_context_with_required_mcp_servers(Arc::clone(&turn_context),&cancellation_token,- &required_servers,+ required_servers,+ required_plugins,).await?}diff --git a/codex-rs/core/src/tasks/regular.rs b/codex-rs/core/src/tasks/regular.rsindex 7b999967c3..fa57342185 100644--- a/codex-rs/core/src/tasks/regular.rs+++ b/codex-rs/core/src/tasks/regular.rs@@ -4,6 +4,7 @@ use tokio_util::sync::CancellationToken;use crate::session::TurnInput;use crate::session::session::Session;+use crate::session::turn::McpStartupRequirements;use crate::session::turn::run_hooks_and_record_inputs;use crate::session::turn::run_turn;use crate::session::turn_context::TurnContext;@@ -73,11 +74,13 @@ impl SessionTask for RegularTask {};let mut next_input = input;let mut prewarmed_client_session = prewarmed_client_session;+ let mut mcp_startup_requirements = McpStartupRequirements::default();loop {let last_agent_message = run_turn(Arc::clone(&sess),Arc::clone(&ctx),next_input,+ &mut mcp_startup_requirements,prewarmed_client_session.take(),cancellation_token.child_token(),)diff --git a/codex-rs/skills/src/mentions.rs b/codex-rs/skills/src/mentions.rsindex 507a8480df..1f391235d1 100644--- a/codex-rs/skills/src/mentions.rs+++ b/codex-rs/skills/src/mentions.rs@@ -64,8 +64,11 @@ pub fn app_id_from_path(path: &str) -> Option<&str> {.filter(|value| !value.is_empty())}+/// Desktop app/browser mentions append `?app=...` or `?browserFamily=...`.+/// Ignore these targeting parameters when matching the plugin ID.pub fn plugin_config_name_from_path(path: &str) -> Option<&str> {path.strip_prefix(PLUGIN_PATH_PREFIX)+ .and_then(|value| value.split('?').next()).filter(|value| !value.is_empty())}diff --git a/codex-rs/skills/src/mentions_tests.rs b/codex-rs/skills/src/mentions_tests.rsindex b4f90e1d23..bdf8874821 100644--- a/codex-rs/skills/src/mentions_tests.rs+++ b/codex-rs/skills/src/mentions_tests.rs@@ -78,3 +78,28 @@ fn handles_many_sigils_without_looping() {let prefix = "$".repeat(256);assert_mentions(&format!("{prefix} not-a-mention"), &[], &[]);}++#[test]+fn plugin_config_names_ignore_mention_query_parameters() {+ let paths = [+ "plugin://sample@test",+ "plugin://sample@test?app=com.example.editor",+ "plugin://sample@test?browserFamily=chrome",+ ];++ assert_eq!(+ paths.map(plugin_config_name_from_path),+ [Some("sample@test"); 3],+ );+}++#[test]+fn plugin_config_names_require_a_plugin_identity() {+ let paths = [+ "plugin://",+ "plugin://?app=com.example.editor",+ "app://sample@test?app=com.example.editor",+ ];++ assert_eq!(paths.map(plugin_config_name_from_path), [None; 3]);+}