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 xAI Grok provider (#1391)

Ali Khokhar89d6b364498d
diff --git a/.env.example b/.env.example
index 9aa7a248..2f434838 100644
--- a/.env.example
+++ b/.env.example
@@ -105,6 +105,10 @@ VERTEX_LOCATION="global"
GROQ_API_KEY=""
+# xAI / Grok (OpenAI-compatible Chat Completions at api.x.ai/v1)
+XAI_API_KEY=""
+
+
# SambaNova Cloud (OpenAI-compatible Chat Completions at api.sambanova.ai/v1)
SAMBANOVA_API_KEY=""
@@ -200,6 +204,7 @@ REASONING_HAIKU=inherit
# Provider config
# Per-provider proxy support: http and socks5, example: "http://username:password@host:port"
OPENAI_PROXY=""
+XAI_PROXY=""
AZURE_OPENAI_PROXY=""
NVIDIA_NIM_PROXY=""
OPENROUTER_PROXY=""
diff --git a/README.md b/README.md
index e06a24ff..7a61e78d 100644
--- a/README.md
+++ b/README.md
@@ -156,6 +156,7 @@ fcc-codex exec "hello"
| [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` |
| [Groq](https://console.groq.com/keys) | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` |
| [OpenAI / ChatGPT](https://learn.chatgpt.com/docs/auth) | Connect ChatGPT in the Admin UI | `openai/<model-id>` |
+| [xAI (Grok)](https://console.x.ai/team/default/api-keys) | `XAI_API_KEY` | `xai/grok-4.5` |
| [Azure OpenAI](https://learn.microsoft.com/azure/foundry/openai/how-to/chatgpt) | `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_BASE_URL` | `azure_openai/<deployment-name>` |
| [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` |
| [Google Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai) | `VERTEX_PROJECT_ID` + ADC | `vertex/google/gemini-3.5-flash` |
diff --git a/pyproject.toml b/pyproject.toml
index f70706db..43383234 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.20.0"
+version = "4.21.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index 6a95d8c0..0dd98f29 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -70,6 +70,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
"gemini": "gemini/models/gemini-3.1-flash-lite",
"vertex": "vertex/google/gemini-3.5-flash",
"groq": "groq/llama-3.3-70b-versatile",
+ "xai": "xai/grok-4.5",
"sambanova": "sambanova/Meta-Llama-3.3-70B-Instruct",
"kilo": "kilo/kilo-auto/free",
"cerebras": "cerebras/llama3.1-8b",
diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.py
index 395f752d..89c0869a 100644
--- a/src/free_claude_code/config/admin/provider_manifest.py
+++ b/src/free_claude_code/config/admin/provider_manifest.py
@@ -137,6 +137,13 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
"[OpenAI compatibility docs](https://console.groq.com/docs/openai)."
),
},
+ "XAI_API_KEY": {
+ "label": "xAI API Key",
+ "description": (
+ "xAI OpenAI-compatible API key for Grok chat and image-understanding "
+ "models."
+ ),
+ },
"SAMBANOVA_API_KEY": {
"label": "SambaNova API Key",
"description": (
diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.py
index 7e47daab..f81f6af6 100644
--- a/src/free_claude_code/config/provider_catalog.py
+++ b/src/free_claude_code/config/provider_catalog.py
@@ -50,6 +50,8 @@ SAMBANOVA_DEFAULT_BASE = "https://api.sambanova.ai/v1"
# Kilo.ai gateway OpenAI-compatible Chat Completions API.
KILO_DEFAULT_BASE = "https://api.kilo.ai/api/gateway"
OPENAI_CODEX_DEFAULT_BASE = "https://chatgpt.com/backend-api/codex"
+# xAI OpenAI-compatible Chat Completions API.
+XAI_DEFAULT_BASE = "https://api.x.ai/v1"
# TokenRouter OpenAI-compatible Chat Completions gateway.
TOKENROUTER_DEFAULT_BASE = "https://api.tokenrouter.com/v1"
# NaraRoute OpenAI-compatible Chat Completions gateway.
@@ -126,6 +128,15 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
default_base_url=OPENAI_CODEX_DEFAULT_BASE,
proxy_attr="openai_proxy",
),
+ "xai": ProviderDescriptor(
+ provider_id="xai",
+ display_name="xAI (Grok)",
+ credential_env="XAI_API_KEY",
+ credential_url="https://console.x.ai/team/default/api-keys",
+ credential_attr="xai_api_key",
+ default_base_url=XAI_DEFAULT_BASE,
+ proxy_attr="xai_proxy",
+ ),
"azure_openai": ProviderDescriptor(
provider_id="azure_openai",
display_name="Azure OpenAI",
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index c68b4ade..52946cdd 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -131,6 +131,9 @@ class Settings(BaseSettings):
# ==================== Groq (OpenAI-compatible) ====================
groq_api_key: str = Field(default="", validation_alias="GROQ_API_KEY")
+ # ==================== xAI / Grok (OpenAI-compatible) ====================
+ xai_api_key: str = Field(default="", validation_alias="XAI_API_KEY")
+
# ==================== Cerebras Inference (OpenAI-compatible) ====================
cerebras_api_key: str = Field(default="", validation_alias="CEREBRAS_API_KEY")
@@ -184,6 +187,7 @@ class Settings(BaseSettings):
# ==================== Per-Provider Proxy ====================
openai_proxy: str = Field(default="", validation_alias="OPENAI_PROXY")
+ xai_proxy: str = Field(default="", validation_alias="XAI_PROXY")
azure_openai_proxy: str = Field(default="", validation_alias="AZURE_OPENAI_PROXY")
nvidia_nim_proxy: str = Field(default="", validation_alias="NVIDIA_NIM_PROXY")
open_router_proxy: str = Field(default="", validation_alias="OPENROUTER_PROXY")
diff --git a/src/free_claude_code/providers/model_listing.py b/src/free_claude_code/providers/model_listing.py
index 1120a34a..0cb0d68e 100644
--- a/src/free_claude_code/providers/model_listing.py
+++ b/src/free_claude_code/providers/model_listing.py
@@ -28,15 +28,41 @@ def model_infos_from_ids(
def extract_openai_model_infos(
- payload: Any, *, provider_name: str
+ payload: Any,
+ *,
+ provider_name: str,
+ collection_field: str = "data",
+ aliases_field: str | None = None,
) -> frozenset[_ProviderModelInfo]:
- """Extract model metadata from an OpenAI-compatible ``/models`` response."""
+ """Extract routable IDs from an OpenAI-compatible model-list response."""
model_ids: set[str] = set()
- for item in model_list_items(payload, provider_name=provider_name):
+ for item in model_list_items(
+ payload,
+ provider_name=provider_name,
+ collection_field=collection_field,
+ ):
model_id = _field(item, "id")
if not isinstance(model_id, str) or not model_id.strip():
- raise _malformed(provider_name, "expected every data item to include id")
+ raise _malformed(
+ provider_name,
+ f"expected every {collection_field} item to include id",
+ )
model_ids.add(model_id)
+ if aliases_field is not None:
+ aliases = _field(item, aliases_field)
+ if not _is_sequence(aliases):
+ raise _malformed(
+ provider_name,
+ f"expected every {collection_field} item to include "
+ f"{aliases_field} array",
+ )
+ for alias in aliases:
+ if not isinstance(alias, str) or not alias.strip():
+ raise _malformed(
+ provider_name,
+ f"expected every {aliases_field} item to be a model id",
+ )
+ model_ids.add(alias)
if not model_ids:
raise _malformed(provider_name, "response did not include any model ids")
@@ -73,11 +99,19 @@ def extract_tool_capable_model_infos(
return frozenset(model_infos)
-def model_list_items(payload: Any, *, provider_name: str) -> tuple[Any, ...]:
+def model_list_items(
+ payload: Any,
+ *,
+ provider_name: str,
+ collection_field: str = "data",
+) -> tuple[Any, ...]:
"""Return a validated OpenAI-shaped model-list data array."""
- data = _field(payload, "data")
+ data = _field(payload, collection_field)
if not _is_sequence(data):
- raise _malformed(provider_name, "expected top-level data array")
+ raise _malformed(
+ provider_name,
+ f"expected top-level {collection_field} array",
+ )
return tuple(data)
diff --git a/src/free_claude_code/providers/openai_chat/profiles.py b/src/free_claude_code/providers/openai_chat/profiles.py
index 87c8e5b2..0cd43f19 100644
--- a/src/free_claude_code/providers/openai_chat/profiles.py
+++ b/src/free_claude_code/providers/openai_chat/profiles.py
@@ -54,6 +54,15 @@ _KIMI_CODE_EFFORTS = (
)
+@dataclass(frozen=True, slots=True)
+class OpenAIModelListing:
+ """Declarative model-list endpoint and response shape."""
+
+ path: str | None = None
+ collection_field: str = "data"
+ aliases_field: str | None = None
+
+
@dataclass(frozen=True, slots=True)
class OpenAIChatProfile:
"""Immutable transport and reasoning behavior for one provider."""
@@ -62,6 +71,7 @@ class OpenAIChatProfile:
reasoning: ReasoningEncoder
postprocessors: tuple[OpenAIChatPostprocessor, ...] = ()
model_ids_are_routable: bool = True
+ model_listing: OpenAIModelListing = OpenAIModelListing()
normalize_base_url: bool = False
reasoning_delta_field: Literal["reasoning_content", "reasoning"] = (
"reasoning_content"
@@ -139,6 +149,19 @@ def _policy(
OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
+ "xai": OpenAIChatProfile(
+ _policy(
+ "XAI",
+ ReasoningReplayMode.REASONING_CONTENT,
+ default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+ ),
+ NO_REASONING,
+ model_listing=OpenAIModelListing(
+ path="/language-models",
+ collection_field="models",
+ aliases_field="aliases",
+ ),
+ ),
"azure_openai": OpenAIChatProfile(
_policy(
"AZURE_OPENAI",
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index 66c2725f..5d7bce0f 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -143,16 +143,29 @@ class OpenAIChatProvider(BaseProvider):
payload = await self._list_models_payload()
if not self._profile.model_ids_are_routable:
return frozenset()
- return extract_openai_model_infos(payload, provider_name=self._provider_name)
+ listing = self._profile.model_listing
+ return extract_openai_model_infos(
+ payload,
+ provider_name=self._provider_name,
+ collection_field=listing.collection_field,
+ aliases_field=listing.aliases_field,
+ )
async def _list_models_payload(self) -> Any:
"""Fetch one OpenAI-compatible model-list payload with shared retries."""
payload = await self._admission.run_with_retry(
- self._client.models.list,
+ self._fetch_models_payload,
provider_failure_override=self._provider_failure_override,
)
return payload
+ async def _fetch_models_payload(self) -> Any:
+ """Fetch the profile-selected model-list endpoint once."""
+ path = self._profile.model_listing.path
+ if path is None:
+ return await self._client.models.list()
+ return await self._client.get(path, cast_to=object)
+
def _build_request_body(
self,
request: MessagesRequest,
diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.py
index 4ce18242..efdd230c 100644
--- a/tests/contracts/test_provider_catalog_order.py
+++ b/tests/contracts/test_provider_catalog_order.py
@@ -10,6 +10,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"open_router",
"groq",
"openai",
+ "xai",
"azure_openai",
"gemini",
"vertex",
diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.py
index 29d529f1..6febfa1c 100644
--- a/tests/contracts/test_smoke_config.py
+++ b/tests/contracts/test_smoke_config.py
@@ -53,6 +53,7 @@ def _settings(**overrides):
"vertex_project_id": "",
"vertex_location": "global",
"groq_api_key": "",
+ "xai_api_key": "",
"sambanova_api_key": "",
"cerebras_api_key": "",
"ollama_api_key": "",
@@ -151,6 +152,23 @@ def test_provider_smoke_models_cover_configured_providers_independent_of_model_m
assert models[0].source == "provider_default"
+def test_xai_provider_smoke_uses_current_grok_model(monkeypatch) -> None:
+ monkeypatch.delenv("FCC_SMOKE_MODEL_XAI", raising=False)
+ config = _smoke_config(
+ settings=_settings(
+ model="ollama/llama3.1",
+ ollama_base_url="",
+ xai_api_key="xai-key",
+ )
+ )
+
+ models = config.provider_smoke_models()
+
+ assert [model.provider for model in models] == ["xai"]
+ assert models[0].full_model == "xai/grok-4.5"
+ assert models[0].source == "provider_default"
+
+
def test_connected_account_provider_smoke_requires_explicit_model(
monkeypatch,
) -> None:
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index 2b5013a8..138c2484 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -23,6 +23,7 @@ from free_claude_code.config.provider_catalog import (
SUPPORTED_PROVIDER_IDS,
TOKENROUTER_DEFAULT_BASE,
VERCEL_AI_GATEWAY_DEFAULT_BASE,
+ XAI_DEFAULT_BASE,
ZAI_DEFAULT_BASE,
)
from free_claude_code.providers.admission import ProviderAdmissionController
@@ -60,6 +61,7 @@ def _make_settings(**overrides):
mock.azure_openai_base_url = "https://test-resource.openai.azure.com/openai/v1/"
mock.nvidia_nim_api_key = "test_key"
mock.open_router_api_key = "test_openrouter_key"
+ mock.xai_api_key = "test_xai_key"
mock.mistral_api_key = "test_mistral_key"
mock.codestral_api_key = "test_codestral_key"
mock.deepseek_api_key = "test_deepseek_key"
@@ -123,6 +125,7 @@ def _make_settings(**overrides):
mock.kilo_api_key = "test_kilo_key"
mock.kilo_proxy = ""
mock.openai_proxy = ""
+ mock.xai_proxy = ""
mock.azure_openai_proxy = ""
mock.provider_rate_limit = 40
mock.provider_rate_window = 60
@@ -192,6 +195,25 @@ def test_ollama_cloud_provider_config_uses_key_and_proxy():
assert config.proxy == "http://proxy.test:8080"
+def test_xai_provider_config_uses_key_base_and_proxy() -> None:
+ descriptor = PROVIDER_CATALOG["xai"]
+ settings = _make_settings(
+ xai_api_key="xai-token",
+ xai_proxy="http://proxy.test:8080",
+ )
+
+ config = build_provider_config(descriptor, settings)
+ with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):
+ provider = create_provider("xai", settings)
+
+ assert descriptor.display_name == "xAI (Grok)"
+ assert descriptor.credential_env == "XAI_API_KEY"
+ assert config.api_key == "xai-token"
+ assert config.base_url == XAI_DEFAULT_BASE
+ assert config.proxy == "http://proxy.test:8080"
+ assert isinstance(provider, OpenAIChatProvider)
+
+
def test_bedrock_provider_config_uses_regional_base_key_and_proxy() -> None:
descriptor = PROVIDER_CATALOG["bedrock"]
settings = _make_settings(
@@ -483,6 +505,7 @@ def test_create_provider_instantiates_each_builtin():
cases = {
"nvidia_nim": NvidiaNimProvider,
"openai": OpenAICodexProvider,
+ "xai": OpenAIChatProvider,
"azure_openai": OpenAIChatProvider,
"open_router": OpenRouterProvider,
"mistral": MistralProvider,
diff --git a/tests/providers/test_xai.py b/tests/providers/test_xai.py
new file mode 100644
index 00000000..bfa6b438
--- /dev/null
+++ b/tests/providers/test_xai.py
@@ -0,0 +1,265 @@
+"""Tests for the xAI OpenAI-chat provider profile and model catalog."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+from openai import AsyncOpenAI
+
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+from free_claude_code.config.provider_catalog import XAI_DEFAULT_BASE
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.openai_chat import OpenAIChatProvider
+from tests.providers.support import (
+ REASONING_OFF,
+ REASONING_ON,
+ immediate_admission,
+ profiled_provider,
+ reasoning_for,
+)
+
+
+def xai_provider() -> OpenAIChatProvider:
+ return profiled_provider(
+ "xai",
+ ProviderConfig(
+ api_key="test-xai-key",
+ base_url=XAI_DEFAULT_BASE,
+ rate_limit=10,
+ rate_window=60,
+ ),
+ admission=immediate_admission(provider_name="xai"),
+ )
+
+
+def test_init_uses_openai_chat_provider(xai_provider: OpenAIChatProvider) -> None:
+ assert xai_provider._api_key == "test-xai-key"
+ assert xai_provider._base_url == "https://api.x.ai/v1"
+ assert xai_provider._provider_name == "XAI"
+
+
+def test_build_request_body_preserves_common_chat_tools_and_images(
+ xai_provider: OpenAIChatProvider,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "grok-4.5",
+ "system": "Be concise.",
+ "messages": [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "Inspect this image."},
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": "aW1hZ2U=",
+ },
+ },
+ ],
+ }
+ ],
+ "tools": [
+ {
+ "name": "inspect_image",
+ "description": "Inspect an image",
+ "input_schema": {
+ "type": "object",
+ "properties": {"detail": {"type": "string"}},
+ },
+ }
+ ],
+ }
+ )
+
+ body = xai_provider._build_request_body(
+ request,
+ reasoning=reasoning_for(request),
+ )
+
+ assert body["model"] == "grok-4.5"
+ assert body["max_tokens"] == ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+ assert body["messages"][0] == {"role": "system", "content": "Be concise."}
+ user_content = body["messages"][1]["content"]
+ assert user_content[0] == {"type": "text", "text": "Inspect this image."}
+ assert user_content[1] == {
+ "type": "image_url",
+ "image_url": {"url": "data:image/png;base64,aW1hZ2U="},
+ }
+ assert body["tools"][0]["function"]["name"] == "inspect_image"
+
+
[email protected]("reasoning", [REASONING_OFF, REASONING_ON])
+def test_build_request_body_does_not_invent_catalog_wide_reasoning_control(
+ xai_provider: OpenAIChatProvider,
+ reasoning,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "grok-4.5",
+ "messages": [{"role": "user", "content": "Hello"}],
+ }
+ )
+
+ body = xai_provider._build_request_body(request, reasoning=reasoning)
+
+ assert "reasoning_effort" not in body
+ assert "reasoning" not in body.get("extra_body", {})
+
+
+def test_build_request_body_replays_prior_reasoning_content(
+ xai_provider: OpenAIChatProvider,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "grok-4.5",
+ "messages": [
+ {"role": "user", "content": "Solve it."},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "Work through it."},
+ {"type": "text", "text": "The answer is 42."},
+ ],
+ },
+ {"role": "user", "content": "Continue."},
+ ],
+ }
+ )
+
+ body = xai_provider._build_request_body(
+ request,
+ reasoning=reasoning_for(request),
+ )
+
+ assert body["messages"][1] == {
+ "role": "assistant",
+ "content": "The answer is 42.",
+ "reasoning_content": "Work through it.",
+ }
+ assert (
+ xai_provider._profile.reasoning_delta(
+ SimpleNamespace(reasoning_content="next thought")
+ )
+ == "next thought"
+ )
+
+
+async def test_lists_language_models_and_routable_aliases(
+ xai_provider: OpenAIChatProvider,
+) -> None:
+ xai_provider._client.get = AsyncMock(
+ return_value={
+ "models": [
+ {
+ "id": "latest",
+ "aliases": ["grok-4.5", "grok-latest"],
+ },
+ {"id": "grok-4.5", "aliases": []},
+ ]
+ }
+ )
+ xai_provider._client.models.list = AsyncMock()
+
+ model_infos = await xai_provider.list_model_infos()
+
+ assert model_infos == frozenset(
+ {
+ ProviderModelInfo("latest"),
+ ProviderModelInfo("grok-4.5"),
+ ProviderModelInfo("grok-latest"),
+ }
+ )
+ xai_provider._client.get.assert_awaited_once_with(
+ "/language-models",
+ cast_to=object,
+ )
+ xai_provider._client.models.list.assert_not_awaited()
+
+
+async def test_language_model_catalog_uses_configured_base_url_and_auth(
+ xai_provider: OpenAIChatProvider,
+) -> None:
+ requests: list[httpx.Request] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ return httpx.Response(
+ 200,
+ json={"models": [{"id": "grok-4.5", "aliases": []}]},
+ )
+
+ await xai_provider._client.close()
+ xai_provider._client = AsyncOpenAI(
+ api_key="wire-xai-key",
+ base_url=XAI_DEFAULT_BASE,
+ max_retries=0,
+ http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+ )
+ try:
+ model_infos = await xai_provider.list_model_infos()
+ finally:
+ await xai_provider.cleanup()
+
+ assert model_infos == frozenset({ProviderModelInfo("grok-4.5")})
+ assert len(requests) == 1
+ assert str(requests[0].url) == "https://api.x.ai/v1/language-models"
+ assert requests[0].headers["authorization"] == "Bearer wire-xai-key"
+
+
+ ("payload", "message"),
+ [
+ ({"data": []}, "top-level models array"),
+ ({"models": [{}]}, "models item to include id"),
+ ({"models": [{"id": "grok"}]}, "include aliases array"),
+ (
+ {"models": [{"id": "grok", "aliases": [""]}]},
+ "aliases item to be a model id",
+ ),
+ ({"models": []}, "did not include any model ids"),
+ ],
+)
+async def test_rejects_malformed_language_model_catalog_atomically(
+ xai_provider: OpenAIChatProvider,
+ payload: dict,
+ message: str,
+) -> None:
+ xai_provider._client.get = AsyncMock(return_value=payload)
+
+ with pytest.raises(ModelListResponseError, match=message):
+ await xai_provider.list_model_infos()
+
+
+async def test_language_model_catalog_uses_shared_retry_admission(
+ xai_provider: OpenAIChatProvider,
+) -> None:
+ request = httpx.Request("GET", "https://api.x.ai/v1/language-models")
+ response = httpx.Response(429, request=request)
+ rate_limit_error = httpx.HTTPStatusError(
+ "rate limited",
+ request=request,
+ response=response,
+ )
+ xai_provider._client.get = AsyncMock(
+ side_effect=[
+ rate_limit_error,
+ {"models": [{"id": "grok-4.5", "aliases": []}]},
+ ]
+ )
+
+ model_infos = await xai_provider.list_model_infos()
+
+ assert model_infos == frozenset({ProviderModelInfo("grok-4.5")})
+ assert xai_provider._client.get.await_count == 2
diff --git a/uv.lock b/uv.lock
index 00b4857c..26a049b7 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.20.0"
+version = "4.21.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },