Treat explicit provider model catalogs as authoritative (#49135)

## Why

Providers with `model_catalog_url` could advertise bundled models absent from their catalog or reuse stale models after a failed refresh. Model metadata could also match by prefix or namespaced suffix instead of the provider's exact model ID.

## What changed

- Suppress bundled model fallback and merging for explicit provider catalogs, including when discovery is disabled.
- Require unique, non-empty catalog slugs and match metadata by exact model ID.
- Serialize explicit catalog refreshes and invalidate in-memory and persisted catalog entries after fetch failures, preventing stale cache reuse.
- Report a clear configuration error when startup has no available model, while allowing an explicitly configured `model`.

## Testing

Add regression coverage for exact model matching, hidden catalog entries, cache invalidation across restart and recovery, invalid slugs, and empty-catalog startup with and without an explicit model. Update app-server model-list expectations and verify the TUI configuration error.

GitOrigin-RevId: ac323a94178e3c48df8d4a159a86fdbac20b03a2
This commit is contained in:
andrewgu-oai
2026-09-29 02:33:55 +00:00
committed by copyberry
parent a9118edae8
commit 458f7046a5
10 changed files with 409 additions and 97 deletions
+128 -10
View File
@@ -4,6 +4,7 @@ use crate::cache::ModelsCacheEntry;
use crate::collaboration_mode_presets::builtin_collaboration_mode_presets;
use crate::config::ModelsManagerConfig;
use crate::model_info;
use chrono::DateTime;
use chrono::Utc;
use codex_http_client::HttpClientFactory;
use codex_login::AuthManager;
@@ -22,6 +23,8 @@ use std::sync::Arc;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering;
use std::time::Duration;
use tokio::sync::Mutex;
use tokio::sync::MutexGuard;
use tokio::sync::RwLock;
use tokio::sync::TryLockError;
use tracing::Instrument as _;
@@ -145,7 +148,7 @@ pub trait ModelsManager: fmt::Debug + Send + Sync {
) -> ModelsManagerFuture<'_, ModelsResponse>;
/// Best-effort refresh when the in-memory catalog belongs to different credentials.
/// Static catalogs need no refresh. Failures leave the existing cache/default fallback.
/// Static catalogs need no refresh. Failures follow the catalog's fallback policy.
fn refresh_after_auth_change(
&self,
_http_client_factory: HttpClientFactory,
@@ -255,12 +258,37 @@ pub type ModelsManagerFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a
/// Shared model manager handle used across runtime services.
pub type SharedModelsManager = Arc<dyn ModelsManager>;
/// Only explicit catalogs serialize refresh and suppress bundled fallback. Auth and discovery
/// settings are still evaluated when models are requested.
#[derive(Debug)]
enum CatalogSource {
Default,
ExplicitProvider(Mutex<()>),
}
impl CatalogSource {
fn fallback_models(&self) -> Option<Vec<ModelInfo>> {
match self {
Self::Default => Some(load_remote_models_from_file().unwrap_or_default()),
Self::ExplicitProvider(_) => None,
}
}
async fn refresh_lock(&self) -> Option<MutexGuard<'_, ()>> {
match self {
Self::Default => None,
Self::ExplicitProvider(lock) => Some(lock.lock().await),
}
}
}
/// OpenAI-compatible model manager backed by bundled models, cache, and `/models`.
#[derive(Debug)]
pub struct OpenAiModelsManager {
remote_models: RwLock<ModelsCacheEntry>,
cache: Option<Arc<dyn ModelsCache>>,
endpoint_client: SharedModelsEndpointClient,
catalog_source: CatalogSource,
api_key_model_discovery_enabled: AtomicBool,
auth_manager: Option<Arc<AuthManager>>,
}
@@ -315,21 +343,29 @@ impl OpenAiModelsManager {
endpoint_client: Arc<dyn ModelsEndpointClient>,
auth_manager: Option<Arc<AuthManager>>,
) -> Self {
let remote_models = load_remote_models_from_file().unwrap_or_default();
Self {
remote_models: RwLock::new(ModelsCacheEntry {
fetched_at: Utc::now(),
etag: None,
client_version: Some(crate::client_version_to_whole()),
identity: endpoint_client.identity(),
models: remote_models,
models: load_remote_models_from_file().unwrap_or_default(),
}),
cache,
api_key_model_discovery_enabled: AtomicBool::new(false),
endpoint_client,
catalog_source: CatalogSource::Default,
auth_manager,
}
}
/// Configure a newly constructed manager to use only the provider's explicit catalog.
/// Clear the bundled seed before sharing it; the existing auth identity must be retained.
pub fn with_provider_catalog(mut self) -> Self {
self.catalog_source = CatalogSource::ExplicitProvider(Mutex::new(()));
self.remote_models.get_mut().models.clear();
self
}
}
impl StaticModelsManager {
@@ -396,7 +432,7 @@ impl ModelsManager for OpenAiModelsManager {
if entry.identity.is_some() && entry.identity == self.endpoint_client.identity() {
entry.models.clone()
} else {
load_remote_models_from_file().unwrap_or_default()
self.catalog_source.fallback_models().unwrap_or_default()
}
})
}
@@ -407,7 +443,7 @@ impl ModelsManager for OpenAiModelsManager {
if entry.identity.is_some() && entry.identity == self.endpoint_client.identity() {
entry.models.clone()
} else {
load_remote_models_from_file().unwrap_or_default()
self.catalog_source.fallback_models().unwrap_or_default()
},
)
}
@@ -416,6 +452,27 @@ impl ModelsManager for OpenAiModelsManager {
self.auth_manager.as_deref()
}
#[tracing::instrument(skip_all, fields(model))]
fn get_model_info<'a>(
&'a self,
model: &'a str,
config: &'a ModelsManagerConfig,
) -> ModelsManagerFuture<'a, ModelInfo> {
Box::pin(async move {
let models = self.get_remote_models().await;
match &self.catalog_source {
CatalogSource::Default => {
construct_model_info_from_candidates(model, &models, config)
}
CatalogSource::ExplicitProvider(_) => construct_model_info(
model,
models.into_iter().find(|candidate| candidate.slug == model),
config,
),
}
})
}
fn list_collaboration_modes(&self) -> Vec<CollaborationModeMask> {
builtin_collaboration_mode_presets()
}
@@ -451,6 +508,7 @@ impl OpenAiModelsManager {
}
async fn refresh_if_new_etag(&self, etag: String, http_client_factory: HttpClientFactory) {
let refresh_guard = self.catalog_source.refresh_lock().await;
let (identity, current_etag) = {
let entry = self.remote_models.read().await;
(entry.identity.clone(), entry.etag.clone())
@@ -468,6 +526,7 @@ impl OpenAiModelsManager {
}
return;
}
drop(refresh_guard);
if let Err(err) = self
.refresh_available_models(RefreshStrategy::Online, &http_client_factory)
.await
@@ -482,6 +541,7 @@ impl OpenAiModelsManager {
refresh_strategy: RefreshStrategy,
http_client_factory: &HttpClientFactory,
) -> CoreResult<()> {
let _refresh_guard = self.catalog_source.refresh_lock().await;
// API-key discovery must be enabled and supported before reusing a remote catalog.
// Otherwise even a matching cache from an earlier run would bypass bundled-only behavior.
// Command-auth providers retain their existing discovery behavior.
@@ -521,14 +581,54 @@ impl OpenAiModelsManager {
http_client_factory: &HttpClientFactory,
) -> CoreResult<()> {
let client_version = crate::client_version_to_whole();
let request_identity = self.endpoint_client.identity();
let ModelsEndpointResponse {
models,
etag,
identity,
} = self
} = match self
.endpoint_client
.list_models(&client_version, http_client_factory.clone())
.await?;
.await
{
Ok(response) => response,
Err(error) => {
if matches!(&self.catalog_source, CatalogSource::ExplicitProvider(_)) {
{
let mut current = self.remote_models.write().await;
if request_identity != self.endpoint_client.identity() {
return Err(error);
}
// Keep this failure in memory even if persistent invalidation fails.
current.fetched_at = DateTime::<Utc>::MIN_UTC;
current.models.clear();
current.etag = None;
current.identity.clone_from(&request_identity);
}
if let Some(identity) = request_identity
&& let Some(cache) = self.cache.as_ref()
{
let invalidation = async {
if let Some(mut entry) = cache.load(&client_version).await?
&& entry.identity.as_deref() == Some(&identity)
&& entry.client_version.as_deref() == Some(&client_version)
{
// Preserve backend lookup keys, but force a cache miss after restart.
entry.fetched_at = DateTime::<Utc>::MIN_UTC;
entry.etag = None;
entry.models.clear();
cache.store(&entry).await?;
}
Ok::<_, crate::cache::ModelsCacheError>(())
};
if let Err(err) = invalidation.await {
error!("failed to invalidate models cache: {err}");
}
}
}
return Err(error);
}
};
if Some(&identity) != self.endpoint_client.identity().as_ref() {
return Ok(());
}
@@ -574,7 +674,6 @@ impl OpenAiModelsManager {
if entry.identity != self.endpoint_client.identity() {
return false;
}
// Visible ChatGPT and OpenAI API-key catalogs are authoritative.
let remote_only = entry
.models
.iter()
@@ -585,8 +684,7 @@ impl OpenAiModelsManager {
.auth_mode()
.is_some_and(AuthMode::has_chatgpt_account)
}));
if !remote_only {
let mut models = load_remote_models_from_file().unwrap_or_default();
if !remote_only && let Some(mut models) = self.catalog_source.fallback_models() {
for model in entry.models {
if let Some(index) = models
.iter()
@@ -615,6 +713,15 @@ impl OpenAiModelsManager {
let Some(identity) = self.endpoint_client.identity() else {
return false;
};
{
let current = self.remote_models.read().await;
// A failed fetch must not be replaced by stale cache data even if invalidation failed.
if current.fetched_at == DateTime::<Utc>::MIN_UTC
&& current.identity.as_ref() == Some(&identity)
{
return false;
}
}
let cache_entry = match cache.load(&client_version).await {
Ok(Some(cache_entry)) => cache_entry,
Ok(None) => {
@@ -626,6 +733,9 @@ impl OpenAiModelsManager {
return false;
}
};
if cache_entry.fetched_at == DateTime::<Utc>::MIN_UTC {
return false;
}
if cache_entry.client_version.as_deref() != Some(client_version.as_str()) {
info!(
expected_version = client_version,
@@ -788,6 +898,14 @@ pub(crate) fn construct_model_info_from_candidates(
// retry for namespaced slugs like `custom/gpt-5.3-codex`.
let remote = find_model_by_longest_prefix(model, candidates)
.or_else(|| find_model_by_namespaced_suffix(model, candidates));
construct_model_info(model, remote, config)
}
fn construct_model_info(
model: &str,
remote: Option<ModelInfo>,
config: &ModelsManagerConfig,
) -> ModelInfo {
let model_info = if let Some(remote) = remote {
ModelInfo {
slug: model.to_string(),