Require models refresh on cli version mismatch (#10414)

codex-rs/core/src/models_manager/cache.rs

@@ -27,7 +27,7 @@ impl ModelsCacheManager {
     }
 
     /// Attempt to load a fresh cache entry. Returns `None` if the cache doesn't exist or is stale.
-    pub(crate) async fn load_fresh(&self) -> Option<ModelsCache> {
+    pub(crate) async fn load_fresh(&self, expected_version: &str) -> Option<ModelsCache> {
         let cache = match self.load().await {
             Ok(cache) => cache?,
             Err(err) => {
@@ -35,6 +35,9 @@ impl ModelsCacheManager {
                 return None;
             }
         };
+        if cache.client_version.as_deref() != Some(expected_version) {
+            return None;
+        }
         if !cache.is_fresh(self.cache_ttl) {
             return None;
         }
@@ -42,10 +45,16 @@ impl ModelsCacheManager {
     }
 
     /// Persist the cache to disk, creating parent directories as needed.
-    pub(crate) async fn persist_cache(&self, models: &[ModelInfo], etag: Option<String>) {
+    pub(crate) async fn persist_cache(
+        &self,
+        models: &[ModelInfo],
+        etag: Option<String>,
+        client_version: String,
+    ) {
         let cache = ModelsCache {
             fetched_at: Utc::now(),
             etag,
+            client_version: Some(client_version),
             models: models.to_vec(),
         };
         if let Err(err) = self.save_internal(&cache).await {
@@ -103,6 +112,20 @@ impl ModelsCacheManager {
         f(&mut cache.fetched_at);
         self.save_internal(&cache).await
     }
+
+    #[cfg(test)]
+    /// Mutate the full cache contents for testing.
+    pub(crate) async fn mutate_cache_for_test<F>(&self, f: F) -> io::Result<()>
+    where
+        F: FnOnce(&mut ModelsCache),
+    {
+        let mut cache = match self.load().await? {
+            Some(cache) => cache,
+            None => return Err(io::Error::new(ErrorKind::NotFound, "cache not found")),
+        };
+        f(&mut cache);
+        self.save_internal(&cache).await
+    }
 }
 
 /// Serialized snapshot of models and metadata cached on disk.
@@ -111,6 +134,8 @@ pub(crate) struct ModelsCache {
     pub(crate) fetched_at: DateTime<Utc>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub(crate) etag: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(crate) client_version: Option<String>,
     pub(crate) models: Vec<ModelInfo>,
 }
 

codex-rs/core/src/models_manager/manager.rs

@@ -210,7 +210,7 @@ impl ModelsManager {
         let transport = ReqwestTransport::new(build_reqwest_client());
         let client = ModelsClient::new(transport, api_provider, api_auth);
 
-        let client_version = format_client_version_to_whole();
+        let client_version = crate::models_manager::client_version_to_whole();
         let (models, etag) = timeout(
             MODELS_REFRESH_TIMEOUT,
             client.list_models(&client_version, HeaderMap::new()),
@@ -221,7 +221,9 @@ impl ModelsManager {
 
         self.apply_remote_models(models.clone()).await;
         *self.etag.write().await = etag.clone();
-        self.cache_manager.persist_cache(&models, etag).await;
+        self.cache_manager
+            .persist_cache(&models, etag, client_version)
+            .await;
         Ok(())
     }
 
@@ -255,7 +257,8 @@ impl ModelsManager {
     async fn try_load_cache(&self) -> bool {
         let _timer =
             codex_otel::start_global_timer("codex.remote_models.load_cache.duration_ms", &[]);
-        let cache = match self.cache_manager.load_fresh().await {
+        let client_version = crate::models_manager::client_version_to_whole();
+        let cache = match self.cache_manager.load_fresh(&client_version).await {
             Some(cache) => cache,
             None => return false,
         };
@@ -350,16 +353,6 @@ impl ModelsManager {
     }
 }
 
-/// Convert a client version string to a whole version string (e.g. "1.2.3-alpha.4" -> "1.2.3")
-fn format_client_version_to_whole() -> String {
-    format!(
-        "{}.{}.{}",
-        env!("CARGO_PKG_VERSION_MAJOR"),
-        env!("CARGO_PKG_VERSION_MINOR"),
-        env!("CARGO_PKG_VERSION_PATCH")
-    )
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -613,6 +606,75 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn refresh_available_models_refetches_when_version_mismatch() {
+        let server = MockServer::start().await;
+        let initial_models = vec![remote_model("old", "Old", 1)];
+        let initial_mock = mount_models_once(
+            &server,
+            ModelsResponse {
+                models: initial_models.clone(),
+            },
+        )
+        .await;
+
+        let codex_home = tempdir().expect("temp dir");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("load default test config");
+        config.features.enable(Feature::RemoteModels);
+        let auth_manager = Arc::new(AuthManager::new(
+            codex_home.path().to_path_buf(),
+            false,
+            AuthCredentialsStoreMode::File,
+        ));
+        let provider = provider_for(server.uri());
+        let manager =
+            ModelsManager::with_provider(codex_home.path().to_path_buf(), auth_manager, provider);
+
+        manager
+            .refresh_available_models(&config, RefreshStrategy::OnlineIfUncached)
+            .await
+            .expect("initial refresh succeeds");
+
+        manager
+            .cache_manager
+            .mutate_cache_for_test(|cache| {
+                let client_version = crate::models_manager::client_version_to_whole();
+                cache.client_version = Some(format!("{client_version}-mismatch"));
+            })
+            .await
+            .expect("cache mutation succeeds");
+
+        let updated_models = vec![remote_model("new", "New", 2)];
+        server.reset().await;
+        let refreshed_mock = mount_models_once(
+            &server,
+            ModelsResponse {
+                models: updated_models.clone(),
+            },
+        )
+        .await;
+
+        manager
+            .refresh_available_models(&config, RefreshStrategy::OnlineIfUncached)
+            .await
+            .expect("second refresh succeeds");
+        assert_models_contain(&manager.get_remote_models(&config).await, &updated_models);
+        assert_eq!(
+            initial_mock.requests().len(),
+            1,
+            "initial refresh should only hit /models once"
+        );
+        assert_eq!(
+            refreshed_mock.requests().len(),
+            1,
+            "version mismatch should fetch /models once"
+        );
+    }
+
     #[tokio::test]
     async fn refresh_available_models_drops_removed_remote_models() {
         let server = MockServer::start().await;

codex-rs/core/src/models_manager/mod.rs

@@ -6,3 +6,13 @@ pub mod model_presets;
 
 #[cfg(any(test, feature = "test-support"))]
 pub use collaboration_mode_presets::test_builtin_collaboration_mode_presets;
+
+/// Convert the client version string to a whole version string (e.g. "1.2.3-alpha.4" -> "1.2.3").
+pub fn client_version_to_whole() -> String {
+    format!(
+        "{}.{}.{}",
+        env!("CARGO_PKG_VERSION_MAJOR"),
+        env!("CARGO_PKG_VERSION_MINOR"),
+        env!("CARGO_PKG_VERSION_PATCH")
+    )
+}