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 ProviderModelInfo the sole model-catalog contract (#1222)
Ali Khokhar2a676cc6d99d
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 4322897c..70305fae 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -582,8 +582,10 @@ compatibility layer.- `ProviderConfig`: shared provider settings such as API key, base URL, ratelimits, timeouts, proxy, and logging flags. It is a frozen internalvalue whose base URL has already been resolved from the catalog.-- `BaseProvider`: the abstract implementation base for cleanup, model listing,- explicit preflight, and `stream_response()`.+- `BaseProvider`: the abstract implementation base for cleanup, explicit+ preflight, `stream_response()`, and the sole provider catalog operation,+ `list_model_infos()`. Providers return application-owned `ProviderModelInfo`+ values directly; there is no parallel IDs-only catalog contract.There is one upstream transport family:[providers/openai_chat/](src/free_claude_code/providers/openai_chat/) implements the concretediff --git a/pyproject.toml b/pyproject.tomlindex eaca8340..226e845f 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "4.11.6"+version = "4.11.7"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/providers/base.py b/src/free_claude_code/providers/base.pyindex 14a8de4c..246c1be2 100644--- a/src/free_claude_code/providers/base.py+++ b/src/free_claude_code/providers/base.py@@ -15,7 +15,6 @@ from free_claude_code.core.diagnostics import ()from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicyfrom free_claude_code.core.trace import trace_event-from free_claude_code.providers.model_listing import model_infos_from_ids@dataclass(frozen=True, slots=True)@@ -102,12 +101,8 @@ class BaseProvider(ABC):"""Release any resources held by this provider."""@abstractmethod- async def list_model_ids(self) -> frozenset[str]:- """Return the model ids currently advertised by this provider."""-async def list_model_infos(self) -> frozenset[ProviderModelInfo]:- """Return advertised model ids with optional provider capability metadata."""- return model_infos_from_ids(await self.list_model_ids())+ """Return the model metadata currently advertised by this provider."""@abstractmethoddef stream_response(diff --git a/src/free_claude_code/providers/cloudflare/client.py b/src/free_claude_code/providers/cloudflare/client.pyindex 7215b796..e2ba36ab 100644--- a/src/free_claude_code/providers/cloudflare/client.py+++ b/src/free_claude_code/providers/cloudflare/client.py@@ -16,8 +16,7 @@ from free_claude_code.providers.base import ProviderConfigfrom free_claude_code.providers.http import maybe_await_aclosefrom free_claude_code.providers.model_listing import (ModelListResponseError,- extract_openai_model_ids,- model_infos_from_ids,+ extract_openai_model_infos,)from free_claude_code.providers.openai_chat import (ChatTemplateReasoning,@@ -96,12 +95,8 @@ class CloudflareProvider(OpenAIChatProvider):await super().cleanup()await self._model_list_client.aclose()- async def list_model_ids(self) -> frozenset[str]:- """Return Cloudflare Workers AI model ids from account model search."""- return frozenset(info.model_id for info in await self.list_model_infos())-async def list_model_infos(self) -> frozenset[ProviderModelInfo]:- """Return Cloudflare Workers AI model ids from account model search."""+ """Return Cloudflare Workers AI metadata from account model search."""async def request() -> httpx.Response:response = await self._model_list_client.get(@@ -124,9 +119,7 @@ class CloudflareProvider(OpenAIChatProvider):raise ModelListResponseError("CLOUDFLARE model-list response is malformed: invalid JSON") from exc- return model_infos_from_ids(- extract_openai_model_ids(payload, provider_name="CLOUDFLARE")- )+ return extract_openai_model_infos(payload, provider_name="CLOUDFLARE")finally:await maybe_await_aclose(response)diff --git a/src/free_claude_code/providers/github_models/client.py b/src/free_claude_code/providers/github_models/client.pyindex 5e8c0011..87c0ef28 100644--- a/src/free_claude_code/providers/github_models/client.py+++ b/src/free_claude_code/providers/github_models/client.py@@ -60,10 +60,6 @@ class GitHubModelsProvider(OpenAIChatProvider):await super().cleanup()await self._model_list_client.aclose()- async def list_model_ids(self) -> frozenset[str]:- """Return GitHub Models ids that support FCC's streaming tool workflow."""- return frozenset(info.model_id for info in await self.list_model_infos())-async def list_model_infos(self) -> frozenset[ProviderModelInfo]:"""Return stream/tool-capable GitHub Models catalog ids."""diff --git a/src/free_claude_code/providers/model_listing.py b/src/free_claude_code/providers/model_listing.pyindex 3d0f6f17..13d4a5bd 100644--- a/src/free_claude_code/providers/model_listing.py+++ b/src/free_claude_code/providers/model_listing.py@@ -27,8 +27,10 @@ def model_infos_from_ids()-def extract_openai_model_ids(payload: Any, *, provider_name: str) -> frozenset[str]:- """Extract model ids from an OpenAI-compatible ``/models`` response."""+def extract_openai_model_infos(+ payload: Any, *, provider_name: str+) -> frozenset[_ProviderModelInfo]:+ """Extract model metadata from an OpenAI-compatible ``/models`` response."""data = _field(payload, "data")if not _is_sequence(data):raise _malformed(provider_name, "expected top-level data array")@@ -42,19 +44,7 @@ def extract_openai_model_ids(payload: Any, *, provider_name: str) -> frozenset[sif not model_ids:raise _malformed(provider_name, "response did not include any model ids")- return frozenset(model_ids)---def extract_openrouter_tool_model_ids(- payload: Any, *, provider_name: str-) -> frozenset[str]:- """Extract OpenRouter model ids that advertise tool-use support."""- return frozenset(- info.model_id- for info in extract_openrouter_tool_model_infos(- payload, provider_name=provider_name- )- )+ return model_infos_from_ids(model_ids)def extract_openrouter_tool_model_infos(diff --git a/src/free_claude_code/providers/open_router/client.py b/src/free_claude_code/providers/open_router/client.pyindex 03ef869f..becfab9f 100644--- a/src/free_claude_code/providers/open_router/client.py+++ b/src/free_claude_code/providers/open_router/client.py@@ -12,10 +12,7 @@ from free_claude_code.core.anthropic.streaming import AnthropicStreamLedgerfrom free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicyfrom free_claude_code.providers.admission import ProviderAdmissionControllerfrom free_claude_code.providers.base import ProviderConfig-from free_claude_code.providers.model_listing import (- extract_openrouter_tool_model_ids,- extract_openrouter_tool_model_infos,-)+from free_claude_code.providers.model_listing import extract_openrouter_tool_model_infosfrom free_claude_code.providers.openai_chat import (OpenAIChatProfile,OpenAIChatProvider,@@ -45,13 +42,6 @@ class OpenRouterProvider(OpenAIChatProvider):admission=admission,)- async def list_model_ids(self) -> frozenset[str]:- """Only advertise OpenRouter models that can run Claude Code tools."""- payload = await self._list_models_payload()- return extract_openrouter_tool_model_ids(- payload, provider_name=self._provider_name- )-async def list_model_infos(self) -> frozenset[ProviderModelInfo]:"""Advertise OpenRouter tool models with reasoning capability metadata."""payload = await self._list_models_payload()diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.pyindex f61f31f6..12fbc741 100644--- a/src/free_claude_code/providers/openai_chat/provider.py+++ b/src/free_claude_code/providers/openai_chat/provider.py@@ -10,6 +10,7 @@ import httpxfrom loguru import loggerfrom openai import AsyncOpenAI+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.core.anthropic import (ContentType,HeuristicToolParser,@@ -43,7 +44,7 @@ from free_claude_code.providers.http import (close_provider_stream,maybe_await_aclose,)-from free_claude_code.providers.model_listing import extract_openai_model_ids+from free_claude_code.providers.model_listing import extract_openai_model_infosfrom free_claude_code.providers.stream_recovery import (RecoveryController,RecoveryFailureAction,@@ -124,13 +125,13 @@ class OpenAIChatProvider(BaseProvider):if client is not None:await client.close()- async def list_model_ids(self) -> frozenset[str]:- """Return model ids from the provider's OpenAI-compatible models endpoint."""+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:+ """Return model metadata from the OpenAI-compatible models endpoint."""payload = await self._admission.run_with_retry(self._client.models.list,provider_failure_override=self._provider_failure_override,)- return extract_openai_model_ids(payload, provider_name=self._provider_name)+ return extract_openai_model_infos(payload, provider_name=self._provider_name)def _build_request_body(self,diff --git a/src/free_claude_code/providers/runtime/model_cache.py b/src/free_claude_code/providers/runtime/model_cache.pyindex 54f224c1..b67cc133 100644--- a/src/free_claude_code/providers/runtime/model_cache.py+++ b/src/free_claude_code/providers/runtime/model_cache.py@@ -4,7 +4,6 @@ from collections.abc import Iterablefrom free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.provider_catalog import SUPPORTED_PROVIDER_IDS-from free_claude_code.providers.model_listing import model_infos_from_idsclass ProviderModelCache:@@ -17,10 +16,6 @@ class ProviderModelCache:self._available_provider_ids = frozenset(available_provider_ids)self._model_infos_by_provider: dict[str, dict[str, ProviderModelInfo]] = {}- def cache_model_ids(self, provider_id: str, model_ids: Iterable[str]) -> None:- """Store raw provider model ids with unknown capability metadata."""- self.cache_model_infos(provider_id, model_infos_from_ids(model_ids))-def cache_model_infos(self, provider_id: str, model_infos: Iterable[ProviderModelInfo]) -> None:@@ -61,10 +56,6 @@ class ProviderModelCache:return Nonereturn info.supports_thinking- def cached_prefixed_model_refs(self) -> tuple[str, ...]:- """Return cached provider models in user-selectable ``provider/model`` form."""- return tuple(info.model_id for info in self.cached_prefixed_model_infos())-def cached_prefixed_model_infos(self) -> tuple[ProviderModelInfo, ...]:"""Return cached provider models with user-selectable prefixed ids."""infos: list[ProviderModelInfo] = []diff --git a/src/free_claude_code/providers/vertex/client.py b/src/free_claude_code/providers/vertex/client.pyindex 79d5ed96..209a684b 100644--- a/src/free_claude_code/providers/vertex/client.py+++ b/src/free_claude_code/providers/vertex/client.py@@ -5,6 +5,7 @@ from typing import Anyimport httpx+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.core.anthropic import ReasoningReplayModefrom free_claude_code.providers.admission import ProviderAdmissionControllerfrom free_claude_code.providers.base import ProviderConfig@@ -14,7 +15,10 @@ from free_claude_code.providers.google_openai import (validate_google_extra_body,)from free_claude_code.providers.http import maybe_await_aclose-from free_claude_code.providers.model_listing import ModelListResponseError+from free_claude_code.providers.model_listing import (+ ModelListResponseError,+ model_infos_from_ids,+)from free_claude_code.providers.openai_chat import (OpenAIChatProfile,OpenAIChatRequestPolicy,@@ -76,7 +80,7 @@ class VertexProvider(GoogleOpenAIProvider):finally:await self._model_list_client.aclose()- async def list_model_ids(self) -> frozenset[str]:+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:"""List Vertex publisher models and translate their resource names."""model_ids: set[str] = set()page_token: str | None = None@@ -97,7 +101,7 @@ class VertexProvider(GoogleOpenAIProvider):"VERTEX model-list response is malformed: response did not include ""any model ids")- return frozenset(model_ids)+ return model_infos_from_ids(model_ids)async def _list_model_page(self, page_token: str | None) -> Any:async def request() -> httpx.Response:diff --git a/tests/api/test_api_handlers.py b/tests/api/test_api_handlers.pyindex 73220062..8cdb80ff 100644--- a/tests/api/test_api_handlers.py+++ b/tests/api/test_api_handlers.py@@ -12,6 +12,7 @@ from free_claude_code.api.handlers import (TokenCountHandler,)from free_claude_code.application.errors import InvalidRequestError+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.settings import Settingsfrom free_claude_code.core.anthropic.models import (Message,@@ -50,8 +51,8 @@ class FakeProvider:async def cleanup(self) -> None:return None- async def list_model_ids(self) -> frozenset[str]:- return frozenset({"test-model"})+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:+ return frozenset({ProviderModelInfo("test-model")})async def stream_response(self,diff --git a/tests/providers/test_bedrock.py b/tests/providers/test_bedrock.pyindex f360ab4c..b2a5133c 100644--- a/tests/providers/test_bedrock.py+++ b/tests/providers/test_bedrock.py@@ -5,6 +5,7 @@ from unittest.mock import AsyncMock, patchimport pytest+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.provider_catalog import BEDROCK_DEFAULT_BASEfrom free_claude_code.providers.base import ProviderConfigfrom free_claude_code.providers.openai_chat import OpenAIChatProvider@@ -137,7 +138,10 @@ async def test_model_discovery_uses_mantle_openai_models_endpoint() -> None:))- assert await provider.list_model_ids() == frozenset(- {"openai.gpt-oss-120b", "amazon.nova-pro-v1:0"}+ assert await provider.list_model_infos() == frozenset(+ {+ ProviderModelInfo("openai.gpt-oss-120b"),+ ProviderModelInfo("amazon.nova-pro-v1:0"),+ })provider._client.models.list.assert_awaited_once_with()diff --git a/tests/providers/test_cloudflare.py b/tests/providers/test_cloudflare.pyindex 45bd1892..d97c18ec 100644--- a/tests/providers/test_cloudflare.py+++ b/tests/providers/test_cloudflare.py@@ -8,6 +8,7 @@ import httpximport pytestfrom free_claude_code.application.errors import ApplicationUnavailableError+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.provider_catalog import CLOUDFLARE_AI_REST_ROOTfrom free_claude_code.core.anthropic.models import Message, MessagesRequestfrom free_claude_code.core.anthropic.stream_contracts import parse_sse_text@@ -188,10 +189,10 @@ async def test_lists_models_from_cloudflare_model_search_endpoint(new_callable=AsyncMock,return_value=response,) as mock_get:- assert await cloudflare_provider.list_model_ids() == frozenset(+ assert await cloudflare_provider.list_model_infos() == frozenset({- "@cf/moonshotai/kimi-k2.6",- "@cf/meta/llama-4-scout-17b-16e-instruct",+ ProviderModelInfo("@cf/moonshotai/kimi-k2.6"),+ ProviderModelInfo("@cf/meta/llama-4-scout-17b-16e-instruct"),})diff --git a/tests/providers/test_github_models.py b/tests/providers/test_github_models.pyindex f921de1d..ea3e5ad6 100644--- a/tests/providers/test_github_models.py+++ b/tests/providers/test_github_models.py@@ -8,6 +8,7 @@ from unittest.mock import AsyncMock, patchimport httpximport pytest+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.provider_catalog import GITHUB_MODELS_DEFAULT_BASEfrom free_claude_code.core.anthropic.models import Message, MessagesRequestfrom free_claude_code.core.anthropic.stream_contracts import parse_sse_text@@ -147,8 +148,8 @@ async def test_lists_stream_tool_capable_models_only(]),) as mock_get:- assert await github_models_provider.list_model_ids() == frozenset(- {"openai/gpt-4.1"}+ assert await github_models_provider.list_model_infos() == frozenset(+ {ProviderModelInfo("openai/gpt-4.1")})mock_get.assert_awaited_once_with(@@ -174,7 +175,7 @@ async def test_model_list_rejects_malformed_payload(),pytest.raises(ModelListResponseError, match="top-level array"),):- await github_models_provider.list_model_ids()+ await github_models_provider.list_model_infos()@pytest.mark.asyncio@@ -192,7 +193,7 @@ async def test_model_list_returns_empty_set_when_no_models_support_streaming_too]),):- assert await github_models_provider.list_model_ids() == frozenset()+ assert await github_models_provider.list_model_infos() == frozenset()@pytest.mark.asynciodiff --git a/tests/providers/test_kimi.py b/tests/providers/test_kimi.pyindex 687a1a67..9e1b44d4 100644--- a/tests/providers/test_kimi.py+++ b/tests/providers/test_kimi.py@@ -6,6 +6,7 @@ from unittest.mock import AsyncMock, MagicMockimport pytestfrom free_claude_code.application.errors import InvalidRequestError+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENSfrom free_claude_code.config.provider_catalog import KIMI_DEFAULT_BASEfrom free_claude_code.core.anthropic.models import Message, MessagesRequest@@ -97,7 +98,9 @@ async def test_model_list_uses_openai_client_models_endpoint(kimi_provider):return_value=SimpleNamespace(data=[SimpleNamespace(id="kimi-k2.5")]))- assert await kimi_provider.list_model_ids() == frozenset({"kimi-k2.5"})+ assert await kimi_provider.list_model_infos() == frozenset(+ {ProviderModelInfo("kimi-k2.5")}+ )kimi_provider._client.models.list.assert_awaited_once_with()diff --git a/tests/providers/test_kimi_code.py b/tests/providers/test_kimi_code.pyindex 9a1dd9ed..e84dda1b 100644--- a/tests/providers/test_kimi_code.py+++ b/tests/providers/test_kimi_code.py@@ -6,6 +6,7 @@ from unittest.mock import AsyncMockimport pytestfrom free_claude_code.application.errors import InvalidRequestError+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.provider_catalog import KIMI_CODE_DEFAULT_BASEfrom free_claude_code.core.anthropic.models import MessagesRequestfrom free_claude_code.providers.base import ProviderConfig@@ -161,7 +162,11 @@ async def test_model_list_uses_subscription_models_endpoint(kimi_code_provider):))- assert await kimi_code_provider.list_model_ids() == frozenset(- {"k3", "kimi-for-coding", "kimi-for-coding-highspeed"}+ assert await kimi_code_provider.list_model_infos() == frozenset(+ {+ ProviderModelInfo("k3"),+ ProviderModelInfo("kimi-for-coding"),+ ProviderModelInfo("kimi-for-coding-highspeed"),+ })kimi_code_provider._client.models.list.assert_awaited_once_with()diff --git a/tests/providers/test_minimax.py b/tests/providers/test_minimax.pyindex 119bf464..9516f983 100644--- a/tests/providers/test_minimax.py+++ b/tests/providers/test_minimax.py@@ -5,6 +5,7 @@ from unittest.mock import AsyncMock, MagicMock, patchimport pytest+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENSfrom free_claude_code.config.provider_catalog import MINIMAX_DEFAULT_BASEfrom free_claude_code.core.anthropic.models import Message, MessagesRequest, Tool@@ -131,8 +132,8 @@ async def test_lists_models_from_openai_models_endpoint(minimax_provider):))- assert await minimax_provider.list_model_ids() == frozenset(- {"MiniMax-M3", "MiniMax-M2.7"}+ assert await minimax_provider.list_model_infos() == frozenset(+ {ProviderModelInfo("MiniMax-M3"), ProviderModelInfo("MiniMax-M2.7")})diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.pyindex f71ffbb4..21268515 100644--- a/tests/providers/test_model_discovery.py+++ b/tests/providers/test_model_discovery.py@@ -71,8 +71,17 @@ def _manager()+def _infos(*model_ids: str) -> frozenset[ProviderModelInfo]:+ return frozenset(ProviderModelInfo(model_id) for model_id in model_ids)+++def test_provider_catalog_contract_is_metadata_only() -> None:+ assert not hasattr(BaseProvider, "list_model_ids")+ assert getattr(BaseProvider.list_model_infos, "__isabstractmethod__", False)++@pytest.mark.asyncio-async def test_nim_lists_openai_compatible_model_ids() -> None:+async def test_nim_lists_openai_compatible_model_infos() -> None:config = ProviderConfig(api_key="test-key", base_url=NVIDIA_NIM_DEFAULT_BASE)with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):provider = NvidiaNimProvider(@@ -85,7 +94,7 @@ async def test_nim_lists_openai_compatible_model_ids() -> None:new_callable=AsyncMock,return_value=SimpleNamespace(data=[SimpleNamespace(id="nvidia/model")]),):- assert await provider.list_model_ids() == frozenset({"nvidia/model"})+ assert await provider.list_model_infos() == _infos("nvidia/model")@pytest.mark.asyncio@@ -104,7 +113,7 @@ async def test_nim_lists_openai_compatible_model_ids() -> None:),],)-async def test_local_openai_chat_providers_list_model_ids(+async def test_local_openai_chat_providers_list_model_infos(provider: OpenAIChatProvider,) -> None:with patch.object(@@ -113,7 +122,7 @@ async def test_local_openai_chat_providers_list_model_ids(new_callable=AsyncMock,return_value=SimpleNamespace(data=[SimpleNamespace(id="local/model")]),) as mock_list:- assert await provider.list_model_ids() == frozenset({"local/model"})+ assert await provider.list_model_infos() == _infos("local/model")mock_list.assert_awaited_once_with()@@ -130,7 +139,7 @@ async def test_deepseek_lists_models_from_root_endpoint() -> None:new_callable=AsyncMock,return_value=SimpleNamespace(data=[SimpleNamespace(id="deepseek-chat")]),) as mock_list:- assert await provider.list_model_ids() == frozenset({"deepseek-chat"})+ assert await provider.list_model_infos() == _infos("deepseek-chat")mock_list.assert_awaited_once_with()@@ -148,7 +157,7 @@ async def test_wafer_lists_models_from_default_models_endpoint() -> None:new_callable=AsyncMock,return_value=SimpleNamespace(data=[SimpleNamespace(id="DeepSeek-V4-Pro")]),) as mock_list:- assert await provider.list_model_ids() == frozenset({"DeepSeek-V4-Pro"})+ assert await provider.list_model_infos() == _infos("DeepSeek-V4-Pro")mock_list.assert_awaited_once_with()@@ -181,8 +190,11 @@ async def test_openrouter_lists_only_tool_capable_models() -> None:]),) as mock_list:- assert await provider.list_model_ids() == frozenset(- {"tool-model", "tool-choice-model"}+ assert await provider.list_model_infos() == frozenset(+ {+ ProviderModelInfo("tool-model", supports_thinking=False),+ ProviderModelInfo("tool-choice-model", supports_thinking=False),+ })mock_list.assert_awaited_once_with()@@ -246,7 +258,7 @@ async def test_openrouter_lists_empty_set_when_no_tool_capable_models() -> None:]),):- assert await provider.list_model_ids() == frozenset()+ assert await provider.list_model_infos() == frozenset()@pytest.mark.asyncio@@ -285,7 +297,7 @@ async def test_model_listing_rejects_malformed_payload() -> None:),pytest.raises(ModelListResponseError, match="malformed"),):- await provider.list_model_ids()+ await provider.list_model_infos()@pytest.mark.asyncio@@ -304,15 +316,14 @@ async def test_model_listing_propagates_upstream_errors() -> None:),pytest.raises(RuntimeError, match="upstream unavailable"),):- await provider.list_model_ids()+ await provider.list_model_infos()class FakeProvider(BaseProvider):def __init__(self,- model_ids: frozenset[str] | None = None,+ model_infos: frozenset[ProviderModelInfo] = frozenset(),*,- model_infos: frozenset[ProviderModelInfo] | None = None,error: BaseException | None = None,started: asyncio.Event | None = None,peer_started: asyncio.Event | None = None,@@ -320,7 +331,6 @@ class FakeProvider(BaseProvider):super().__init__(ProviderConfig(api_key="test", base_url="https://test.invalid"))- self._model_ids = model_ids or frozenset()self._model_infos = model_infosself._error = errorself._started = started@@ -348,17 +358,9 @@ class FakeProvider(BaseProvider):if self._error is not None:raise self._error- async def list_model_ids(self) -> frozenset[str]:- await self._before_model_list()- if self._model_infos is not None:- return frozenset(info.model_id for info in self._model_infos)- return self._model_ids-async def list_model_infos(self) -> frozenset[ProviderModelInfo]:await self._before_model_list()- if self._model_infos is not None:- return self._model_infos- return frozenset(ProviderModelInfo(model_id) for model_id in self._model_ids)+ return self._model_infosasync def stream_response(self,@@ -379,8 +381,8 @@ async def test_runtime_warm_caches_all_referenced_provider_models() -> None:nvidia_nim_api_key="nim-key",open_router_api_key="open-router-key",)- nim = FakeProvider(frozenset({"nim-model"}))- router = FakeProvider(frozenset({"anthropic/claude-opus"}))+ nim = FakeProvider(_infos("nim-model"))+ router = FakeProvider(_infos("anthropic/claude-opus"))runtime = _manager(settings,{@@ -409,7 +411,7 @@ async def test_runtime_warm_treats_model_lists_as_discovery_metadata() -> None:)runtime = _manager(settings,- {"nvidia_nim": FakeProvider(frozenset({"different-model"}))},+ {"nvidia_nim": FakeProvider(_infos("different-model"))},)result = await runtime.warm_referenced_model_cache()@@ -429,7 +431,7 @@ async def test_runtime_warm_reports_query_failures_without_blocking() -> None:runtime = _manager(settings,{- "nvidia_nim": FakeProvider(frozenset({"nim-model"})),+ "nvidia_nim": FakeProvider(_infos("nim-model")),"open_router": FakeProvider(error=ModelListResponseError("bad model-list shape")),@@ -458,12 +460,12 @@ async def test_runtime_warm_queries_referenced_providers_concurrently() -> None:settings,{"nvidia_nim": FakeProvider(- frozenset({"nim-model"}),+ _infos("nim-model"),started=nim_started,peer_started=router_started,),"open_router": FakeProvider(- frozenset({"anthropic/claude-opus"}),+ _infos("anthropic/claude-opus"),started=router_started,peer_started=nim_started,),@@ -479,8 +481,8 @@ async def test_startup_discovery_queries_each_successful_provider_once() -> Nonenvidia_nim_api_key="nim-key",open_router_api_key="open-router-key",)- nim = FakeProvider(frozenset({"nim-model"}))- router = FakeProvider(frozenset({"anthropic/claude-sonnet"}))+ nim = FakeProvider(_infos("nim-model"))+ router = FakeProvider(_infos("anthropic/claude-sonnet"))runtime = _manager(settings,{"nvidia_nim": nim, "open_router": router},@@ -528,9 +530,9 @@ async def test_runtime_refresh_model_list_cache_uses_configured_remote_keys_and_runtime = _manager(settings,{- "open_router": FakeProvider(frozenset({"anthropic/claude-sonnet"})),- "lmstudio": FakeProvider(frozenset({"local-qwen"})),- "ollama": FakeProvider(frozenset({"llama3.1"})),+ "open_router": FakeProvider(_infos("anthropic/claude-sonnet")),+ "lmstudio": FakeProvider(_infos("local-qwen")),+ "ollama": FakeProvider(_infos("llama3.1")),},)@@ -554,7 +556,7 @@ async def test_runtime_refresh_model_list_cache_treats_vertex_project_as_configu)runtime = _manager(settings,- {"vertex": FakeProvider(frozenset({"google/gemini-3.5-flash"}))},+ {"vertex": FakeProvider(_infos("google/gemini-3.5-flash"))},)result = await runtime.refresh_model_list_cache()@@ -613,12 +615,12 @@ def test_runtime_metadata_cache_exposes_ids_and_prefixed_infos() -> None:def test_runtime_metadata_cache_enforces_replaced_provider_scope() -> None:cache = ProviderModelCache({"open_router", "lmstudio"})- cache.cache_model_ids("open_router", {"old-model"})- cache.cache_model_ids("lmstudio", {"local-model"})+ cache.cache_model_infos("open_router", _infos("old-model"))+ cache.cache_model_infos("lmstudio", _infos("local-model"))cache.set_available_providers({"deepseek", "lmstudio"})- cache.cache_model_ids("open_router", {"late-old-model"})- cache.cache_model_ids("deepseek", {"new-model"})+ cache.cache_model_infos("open_router", _infos("late-old-model"))+ cache.cache_model_infos("deepseek", _infos("new-model"))assert cache.cached_model_ids() == {"deepseek": frozenset({"new-model"}),@@ -626,9 +628,9 @@ def test_runtime_metadata_cache_enforces_replaced_provider_scope() -> None:}-def test_runtime_model_id_cache_keeps_unknown_thinking_support() -> None:+def test_runtime_metadata_cache_keeps_unknown_thinking_support() -> None:cache = ProviderModelCache()- cache.cache_model_ids("open_router", {"plain-model"})+ cache.cache_model_infos("open_router", _infos("plain-model"))assert cache.cached_model_ids() == {"open_router": frozenset({"plain-model"})}assert cache.cached_model_supports_thinking("open_router", "plain-model") is None@@ -637,13 +639,13 @@ def test_runtime_model_id_cache_keeps_unknown_thinking_support() -> None:)-def test_runtime_cached_prefixed_model_refs_are_deterministic() -> None:+def test_runtime_cached_prefixed_model_infos_are_deterministic() -> None:cache = ProviderModelCache()- cache.cache_model_ids("deepseek", {"deepseek-chat"})- cache.cache_model_ids("open_router", {"z-model", "a-model"})+ cache.cache_model_infos("deepseek", _infos("deepseek-chat"))+ cache.cache_model_infos("open_router", _infos("z-model", "a-model"))- assert cache.cached_prefixed_model_refs() == (- "open_router/a-model",- "open_router/z-model",- "deepseek/deepseek-chat",+ assert cache.cached_prefixed_model_infos() == (+ ProviderModelInfo("open_router/a-model"),+ ProviderModelInfo("open_router/z-model"),+ ProviderModelInfo("deepseek/deepseek-chat"),)diff --git a/tests/providers/test_preflight_contract.py b/tests/providers/test_preflight_contract.pyindex 9890334d..cb97d08b 100644--- a/tests/providers/test_preflight_contract.py+++ b/tests/providers/test_preflight_contract.py@@ -4,6 +4,7 @@ from collections.abc import AsyncIteratorimport pytest+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.core.anthropic.models import Message, MessagesRequestfrom free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicyfrom free_claude_code.providers.base import BaseProvider, ProviderConfig@@ -28,7 +29,7 @@ class ProviderWithoutPreflight(BaseProvider):async def cleanup(self) -> None:return None- async def list_model_ids(self) -> frozenset[str]:+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:return frozenset()async def stream_response(diff --git a/tests/providers/test_vertex.py b/tests/providers/test_vertex.pyindex c0971404..301233c6 100644--- a/tests/providers/test_vertex.py+++ b/tests/providers/test_vertex.py@@ -13,6 +13,7 @@ from free_claude_code.application.errors import (ApplicationUnavailableError,InvalidRequestError,)+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.provider_catalog import VERTEX_AI_API_ROOTfrom free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy@@ -413,9 +414,14 @@ async def test_vertex_model_discovery_follows_native_pagination() -> None:new_callable=AsyncMock,side_effect=responses,) as get:- model_ids = await provider.list_model_ids()+ model_infos = await provider.list_model_infos()- assert model_ids == frozenset({"google/gemini-3.5-flash", "google/gemini-3.1-pro"})+ assert model_infos == frozenset(+ {+ ProviderModelInfo("google/gemini-3.5-flash"),+ ProviderModelInfo("google/gemini-3.1-pro"),+ }+ )assert get.await_args_list[0].kwargs == {"params": None,"headers": {@@ -462,7 +468,7 @@ async def test_vertex_model_discovery_rejects_unusable_success_response(),pytest.raises(ModelListResponseError, match="VERTEX model-list response"),):- await provider.list_model_ids()+ await provider.list_model_infos()assert response.is_closed@@ -491,4 +497,4 @@ async def test_vertex_model_discovery_rejects_repeated_page_token() -> None:),pytest.raises(ModelListResponseError, match="repeated nextPageToken"),):- await provider.list_model_ids()+ await provider.list_model_infos()diff --git a/tests/providers/test_wafer.py b/tests/providers/test_wafer.pyindex 9d45e82a..616fd076 100644--- a/tests/providers/test_wafer.py+++ b/tests/providers/test_wafer.py@@ -4,6 +4,7 @@ from unittest.mock import AsyncMock, MagicMockimport pytest+from free_claude_code.application.model_metadata import ProviderModelInfofrom free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENSfrom free_claude_code.config.provider_catalog import WAFER_DEFAULT_BASEfrom free_claude_code.core.anthropic.models import Message, MessagesRequest, Tool@@ -124,8 +125,8 @@ async def test_lists_models_from_openai_models_endpoint(wafer_provider):))- assert await wafer_provider.list_model_ids() == frozenset(- {"DeepSeek-V4-Pro", "MiniMax-M2.7"}+ assert await wafer_provider.list_model_infos() == frozenset(+ {ProviderModelInfo("DeepSeek-V4-Pro"), ProviderModelInfo("MiniMax-M2.7")})wafer_provider._client.models.list.assert_awaited_once_with()diff --git a/uv.lock b/uv.lockindex 55613d25..f79541f5 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "4.11.6"+version = "4.11.7"source = { editable = "." }dependencies = [{ name = "aiohttp" },