Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Add Codex App model catalog support (#1297)
Ali Khokharc36c97f8a412
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 54e1dadc..a12ffa8d 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -12,8 +12,8 @@ and how contributors should extend it.Free Claude Code is a local proxy for agent clients. It accepts AnthropicMessages traffic from Claude Code and Pi clients and OpenAI Responses traffic-from Codex clients, routes the request to a configured upstream provider, and-preserves the wire protocol expected by the caller.+from Codex CLI, IDE, and App clients, routes the request to a configured+upstream provider, and preserves the wire protocol expected by the caller.There are three runtime surfaces:@@ -27,7 +27,7 @@ There are three runtime surfaces:```mermaidflowchart LRClaudeCode[Claude Code CLI and Extensions] --> ProxyAPI[FastAPI Proxy]- Codex[Codex CLI and Extensions] --> ProxyAPI+ Codex[Codex CLI, IDE, and App] --> ProxyAPIPi[Pi Coding Agent] --> ProxyAPIAdminUI[Local Admin UI] --> ProxyAPIBots[Discord or Telegram Bots] --> Messaging[Messaging Bridge]@@ -301,8 +301,11 @@ Settings-configured providers and currently connected accounts contribute tothe same availability set. Account connect/disconnect performs a targeted modelrefresh or eviction; it does not mutate settings or replace a providergeneration.-This keeps the server model inventory stable without extra synchronization;-Claude clients may independently retain the list they fetched at startup.+Runtime integrations may observe those lifecycle events through one neutral+catalog publisher supplied by the composition root. Publication is fail-open+and occurs only after settings or cache changes; provider adapters remain the+sole owners of upstream discovery. Claude and Codex clients may independently+retain the model list they loaded at startup.## Configuration Model@@ -539,11 +542,26 @@ translate reasoning. The catalog is not part of an individual providergeneration, so a hot replacement does not erase the last useful model list.Discovery failures retain prior entries.-Codex-specific model picker shaping stays out of this route. `fcc-codex` fetches-the same `/v1/models` response at launch, converts FCC gateway IDs into-provider-selectable Codex slugs, writes `~/.fcc/codex-model-catalog.json`, and-passes it as `model_catalog_json`. Codex users open the native picker with-`/model`; FCC does not implement a proxy-level `/models` alias.+Codex-specific model picker shaping stays out of this route.+[runtime/codex_catalog.py](src/free_claude_code/runtime/codex_catalog.py) is the+composition bridge: it asks this route's pure builder for the exact application+inventory, passes that response to the existing Codex adapter, and writes+`~/.fcc/codex-model-catalog.json` without making a loopback HTTP request.+`ProviderRuntimeManager` invokes the bridge after authoritative settings,+discovery, provider-test, or connected-account changes. Startup creates a+missing file after routed-provider warming but preserves an existing+last-known-good catalog until the background discovery pass publishes the+complete accumulated inventory. Writes are atomic and identical bytes are not+rewritten. Projection or filesystem failures emit only a concise warning and do+not fail server startup, Admin operations, discovery, or inference. Shutdown+never publishes the cleared in-memory cache.++The Codex App reads `model_catalog_json` at startup, so it must restart to see a+later catalog publication. `fcc-codex` remains an additional launch-time+synchronizer: it fetches the same `/v1/models` response, uses the same adapter+and writer, and passes the path as an ephemeral override. Codex users open the+native picker with `/model`; FCC does not implement a proxy-level `/models`+alias.## Provider Architecture@@ -1047,6 +1065,8 @@ instead of stopping at its login gate.`model_catalog_json` file under `~/.fcc/`, and injects that path so Codex'snative `/model` picker lists FCC provider slugs. Catalog generation isfail-open: launch continues with a warning if the catalog cannot be prepared.+- The server lifecycle independently keeps that same file synchronized for+ Codex App and IDE processes that are not launched through `fcc-codex`.- Catalog discovery and inference both authenticate with HTTP bearer authorization.- It stores the proxy auth token in `FCC_CODEX_API_KEY` for Codex's provider`env_key` to read. This process-local variable is a client credential carrier,diff --git a/README.md b/README.mdindex b5d243c1..c819ce04 100644--- a/README.md+++ b/README.md@@ -300,6 +300,43 @@ Match the port and authentication token to the Admin UI, then reload the extensi</details>+<details>+<summary><strong>Codex App</strong></summary>++Start FCC, then add its provider and generated model catalog to your user-level Codex configuration.++**Windows** — edit `%USERPROFILE%\.codex\config.toml` and replace `YOUR_USERNAME`:++```toml+model_provider = "fcc"+model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"+model_catalog_json = "C:/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"++[model_providers.fcc]+name = "Free Claude Code"+base_url = "http://127.0.0.1:8082/v1"+http_headers = { Authorization = "Bearer freecc" }+wire_api = "responses"+```++**macOS** — edit `~/.codex/config.toml` and replace `YOUR_USERNAME`:++```toml+model_provider = "fcc"+model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"+model_catalog_json = "/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"++[model_providers.fcc]+name = "Free Claude Code"+base_url = "http://127.0.0.1:8082/v1"+http_headers = { Authorization = "Bearer freecc" }+wire_api = "responses"+```++Match the model, port, and bearer token to the Admin UI. Restart the Codex App after setup or model changes, then use its model picker to select any FCC provider/model slug.++</details>+<details><summary><strong>Codex in VS Code</strong></summary>diff --git a/pyproject.toml b/pyproject.tomlindex b045e4bd..5e7f5caf 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "4.15.1"+version = "4.16.0"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/src/free_claude_code/cli/launchers/codex_model_catalog.py b/src/free_claude_code/cli/launchers/codex_model_catalog.pyindex 32504d87..129b025a 100644--- a/src/free_claude_code/cli/launchers/codex_model_catalog.py+++ b/src/free_claude_code/cli/launchers/codex_model_catalog.py@@ -67,16 +67,24 @@ def build_codex_model_catalog(models_response: Mapping[str, Any]) -> dict[str, Areturn {"models": models}-def write_codex_model_catalog(catalog_path: Path, catalog: Mapping[str, Any]) -> None:- """Atomically write a Codex model catalog JSON file."""+def write_codex_model_catalog(catalog_path: Path, catalog: Mapping[str, Any]) -> bool:+ """Atomically write changed Codex model catalog JSON."""++ content = (json.dumps(catalog, ensure_ascii=True, indent=2) + "\n").encode()+ try:+ if catalog_path.read_bytes() == content:+ return False+ except FileNotFoundError:+ passcatalog_path.parent.mkdir(parents=True, exist_ok=True)temp_path = catalog_path.with_name(f".{catalog_path.name}.{uuid.uuid4().hex}.tmp")- temp_path.write_text(- json.dumps(catalog, ensure_ascii=True, indent=2) + "\n",- encoding="utf-8",- )- temp_path.replace(catalog_path)+ try:+ temp_path.write_bytes(content)+ temp_path.replace(catalog_path)+ finally:+ temp_path.unlink(missing_ok=True)+ return Truedef _catalog_candidates(diff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.pyindex 220c1261..7d86a260 100644--- a/src/free_claude_code/runtime/bootstrap.py+++ b/src/free_claude_code/runtime/bootstrap.py@@ -23,6 +23,7 @@ from free_claude_code.providers.runtime.factory import create_providerfrom .application import ApplicationRuntime, RestartCallbackfrom .asgi import RuntimeASGIApp+from .codex_catalog import CodexModelCatalogPublisherfrom .provider_manager import ProviderRuntimeManager@@ -51,6 +52,7 @@ def build_asgi_app(settings,runtime_factory=runtime_factory,connected_provider_ids=openai_auth.connected_provider_ids,+ model_catalog_publisher=CodexModelCatalogPublisher(),)runtime = ApplicationRuntime(provider_manager,diff --git a/src/free_claude_code/runtime/codex_catalog.py b/src/free_claude_code/runtime/codex_catalog.pynew file mode 100644index 00000000..92b498b0--- /dev/null+++ b/src/free_claude_code/runtime/codex_catalog.py@@ -0,0 +1,49 @@+"""Publish the application model inventory for Codex clients."""++from pathlib import Path++from free_claude_code.api.model_catalog import build_models_list_response+from free_claude_code.application.ports import RequestRuntimePort+from free_claude_code.cli.launchers.codex_model_catalog import (+ build_codex_model_catalog,+ write_codex_model_catalog,+)+from free_claude_code.config.paths import codex_model_catalog_path+++class CodexModelCatalogPublisher:+ """Own synchronization of the stable Codex model catalog file."""++ def __init__(self, catalog_path: Path | None = None) -> None:+ self._catalog_path = catalog_path++ def ensure_exists(self, runtime: RequestRuntimePort) -> None:+ """Publish a startup catalog only when no prior catalog exists."""++ catalog_path = self._resolved_catalog_path()+ if catalog_path.exists():+ return+ self._publish(runtime, catalog_path)++ def publish(self, runtime: RequestRuntimePort) -> None:+ """Publish the complete current application model inventory."""++ self._publish(runtime, self._resolved_catalog_path())++ def _publish(+ self,+ runtime: RequestRuntimePort,+ catalog_path: Path,+ ) -> None:+ models_response = build_models_list_response(+ runtime.current_settings(),+ runtime,+ )+ catalog = build_codex_model_catalog(models_response.model_dump())+ models = catalog.get("models")+ if not isinstance(models, list) or not models:+ raise ValueError("Codex model catalog contains no routable models.")+ write_codex_model_catalog(catalog_path, catalog)++ def _resolved_catalog_path(self) -> Path:+ return self._catalog_path or codex_model_catalog_path()diff --git a/src/free_claude_code/runtime/provider_manager.py b/src/free_claude_code/runtime/provider_manager.pyindex f0fe0248..8afee284 100644--- a/src/free_claude_code/runtime/provider_manager.py+++ b/src/free_claude_code/runtime/provider_manager.py@@ -3,6 +3,7 @@import asynciofrom collections.abc import Callable, Iterablefrom dataclasses import dataclass, field+from typing import Protocolfrom loguru import logger@@ -11,6 +12,7 @@ from free_claude_code.application.model_metadata import (ProviderModelInfo,ProviderModelRefreshResult,)+from free_claude_code.application.ports import RequestRuntimePortfrom free_claude_code.config.settings import Settingsfrom free_claude_code.core.trace import trace_eventfrom free_claude_code.providers.base import BaseProvider@@ -26,6 +28,14 @@ ConnectedProviderIds = Callable[[], tuple[str, ...]]CommitConfig = Callable[[], None]+class ModelCatalogPublisher(Protocol):+ """Synchronize an external view of the application model inventory."""++ def ensure_exists(self, runtime: RequestRuntimePort) -> None: ...++ def publish(self, runtime: RequestRuntimePort) -> None: ...++@dataclass(slots=True, eq=False)class _ProviderGeneration:generation_id: int@@ -89,9 +99,11 @@ class ProviderRuntimeManager:*,runtime_factory: ProviderRuntimeFactory = ProviderRuntime,connected_provider_ids: ConnectedProviderIds = tuple,+ model_catalog_publisher: ModelCatalogPublisher | None = None,) -> None:self._runtime_factory = runtime_factoryself._connected_provider_ids = connected_provider_ids+ self._model_catalog_publisher = model_catalog_publisherself._replace_lock = asyncio.Lock()self._close_lock = asyncio.Lock()self._model_cache = ProviderModelCache(@@ -145,6 +157,7 @@ class ProviderRuntimeManager:model_infos: Iterable[ProviderModelInfo],) -> None:self._model_cache.cache_model_infos(provider_id, model_infos)+ self._publish_model_catalog()async def warm_referenced_model_cache(self) -> ProviderModelRefreshResult:"""Warm routed provider catalogs before clients perform model discovery."""@@ -156,7 +169,9 @@ class ProviderRuntimeManager:self._model_cache,self._connected_provider_ids(),)- return await discovery.warm_referenced_model_cache()+ result = await discovery.warm_referenced_model_cache()+ self._ensure_model_catalog()+ return resultfinally:await lease.release()@@ -189,6 +204,7 @@ class ProviderRuntimeManager:raise ApplicationUnavailableError("Provider runtime is shutting down.")if not connected:self._model_cache.remove_provider(provider_id)+ self._publish_model_catalog()return ProviderModelRefreshResult()self._model_cache.add_provider(provider_id)discovery = ProviderModelDiscovery(@@ -197,7 +213,9 @@ class ProviderRuntimeManager:self._model_cache,self._connected_provider_ids(),)- return await discovery.refresh_provider(provider_id)+ result = await discovery.refresh_provider(provider_id)+ self._publish_model_catalog()+ return resultdef _synchronize_model_cache_scope(self) -> None:"""Drop metadata whose settings or connected account is no longer usable."""@@ -254,6 +272,7 @@ class ProviderRuntimeManager:settings, self._connected_provider_ids()))+ self._publish_model_catalog()previous.retired = Trueself._retired[previous.generation_id] = previousself._trace_published(candidate, previous=previous, reason=reason)@@ -323,10 +342,36 @@ class ProviderRuntimeManager:self._model_cache,self._connected_provider_ids(),)- return await discovery.refresh_model_list_cache(only_missing=only_missing)+ result = await discovery.refresh_model_list_cache(only_missing=only_missing)+ self._publish_model_catalog()+ return resultfinally:await self._release(generation)+ def _ensure_model_catalog(self) -> None:+ publisher = self._model_catalog_publisher+ if publisher is None:+ return+ self._run_model_catalog_publication(publisher.ensure_exists)++ def _publish_model_catalog(self) -> None:+ publisher = self._model_catalog_publisher+ if publisher is None:+ return+ self._run_model_catalog_publication(publisher.publish)++ def _run_model_catalog_publication(+ self,+ publication: Callable[[RequestRuntimePort], None],+ ) -> None:+ try:+ publication(self)+ except Exception as exc:+ logger.warning(+ "Model catalog publication failed: exc_type={}",+ type(exc).__name__,+ )+async def _refresh_generation_in_background(self,generation: _ProviderGeneration,diff --git a/tests/api/test_app_lifespan_and_errors.py b/tests/api/test_app_lifespan_and_errors.pyindex baf668fa..3f65aff9 100644--- a/tests/api/test_app_lifespan_and_errors.py+++ b/tests/api/test_app_lifespan_and_errors.py@@ -11,6 +11,7 @@ from free_claude_code.application.errors import (ApplicationUnavailableError,InvalidRequestError,)+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.settings import Settingsfrom free_claude_code.messaging.transcription import TranscriptionServicefrom free_claude_code.providers.nvidia_nim.client import NvidiaNimProvider@@ -335,6 +336,28 @@ def test_bootstrap_configures_default_log_and_publishes_only_services(tmp_path):assert set(api_app.state._state) == {"services"}+def test_bootstrap_wires_the_codex_catalog_publisher() -> None:+ publisher = MagicMock()++ with (+ patch("free_claude_code.runtime.bootstrap.configure_logging"),+ patch(+ "free_claude_code.runtime.bootstrap.CodexModelCatalogPublisher",+ return_value=publisher,+ ) as publisher_type,+ ):+ asgi_app = build_asgi_app(_settings())++ manager = asgi_app.runtime.provider_manager+ manager.cache_model_infos(+ "nvidia_nim",+ {ProviderModelInfo("published-model")},+ )++ publisher_type.assert_called_once_with()+ publisher.publish.assert_called_once_with(manager)++def test_bootstrap_honors_process_log_file_override(monkeypatch, tmp_path):log_path = tmp_path / "custom.log"monkeypatch.setenv("LOG_FILE", str(log_path))diff --git a/tests/cli/test_codex_model_catalog.py b/tests/cli/test_codex_model_catalog.pyindex d23eaeb7..c8918e21 100644--- a/tests/cli/test_codex_model_catalog.py+++ b/tests/cli/test_codex_model_catalog.py@@ -153,6 +153,23 @@ def test_generated_catalog_schema_is_accepted_by_installed_codex()codex_home = tmp_path / "codex-home"codex_home.mkdir()+ (codex_home / "config.toml").write_text(+ "\n".join(+ (+ 'model_provider = "fcc"',+ 'model = "nvidia_nim/test-model"',+ f"model_catalog_json = {json.dumps(str(catalog_path))}",+ "",+ "[model_providers.fcc]",+ 'name = "Free Claude Code"',+ 'base_url = "http://127.0.0.1:8082/v1"',+ 'http_headers = { Authorization = "Bearer freecc" }',+ 'wire_api = "responses"',+ "",+ )+ ),+ encoding="utf-8",+ )codex_env = os.environ.copy()for key in ("CODEX_THREAD_ID",@@ -164,13 +181,7 @@ def test_generated_catalog_schema_is_accepted_by_installed_codex(codex_env["CODEX_HOME"] = str(codex_home)result = subprocess.run(- [- codex_binary,- "debug",- "models",- "-c",- f"model_catalog_json={json.dumps(str(catalog_path))}",- ],+ [codex_binary, "debug", "models"],capture_output=True,check=False,encoding="utf-8",@@ -182,3 +193,43 @@ def test_generated_catalog_schema_is_accepted_by_installed_codex(assert result.returncode == 0, result.stderrassert "nvidia_nim/test-model" in result.stdout+++def test_catalog_writer_skips_identical_content_and_replaces_changes(+ tmp_path: Path,+) -> None:+ catalog_path = tmp_path / "codex-model-catalog.json"+ first = build_codex_model_catalog(_models_payload("anthropic/nvidia_nim/first"))+ second = build_codex_model_catalog(_models_payload("anthropic/nvidia_nim/second"))++ assert write_codex_model_catalog(catalog_path, first) is True+ assert write_codex_model_catalog(catalog_path, first) is False+ assert list(tmp_path.glob(".codex-model-catalog.json.*.tmp")) == []++ assert write_codex_model_catalog(catalog_path, second) is True+ assert json.loads(catalog_path.read_text(encoding="utf-8")) == second+ assert list(tmp_path.glob(".codex-model-catalog.json.*.tmp")) == []+++def test_catalog_writer_cleans_temporary_file_after_replace_failure(+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+) -> None:+ catalog_path = tmp_path / "codex-model-catalog.json"+ catalog_path.write_text("previous\n", encoding="utf-8")++ def fail_replace(_source: Path, _destination: Path) -> Path:+ raise PermissionError("destination is locked")++ monkeypatch.setattr(Path, "replace", fail_replace)++ with pytest.raises(PermissionError, match="locked"):+ write_codex_model_catalog(+ catalog_path,+ build_codex_model_catalog(+ _models_payload("anthropic/nvidia_nim/replacement")+ ),+ )++ assert catalog_path.read_text(encoding="utf-8") == "previous\n"+ assert list(tmp_path.glob(".codex-model-catalog.json.*.tmp")) == []diff --git a/tests/runtime/test_codex_catalog.py b/tests/runtime/test_codex_catalog.pynew file mode 100644index 00000000..9b3d6bd5--- /dev/null+++ b/tests/runtime/test_codex_catalog.py@@ -0,0 +1,100 @@+import json+from pathlib import Path+from unittest.mock import patch++import pytest++from free_claude_code.application.model_metadata import ProviderModelInfo+from free_claude_code.application.ports import (+ RequestRuntimeLease,+ RequestRuntimePort,+)+from free_claude_code.config.settings import Settings+from free_claude_code.runtime.codex_catalog import CodexModelCatalogPublisher+++class FakeRequestRuntime(RequestRuntimePort):+ def __init__(+ self,+ *,+ settings: Settings,+ cached_infos: tuple[ProviderModelInfo, ...] = (),+ ) -> None:+ self._settings = settings+ self._cached_infos = cached_infos++ async def acquire(self) -> RequestRuntimeLease:+ raise AssertionError("Catalog publication must not acquire a provider lease.")++ def current_settings(self) -> Settings:+ return self._settings++ def cached_model_supports_thinking(+ self, provider_id: str, model_id: str+ ) -> bool | None:+ return None++ def cached_prefixed_model_infos(self) -> tuple[ProviderModelInfo, ...]:+ return self._cached_infos+++def _runtime() -> FakeRequestRuntime:+ settings = Settings().model_copy(update={"model": "nvidia_nim/configured"})+ return FakeRequestRuntime(+ settings=settings,+ cached_infos=(ProviderModelInfo("open_router/discovered"),),+ )+++def _catalog_slugs(path: Path) -> list[str]:+ payload = json.loads(path.read_text(encoding="utf-8"))+ return [model["slug"] for model in payload["models"]]+++def test_publisher_projects_the_application_catalog_without_compatibility_ids(+ tmp_path: Path,+) -> None:+ catalog_path = tmp_path / "codex-model-catalog.json"+ publisher = CodexModelCatalogPublisher(catalog_path)++ publisher.publish(_runtime())++ assert _catalog_slugs(catalog_path) == [+ "nvidia_nim/configured",+ "open_router/discovered",+ ]+++def test_startup_publication_creates_missing_catalog_and_preserves_existing(+ tmp_path: Path,+) -> None:+ catalog_path = tmp_path / "codex-model-catalog.json"+ publisher = CodexModelCatalogPublisher(catalog_path)++ publisher.ensure_exists(_runtime())+ assert _catalog_slugs(catalog_path) == [+ "nvidia_nim/configured",+ "open_router/discovered",+ ]++ catalog_path.write_text("complete prior catalog\n", encoding="utf-8")+ publisher.ensure_exists(_runtime())++ assert catalog_path.read_text(encoding="utf-8") == "complete prior catalog\n"+++def test_empty_projection_preserves_existing_catalog(tmp_path: Path) -> None:+ catalog_path = tmp_path / "codex-model-catalog.json"+ catalog_path.write_text("last known good\n", encoding="utf-8")+ publisher = CodexModelCatalogPublisher(catalog_path)++ with (+ patch(+ "free_claude_code.runtime.codex_catalog.build_codex_model_catalog",+ return_value={"models": []},+ ),+ pytest.raises(ValueError, match="no routable models"),+ ):+ publisher.publish(_runtime())++ assert catalog_path.read_text(encoding="utf-8") == "last known good\n"diff --git a/tests/runtime/test_provider_manager.py b/tests/runtime/test_provider_manager.pyindex 335da953..13c0eb0e 100644--- a/tests/runtime/test_provider_manager.py+++ b/tests/runtime/test_provider_manager.py@@ -6,6 +6,7 @@ import pytestfrom free_claude_code.application.errors import ApplicationUnavailableErrorfrom free_claude_code.application.model_metadata import ProviderModelInfo+from free_claude_code.application.ports import RequestRuntimePortfrom free_claude_code.config.settings import Settingsfrom free_claude_code.providers.base import BaseProviderfrom free_claude_code.providers.nvidia_nim import NvidiaNimProvider@@ -52,6 +53,27 @@ class RuntimeFactory:return runtime+class RecordingModelCatalogPublisher:+ def __init__(self) -> None:+ self.events: list[str] = []+ self.snapshots: list[tuple[str, tuple[str, ...]]] = []++ def ensure_exists(self, runtime: RequestRuntimePort) -> None:+ self._record("ensure_exists", runtime)++ def publish(self, runtime: RequestRuntimePort) -> None:+ self._record("publish", runtime)++ def _record(self, event: str, runtime: RequestRuntimePort) -> None:+ self.events.append(event)+ self.snapshots.append(+ (+ runtime.current_settings().model,+ tuple(info.model_id for info in runtime.cached_prefixed_model_infos()),+ )+ )++def _settings(model: str) -> Settings:return Settings().model_copy(update={"model": model})@@ -108,6 +130,146 @@ async def test_connected_provider_refresh_and_eviction_are_targeted() -> None:await manager.close()+async def test_catalog_publication_tracks_warm_refresh_and_direct_cache() -> None:+ factory = RuntimeFactory()+ publisher = RecordingModelCatalogPublisher()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ model_catalog_publisher=publisher,+ )+ factory.runtimes[0].provider.list_model_infos = AsyncMock(+ return_value=frozenset({ProviderModelInfo("warm-model")})+ )++ await manager.warm_referenced_model_cache()+ manager.start_model_list_refresh()+ refresh_task = manager._refresh_task+ assert refresh_task is not None+ await refresh_task+ manager.cache_model_infos(+ "nvidia_nim",+ {ProviderModelInfo("tested-model")},+ )++ assert publisher.events == ["ensure_exists", "publish", "publish"]+ assert publisher.snapshots == [+ ("nvidia_nim/one", ("nvidia_nim/warm-model",)),+ ("nvidia_nim/one", ("nvidia_nim/warm-model",)),+ ("nvidia_nim/one", ("nvidia_nim/tested-model",)),+ ]++ await manager.close()+ assert publisher.events == ["ensure_exists", "publish", "publish"]+++async def test_failed_startup_discovery_still_ensures_a_fresh_catalog() -> None:+ factory = RuntimeFactory()+ publisher = RecordingModelCatalogPublisher()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/configured"),+ runtime_factory=factory,+ model_catalog_publisher=publisher,+ )+ factory.runtimes[0].provider.list_model_infos = AsyncMock(+ side_effect=RuntimeError("upstream unavailable")+ )++ result = await manager.warm_referenced_model_cache()++ assert result.failed_provider_ids == ("nvidia_nim",)+ assert publisher.events == ["ensure_exists"]+ assert publisher.snapshots == [("nvidia_nim/configured", ())]+ await manager.close()+++async def test_catalog_publication_tracks_connected_account_changes() -> None:+ factory = RuntimeFactory()+ publisher = RecordingModelCatalogPublisher()+ connected: set[str] = set()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ connected_provider_ids=lambda: tuple(connected),+ model_catalog_publisher=publisher,+ )+ factory.runtimes[0].provider.list_model_infos = AsyncMock(+ return_value=frozenset({ProviderModelInfo("gpt-connected")})+ )++ connected.add("openai")+ await manager.connected_provider_changed("openai", connected=True)+ connected.clear()+ await manager.connected_provider_changed("openai", connected=False)++ assert publisher.events == ["publish", "publish"]+ assert publisher.snapshots == [+ ("nvidia_nim/one", ("openai/gpt-connected",)),+ ("nvidia_nim/one", ()),+ ]+ await manager.close()+++async def test_catalog_publication_tracks_replacement_and_its_refresh() -> None:+ factory = RuntimeFactory()+ publisher = RecordingModelCatalogPublisher()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ model_catalog_publisher=publisher,+ )++ await manager.replace(+ _settings("nvidia_nim/two"),+ commit=lambda: None,+ )+ refresh_task = manager._refresh_task+ assert refresh_task is not None+ await refresh_task++ assert publisher.events == ["publish", "publish"]+ assert publisher.snapshots == [+ ("nvidia_nim/two", ()),+ ("nvidia_nim/two", ()),+ ]+ await manager.close()+++async def test_catalog_publication_failure_is_warning_only_and_secret_safe() -> None:+ factory = RuntimeFactory()+ secret = "private-catalog-write-detail"+ publisher = MagicMock()+ publisher.ensure_exists.side_effect = PermissionError(secret)+ publisher.publish.side_effect = PermissionError(secret)+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ model_catalog_publisher=publisher,+ )++ with patch("free_claude_code.runtime.provider_manager.logger.warning") as warning:+ await manager.warm_referenced_model_cache()+ manager.cache_model_infos(+ "nvidia_nim",+ {ProviderModelInfo("tested-model")},+ )++ assert warning.call_count == 2+ log_blob = " ".join(+ str(value)+ for call in warning.call_args_list+ for value in (*call.args, *call.kwargs.values())+ )+ assert "PermissionError" in log_blob+ assert secret not in log_blob+ await manager.close()++@pytest.mark.asyncioasync def test_replacement_keeps_leased_generation_open_until_final_release() -> None:factory = RuntimeFactory()diff --git a/uv.lock b/uv.lockindex 24526446..0bfad1ec 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "4.15.1"+version = "4.16.0"source = { editable = "." }dependencies = [{ name = "aiohttp" },