Add explicit cloud catalog refresh before turn admission (#61449)

## Why

Hosts need to refresh cloud plugin and skill catalogs without starting a turn or waiting for step preparation.

## What changed

- Add `CodexThread::refresh_cloud_plugins()` and a turn-independent extension callback that bypass cached catalog reuse and failure cooldowns.
- Run catalog contributors concurrently while serializing publication with step snapshot capture. Invalidate MCP resource caches before explicit discovery and schedule MCP reconciliation afterward.
- Accept complete and partial catalogs, report discovery errors, and keep failed or cancelled refreshes retryable.
- Allow hosts to gate cloud plugin discovery through effective configuration.

## Testing

Add coverage for discovery before turn admission, catalog replacement and reuse, immediate retry after failure, concurrent contributors, and cancellation-safe publication and invalidation.

GitOrigin-RevId: 83e847fcab6562581af2c9e831b1d2a310f2b270
This commit is contained in:
Anthony Tafoya
2026-11-14 02:45:51 +00:00
committed by copyberry
parent 32cec881b7
commit d26406987e
32 changed files with 953 additions and 247 deletions
+147 -85
View File
@@ -1,6 +1,7 @@
//! Refreshes cloud plugins before a step when their auth or Apps resources change.
//! Partial catalogs and catalogs with warnings remain usable and retry with thread-owned exponential backoff.
//! Accepted complete and partial catalogs replace prior entries; failures retain same-auth fallback.
//! Refreshes cloud plugins explicitly or when their accepted auth/resource generation is stale.
//! Partial catalogs and warnings remain usable and retry with exponential backoff.
//! Complete and partial results replace the catalog; failed attempts retain same-auth fallback.
//! Core serializes discovery and step snapshots with its per-thread catalog lock.
use crate::PluginListQuery;
use crate::PluginsThreadState;
@@ -9,7 +10,8 @@ use codex_core::config::Config;
use codex_core_plugins::PluginCatalog;
use codex_core_plugins::PluginIdentity;
use codex_extension_api::CatalogRefreshBackoff;
use codex_extension_api::CatalogRefreshInput;
use codex_extension_api::CatalogRefreshInput as StepCatalogRefreshInput;
use codex_extension_api::CloudCatalogRefreshInput;
use codex_extension_api::ConfigContributor;
use codex_extension_api::ExtensionData;
use codex_extension_api::ExtensionFuture;
@@ -17,7 +19,6 @@ use codex_extension_api::McpServerContribution;
use codex_extension_api::ThreadLifecycleContributor;
use codex_extension_api::ThreadStartInput;
use codex_extension_api::TurnLifecycleContributor;
use codex_features::Feature;
use codex_mcp::CODEX_APPS_MCP_SERVER_NAME;
use codex_mcp::McpResourceClient;
use std::collections::HashSet;
@@ -26,71 +27,59 @@ const MAX_PROJECTED_CLOUD_PLUGINS: usize = 100;
pub(crate) const MAX_PLUGIN_DISPLAY_NAME_CHARS: usize = 64;
pub(crate) const MAX_CONNECTOR_IDS_PER_PLUGIN: usize = 64;
struct CloudPluginRefreshError {
error: String,
catalog_cleared: bool,
/// Cooldown for the step caller to store after a current-generation failure.
/// Superseded attempts return `None`, allowing the next step to retry immediately.
retry_backoff: Option<CatalogRefreshBackoff>,
}
fn cloud_catalog_query(
input: CloudCatalogRefreshInput<'_>,
turn_id: Option<&str>,
) -> PluginListQuery {
PluginListQuery {
thread_id: input.thread_store.level_id().to_string(),
turn_id: turn_id.map(str::to_owned),
mcp_resources: input.session_store.get::<McpResourceClient>(),
snapshots: Vec::new(),
}
}
impl PluginContributor {
#[expect(
clippy::await_holding_invalid_type,
reason = "cloud discovery must remain serialized through fetching and catalog publication"
)]
async fn refresh_cloud_catalog(&self, input: CatalogRefreshInput<'_>) -> bool {
/// Returns whether publishing or clearing a catalog requires MCP reprojection.
async fn discover_cloud_catalog(
&self,
state: &PluginsThreadState,
query: PluginListQuery,
) -> Result<bool, CloudPluginRefreshError> {
let Some(provider) = &self.providers.cloud else {
return false;
return Ok(false);
};
let Some(state) = input.thread_store.get::<PluginsThreadState>() else {
return false;
let (auth_cache_key, resource_cache_key, catalog_cleared) = {
let mut state = state.contributor_state();
if !state.plugins_enabled {
return Ok(false);
}
let resource_cache_key = query
.mcp_resources
.as_ref()
.and_then(|client| client.server_cache_key(CODEX_APPS_MCP_SERVER_NAME));
let previous_catalog_auth = state
.cloud_generation
.as_ref()
.filter(|generation| generation.catalog.is_some())
.map(|generation| generation.auth_cache_key.clone());
let auth_cache_key =
state.prepare_cloud_generation(query.mcp_resources.as_deref().cloned());
let catalog_cleared =
previous_catalog_auth.is_some_and(|previous| previous != auth_cache_key);
(auth_cache_key, resource_cache_key, catalog_cleared)
};
// Wait without holding catalog state or the MCP runtime permit, then recheck the cache.
let _refresh = state.cloud_refresh_lock.lock().await;
let query = PluginListQuery {
thread_id: input.thread_store.level_id().to_string(),
turn_id: input.turn_id.to_string(),
mcp_resources: input.session_store.get::<McpResourceClient>(),
snapshots: Vec::new(),
};
let (auth_cache_key, resource_cache_key, catalog_cleared) =
{
let mut state = state.contributor_state();
if !state.plugins_enabled {
return false;
}
let auth = query
.mcp_resources
.as_ref()
.map(|client| client.auth_cache_key_for_server(CODEX_APPS_MCP_SERVER_NAME));
let resource_cache_key = query
.mcp_resources
.as_ref()
.and_then(|client| client.server_cache_key(CODEX_APPS_MCP_SERVER_NAME));
if state.cloud_retry.as_ref().is_some_and(|retry| {
retry.is_pending(auth.as_ref(), resource_cache_key.as_ref())
}) {
return false;
}
let previous_catalog_auth = state
.cloud_generation
.as_ref()
.filter(|generation| generation.catalog.is_some())
.map(|generation| generation.auth_cache_key.clone());
if let Some(generation) = &state.cloud_generation
&& previous_catalog_auth.as_ref() == Some(&auth)
&& generation.is_auth_current()
&& generation.resource_cache_key == resource_cache_key
&& generation
.catalog
.as_ref()
.is_some_and(|catalog| !catalog.is_partial && catalog.warnings.is_empty())
{
state.cloud_retry = None;
return false;
}
let auth_cache_key =
state.prepare_cloud_generation(query.mcp_resources.as_deref().cloned());
let catalog_cleared =
previous_catalog_auth.is_some_and(|previous| previous != auth_cache_key);
(auth_cache_key, resource_cache_key, catalog_cleared)
};
let result = provider.list(query).await;
let mut state = state.contributor_state();
let catalog_published = match result {
match result {
Ok(catalog) => {
let needs_retry = catalog.is_partial || !catalog.warnings.is_empty();
let published = state.publish_cloud_catalog(
@@ -112,26 +101,38 @@ impl PluginContributor {
tracing::debug!(
"cloud plugin discovery finished after auth or resources changed"
);
return Err(CloudPluginRefreshError {
error: "cloud plugin discovery was superseded".to_string(),
catalog_cleared,
retry_backoff: None,
});
}
published
}
Err(_) => {
if state.cloud_generation.as_ref().is_some_and(|generation| {
generation.auth_cache_key == auth_cache_key
&& generation.is_auth_current()
&& generation.current_resource_cache_key() == resource_cache_key
}) {
state.cloud_retry = Some(CatalogRefreshBackoff::after_failure(
auth_cache_key,
resource_cache_key,
state.cloud_retry.as_ref(),
));
}
Err(error) => {
let retry_backoff = state
.cloud_generation
.as_ref()
.filter(|generation| {
generation.auth_cache_key == auth_cache_key
&& generation.is_auth_current()
&& generation.current_resource_cache_key() == resource_cache_key
})
.map(|_| {
CatalogRefreshBackoff::after_failure(
auth_cache_key,
resource_cache_key,
state.cloud_retry.as_ref(),
)
});
tracing::warn!("cloud plugin discovery failed");
false
return Err(CloudPluginRefreshError {
error: error.to_string(),
catalog_cleared,
retry_backoff,
});
}
};
catalog_cleared || catalog_published
}
Ok(true)
}
}
@@ -144,7 +145,7 @@ impl ThreadLifecycleContributor<Config> for PluginContributor {
let state = input.thread_store.get_or_init(PluginsThreadState::default);
{
let mut state = state.contributor_state();
state.plugins_enabled = input.config.features.enabled(Feature::Plugins);
state.plugins_enabled = self.providers.cloud_enabled(input.config);
state.extension_metrics = input.extension_metrics;
}
if let Some(resources) = &input.mcp_resource_client {
@@ -162,14 +163,14 @@ impl ConfigContributor<Config> for PluginContributor {
_previous_config: &Config,
new_config: &Config,
) {
let plugins_enabled = new_config.features.enabled(Feature::Plugins);
let plugins_enabled = self.providers.cloud_enabled(new_config);
let state = thread_store.get_or_init(PluginsThreadState::default);
let mut state = state.contributor_state();
if state.plugins_enabled != plugins_enabled {
state.cloud_retry = None;
}
state.plugins_enabled = plugins_enabled;
if self.providers.cloud.is_none() || !plugins_enabled {
if !plugins_enabled {
state.cloud_generation = None;
state.cloud_retry = None;
}
@@ -179,9 +180,70 @@ impl ConfigContributor<Config> for PluginContributor {
impl TurnLifecycleContributor for PluginContributor {
fn refresh_catalog_for_step<'a>(
&'a self,
input: CatalogRefreshInput<'a>,
input: StepCatalogRefreshInput<'a>,
) -> ExtensionFuture<'a, bool> {
Box::pin(self.refresh_cloud_catalog(input))
Box::pin(async move {
let Some(state) = input.thread_store.get::<PluginsThreadState>() else {
return false;
};
let query = cloud_catalog_query(input.into(), Some(input.turn_id));
{
let mut state = state.contributor_state();
let auth = query
.mcp_resources
.as_ref()
.map(|client| client.auth_cache_key_for_server(CODEX_APPS_MCP_SERVER_NAME));
let resources = query
.mcp_resources
.as_ref()
.and_then(|client| client.server_cache_key(CODEX_APPS_MCP_SERVER_NAME));
if let Some(generation) = &state.cloud_generation
&& generation
.catalog
.as_ref()
.is_some_and(|catalog| !catalog.is_partial && catalog.warnings.is_empty())
&& generation.auth_cache_key == auth
&& generation.is_auth_current()
&& generation.resource_cache_key == resources
{
state.cloud_retry = None;
return false;
}
if state
.cloud_retry
.as_ref()
.is_some_and(|retry| retry.is_pending(auth.as_ref(), resources.as_ref()))
{
return false;
}
}
match self.discover_cloud_catalog(&state, query).await {
Ok(changed) => changed,
Err(failure) => {
if let Some(retry_backoff) = failure.retry_backoff {
state.contributor_state().cloud_retry = Some(retry_backoff);
}
failure.catalog_cleared
}
}
})
}
fn refresh_cloud_catalog<'a>(
&'a self,
input: CloudCatalogRefreshInput<'a>,
) -> ExtensionFuture<'a, Result<(), String>> {
Box::pin(async move {
let Some(state) = input.thread_store.get::<PluginsThreadState>() else {
return Ok(());
};
// A failed explicit attempt gets an immediate retry on the next step.
state.contributor_state().cloud_retry = None;
self.discover_cloud_catalog(&state, cloud_catalog_query(input, /*turn_id*/ None))
.await
.map(|_| ())
.map_err(|failure| failure.error)
})
}
}