From 0df4aa67781ae45a3c97befa4db48b734afe46d9 Mon Sep 17 00:00:00 2001 From: jif Date: Fri, 16 Oct 2026 16:34:08 +0000 Subject: [PATCH] Honor MCP tool-list changes within a turn (#54656) ## Why MCP servers can expose new tools during discovery. Refreshing the catalog after a tool-list notification lets Codex discover and call those tools in the same turn. ## What changed - Add the disabled-by-default `mcp_tool_list_changed` feature for ordinary MCP servers. - Track notifications in transport order and refresh catalogs before subsequent discovery or tool binding. Coalesce concurrent refreshes and retry listings invalidated by notifications, including during pagination. - Retain the previous catalog on refresh failure, apply a retry cooldown, and invalidate affected startup caches. Allow notification refreshes to proceed while admitted calls finish. ## Testing Add coverage for same-turn discovery and invocation in direct and Code Mode, notifications during startup and pagination, disabled behavior, cache invalidation, and concurrent refreshes with timeout recovery. GitOrigin-RevId: 9afee8deba00dd9851b5f32625f61f96965aa00c --- codex-rs/codex-mcp/src/client_tool_catalog.rs | 95 ++++++++++- codex-rs/codex-mcp/src/connection_manager.rs | 47 +++++- .../src/connection_manager/tool_catalog.rs | 11 +- .../codex-mcp/src/connection_manager_tests.rs | 156 +++++++++++++++++- codex-rs/codex-mcp/src/mcp/mod.rs | 2 + codex-rs/codex-mcp/src/mcp/mod_tests.rs | 1 + codex-rs/codex-mcp/src/rmcp_client.rs | 7 +- codex-rs/codex-mcp/src/tool_catalog_cache.rs | 37 ++++- codex-rs/core/config.schema.json | 6 + codex-rs/core/src/config/mod.rs | 1 + codex-rs/core/tests/suite/rmcp_client.rs | 138 ++++++++++++++++ codex-rs/core/tests/suite/scenarios.rs | 52 ++++++ ...rios__mcp_tool_discovery_CodeModeOnly.snap | 56 +++++++ ..._scenarios__mcp_tool_discovery_Direct.snap | 69 ++++++++ codex-rs/features/src/lib.rs | 8 + .../rmcp-client/src/bin/test_stdio_server.rs | 57 ++++++- codex-rs/rmcp-client/src/lib.rs | 2 + codex-rs/rmcp-client/src/rmcp_client.rs | 39 ++++- codex-rs/rmcp-client/src/tool_list_changes.rs | 73 ++++++++ 19 files changed, 832 insertions(+), 25 deletions(-) create mode 100644 codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_CodeModeOnly.snap create mode 100644 codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_Direct.snap create mode 100644 codex-rs/rmcp-client/src/tool_list_changes.rs diff --git a/codex-rs/codex-mcp/src/client_tool_catalog.rs b/codex-rs/codex-mcp/src/client_tool_catalog.rs index 0501f1c782..233d835256 100644 --- a/codex-rs/codex-mcp/src/client_tool_catalog.rs +++ b/codex-rs/codex-mcp/src/client_tool_catalog.rs @@ -4,21 +4,32 @@ //! Only active readers, calls, and frozen model bindings pin earlier snapshots. //! Explicit refreshes publish after calls using this client's current revision finish. //! Equivalent shared publications preserve calls, but explicit refreshes invalidate them. +//! Ordinary servers coalesce list-change notifications and publish only a stable listing. +//! Notifications update discovery without waiting for admitted calls to finish. +//! Failed refreshes retain the last catalog and share a short retry cooldown. use std::collections::HashSet; use std::future::Future; use std::sync::Arc; +use std::sync::atomic::AtomicU64; +use std::sync::atomic::Ordering; +use std::time::Duration; +use anyhow::Context; use anyhow::Result; +use anyhow::bail; use codex_connectors::ConnectorRuntimeSnapshot; +use codex_rmcp_client::ToolListRevision; use tokio::sync::Mutex; use tokio::sync::RwLock; use tokio::sync::RwLockReadGuard; use tokio::sync::watch; +use tokio::time::Instant; use crate::tools::ToolInfo; type ToolCatalogUpdates = watch::Receiver>>>; +const NOTIFICATION_REFRESH_COOLDOWN: Duration = Duration::from_secs(5); /// The exact Apps catalog returned by an awaited refresh of one published runtime. pub struct CodexAppsToolSnapshot { @@ -31,8 +42,12 @@ pub struct CodexAppsToolSnapshot { pub(crate) struct ClientToolCatalog { current: RwLock, - /// Serialize fetches without blocking calls against the current catalog. - refresh_lock: Mutex<()>, + /// Explicit refreshes still wait for call preparation and execution. + calls: RwLock<()>, + /// Serialize fetches and retain the next retry time after failure or cancellation. + refresh_lock: Mutex>, + /// Starts at zero so notifications during the initial listing stay pending. + listed_notification_revision: AtomicU64, } struct CatalogState { @@ -81,7 +96,9 @@ impl ClientToolCatalog { last_refresh_revision: 0, source, }), - refresh_lock: Mutex::new(()), + refresh_lock: Mutex::new(None), + calls: RwLock::new(()), + listed_notification_revision: AtomicU64::new(0), } } @@ -139,6 +156,66 @@ impl ClientToolCatalog { } } + pub(crate) fn notifications_current(&self, notifications: &ToolListRevision) -> bool { + self.listed_notification_revision.load(Ordering::Acquire) == notifications.current() + } + + /// Refresh ordinary server catalogs, coalescing concurrent readers. Never mark a + /// listing current if another notification arrived while fetching its pages. + /// Retry once; persistent churn stays pending until the retry cooldown expires. + #[expect( + clippy::await_holding_invalid_type, + reason = "refreshes must remain serialized through fetching and catalog publication" + )] + pub(crate) async fn refresh_after_notifications( + &self, + notifications: &ToolListRevision, + timeout: Duration, + mut fetch: F, + ) -> Result<()> + where + F: FnMut() -> Fut, + Fut: Future>>, + { + if self.notifications_current(notifications) { + return Ok(()); + } + let deadline = Instant::now() + timeout; + let mut retry_after = tokio::time::timeout_at(deadline, self.refresh_lock.lock()) + .await + .context("MCP tool catalog refresh timed out")?; + if self.notifications_current(notifications) + || retry_after.is_some_and(|deadline| Instant::now() < deadline) + { + return Ok(()); + } + // Also bound retries if the caller cancels this future during the fetch. + *retry_after = Some(deadline + NOTIFICATION_REFRESH_COOLDOWN); + let result = tokio::time::timeout_at(deadline, async { + for _ in 0..2 { + let revision = notifications.current(); + let tools = fetch().await; + let mut current = self.current.write().await; + if notifications.current() != revision { + continue; + } + current.source = CatalogSource::Local(tools?.into()); + current.revision += 1; + self.listed_notification_revision + .store(revision, Ordering::Release); + return Ok(()); + } + bail!("MCP tool list changed during catalog refresh") + }) + .await + .context("MCP tool catalog refresh timed out") + .and_then(std::convert::identity); + *retry_after = result + .is_err() + .then(|| Instant::now() + NOTIFICATION_REFRESH_COOLDOWN); + result + } + /// Serialize fetching and publication, leaving the current catalog usable during the fetch. /// The publication callback runs alongside the exact-client update under the write lock. #[expect( @@ -153,6 +230,7 @@ impl ClientToolCatalog { { let _refresh = self.refresh_lock.lock().await; let (tools, context) = fetch().await?; + let _calls = self.calls.write().await; let mut current = self.current.write().await; let result = publish(&tools, context); match &mut current.source { @@ -172,7 +250,8 @@ impl ClientToolCatalog { Ok(result) } - /// Reject stale calls before preparation and hold catalog authority until execution finishes. + /// Reject stale calls before preparation. Explicit refreshes wait for execution; + /// ordinary list-change notifications may publish while an admitted call runs. #[expect( clippy::await_holding_invalid_type, reason = "catalog publication must wait for call preparation and execution" @@ -186,6 +265,7 @@ impl ClientToolCatalog { F: FnOnce() -> Fut, Fut: Future, { + let _calls = self.calls.read().await; let (current, snapshot) = self.read_current().await; if current.last_refresh_revision > expected.revision || (snapshot.revision != expected.revision @@ -193,6 +273,13 @@ impl ClientToolCatalog { { return None; } + let current = match current.source { + CatalogSource::Local(_) => { + drop(current); + None + } + CatalogSource::Live { .. } => Some(current), + }; let result = run().await; drop(current); Some(result) diff --git a/codex-rs/codex-mcp/src/connection_manager.rs b/codex-rs/codex-mcp/src/connection_manager.rs index 0f70d060bd..8d2c471252 100644 --- a/codex-rs/codex-mcp/src/connection_manager.rs +++ b/codex-rs/codex-mcp/src/connection_manager.rs @@ -185,6 +185,8 @@ struct McpServerView { tool_filter: ToolFilter, tool_timeout: Option, catalog_item_limit: usize, + refresh_tool_list: bool, + refresh_timeout: Duration, } impl McpServerView { @@ -210,11 +212,44 @@ impl McpServerView { } } + async fn refresh_notified_catalog(&self, server_name: &str, client: &ManagedClient) { + if !self.refresh_tool_list || self.connection.client.is_codex_apps_mcp_server { + return; + } + let timeout = self.refresh_timeout; + let result = client + .tool_catalog + .refresh_after_notifications(&client.client.tool_list_revision(), timeout, || { + crate::rmcp_client::list_tools_for_client_uncached( + server_name, + /*is_codex_apps_mcp_server*/ false, + "list_changed", + &client.client, + Some(timeout), + self.catalog_item_limit, + client.server_instructions.as_deref(), + ) + }) + .await; + if result.is_err() { + tracing::warn!( + server_name, + "MCP tool catalog refresh failed; retaining the previous catalog" + ); + } + } + async fn listed_tools( &self, + server_name: &str, tool_plugin_context: &ToolPluginContext, ) -> Result, StartupOutcomeError> { - let tools = self.connection.client.listed_tools().await?; + let tools = if let Some(client) = self.connection.client.ready_client() { + self.refresh_notified_catalog(server_name, &client).await; + client.listed_tools().await + } else { + self.connection.client.listed_tools().await? + }; let tools = filter_tools(tools, &self.tool_filter); Ok(if self.connection.client.is_codex_apps_mcp_server { prepare_codex_apps_tools_for_model(tools, tool_plugin_context) @@ -494,6 +529,7 @@ impl McpConnectionSet { }; if let Some(previous_view) = reusable_previous.and_then(|previous| previous.servers.get(&server_name)) + && previous_view.refresh_tool_list == config.mcp_tool_list_changed { let connection = Arc::clone(&previous_view.connection); let reusable_pending_startup = connection.identity.as_ref() @@ -539,6 +575,8 @@ impl McpConnectionSet { connection, protocol_mode, startup_readiness: configured_config.startup_readiness, + refresh_tool_list: config.mcp_tool_list_changed, + refresh_timeout: startup_timeout, metadata, tool_filter: configured_tool_filter, tool_timeout: configured_tool_timeout, @@ -597,7 +635,7 @@ impl McpConnectionSet { } } let cancel_token = startup_cancellation_token.child_token(); - let tool_catalog_cache_context = if server_name == CODEX_APPS_MCP_SERVER_NAME + let mut tool_catalog_cache_context = if server_name == CODEX_APPS_MCP_SERVER_NAME || server.requires_read_only_mcp_tools() { None @@ -617,6 +655,9 @@ impl McpConnectionSet { } else { None }; + if let Some(context) = &mut tool_catalog_cache_context { + context.track_tool_list_changes = config.mcp_tool_list_changed; + } let has_runtime_auth = runtime_auth_provider.is_some(); let async_managed_client = AsyncManagedClient::new( server_name.clone(), @@ -677,6 +718,8 @@ impl McpConnectionSet { }), protocol_mode, startup_readiness: configured_config.startup_readiness, + refresh_tool_list: config.mcp_tool_list_changed, + refresh_timeout: startup_timeout, metadata, tool_filter: configured_tool_filter, tool_timeout: configured_tool_timeout, diff --git a/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs b/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs index 45cea49bb0..711e747fba 100644 --- a/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs +++ b/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs @@ -171,7 +171,13 @@ impl McpConnectionSet { } return None; }; - if client.client.is_closed().await { + if client.client.is_closed().await + || (view.refresh_tool_list + && !view.connection.client.is_codex_apps_mcp_server + && !client + .tool_catalog + .notifications_current(&client.client.tool_list_revision())) + { return None; } let revision = client.tool_catalog.read(|catalog| catalog.revision).await; @@ -213,7 +219,7 @@ impl McpConnectionSet { .startup_complete .load(Ordering::Acquire); let server_tools = view - .listed_tools(&self.tool_plugin_context) + .listed_tools(server_name, &self.tool_plugin_context) .instrument(trace_span!( "list_tools_for_server", server_name = %server_name, @@ -392,6 +398,7 @@ impl McpConnectionSet { trace!(server_name = %server_name, "omitting MCP server without an exact ready client"); return None; }; + view.refresh_notified_catalog(server_name, &client).await; client.tool_timeout = view.tool_timeout; let snapshot = client.tool_catalog.read(Arc::new).await; let server_tools = snapshot.tools.to_vec(); diff --git a/codex-rs/codex-mcp/src/connection_manager_tests.rs b/codex-rs/codex-mcp/src/connection_manager_tests.rs index 482f346557..758e6419dc 100644 --- a/codex-rs/codex-mcp/src/connection_manager_tests.rs +++ b/codex-rs/codex-mcp/src/connection_manager_tests.rs @@ -134,6 +134,8 @@ impl McpConnectionSet { self.servers.insert( name, McpServerView { + refresh_tool_list: true, + refresh_timeout: DEFAULT_STARTUP_TIMEOUT, tool_filter: ToolFilter::default(), protocol_mode: crate::McpProtocolMode::Legacy, startup_readiness: Default::default(), @@ -339,7 +341,25 @@ struct MutableToolsServer { impl ServerHandler for MutableToolsServer { fn get_info(&self) -> ServerConfig { - ServerConfig::new(ServerCapabilities::builder().enable_tools().build()) + ServerConfig::new( + ServerCapabilities::builder() + .enable_tools() + .enable_tool_list_changed() + .build(), + ) + } + + async fn call_tool( + &self, + _request: rmcp::model::CallToolRequestParams, + context: RequestContext, + ) -> Result { + context + .peer + .notify_tool_list_changed() + .await + .map_err(|error| McpError::internal_error(error.to_string(), None))?; + Ok(rmcp::model::CallToolResult::success(Vec::new()).into()) } async fn list_tools( @@ -2632,6 +2652,16 @@ async fn tool_catalog_cache_sanitizes_tools_and_tracks_environment_generation() None ); + let fallback = first_context.current_tools(); + let mut tracking_context = first_context.clone(); + tracking_context.track_tool_list_changes = true; + assert!(!tracking_context.has_tools()); + assert_eq!(tracking_context.current_tools_or(fallback), None); + assert!( + first_context.has_tools(), + "disabled refresh preserves cached startup" + ); + drop(first_environment); replace_environment("ws://127.0.0.1:2"); assert!(first_environment_weak.upgrade().is_none()); @@ -5235,6 +5265,8 @@ async fn manager_with_reusable_ready_server( manager.servers.insert( "docs".to_string(), McpServerView { + refresh_tool_list: true, + refresh_timeout: DEFAULT_STARTUP_TIMEOUT, protocol_mode: crate::McpProtocolMode::Legacy, startup_readiness: Default::default(), connection: Arc::new(McpServerConnection { @@ -5591,7 +5623,7 @@ async fn refreshed_catalog_follows_reused_client_without_mutating_old_bindings() Ok(()) } -#[tokio::test] +#[tokio::test(start_paused = true)] async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> anyhow::Result<()> { let tools = Arc::new(tokio::sync::RwLock::new(vec![Tool::new( "old_search", @@ -5640,7 +5672,7 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a .await?; let managed_client = ManagedClient { _auth_change_notifications: None, - client, + client: Arc::clone(&client), server_info: create_test_server_info("Mutable tools"), tool_catalog: Arc::new(ClientToolCatalog::new(initial_tools, /*updates*/ None)), tool_timeout: None, @@ -5649,7 +5681,7 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a codex_apps_tools_cache_context: None, }; let runtime_context = reusable_server_runtime_context(); - let config = reusable_server_config("http://127.0.0.1:1"); + let mut config = reusable_server_config("http://127.0.0.1:1"); let approval_policy = Constrained::allow_any(AskForApproval::OnRequest); let permission_profile = Constrained::allow_any(PermissionProfile::default()); let mut previous = McpConnectionSet::new_uninitialized( @@ -5661,6 +5693,8 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a previous.servers.insert( "docs".to_string(), McpServerView { + refresh_tool_list: true, + refresh_timeout: DEFAULT_STARTUP_TIMEOUT, protocol_mode: crate::McpProtocolMode::Legacy, startup_readiness: Default::default(), connection: Arc::new(McpServerConnection { @@ -5690,6 +5724,35 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a ); let previous = Arc::new(previous); let old_step = capture_binding(&previous).await; + let cache = McpToolCatalogCache::default(); + let mut cache = cache + .context( + "docs", + &config, + &runtime_context, + /*resolved_environment*/ None, + ( + &ElicitationCapability::default(), + &ClientMcpExtensions::default(), + ), + Some(( + previous.servers["docs"] + .connection + .identity + .as_ref() + .unwrap(), + crate::McpProtocolMode::Legacy, + /*agent_plugin*/ false, + )), + ) + .expect("cache context"); + cache.track_tool_list_changes = true; + let mut ticket = cache.begin_fetch(); + ticket.tool_list_revision = Some(client.tool_list_revision()); + cache.publish_if_newest(ticket, old_step.tools()); + assert!(cache.has_tools()); + // Reused connections must use the new view's timeout, not their startup timeout. + config.startup_timeout_sec = Some(Duration::from_secs(1)); *tools.write().await = vec![Tool::new( "new_search", "new search", @@ -5724,6 +5787,91 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a .collect::>(), vec!["old_search".to_string()] ); + let prepared = old_step + .prepare_call("docs", "old_search") + .expect("prepared call"); + let (entered, started) = tokio::sync::oneshot::channel(); + let (release, resumed) = tokio::sync::oneshot::channel(); + let call = tokio::spawn(async move { + prepared + .call_with_preparation(/*requested_timeout*/ None, || async { + entered.send(()).unwrap(); + resumed.await?; + anyhow::bail!("stop after preparation") + }) + .await + }); + started.await?; + // Refresh must not wait for this admitted call or lose healthy resource endpoints. + client + .call_tool( + "notify".into(), + /*arguments*/ None, + /*meta*/ None, + /*timeout*/ None, + ) + .await?; + assert!( + reconciled + .stable_catalog_revisions(&[], &HashSet::new()) + .await + .is_none() + ); + assert!(!cache.has_tools()); + assert_eq!( + cache.current_tools_or(Some(old_step.tools().to_vec())), + None + ); + let failed = tokio::time::timeout(Duration::from_secs(3), capture_binding(&reconciled)) + .await + .expect("refresh must use the reconciled timeout"); + assert_eq!(failed.tools(), old_step.tools()); + assert_eq!( + failed.list_all_resources(|_| true).await, + HashMap::from([("docs".to_string(), vec![])]) + ); + assert_eq!( + failed.list_all_resource_templates(|_| true).await, + HashMap::from([("docs".to_string(), vec![])]) + ); + let retry_started = tokio::time::Instant::now(); + let retry = capture_binding(&reconciled).await; + assert_eq!(retry.tools(), old_step.tools()); + assert_eq!(retry_started.elapsed(), Duration::ZERO); + block_tool_listing.store(false, Ordering::Release); + tokio::time::advance(Duration::from_secs(5)).await; + let (first, second) = tokio::time::timeout(Duration::from_secs(1), async { + tokio::join!(capture_binding(&previous), capture_binding(&reconciled)) + }) + .await + .expect("notification refresh must not wait for a running call"); + release.send(()).unwrap(); + call.await?.expect_err("test stops before dispatch"); + assert_eq!(first.tools(), second.tools()); + assert_eq!( + model_tool_names(first.tools()), + HashSet::from([ToolName::namespaced("mcp__docs", "new_search"),]) + ); + assert_eq!( + old_step.tools(), + new_step.tools(), + "old bindings remain immutable" + ); + assert!( + reconciled + .prepare_call_for_tool(Arc::clone(old_step.config()), &old_step.tools()[0],) + .await + .is_none() + ); + let refreshed = previous.test_client("docs").client().await?; + assert_eq!( + refreshed + .tool_catalog + .read(|catalog| catalog.revision) + .await, + 1, + "concurrent readers publish one refresh on their shared client" + ); Ok(()) } diff --git a/codex-rs/codex-mcp/src/mcp/mod.rs b/codex-rs/codex-mcp/src/mcp/mod.rs index 137f1bff04..ba791d514f 100644 --- a/codex-rs/codex-mcp/src/mcp/mod.rs +++ b/codex-rs/codex-mcp/src/mcp/mod.rs @@ -186,6 +186,8 @@ pub struct McpConfig { pub non_prefixed_mcp_tool_servers: Vec, /// Protocol mode for servers other than the host-owned Codex Apps registration. pub protocol_mode: McpProtocolMode, + /// Refresh ordinary server catalogs after tools/list_changed notifications. + pub mcp_tool_list_changed: bool, /// Independent protocol mode for the trusted, HTTP Codex Apps registration. pub host_owned_apps_protocol_mode: McpProtocolMode, /// Client-side elicitation capabilities advertised during MCP initialization. diff --git a/codex-rs/codex-mcp/src/mcp/mod_tests.rs b/codex-rs/codex-mcp/src/mcp/mod_tests.rs index 8332b18048..b0bea88b78 100644 --- a/codex-rs/codex-mcp/src/mcp/mod_tests.rs +++ b/codex-rs/codex-mcp/src/mcp/mod_tests.rs @@ -113,6 +113,7 @@ pub(crate) fn test_mcp_config(codex_home: PathBuf) -> McpConfig { prefix_mcp_tool_names: true, non_prefixed_mcp_tool_servers: Vec::new(), protocol_mode: McpProtocolMode::Legacy, + mcp_tool_list_changed: true, host_owned_apps_protocol_mode: McpProtocolMode::Legacy, client_elicitation_capability: ElicitationCapability::default(), mcp_server_catalog: ResolvedMcpCatalog::default(), diff --git a/codex-rs/codex-mcp/src/rmcp_client.rs b/codex-rs/codex-mcp/src/rmcp_client.rs index ae46bd180a..7e9f4964ff 100644 --- a/codex-rs/codex-mcp/src/rmcp_client.rs +++ b/codex-rs/codex-mcp/src/rmcp_client.rs @@ -1046,10 +1046,15 @@ async fn start_server_task( (None, None) => tools.into(), _ => unreachable!("Codex Apps fetch ticket requires cache context"), }; - if let (Some(cache_context), Some(fetch_ticket)) = ( + if let (Some(cache_context), Some(mut fetch_ticket)) = ( tool_catalog_cache_context.as_ref(), tool_catalog_fetch_ticket, ) { + if cache_context.track_tool_list_changes { + // A notification makes this session's startup catalog ineligible for reuse. + // Discovery can be session-specific, so do not cache later live catalogs. + fetch_ticket.tool_list_revision = Some(client.tool_list_revision()); + } cache_context.publish_if_newest(fetch_ticket, &client_tools); } if is_codex_apps_mcp_server || tool_catalog_cache_context.is_some() { diff --git a/codex-rs/codex-mcp/src/tool_catalog_cache.rs b/codex-rs/codex-mcp/src/tool_catalog_cache.rs index d3608afe98..60989beb4b 100644 --- a/codex-rs/codex-mcp/src/tool_catalog_cache.rs +++ b/codex-rs/codex-mcp/src/tool_catalog_cache.rs @@ -17,6 +17,7 @@ use codex_config::McpServerConfig; use codex_config::McpServerTransportConfig; use codex_exec_server::Environment; use codex_protocol::mcp::ClientMcpExtensions; +use codex_rmcp_client::ToolListRevision; use lru::LruCache; use rmcp::model::ElicitationCapability; use sha1::Digest; @@ -70,14 +71,17 @@ struct OptionalStartupDeadline { struct ToolCatalogSnapshot { tools: Vec, published_at: Instant, + tool_list_revision: Option, } #[derive(Clone)] pub(crate) struct McpToolCatalogCacheContext { + pub(crate) track_tool_list_changes: bool, entry: Arc, } pub(crate) struct McpToolCatalogFetchTicket { + pub(crate) tool_list_revision: Option, generation: u64, } @@ -102,7 +106,10 @@ impl McpToolCatalogCache { let entry = lock_unpoisoned(&self.entries) .get_or_insert(identity, || Arc::new(ToolCatalogCacheEntry::default())) .clone(); - Some(McpToolCatalogCacheContext { entry }) + Some(McpToolCatalogCacheContext { + entry, + track_tool_list_changes: false, + }) } } @@ -116,6 +123,16 @@ impl Default for ToolCatalogCacheEntry { } impl McpToolCatalogCacheContext { + fn accepts_snapshot(&self, snapshot: &ToolCatalogSnapshot) -> bool { + // Enabling refresh must not reuse a catalog published without notification tracking. + snapshot + .tool_list_revision + .as_ref() + .map_or(!self.track_tool_list_changes, |revision| { + revision.current() == 0 + }) + } + pub(crate) fn has_tools(&self) -> bool { self.current_revision_if(|_| true).is_some() } @@ -129,6 +146,7 @@ impl McpToolCatalogCacheContext { let state = lock_unpoisoned(&self.entry.state); let snapshot = state.snapshot.as_ref()?; (!state.disabled_by_server + && self.accepts_snapshot(snapshot) && !snapshot.tools.is_empty() && snapshot.published_at.elapsed() <= TOOL_CATALOG_CACHE_TTL && accepts_tools(&snapshot.tools)) @@ -142,10 +160,10 @@ impl McpToolCatalogCacheContext { ) -> Instant { let mut state = lock_unpoisoned(&self.entry.state); if state.disabled_by_server - || state - .snapshot - .as_ref() - .is_some_and(|snapshot| snapshot.published_at.elapsed() <= TOOL_CATALOG_CACHE_TTL) + || state.snapshot.as_ref().is_some_and(|snapshot| { + self.accepts_snapshot(snapshot) + && snapshot.published_at.elapsed() <= TOOL_CATALOG_CACHE_TTL + }) { return default_deadline; } @@ -175,7 +193,12 @@ impl McpToolCatalogCacheContext { fallback: Option>, ) -> Option> { let state = lock_unpoisoned(&self.entry.state); - if state.disabled_by_server { + if state.disabled_by_server + || state + .snapshot + .as_ref() + .is_some_and(|snapshot| !self.accepts_snapshot(snapshot)) + { return None; } state @@ -188,6 +211,7 @@ impl McpToolCatalogCacheContext { pub(crate) fn begin_fetch(&self) -> McpToolCatalogFetchTicket { McpToolCatalogFetchTicket { + tool_list_revision: None, generation: self .entry .next_fetch_generation @@ -219,6 +243,7 @@ impl McpToolCatalogCacheContext { state.snapshot = Some(ToolCatalogSnapshot { tools, published_at: Instant::now(), + tool_list_revision: ticket.tool_list_revision, }); } } diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json index 44f9a381b8..2331f64ed6 100644 --- a/codex-rs/core/config.schema.json +++ b/codex-rs/core/config.schema.json @@ -1039,6 +1039,9 @@ "mcp_oauth_refresh_coordination": { "type": "boolean" }, + "mcp_tool_list_changed": { + "type": "boolean" + }, "memories": { "type": "boolean" }, @@ -7422,6 +7425,9 @@ "mcp_oauth_refresh_coordination": { "type": "boolean" }, + "mcp_tool_list_changed": { + "type": "boolean" + }, "memories": { "type": "boolean" }, diff --git a/codex-rs/core/src/config/mod.rs b/codex-rs/core/src/config/mod.rs index 20939cf80b..2b99142597 100644 --- a/codex-rs/core/src/config/mod.rs +++ b/codex-rs/core/src/config/mod.rs @@ -1881,6 +1881,7 @@ impl Config { xaa_enabled: self.features.enabled(Feature::UseXaa) && self.mcp_enterprise_managed_auth.is_some(), mcp_oauth_credentials_store_mode: self.mcp_oauth_credentials_store_mode, + mcp_tool_list_changed: self.features.enabled(Feature::McpToolListChanged), oauth_refresh_mode: if self.features.enabled(Feature::McpOAuthRefreshCoordination) { McpOAuthRefreshMode::Coordinated } else { diff --git a/codex-rs/core/tests/suite/rmcp_client.rs b/codex-rs/core/tests/suite/rmcp_client.rs index 2c0fcf270b..bd5592620f 100644 --- a/codex-rs/core/tests/suite/rmcp_client.rs +++ b/codex-rs/core/tests/suite/rmcp_client.rs @@ -1068,6 +1068,144 @@ async fn future_environment_mcp_policy_applies_on_the_next_turn() -> anyhow::Res Ok(()) } +#[test_case(Some("discovery"), true; "notification_during_listing")] +#[test_case(Some("pagination"), true; "notification_invalidates_cursor")] +#[test_case(None, false; "disabled")] +#[test_case(Some("startup"), true; "notification_during_startup")] +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn discovers_and_calls_new_mcp_tool_in_same_turn( + invalidation: Option<&'static str>, + enabled: bool, +) -> anyhow::Result<()> { + skip_if_no_network!(Ok(())); + skip_if_wine_exec!(Ok(()), "requires a Windows test_stdio_server binary"); + mcp_tool_discovery_scenario(ToolMode::Direct, invalidation, enabled) + .await + .map(|_| ()) +} + +pub(super) async fn mcp_tool_discovery_scenario( + tool_mode: ToolMode, + invalidation: Option<&'static str>, + enabled: bool, +) -> anyhow::Result> { + let server = responses::start_mock_server().await; + let command = remote_aware_stdio_server_bin()?; + let test = test_codex() + .with_config(move |config| { + config.code_mode.disable_in_process_fallback = true; + config + .features + .enable(Feature::CodeModeHost) + .expect("enable Code Mode host"); + if enabled { + config + .features + .enable(Feature::McpToolListChanged) + .expect("enable tool-list refresh"); + } + let mut env = HashMap::from([ + ("MCP_TEST_DISCOVER_TOOLS".to_string(), "1".to_string()), + ("MCP_TEST_VALUE".to_string(), "discovered".to_string()), + ]); + if let Some(phase) = invalidation { + env.insert("MCP_TEST_INVALIDATE_LISTING".to_string(), phase.to_string()); + } + insert_mcp_server( + config, + "discovery", + stdio_transport(command, Some(env), Vec::new()), + TestMcpServerOptions { + environment_id: remote_aware_environment_id(), + ..Default::default() + }, + ); + }) + .with_model_info_override("gpt-5.5", move |model| { + model.tool_mode = Some(tool_mode); + model.supports_search_tool = false; + model.use_responses_lite = false; + }) + .build_with_auto_env(&server) + .await?; + wait_for_mcp_server(&test.codex, "discovery").await?; + let mut mocks = Vec::new(); + for (call_id, tool, arguments) in [ + ("discover", "search_tools", r#"{"message":"find echo"}"#), + ("invoke", "echo", r#"{"message":"hello"}"#), + ] { + if !enabled && tool == "echo" { + break; + } + let call = if tool_mode == ToolMode::CodeModeOnly { + responses::ev_custom_tool_call( + call_id, + "exec", + &format!("text(await tools.mcp__discovery__{tool}({arguments}));"), + ) + } else { + responses::ev_function_call_with_namespace(call_id, "mcp__discovery", tool, arguments) + }; + mocks.push( + responses::mount_sse_once( + &server, + responses::sse(vec![ + responses::ev_response_created(call_id), + call, + responses::ev_completed(call_id), + ]), + ) + .await, + ); + } + mocks.push(responses::mount_sse_once(&server, responses::sse_completed("done")).await); + test.submit_turn("Discover the echo tool, then call it with hello.") + .await?; + let requests = mocks + .iter() + .map(responses::ResponseMock::single_request) + .collect::>(); + if tool_mode == ToolMode::Direct { + assert!( + requests[0] + .tool_by_name("mcp__discovery", "search_tools") + .is_some() + ); + assert_eq!( + requests[0].tool_by_name("mcp__discovery", "echo").is_some(), + invalidation == Some("startup") + ); + if !enabled { + assert_eq!( + requests[1].body_json()["tools"], + requests[0].body_json()["tools"] + ); + return Ok(requests); + } + assert!(requests[1].tool_by_name("mcp__discovery", "echo").is_some()); + let output = requests[2] + .function_call_output_text("invoke") + .expect("echo output"); + let (_, payload) = output + .split_once("\nOutput:\n") + .expect("wrapped MCP output"); + assert_eq!( + serde_json::from_str::(payload)?, + json!({ + "echo": "ECHOING: hello", "env": "discovered", + }) + ); + } else { + assert!( + requests[2] + .custom_tool_call_output("invoke") + .to_string() + .contains("ECHOING: hello") + ); + } + Ok(requests) +} + #[test_case("rmcp", "mcp__rmcp"; "simple name")] #[test_case("npm:@scope/package.name", "mcp__npm__scope_package_name"; "npm name")] #[tokio::test(flavor = "multi_thread", worker_threads = 1)] diff --git a/codex-rs/core/tests/suite/scenarios.rs b/codex-rs/core/tests/suite/scenarios.rs index 59894c49f8..d630531538 100644 --- a/codex-rs/core/tests/suite/scenarios.rs +++ b/codex-rs/core/tests/suite/scenarios.rs @@ -328,6 +328,58 @@ async fn code_mode_mcp_schema_limits_preserve_explicit_overrides() -> Result<()> Ok(()) } +#[test_case::test_case(ToolMode::Direct; "direct")] +#[test_case::test_case(ToolMode::CodeModeOnly; "code_mode")] +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn mcp_tool_discovery_in_same_turn(tool_mode: ToolMode) -> Result<()> { + skip_if_no_network!(Ok(())); + skip_if_wine_exec!(Ok(()), "requires a Windows test_stdio_server binary"); + let requests = super::rmcp_client::mcp_tool_discovery_scenario( + tool_mode, /*invalidation*/ None, /*enabled*/ true, + ) + .await?; + let mut bodies = requests + .iter() + .map(core_test_support::responses::ResponsesRequest::body_json) + .collect::>(); + // Cargo and Bazel can serialize embedded JSON in different key orders. + // Normalize each output text before snapshot truncation and hashing. + for body in &mut bodies { + for item in body["input"].as_array_mut().expect("request input") { + if item["type"] != "function_call_output" && item["type"] != "custom_tool_call_output" { + continue; + } + let parts = match &mut item["output"] { + serde_json::Value::Array(parts) => parts + .iter_mut() + .map(|part| &mut part["text"]) + .collect::>(), + output => vec![output], + }; + for part in parts { + let text = part.as_str().expect("text output"); + let mut normalized = context_snapshot::normalize_json_lines(text); + if text.ends_with('\n') { + normalized.push('\n'); + } + *part = normalized.into(); + } + } + } + let entries = bodies.iter().map(SnapshotEntry::body).collect::>(); + insta::assert_snapshot!( + format!("mcp_tool_discovery_{tool_mode:?}"), + context_snapshot::format_context_snapshot( + "An MCP discovery call announces a new tool, which is called in the same turn.", + &entries, + &ContextSnapshotOptions::default() + .rewrite_known_segments() + .include_request_settings(), + ) + ); + Ok(()) +} + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] async fn astra_asks_an_async_question_and_receives_the_answer_while_working() -> Result<()> { skip_if_no_network!(Ok(())); diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_CodeModeOnly.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_CodeModeOnly.snap new file mode 100644 index 0000000000..33f69ec0bf --- /dev/null +++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_CodeModeOnly.snap @@ -0,0 +1,56 @@ +--- +source: core/tests/suite/scenarios.rs +expression: "context_snapshot::format_context_snapshot(\"An MCP discovery call announces a new tool, which is called in the same turn.\",\n&entries,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)" +--- +Scenario: An MCP discovery call announces a new tool, which is called in the same turn. + +## Window 1 +Settings: + include: ["reasoning.encrypted_content"] + model: "gpt-5.5" + parallel_tool_calls: true + prompt_cache_key: "" + reasoning: {"effort":"medium"} + store: false + stream: true + text: {"verbosity":"low"} + tool_choice: "auto" + tools (4; hash=c0d891b72dfe19c6): + - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=5f9adb37c23e2085 + - function/wait: Waits on a yielded `exec` cell and returns new output or completion. - Use `wait` only after `exe...; args=[cell_id, max_tokens, terminate, yield_time_ms]; hash=6692d8f6c55be489 + - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6 + - web_search; hash=e214d4db1bc49e89 +-- request 1 (request) -- +00:message/developer: + +01:message/developer: + +02:message/user: + +03:message/user: + Discover the echo tool, then call it with hello. + +## Window 2 (after request 1) +Settings: relative to window 1 + tools (4; hash=f74ded0dd31e19a8): + ~ custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=f36b0269278fcd9d +-- request 2 (request) -- +00:message/developer: + +01:message/developer: + +02:message/user: + +03:message/user: + Discover the echo tool, then call it with hello. +04:custom_tool_call/exec:text(await tools.mcp__discovery__search_tools({"message":"find echo"})); +05:custom_tool_call_output:Script completed + Wall time seconds + Output: + | {"content":[],"isError":false,"structuredContent":{"tools":[{"annotations":{"readOnlyHint":true},"descri...l"}]}},"required":["echo","env"],"type":"object"}}]}} [hash=df19b4e245e07b80] +-- request 3 (request) -- +06:custom_tool_call/exec:text(await tools.mcp__discovery__echo({"message":"hello"})); +07:custom_tool_call_output:Script completed + Wall time seconds + Output: + | {"content":[],"isError":false,"structuredContent":{"echo":"ECHOING: hello","env":"discovered"}} diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_Direct.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_Direct.snap new file mode 100644 index 0000000000..e91e191f32 --- /dev/null +++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_Direct.snap @@ -0,0 +1,69 @@ +--- +source: core/tests/suite/scenarios.rs +expression: "context_snapshot::format_context_snapshot(\"An MCP discovery call announces a new tool, which is called in the same turn.\",\n&entries,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)" +--- +Scenario: An MCP discovery call announces a new tool, which is called in the same turn. + +## Window 1 +Settings: + include: ["reasoning.encrypted_content"] + model: "gpt-5.5" + parallel_tool_calls: true + prompt_cache_key: "" + reasoning: {"effort":"medium"} + store: false + stream: true + text: {"verbosity":"low"} + tool_choice: "auto" + tools (11; hash=d2c3940ebd5ac02b): + - function/exec_command: Runs a command in a PTY, returning output or a session ID for ongoing interaction.; args=[cmd, justification, login, max_output_tokens, prefix_rule, sandbox_permissions, shell, tty, workdir, yield_time_ms]; hash=c04108e51a8548c5 + - function/write_stdin: Writes characters to an existing unified exec session and returns recent output.; args=[chars, max_output_tokens, session_id, yield_time_ms]; hash=7fb62d8a3e2df4e2 + - function/list_mcp_resources: Lists resources provided by MCP servers. Resources allow servers to share data that provides cont...; args=[cursor, server]; hash=6792edaff13561bd + - function/list_mcp_resource_templates: Lists resource templates provided by MCP servers. Parameterized resource templates allow servers ...; args=[cursor, server]; hash=60f17c90ef7a4ebb + - function/read_mcp_resource: Read a specific resource from an MCP server given the server name and resource URI.; args=[server, uri]; hash=24246896b39008ae + - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6 + - custom/apply_patch: The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the pat...; hash=dea9f12b0111a4ba + - function/view_image: View a local image file from the filesystem when visual inspection is needed. Use this for images...; args=[detail, path]; hash=3b766d5bdec5d50e + - namespace/multi_agent_v1: Tools for spawning and managing sub-agents.; hash=2327142bda177c50 + - function/close_agent + - function/resume_agent + - function/send_input + - function/spawn_agent + - function/wait_agent + - namespace/mcp__discovery: Use these tools to exercise the rmcp test server.; hash=55b000f43c815c1f + - function/search_tools + - web_search; hash=e214d4db1bc49e89 +-- request 1 (request) -- +00:message/developer: + +01:message/developer: + +02:message/user: + +03:message/user: + Discover the echo tool, then call it with hello. + +## Window 2 (after request 1) +Settings: relative to window 1 + tools (11; hash=21579d54e22ad527): + ~ namespace/mcp__discovery: Use these tools to exercise the rmcp test server.; hash=66db79539eaf6be3 + - function/echo + - function/search_tools +-- request 2 (request) -- +00:message/developer: + +01:message/developer: + +02:message/user: + +03:message/user: + Discover the echo tool, then call it with hello. +04:function_call/mcp__discovery.search_tools:{"message":"find echo"} +05:function_call_output:Wall time: seconds + Output: + {"tools":[{"annotations":{"readOnlyHint":true},"description":"Echo back the provided message and include...ll"}]}},"required":["echo","env"],"type":"object"}}]} [hash=ccb6ffb1e2ec3a2c] +-- request 3 (request) -- +06:function_call/mcp__discovery.echo:{"message":"hello"} +07:function_call_output:Wall time: seconds + Output: + {"echo":"ECHOING: hello","env":"discovered"} diff --git a/codex-rs/features/src/lib.rs b/codex-rs/features/src/lib.rs index 4030e8e4a6..edcaa6ffd7 100644 --- a/codex-rs/features/src/lib.rs +++ b/codex-rs/features/src/lib.rs @@ -249,6 +249,8 @@ pub enum Feature { EnableMcpApps, /// Enable MCP protocol version 2026-07-28 support. Mcp20260728, + /// Honor ordinary MCP server tool-list notifications within a turn. + McpToolListChanged, /// Enable MCP protocol version 2026-07-28 for the host-owned Codex Apps server. CodexAppsMcp20260728, /// Let RMCP coordinate OAuth refresh through the configured credential store. @@ -1546,6 +1548,12 @@ pub const FEATURES: &[FeatureSpec] = &[ stage: Stage::UnderDevelopment, default_enabled: false, }, + FeatureSpec { + id: Feature::McpToolListChanged, + key: "mcp_tool_list_changed", + stage: Stage::UnderDevelopment, + default_enabled: false, + }, FeatureSpec { id: Feature::CodexAppsMcp20260728, key: "codex_apps_mcp_2026_07_28", diff --git a/codex-rs/rmcp-client/src/bin/test_stdio_server.rs b/codex-rs/rmcp-client/src/bin/test_stdio_server.rs index 70a5476ee9..8ea0150268 100644 --- a/codex-rs/rmcp-client/src/bin/test_stdio_server.rs +++ b/codex-rs/rmcp-client/src/bin/test_stdio_server.rs @@ -43,6 +43,8 @@ struct TestToolServer { resources: Arc>, resource_templates: Arc>, supports_openai_form_elicitation: Arc, + tools_discovered: Arc, + invalidated_listing: Arc, } const MEMO_URI: &str = "memo://codex/example-note"; @@ -181,6 +183,8 @@ impl TestToolServer { resources: Arc::new(resources), resource_templates: Arc::new(resource_templates), supports_openai_form_elicitation: Arc::new(AtomicBool::new(false)), + tools_discovered: Arc::default(), + invalidated_listing: Arc::default(), } } @@ -559,7 +563,7 @@ impl ServerHandler for TestToolServer { fn list_tools( &self, request: Option, - _context: rmcp::service::RequestContext, + context: rmcp::service::RequestContext, ) -> impl std::future::Future> + Send + '_ { let tools = self.tools.clone(); async move { @@ -572,6 +576,49 @@ impl ServerHandler for TestToolServer { .get_or_insert_with(MetaObject::new) .insert("ui".to_string(), json!({ "visibility": ["app"] })); } + if std::env::var_os("MCP_TEST_DISCOVER_TOOLS").is_some() { + tools.retain(|tool| tool.name == "echo"); + let mut search = tools[0].clone(); + search.name = Cow::Borrowed("search_tools"); + search.description = Some(Cow::Borrowed("Discover the echo tool.")); + let discovered = self.tools_discovered.load(Ordering::Acquire); + if !discovered { + tools.clear(); + } + let invalidation = std::env::var("MCP_TEST_INVALIDATE_LISTING"); + let cursor = request.as_ref().and_then(|request| request.cursor.as_ref()); + if invalidation.as_deref() == Ok("pagination") + && discovered + && !self.invalidated_listing.load(Ordering::Acquire) + && cursor.is_none() + { + return Ok(ListToolsResult { + tools: vec![search], + next_cursor: Some("stale".to_string()), + ..Default::default() + }); + } + let invalidate = match invalidation.as_deref() { + Ok("startup") => !discovered, + Ok("discovery") => discovered, + Ok("pagination") => discovered && cursor.is_some(), + _ => false, + }; + if invalidate && !self.invalidated_listing.swap(true, Ordering::AcqRel) { + self.tools_discovered.store(true, Ordering::Release); + // Invalidate an incomplete listing before returning its response. + tools.clear(); + context + .peer + .notify_tool_list_changed() + .await + .map_err(|error| McpError::internal_error(error.to_string(), None))?; + if invalidation.as_deref() == Ok("pagination") { + return Err(McpError::invalid_params("expired tool-list cursor", None)); + } + } + tools.insert(0, search); + } let mut result = ListToolsResult::with_all_items(tools); match ( std::env::var("MCP_TEST_TOOL_PAGINATION").as_deref(), @@ -642,6 +689,14 @@ impl ServerHandler for TestToolServer { context: rmcp::service::RequestContext, ) -> Result { match request.name.as_ref() { + "search_tools" if std::env::var_os("MCP_TEST_DISCOVER_TOOLS").is_some() => { + self.tools_discovered.store(true, Ordering::Release); + context.peer.notify_tool_list_changed().await + .map_err(|error| McpError::internal_error(error.to_string(), None))?; + Ok(Self::structured_result(json!({ + "tools": self.tools.iter().filter(|tool| tool.name == "echo").collect::>() + }))) + } "js" => { let args = Self::parse_call_args::(&request, "js")?; if args.code == "nodeRepl.fail()" { diff --git a/codex-rs/rmcp-client/src/lib.rs b/codex-rs/rmcp-client/src/lib.rs index 54b46ef07c..615f64280e 100644 --- a/codex-rs/rmcp-client/src/lib.rs +++ b/codex-rs/rmcp-client/src/lib.rs @@ -31,6 +31,7 @@ mod service_error; mod startup_error; mod stdio_server_launcher; mod tool_input; +mod tool_list_changes; mod trace_context; mod user_verification; mod utils; @@ -103,4 +104,5 @@ pub use startup_error::is_authentication_required_error; pub use stdio_server_launcher::ExecutorStdioServerLauncher; pub use stdio_server_launcher::LocalStdioServerLauncher; pub use stdio_server_launcher::StdioServerLauncher; +pub use tool_list_changes::ToolListRevision; pub use user_verification::UserVerificationReason; diff --git a/codex-rs/rmcp-client/src/rmcp_client.rs b/codex-rs/rmcp-client/src/rmcp_client.rs index 39dc2cdda4..552a80bc62 100644 --- a/codex-rs/rmcp-client/src/rmcp_client.rs +++ b/codex-rs/rmcp-client/src/rmcp_client.rs @@ -7,6 +7,7 @@ use std::sync::Arc; use std::sync::Mutex as StdMutex; use std::sync::OnceLock; use std::sync::PoisonError; +use std::sync::atomic::AtomicU64; use std::sync::atomic::AtomicUsize; use std::sync::atomic::Ordering; use std::time::Duration; @@ -99,6 +100,7 @@ use crate::stdio_server_launcher::StdioServerCommand; use crate::stdio_server_launcher::StdioServerLauncher; use crate::stdio_server_launcher::StdioServerProcessHandle; use crate::stdio_server_launcher::StdioServerTransport; +use crate::tool_list_changes::track_tool_list_changes; use crate::utils::build_default_headers; use codex_config::types::OAuthCredentialsStoreMode; @@ -408,9 +410,15 @@ pub struct RmcpClient { initialize_context: Mutex>, session_recovery_lock: Semaphore, elicitation_pause_state: ElicitationPauseState, + tool_list_revision: Arc, } impl RmcpClient { + /// Tool catalog invalidation sequence, ordered before subsequent responses. + pub fn tool_list_revision(&self) -> crate::ToolListRevision { + crate::ToolListRevision(Arc::clone(&self.tool_list_revision)) + } + /// Requests server-side read-only filtering and invocation checks for every tool request. pub fn with_read_only_tools(mut self, requires_read_only_tools: bool) -> Self { self.requires_read_only_tools = requires_read_only_tools; @@ -448,6 +456,7 @@ impl RmcpClient { initialize_context: Mutex::new(None), session_recovery_lock: Semaphore::new(/*permits*/ 1), elicitation_pause_state: ElicitationPauseState::new(), + tool_list_revision: Arc::default(), }) } @@ -522,6 +531,7 @@ impl RmcpClient { requires_read_only_tools: false, session_recovery_lock: Semaphore::new(/*permits*/ 1), elicitation_pause_state: ElicitationPauseState::new(), + tool_list_revision: Arc::default(), }) } @@ -629,6 +639,7 @@ impl RmcpClient { requires_read_only_tools: false, session_recovery_lock: Semaphore::new(/*permits*/ 1), elicitation_pause_state: ElicitationPauseState::new(), + tool_list_revision: Arc::default(), }) } @@ -1315,19 +1326,31 @@ impl RmcpClient { let (transport, oauth_runtime) = match pending_transport { PendingTransport::InProcess { transport } => ( client_service - .serve_with_lifecycle(transport, lifecycle) + .serve_with_lifecycle( + track_tool_list_changes(transport, Arc::clone(&self.tool_list_revision)), + lifecycle, + ) .boxed(), None, ), PendingTransport::Stdio { transport } => ( client_service - .serve_with_lifecycle(*transport, lifecycle) + .serve_with_lifecycle( + track_tool_list_changes(*transport, Arc::clone(&self.tool_list_revision)), + lifecycle, + ) .boxed(), None, ), PendingTransport::StreamableHttp { transport } => ( client_service - .serve_with_lifecycle(capture_event_notifications(transport), lifecycle) + .serve_with_lifecycle( + track_tool_list_changes( + capture_event_notifications(transport), + Arc::clone(&self.tool_list_revision), + ), + lifecycle, + ) .boxed(), None, ), @@ -1336,13 +1359,19 @@ impl RmcpClient { oauth_runtime, } => ( client_service - .serve_with_lifecycle(transport, lifecycle) + .serve_with_lifecycle( + track_tool_list_changes(transport, Arc::clone(&self.tool_list_revision)), + lifecycle, + ) .boxed(), Some(oauth_runtime), ), PendingTransport::StreamableHttpWithAccessTokenOnly { transport } => ( client_service - .serve_with_lifecycle(transport, lifecycle) + .serve_with_lifecycle( + track_tool_list_changes(transport, Arc::clone(&self.tool_list_revision)), + lifecycle, + ) .boxed(), None, ), diff --git a/codex-rs/rmcp-client/src/tool_list_changes.rs b/codex-rs/rmcp-client/src/tool_list_changes.rs new file mode 100644 index 0000000000..8f81a50714 --- /dev/null +++ b/codex-rs/rmcp-client/src/tool_list_changes.rs @@ -0,0 +1,73 @@ +//! Records catalog invalidations in transport order, before a later tool response can +//! let inference continue. The SDK still receives and handles every message normally. + +use std::future::Future; +use std::sync::Arc; +use std::sync::atomic::AtomicU64; +use std::sync::atomic::Ordering; + +use rmcp::model::JsonRpcMessage; +use rmcp::model::ServerNotification; +use rmcp::service::RoleClient; +use rmcp::service::RxJsonRpcMessage; +use rmcp::service::TxJsonRpcMessage; +use rmcp::transport::IntoTransport; +use rmcp::transport::Transport; + +/// Read-only observation of notifications received by one connection. Retaining this +/// handle does not keep the connection alive. +#[derive(Clone)] +pub struct ToolListRevision(pub(crate) Arc); + +impl ToolListRevision { + pub fn current(&self) -> u64 { + self.0.load(Ordering::Acquire) + } +} + +pub(crate) fn track_tool_list_changes( + transport: T, + revision: Arc, +) -> impl Transport + 'static +where + T: IntoTransport, + E: std::error::Error + Send + Sync + 'static, +{ + ToolListChanges { + inner: transport.into_transport(), + revision, + } +} + +struct ToolListChanges { + inner: T, + revision: Arc, +} + +impl + 'static> Transport for ToolListChanges { + type Error = T::Error; + + fn send( + &mut self, + message: TxJsonRpcMessage, + ) -> impl Future> + Send + 'static { + self.inner.send(message) + } + + async fn receive(&mut self) -> Option> { + let message = self.inner.receive().await?; + if let JsonRpcMessage::Notification(notification) = &message + && matches!( + notification.notification, + ServerNotification::ToolListChangedNotification(_) + ) + { + self.revision.fetch_add(1, Ordering::AcqRel); + } + Some(message) + } + + fn close(&mut self) -> impl Future> + Send { + self.inner.close() + } +}