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

Make provider model discovery the sole catalog owner (#1221)

Ali Khokhar1a476562fcd7
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index a02c02ad..4322897c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -491,10 +491,18 @@ request-scoped policy passed to execution.
Provider model discovery and optional thinking metadata live in the
application-level catalog owned by `ProviderRuntimeManager`.
+[providers/runtime/discovery.py](src/free_claude_code/providers/runtime/discovery.py)
+is the sole owner of provider model-list queries and cache population. Startup
+synchronously warms the providers referenced by model routing before clients can
+perform their one-time model fetch, then a background pass fills the remaining
+configured provider catalogs without querying successful warm-ups again.
Discovery is an adapter operation, not an assumption that every upstream has an
OpenAI `/models` route. For example, Vertex translates that operation to
Google's paginated `publishers/google/models` API and converts publisher resource
names into the exact model IDs accepted by its OpenAI-compatible endpoint.
+Catalog contents are discovery metadata, not execution validation; the provider
+request remains authoritative when an upstream accepts a model absent from its
+list or rejects a listed model.
`ProviderModelInfo.supports_thinking` alone owns discovered per-model thinking
support for model-list presentation; it does not select request behavior.
Provider adapters must never branch on upstream model names or versions to
@@ -554,9 +562,9 @@ drain, while new generations and separate server instances never reuse it. Hot
replacement therefore begins with fresh quota and recovery state; an old and new
generation enforce independent budgets while old request leases drain.
Application-level generation publication, request leases, model metadata,
-discovery orchestration, and configured-model validation belong to
-`ProviderRuntimeManager` in the runtime package. This separates a single
-generation's resources from process-lifetime state.
+and discovery orchestration belong to `ProviderRuntimeManager` in the runtime
+package. This separates a single generation's resources from process-lifetime
+state.
[application/model_metadata.py](src/free_claude_code/application/model_metadata.py) owns the immutable
`ProviderModelInfo` value consumed by the application catalog. Provider-specific
diff --git a/pyproject.toml b/pyproject.toml
index 4ff60f60..eaca8340 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.11.5"
+version = "4.11.6"
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/config/model_refs.py b/src/free_claude_code/config/model_refs.py
index 5f76374d..19dc88bf 100644
--- a/src/free_claude_code/config/model_refs.py
+++ b/src/free_claude_code/config/model_refs.py
@@ -6,12 +6,11 @@ from typing import Protocol
@dataclass(frozen=True, slots=True)
class ConfiguredChatModelRef:
- """A unique configured chat model reference and the env keys that set it."""
+ """A unique configured chat model reference."""
model_ref: str
provider_id: str
model_id: str
- sources: tuple[str, ...]
class ChatModelConfig(Protocol):
@@ -37,27 +36,25 @@ def parse_model_name(model_ref: str) -> str:
def configured_chat_model_refs(
settings: ChatModelConfig,
) -> tuple[ConfiguredChatModelRef, ...]:
- """Return unique configured chat provider/model refs with source env keys."""
-
- candidates = (
- ("MODEL", settings.model),
- ("MODEL_FABLE", settings.model_fable),
- ("MODEL_OPUS", settings.model_opus),
- ("MODEL_SONNET", settings.model_sonnet),
- ("MODEL_HAIKU", settings.model_haiku),
+ """Return unique configured chat provider/model refs."""
+
+ model_refs = dict.fromkeys(
+ model_ref
+ for model_ref in (
+ settings.model,
+ settings.model_fable,
+ settings.model_opus,
+ settings.model_sonnet,
+ settings.model_haiku,
+ )
+ if model_ref is not None
)
- sources_by_ref: dict[str, list[str]] = {}
- for source, model_ref in candidates:
- if model_ref is None:
- continue
- sources_by_ref.setdefault(model_ref, []).append(source)
return tuple(
ConfiguredChatModelRef(
model_ref=model_ref,
provider_id=parse_provider_type(model_ref),
model_id=parse_model_name(model_ref),
- sources=tuple(sources),
)
- for model_ref, sources in sources_by_ref.items()
+ for model_ref in model_refs
)
diff --git a/src/free_claude_code/providers/runtime/discovery.py b/src/free_claude_code/providers/runtime/discovery.py
index caf082c8..e08121a1 100644
--- a/src/free_claude_code/providers/runtime/discovery.py
+++ b/src/free_claude_code/providers/runtime/discovery.py
@@ -3,8 +3,10 @@
import asyncio
from collections.abc import Callable
+import httpx
from loguru import logger
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.model_metadata import (
ProviderModelInfo,
ProviderModelRefreshResult,
@@ -12,18 +14,34 @@ from free_claude_code.application.model_metadata import (
from free_claude_code.config.model_refs import configured_chat_model_refs
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.settings import Settings
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.providers.base import BaseProvider
+from free_claude_code.providers.model_listing import ModelListResponseError
from .config import has_provider_configuration
from .model_cache import ProviderModelCache
-from .validation import provider_query_failure_reason
ProviderResolver = Callable[[str], BaseProvider]
-def referenced_provider_ids(settings: Settings) -> frozenset[str]:
- """Return provider ids referenced by configured chat model refs."""
- return frozenset(ref.provider_id for ref in configured_chat_model_refs(settings))
+def _provider_query_failure_reason(exc: BaseException, settings: Settings) -> str:
+ """Return a concise model-list query failure reason for user-facing logs."""
+ if isinstance(exc, ModelListResponseError):
+ return f"malformed model-list response: {exc.message}"
+ if isinstance(exc, httpx.HTTPStatusError):
+ return f"query failure: HTTP {exc.response.status_code}"
+ if isinstance(exc, ApplicationUnavailableError):
+ return f"query failure: {exc.message}"
+ if isinstance(exc, ExecutionFailure) and settings.log_api_error_tracebacks:
+ return f"query failure: {exc.message}"
+ return f"query failure: {type(exc).__name__}"
+
+
+def referenced_provider_ids(settings: Settings) -> tuple[str, ...]:
+ """Return unique provider ids referenced by configured chat models."""
+ return tuple(
+ dict.fromkeys(ref.provider_id for ref in configured_chat_model_refs(settings))
+ )
def model_cache_provider_ids_for_settings(settings: Settings) -> tuple[str, ...]:
@@ -58,6 +76,10 @@ class ProviderModelDiscovery:
self._provider_resolver = provider_resolver
self._model_cache = model_cache
+ async def warm_referenced_model_cache(self) -> ProviderModelRefreshResult:
+ """Synchronously cache model metadata for routed providers."""
+ return await self._refresh_model_infos(referenced_provider_ids(self._settings))
+
async def refresh_model_list_cache(
self, *, only_missing: bool = False
) -> ProviderModelRefreshResult:
@@ -114,5 +136,5 @@ class ProviderModelDiscovery:
logger.warning(
"Provider model discovery skipped: provider={} reason={}",
provider_id,
- provider_query_failure_reason(exc, self._settings),
+ _provider_query_failure_reason(exc, self._settings),
)
diff --git a/src/free_claude_code/providers/runtime/validation.py b/src/free_claude_code/providers/runtime/validation.py
deleted file mode 100644
index ba6a7318..00000000
--- a/src/free_claude_code/providers/runtime/validation.py
+++ /dev/null
@@ -1,122 +0,0 @@
-"""Configured provider model validation."""
-
-import asyncio
-from collections import defaultdict
-from collections.abc import Callable
-
-import httpx
-from loguru import logger
-
-from free_claude_code.application.errors import ApplicationUnavailableError
-from free_claude_code.application.model_metadata import ProviderModelInfo
-from free_claude_code.config.model_refs import (
- ConfiguredChatModelRef,
- configured_chat_model_refs,
-)
-from free_claude_code.config.settings import Settings
-from free_claude_code.core.failures import ExecutionFailure
-from free_claude_code.providers.base import BaseProvider
-from free_claude_code.providers.model_listing import ModelListResponseError
-
-from .model_cache import ProviderModelCache
-
-ProviderResolver = Callable[[str], BaseProvider]
-
-
-def provider_query_failure_reason(exc: BaseException, settings: Settings) -> str:
- """Return a concise model-list query failure reason for user-facing logs."""
- if isinstance(exc, ModelListResponseError):
- return f"malformed model-list response: {exc.message}"
- if isinstance(exc, httpx.HTTPStatusError):
- return f"query failure: HTTP {exc.response.status_code}"
- if isinstance(exc, ApplicationUnavailableError):
- return f"query failure: {exc.message}"
- if isinstance(exc, ExecutionFailure) and settings.log_api_error_tracebacks:
- return f"query failure: {exc.message}"
- return f"query failure: {type(exc).__name__}"
-
-
-class ConfiguredModelValidator:
- """Validate configured provider/model refs against upstream model lists."""
-
- def __init__(
- self,
- settings: Settings,
- provider_resolver: ProviderResolver,
- model_cache: ProviderModelCache,
- ) -> None:
- self._settings = settings
- self._provider_resolver = provider_resolver
- self._model_cache = model_cache
-
- async def validate_configured_models(self) -> None:
- """Fail unless every configured chat model exists upstream."""
- refs = configured_chat_model_refs(self._settings)
- refs_by_provider: dict[str, list[ConfiguredChatModelRef]] = defaultdict(list)
- for ref in refs:
- refs_by_provider[ref.provider_id].append(ref)
-
- failures: list[str] = []
- tasks: dict[str, asyncio.Task[frozenset[ProviderModelInfo]]] = {}
- for provider_id, provider_refs in refs_by_provider.items():
- try:
- provider = self._provider_resolver(provider_id)
- except Exception as exc:
- failures.extend(
- self._format_provider_query_failures(provider_refs, exc)
- )
- continue
- tasks[provider_id] = asyncio.create_task(provider.list_model_infos())
-
- if tasks:
- results = await asyncio.gather(*tasks.values(), return_exceptions=True)
- for (provider_id, _task), result in zip(
- tasks.items(), results, strict=True
- ):
- provider_refs = refs_by_provider[provider_id]
- if isinstance(result, BaseException):
- if isinstance(result, asyncio.CancelledError):
- raise result
- failures.extend(
- self._format_provider_query_failures(provider_refs, result)
- )
- continue
- model_ids = frozenset(info.model_id for info in result)
- self._model_cache.cache_model_infos(provider_id, result)
- failures.extend(
- self._format_missing_model_failure(ref)
- for ref in provider_refs
- if ref.model_id not in model_ids
- )
-
- if failures:
- message = "Configured model validation failed:\n" + "\n".join(
- f"- {failure}" for failure in failures
- )
- raise ApplicationUnavailableError(message)
-
- logger.info(
- "Configured provider models validated: models={} providers={}",
- len(refs),
- len(refs_by_provider),
- )
-
- def _format_provider_query_failures(
- self,
- refs: list[ConfiguredChatModelRef],
- exc: BaseException,
- ) -> list[str]:
- reason = provider_query_failure_reason(exc, self._settings)
- return [self._format_model_validation_failure(ref, reason) for ref in refs]
-
- def _format_missing_model_failure(self, ref: ConfiguredChatModelRef) -> str:
- return self._format_model_validation_failure(ref, "missing model")
-
- @staticmethod
- def _format_model_validation_failure(
- ref: ConfiguredChatModelRef, problem: str
- ) -> str:
- return (
- f"sources={','.join(ref.sources)} provider={ref.provider_id} "
- f"model={ref.model_id} problem={problem}"
- )
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index 9a694b2b..32febe12 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -138,7 +138,7 @@ class ApplicationRuntime:
logger.info("Starting Claude Code Proxy...")
try:
warn_if_process_auth_token(self.settings)
- await self._validate_configured_models_best_effort()
+ await self.provider_manager.warm_referenced_model_cache()
self.provider_manager.start_model_list_refresh()
await self._start_messaging_if_configured()
logging.getLogger("uvicorn.error").info(
@@ -286,17 +286,6 @@ class ApplicationRuntime:
"fields": list(fields),
}
- async def _validate_configured_models_best_effort(self) -> None:
- try:
- await self.provider_manager.validate_configured_models()
- except ApplicationUnavailableError as exc:
- logger.warning(
- "Configured provider model validation failed during startup; "
- "server will continue and requests will fail at provider resolution "
- "when config is incomplete. {}",
- exc.message,
- )
-
async def _start_messaging_if_configured(self) -> None:
try:
components = messaging_platform_factory.create_messaging_components(
diff --git a/src/free_claude_code/runtime/provider_manager.py b/src/free_claude_code/runtime/provider_manager.py
index 790023ca..a312dbf3 100644
--- a/src/free_claude_code/runtime/provider_manager.py
+++ b/src/free_claude_code/runtime/provider_manager.py
@@ -20,7 +20,6 @@ from free_claude_code.providers.runtime.discovery import (
model_cache_provider_ids_for_settings,
)
from free_claude_code.providers.runtime.model_cache import ProviderModelCache
-from free_claude_code.providers.runtime.validation import ConfiguredModelValidator
ProviderRuntimeFactory = Callable[[Settings], ProviderRuntime]
CommitConfig = Callable[[], None]
@@ -141,15 +140,16 @@ class ProviderRuntimeManager:
) -> None:
self._model_cache.cache_model_infos(provider_id, model_infos)
- async def validate_configured_models(self) -> None:
+ async def warm_referenced_model_cache(self) -> ProviderModelRefreshResult:
+ """Warm routed provider catalogs before clients perform model discovery."""
lease = await self.acquire()
try:
- validator = ConfiguredModelValidator(
+ discovery = ProviderModelDiscovery(
lease.settings,
lease.resolve_provider,
self._model_cache,
)
- await validator.validate_configured_models()
+ return await discovery.warm_referenced_model_cache()
finally:
await lease.release()
diff --git a/tests/api/test_app_lifespan_and_errors.py b/tests/api/test_app_lifespan_and_errors.py
index e24897e8..baf668fa 100644
--- a/tests/api/test_app_lifespan_and_errors.py
+++ b/tests/api/test_app_lifespan_and_errors.py
@@ -73,7 +73,11 @@ async def test_runtime_startup_logs_admin_url_without_printed_server_banner():
with (
patch("builtins.print") as printed,
- patch.object(manager, "validate_configured_models", new=AsyncMock()),
+ patch.object(
+ manager,
+ "warm_referenced_model_cache",
+ new=AsyncMock(),
+ ) as warm_cache,
patch.object(manager, "start_model_list_refresh") as start_refresh,
patch.object(manager, "close", new=AsyncMock()),
patch(
@@ -86,6 +90,7 @@ async def test_runtime_startup_logs_admin_url_without_printed_server_banner():
await runtime.close()
printed.assert_not_called()
+ warm_cache.assert_awaited_once()
start_refresh.assert_called_once()
get_logger.assert_any_call("uvicorn.error")
uvicorn_logger.info.assert_called_once_with(
@@ -166,15 +171,29 @@ def test_general_exception_default_log_excludes_exception_message():
@pytest.mark.asyncio
-async def test_model_validation_failure_does_not_block_runtime_startup():
+async def test_runtime_startup_warms_catalog_before_background_refresh():
settings = _settings(messaging_platform="none")
manager = ProviderRuntimeManager(settings)
runtime = ApplicationRuntime(manager, transcriber=None)
- validation = AsyncMock(side_effect=ApplicationUnavailableError("bad model"))
+ events: list[str] = []
+
+ async def warm_cache() -> None:
+ events.append("warm")
+
+ def start_refresh() -> None:
+ events.append("background")
with (
- patch.object(manager, "validate_configured_models", new=validation),
- patch.object(manager, "start_model_list_refresh") as start_refresh,
+ patch.object(
+ manager,
+ "warm_referenced_model_cache",
+ side_effect=warm_cache,
+ ) as warm,
+ patch.object(
+ manager,
+ "start_model_list_refresh",
+ side_effect=start_refresh,
+ ) as refresh,
patch.object(manager, "close", new=AsyncMock()),
patch(
"free_claude_code.runtime.application.messaging_platform_factory.create_messaging_components",
@@ -184,8 +203,9 @@ async def test_model_validation_failure_does_not_block_runtime_startup():
await runtime.start()
await runtime.close()
- validation.assert_awaited_once()
- start_refresh.assert_called_once()
+ warm.assert_awaited_once()
+ refresh.assert_called_once()
+ assert events == ["warm", "background"]
def test_startup_failure_message_preserves_existing_concise_contract():
diff --git a/tests/config/test_config.py b/tests/config/test_config.py
index cd7adcf7..2f50d9b4 100644
--- a/tests/config/test_config.py
+++ b/tests/config/test_config.py
@@ -1134,10 +1134,8 @@ class TestPerModelMapping:
)
assert parse_model_name("cerebras/llama3.1-8b") == "llama3.1-8b"
- def test_configured_chat_model_refs_collects_unique_models_with_sources(
- self, monkeypatch
- ):
- """Startup validation model collection is limited to configured chat refs."""
+ def test_configured_chat_model_refs_collects_unique_models(self, monkeypatch):
+ """Model discovery is limited to configured chat references."""
from free_claude_code.config.settings import Settings
monkeypatch.setenv("FCC_SMOKE_MODEL_NVIDIA_NIM", "nvidia_nim/smoke")
@@ -1158,10 +1156,7 @@ class TestPerModelMapping:
]
assert refs[0].provider_id == "nvidia_nim"
assert refs[0].model_id == "fallback"
- assert refs[0].sources == ("MODEL", "MODEL_SONNET")
assert refs[1].provider_id == "open_router"
assert refs[1].model_id == "anthropic/claude-fable-5"
- assert refs[1].sources == ("MODEL_FABLE",)
assert refs[2].provider_id == "open_router"
assert refs[2].model_id == "anthropic/claude-opus"
- assert refs[2].sources == ("MODEL_OPUS",)
diff --git a/tests/providers/test_model_validation.py b/tests/providers/test_model_discovery.py
similarity index 83%
rename from tests/providers/test_model_validation.py
rename to tests/providers/test_model_discovery.py
index 06512477..f71ffbb4 100644
--- a/tests/providers/test_model_validation.py
+++ b/tests/providers/test_model_discovery.py
@@ -6,7 +6,6 @@ from unittest.mock import AsyncMock, patch
import pytest
-from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.nim import NimSettings
from free_claude_code.config.provider_catalog import (
@@ -327,6 +326,7 @@ class FakeProvider(BaseProvider):
self._started = started
self._peer_started = peer_started
self.cleaned = False
+ self.model_list_calls = 0
def preflight_stream(
self,
@@ -340,6 +340,7 @@ class FakeProvider(BaseProvider):
self.cleaned = True
async def _before_model_list(self) -> None:
+ self.model_list_calls += 1
if self._started is not None:
self._started.set()
if self._peer_started is not None:
@@ -372,73 +373,84 @@ class FakeProvider(BaseProvider):
@pytest.mark.asyncio
-async def test_runtime_validation_succeeds_for_all_configured_models() -> None:
+async def test_runtime_warm_caches_all_referenced_provider_models() -> None:
settings = _settings(
model_opus="open_router/anthropic/claude-opus",
nvidia_nim_api_key="nim-key",
open_router_api_key="open-router-key",
)
+ nim = FakeProvider(frozenset({"nim-model"}))
+ router = FakeProvider(frozenset({"anthropic/claude-opus"}))
runtime = _manager(
settings,
{
- "nvidia_nim": FakeProvider(frozenset({"nim-model"})),
- "open_router": FakeProvider(frozenset({"anthropic/claude-opus"})),
+ "nvidia_nim": nim,
+ "open_router": router,
},
)
- await runtime.validate_configured_models()
+ result = await runtime.warm_referenced_model_cache()
+ assert result.refreshed_provider_ids == ("nvidia_nim", "open_router")
+ assert result.failed_provider_ids == ()
assert runtime.cached_model_ids() == {
"nvidia_nim": frozenset({"nim-model"}),
"open_router": frozenset({"anthropic/claude-opus"}),
}
+ assert nim.model_list_calls == 1
+ assert router.model_list_calls == 1
@pytest.mark.asyncio
-async def test_runtime_validation_reports_missing_model_with_sources() -> None:
- settings = _settings(model_sonnet="nvidia_nim/nim-model")
+async def test_runtime_warm_treats_model_lists_as_discovery_metadata() -> None:
+ settings = _settings(
+ model_sonnet="nvidia_nim/nim-model",
+ nvidia_nim_api_key="nim-key",
+ )
runtime = _manager(
settings,
{"nvidia_nim": FakeProvider(frozenset({"different-model"}))},
)
- with pytest.raises(ApplicationUnavailableError) as exc_info:
- await runtime.validate_configured_models()
+ result = await runtime.warm_referenced_model_cache()
- message = exc_info.value.message
- assert "sources=MODEL,MODEL_SONNET" in message
- assert "provider=nvidia_nim" in message
- assert "model=nim-model" in message
- assert "problem=missing model" in message
+ assert result.refreshed_provider_ids == ("nvidia_nim",)
+ assert result.failed_provider_ids == ()
+ assert runtime.cached_model_ids() == {"nvidia_nim": frozenset({"different-model"})}
@pytest.mark.asyncio
-async def test_runtime_validation_aggregates_multiple_failures() -> None:
- settings = _settings(model_opus="open_router/anthropic/claude-opus")
+async def test_runtime_warm_reports_query_failures_without_blocking() -> None:
+ settings = _settings(
+ model_opus="open_router/anthropic/claude-opus",
+ nvidia_nim_api_key="nim-key",
+ open_router_api_key="open-router-key",
+ )
runtime = _manager(
settings,
{
- "nvidia_nim": FakeProvider(frozenset({"different-model"})),
+ "nvidia_nim": FakeProvider(frozenset({"nim-model"})),
"open_router": FakeProvider(
error=ModelListResponseError("bad model-list shape")
),
},
)
- with pytest.raises(ApplicationUnavailableError) as exc_info:
- await runtime.validate_configured_models()
+ with patch(
+ "free_claude_code.providers.runtime.discovery.logger.warning"
+ ) as warning:
+ result = await runtime.warm_referenced_model_cache()
- message = exc_info.value.message
- assert "sources=MODEL provider=nvidia_nim model=nim-model" in message
- assert "problem=missing model" in message
- assert "sources=MODEL_OPUS provider=open_router model=anthropic/claude-opus" in (
- message
- )
- assert "problem=malformed model-list response" in message
+ assert result.refreshed_provider_ids == ("nvidia_nim",)
+ assert result.failed_provider_ids == ("open_router",)
+ assert runtime.cached_model_ids() == {"nvidia_nim": frozenset({"nim-model"})}
+ logged = " ".join(str(arg) for call in warning.call_args_list for arg in call.args)
+ assert "open_router" in logged
+ assert "malformed model-list response: bad model-list shape" in logged
@pytest.mark.asyncio
-async def test_runtime_validation_queries_providers_concurrently() -> None:
+async def test_runtime_warm_queries_referenced_providers_concurrently() -> None:
nim_started = asyncio.Event()
router_started = asyncio.Event()
settings = _settings(model_opus="open_router/anthropic/claude-opus")
@@ -458,7 +470,51 @@ async def test_runtime_validation_queries_providers_concurrently() -> None:
},
)
- await asyncio.wait_for(runtime.validate_configured_models(), timeout=1.0)
+ await asyncio.wait_for(runtime.warm_referenced_model_cache(), timeout=1.0)
+
+
+async def test_startup_discovery_queries_each_successful_provider_once() -> None:
+ settings = _settings(
+ nvidia_nim_api_key="nim-key",
+ open_router_api_key="open-router-key",
+ )
+ nim = FakeProvider(frozenset({"nim-model"}))
+ router = FakeProvider(frozenset({"anthropic/claude-sonnet"}))
+ runtime = _manager(
+ settings,
+ {"nvidia_nim": nim, "open_router": router},
+ )
+
+ await runtime.warm_referenced_model_cache()
+ runtime.start_model_list_refresh()
+ refresh_task = runtime._refresh_task
+ assert refresh_task is not None
+ await refresh_task
+
+ assert nim.model_list_calls == 1
+ assert router.model_list_calls == 1
+ assert runtime.cached_model_ids() == {
+ "nvidia_nim": frozenset({"nim-model"}),
+ "open_router": frozenset({"anthropic/claude-sonnet"}),
+ }
+
+
+async def test_failed_startup_warm_remains_eligible_for_background_refresh() -> None:
+ settings = _settings(nvidia_nim_api_key="nim-key")
+ nim = FakeProvider(error=RuntimeError("upstream unavailable"))
+ runtime = _manager(settings, {"nvidia_nim": nim})
+
+ warm_result = await runtime.warm_referenced_model_cache()
+ runtime.start_model_list_refresh()
+ refresh_task = runtime._refresh_task
+ assert refresh_task is not None
+ await refresh_task
+
+ assert warm_result.failed_provider_ids == ("nvidia_nim",)
+ assert nim.model_list_calls == 2
+ assert runtime.cached_model_ids() == {}
@pytest.mark.asyncio
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index 0113cf08..3f2bc02e 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -636,7 +636,7 @@ async def test_startup_failure_closes_owned_transcriber() -> None:
with (
patch.object(
manager,
- "validate_configured_models",
+ "warm_referenced_model_cache",
AsyncMock(side_effect=RuntimeError("startup failed")),
),
pytest.raises(RuntimeError, match="startup failed"),
@@ -708,8 +708,8 @@ async def test_public_start_retries_transient_partial_messaging_cleanup() -> Non
with (
patch.object(
- runtime,
- "_validate_configured_models_best_effort",
+ manager,
+ "warm_referenced_model_cache",
AsyncMock(),
),
patch.object(manager, "start_model_list_refresh"),
@@ -770,8 +770,8 @@ async def test_public_start_retains_persistently_unclean_partial_messaging_graph
with (
patch.object(
- runtime,
- "_validate_configured_models_best_effort",
+ manager,
+ "warm_referenced_model_cache",
AsyncMock(),
),
patch.object(manager, "start_model_list_refresh"),
diff --git a/uv.lock b/uv.lock
index f76351fd..55613d25 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.11.5"
+version = "4.11.6"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },