Skip to content

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.md
index 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 Anthropic
Messages 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:
```mermaid
flowchart LR
ClaudeCode[Claude Code CLI and Extensions] --> ProxyAPI[FastAPI Proxy]
- Codex[Codex CLI and Extensions] --> ProxyAPI
+ Codex[Codex CLI, IDE, and App] --> ProxyAPI
Pi[Pi Coding Agent] --> ProxyAPI
AdminUI[Local Admin UI] --> ProxyAPI
Bots[Discord or Telegram Bots] --> Messaging[Messaging Bridge]
@@ -301,8 +301,11 @@ Settings-configured providers and currently connected accounts contribute to
the same availability set. Account connect/disconnect performs a targeted model
refresh or eviction; it does not mutate settings or replace a provider
generation.
-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 provider
generation, 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's
native `/model` picker lists FCC provider slugs. Catalog generation is
fail-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.md
index 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.toml
index 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.py
index 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, A
return {"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:
+ pass
catalog_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 True
def _catalog_candidates(
diff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.py
index 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_provider
from .application import ApplicationRuntime, RestartCallback
from .asgi import RuntimeASGIApp
+from .codex_catalog import CodexModelCatalogPublisher
from .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.py
new file mode 100644
index 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.py
index 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 asyncio
from collections.abc import Callable, Iterable
from dataclasses import dataclass, field
+from typing import Protocol
from loguru import logger
@@ -11,6 +12,7 @@ from free_claude_code.application.model_metadata import (
ProviderModelInfo,
ProviderModelRefreshResult,
)
+from free_claude_code.application.ports import RequestRuntimePort
from free_claude_code.config.settings import Settings
from free_claude_code.core.trace import trace_event
from 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_factory
self._connected_provider_ids = connected_provider_ids
+ self._model_catalog_publisher = model_catalog_publisher
self._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 result
finally:
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 result
def _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 = True
self._retired[previous.generation_id] = previous
self._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 result
finally:
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.py
index 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 ProviderModelInfo
from free_claude_code.config.settings import Settings
from free_claude_code.messaging.transcription import TranscriptionService
from 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.py
index 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.stderr
assert "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.py
new file mode 100644
index 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.py
index 335da953..13c0eb0e 100644
--- a/tests/runtime/test_provider_manager.py
+++ b/tests/runtime/test_provider_manager.py
@@ -6,6 +6,7 @@ import pytest
from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.application.ports import RequestRuntimePort
from free_claude_code.config.settings import Settings
from free_claude_code.providers.base import BaseProvider
from 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.asyncio
async def test_replacement_keeps_leased_generation_open_until_final_release() -> None:
factory = RuntimeFactory()
diff --git a/uv.lock b/uv.lock
index 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" },