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

Separate model catalogs from HTTP and sort pickers (#1802)

Ali Khokharb9aa5a637e10
diff --git a/e2e/test_admin_models.py b/e2e/test_admin_models.py
index 777cae35..48039825 100644
--- a/e2e/test_admin_models.py
+++ b/e2e/test_admin_models.py
@@ -130,3 +130,67 @@ def test_fallback_editor_remains_usable_at_narrow_viewport(
assert page.evaluate(
"document.documentElement.scrollWidth <= document.documentElement.clientWidth"
)
+
+
+def test_model_suggestions_keep_server_order_after_provider_check_and_late_response(
+ page: Page,
+ admin_base_url: str,
+) -> None:
+ models = [
+ "alpha/Apple",
+ "alpha/apple",
+ "alpha/ss",
+ "alpha/ß",
+ "alpha/z",
+ "alpha-2/model",
+ ]
+ page.route(
+ "**/admin/api/models",
+ lambda route: route.fulfill(json={"models": models, "failed_providers": []}),
+ )
+ _open_models(page, admin_base_url)
+ page.wait_for_function("!state.startupRequest && !state.startupTimer")
+ field = page.locator('.field[data-key="MODEL_SONNET"]')
+ field.locator("input").fill("")
+ expect(field.get_by_role("option")).to_have_text(["None", *models])
+ field.locator("input").fill("open_router/custom-unsaved")
+ field.locator("input").press("Tab")
+
+ models.append("open_router/new-model")
+ page.route(
+ "**/admin/api/providers/open_router/test",
+ lambda route: route.fulfill(json={"ok": True, "models": ["new-model"]}),
+ )
+ page.get_by_role("button", name="Providers", exact=True).click()
+ with page.expect_request("**/admin/api/models"):
+ page.locator('[data-provider="open_router"]').get_by_role(
+ "button", name="Refresh models", exact=True
+ ).click()
+ page.get_by_role("button", name="Model Config", exact=True).click()
+ expect(field.locator("input")).to_have_value("open_router/custom-unsaved")
+ field.locator("input").fill("")
+ expect(field.get_by_role("option")).to_have_text(["None", *models])
+ field.locator("input").press("Escape")
+ optional = page.locator('.field[data-key="MODEL_OPUS"]')
+ optional.locator("input").fill("")
+ expect(optional.get_by_role("option")).to_have_text(["None", *models])
+
+ page.wait_for_function("!state.startupRequest && !state.startupTimer")
+ page.unroute("**/admin/api/models")
+ pending = []
+
+ def hold_catalog(route):
+ pending.append(route)
+ page.evaluate("count => { window.heldCatalogLoads = count; }", len(pending))
+
+ page.route("**/admin/api/models", hold_catalog)
+ for _ in range(2):
+ with page.expect_request("**/admin/api/models"):
+ page.evaluate("void hydrateModelOptions()")
+ page.wait_for_function("window.heldCatalogLoads === 2")
+ with page.expect_response("**/admin/api/models"):
+ pending[1].fulfill(json={"models": models, "failed_providers": []})
+ with page.expect_response("**/admin/api/models") as stale:
+ pending[0].fulfill(json={"models": ["old/stale"], "failed_providers": []})
+ stale.value.finished()
+ expect(optional.get_by_role("option")).to_have_text(["None", *models])
diff --git a/e2e/test_code_sessions.py b/e2e/test_code_sessions.py
index 1ec872c8..22ed514b 100644
--- a/e2e/test_code_sessions.py
+++ b/e2e/test_code_sessions.py
@@ -14,6 +14,49 @@ from free_claude_code.runtime.codex_protocol import CodexProtocol
from tests.code_sessions_support import CodexPackets
+def test_model_picker_uses_application_order_and_keeps_configured_selection(
+ page,
+ admin_base_url,
+ tmp_path,
+ code_control,
+ monkeypatch,
+):
+ from free_claude_code.application.model_metadata import ProviderModelInfo
+ from free_claude_code.config.settings import Settings
+ from free_claude_code.runtime.codex_app_server import CodexHarnessFactory
+ from tests.runtime.test_codex_catalog import FakeRequestRuntime
+
+ refs = (
+ "deepseek/other",
+ "open_router/Apple",
+ "open_router/apple",
+ "open_router/Zulu",
+ )
+ code_control.harness.model = refs[-1]
+ code_control.harness.configurations = dict.fromkeys(refs, "capabilities")
+ runtime = FakeRequestRuntime(
+ settings=Settings().model_copy(update={"model": refs[-1]}),
+ cached_infos=tuple(ProviderModelInfo(ref) for ref in reversed(refs)),
+ )
+ factory = CodexHarnessFactory(runtime, binary="codex")
+ monkeypatch.setattr(code_control.harness, "catalog", factory.catalog)
+ create_session(page, admin_base_url, tmp_path)
+ expect(page.locator("#codeProvider")).to_have_value("open_router")
+ expect(page.locator("#codeModel")).to_have_value("Zulu")
+ assert page.locator("#codeProvider option").evaluate_all(
+ "options => options.map(option => option.value)"
+ ) == ["deepseek", "open_router"]
+ page.locator("#codeComposer").fill("Keep this draft")
+ page.locator("#codeModel").fill("")
+ expect(page.locator("#codeModel").locator("..").get_by_role("option")).to_have_text(
+ ["Apple", "apple", "Zulu"]
+ )
+ page.locator("#codeModel").press("Escape")
+ page.evaluate("window.CodeSessions.refresh()")
+ expect(page.locator("#codeModel")).to_have_value("Zulu")
+ expect(page.locator("#codeComposer")).to_have_value("Keep this draft")
+
+
@pytest.mark.parametrize("width", [1440, 900, 390])
def test_five_header_controls_fit_without_hiding_composer(
page, admin_base_url, tmp_path, code_control, width
diff --git a/pyproject.toml b/pyproject.toml
index e1405661..dc21dee8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "6.2.30"
+version = "6.2.31"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/smoke/capabilities.py b/smoke/capabilities.py
index af2d657f..09c1ecf7 100644
--- a/smoke/capabilities.py
+++ b/smoke/capabilities.py
@@ -593,7 +593,8 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"version, proxy, config conflict, or catalog failure exits without fallback",
(
"tests/cli/test_opencode_launcher.py",
- "tests/harnesses/test_model_catalog.py",
+ "tests/application/test_model_catalog.py",
+ "tests/cli/test_model_catalog_decoder.py",
"tests/cli/test_catalog_http.py",
),
("test_opencode_cli_prompt_e2e",),
@@ -609,7 +610,8 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
(
"tests/cli/test_aider_config.py",
"tests/cli/test_aider_launcher.py",
- "tests/harnesses/test_model_catalog.py",
+ "tests/application/test_model_catalog.py",
+ "tests/cli/test_model_catalog_decoder.py",
"tests/cli/test_catalog_http.py",
),
("test_aider_cli_prompt_e2e",),
@@ -624,7 +626,8 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"version, proxy, catalog, or private-file failure exits before inference",
(
"tests/cli/test_cline_launcher.py",
- "tests/harnesses/test_model_catalog.py",
+ "tests/application/test_model_catalog.py",
+ "tests/cli/test_model_catalog_decoder.py",
"tests/cli/test_catalog_http.py",
),
("test_cline_cli_prompt_e2e",),
@@ -671,7 +674,8 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"version, process config conflict, proxy, or catalog failure exits before inference",
(
"tests/cli/test_grok_launcher.py",
- "tests/harnesses/test_model_catalog.py",
+ "tests/application/test_model_catalog.py",
+ "tests/cli/test_model_catalog_decoder.py",
"tests/cli/test_catalog_http.py",
),
("test_grok_cli_headless_e2e",),
diff --git a/smoke/features.py b/smoke/features.py
index a03515ae..c94e083b 100644
--- a/smoke/features.py
+++ b/smoke/features.py
@@ -136,7 +136,8 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
"OpenCode discovers FCC models and sends Responses through the proxy",
(
"tests/cli/test_opencode_launcher.py",
- "tests/harnesses/test_model_catalog.py",
+ "tests/application/test_model_catalog.py",
+ "tests/cli/test_model_catalog_decoder.py",
"tests/cli/test_catalog_http.py",
),
("test_probe_and_models_routes",),
@@ -154,7 +155,8 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
(
"tests/cli/test_aider_config.py",
"tests/cli/test_aider_launcher.py",
- "tests/harnesses/test_model_catalog.py",
+ "tests/application/test_model_catalog.py",
+ "tests/cli/test_model_catalog_decoder.py",
"tests/cli/test_catalog_http.py",
),
("test_probe_and_models_routes",),
@@ -171,7 +173,8 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
"Cline discovers FCC models and sends Responses through the proxy",
(
"tests/cli/test_cline_launcher.py",
- "tests/harnesses/test_model_catalog.py",
+ "tests/application/test_model_catalog.py",
+ "tests/cli/test_model_catalog_decoder.py",
"tests/cli/test_catalog_http.py",
),
("test_probe_and_models_routes",),
@@ -218,7 +221,8 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
"Grok Build discovers FCC models and sends Responses through the proxy",
(
"tests/cli/test_grok_launcher.py",
- "tests/harnesses/test_model_catalog.py",
+ "tests/application/test_model_catalog.py",
+ "tests/cli/test_model_catalog_decoder.py",
"tests/cli/test_catalog_http.py",
),
("test_probe_and_models_routes",),
diff --git a/src/free_claude_code/api/admin_routes.py b/src/free_claude_code/api/admin_routes.py
index 8dd36e66..7de19135 100644
--- a/src/free_claude_code/api/admin_routes.py
+++ b/src/free_claude_code/api/admin_routes.py
@@ -20,9 +20,9 @@ from free_claude_code.application.connected_accounts import (
ConnectedAccountLoginMode,
)
from free_claude_code.application.errors import ApplicationError
+from free_claude_code.application.model_catalog import read_model_catalog
from free_claude_code.application.model_metadata import ProviderModelRefreshResult
from free_claude_code.config.admin.manifest import FIELD_BY_KEY
-from free_claude_code.config.model_refs import configured_chat_model_refs
from free_claude_code.config.provider_catalog import (
PROVIDER_CATALOG,
ProviderAuthKind,
@@ -329,18 +329,12 @@ def _model_options(
*,
refresh_result: ProviderModelRefreshResult | None = None,
) -> dict[str, list[str]]:
- configured = {
- ref.model_ref
- for ref in configured_chat_model_refs(services.requests.current_settings())
- }
- discovered = {
- info.model_id for info in services.requests.cached_prefixed_model_infos()
- }
+ catalog = read_model_catalog(services.requests)
failed_provider_ids = (
refresh_result.failed_provider_ids if refresh_result is not None else ()
)
return {
- "models": sorted(configured | discovered, key=str.casefold),
+ "models": [model.provider_model_ref for model in catalog.models],
"failed_providers": list(failed_provider_ids),
}
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index cedba273..1fe0b3e9 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -1271,10 +1271,7 @@ async function testProvider(providerId, button) {
"ok",
`${result.models.length} models available`,
);
- setModelOptions([
- ...state.modelOptions,
- ...result.models.map((model) => `${providerId}/${model}`),
- ]);
+ await hydrateModelOptions();
} else {
updateProviderCheckResult(
providerId,
@@ -1354,7 +1351,7 @@ function providerDisplayName(providerId) {
function setModelOptions(models) {
state.modelOptions = Array.from(
new Set(models.filter((model) => typeof model === "string" && model.trim())),
- ).sort((left, right) => left.localeCompare(right));
+ );
state.modelComboboxes.forEach((combobox) => {
if (combobox.isOpen) combobox.render(combobox.query);
});
diff --git a/src/free_claude_code/api/model_catalog.py b/src/free_claude_code/api/model_catalog.py
index 312e7055..c9dce48f 100644
--- a/src/free_claude_code/api/model_catalog.py
+++ b/src/free_claude_code/api/model_catalog.py
@@ -1,14 +1,13 @@
"""Model-list response construction for FCC clients."""
import math
-from dataclasses import dataclass
from enum import StrEnum
from typing import Literal
from pydantic import BaseModel, Field
+from free_claude_code.application.model_catalog import ModelCatalog, read_model_catalog
from free_claude_code.application.ports import ModelCatalogPort
-from free_claude_code.config.model_refs import configured_chat_model_refs
from free_claude_code.config.settings import Settings
from free_claude_code.core.gateway_model_ids import (
gateway_model_id,
@@ -92,6 +91,7 @@ class ModelsListResponse(BaseModel):
first_id: str | None
has_more: bool
last_id: str | None
+ default_model_id: str | None = None
SUPPORTED_CLAUDE_MODELS = [
@@ -138,15 +138,6 @@ SUPPORTED_CLAUDE_MODELS = [
]
-@dataclass(frozen=True, slots=True)
-class _InventoryModel:
- provider_model_ref: str
- supports_thinking: bool | None
- input_modalities: frozenset[ModelInputModality] | None
- context_window_tokens: int | None
- max_output_tokens: int | None
-
-
def build_models_list_response(
settings: Settings,
runtime: ModelCatalogPort,
@@ -154,9 +145,10 @@ def build_models_list_response(
view: ModelCatalogView = ModelCatalogView.CLAUDE,
) -> ModelsListResponse:
"""Return the application model inventory in the requested client view."""
+ catalog = read_model_catalog(runtime, settings)
if view is ModelCatalogView.CLAUDE:
- return _build_claude_models_response(settings, runtime)
- return _build_direct_models_response(settings, runtime, view=view)
+ return _build_claude_models_response(catalog)
+ return _build_direct_models_response(settings, catalog, view=view)
def build_muse_models_list_response(
@@ -186,35 +178,21 @@ def build_muse_models_list_response(
return catalog
-def _build_claude_models_response(
- settings: Settings, runtime: ModelCatalogPort
-) -> ModelsListResponse:
- """Preserve the established Claude-compatible catalog exactly."""
- models: list[ModelResponse] = []
- seen: set[str] = set()
-
- for ref in configured_chat_model_refs(settings):
- model_info = runtime.cached_model_info(ref.provider_id, ref.model_id)
- _append_provider_model_variants(
- models,
- seen,
- ref.model_ref,
- supports_thinking=(
- model_info.supports_thinking if model_info is not None else None
- ),
- )
-
- for model_info in runtime.cached_prefixed_model_infos():
- _append_provider_model_variants(
- models,
- seen,
- model_info.model_id,
- supports_thinking=model_info.supports_thinking,
+def _build_claude_models_response(catalog: ModelCatalog) -> ModelsListResponse:
+ """Keep shortcuts first and provider variants together in catalog order."""
+ models = list(SUPPORTED_CLAUDE_MODELS)
+ for model in catalog.models:
+ ref = model.provider_model_ref
+ if model.supports_reasoning is not False:
+ models.append(
+ _discovered_model_response(gateway_model_id(ref), display_name=ref)
+ )
+ models.append(
+ _discovered_model_response(
+ no_thinking_gateway_model_id(ref),
+ display_name=f"{ref} (no thinking)",
+ )
)
-
- for model in SUPPORTED_CLAUDE_MODELS:
- _append_unique_model(models, seen, model)
-
return ModelsListResponse(
data=models,
first_id=models[0].id if models else None,
@@ -225,7 +203,7 @@ def _build_claude_models_response(
def _build_direct_models_response(
settings: Settings,
- runtime: ModelCatalogPort,
+ catalog: ModelCatalog,
*,
view: ModelCatalogView,
) -> ModelsListResponse:
@@ -236,34 +214,22 @@ def _build_direct_models_response(
else None
)
- for inventory_model in _collect_inventory(settings, runtime):
- provider_model_ref = inventory_model.provider_model_ref
- allows_reasoning = inventory_model.supports_thinking is not False
- model_id = (
- provider_model_ref
- if allows_reasoning
- else no_thinking_gateway_model_id(provider_model_ref)
- )
+ for model in catalog.models:
+ allows_reasoning = model.supports_reasoning is not False
models.append(
ModelResponse(
- id=model_id,
- display_name=(
- provider_model_ref
- if allows_reasoning
- else f"{provider_model_ref} (no thinking)"
- ),
+ id=model.wire_slug,
+ display_name=model.display_name,
created_at=DISCOVERED_MODEL_CREATED_AT,
- provider_model_ref=provider_model_ref,
+ provider_model_ref=model.provider_model_ref,
api_backend=(
"responses" if view is ModelCatalogView.RESPONSES else None
),
max_retries=0 if view is ModelCatalogView.RESPONSES else None,
- supports_reasoning=inventory_model.supports_thinking,
- input_modalities=_serialize_input_modalities(
- inventory_model.input_modalities
- ),
- context_window_tokens=inventory_model.context_window_tokens,
- max_output_tokens=inventory_model.max_output_tokens,
+ supports_reasoning=model.supports_reasoning,
+ input_modalities=_serialize_input_modalities(model.input_modalities),
+ context_window_tokens=model.context_window_tokens,
+ max_output_tokens=model.max_output_tokens,
supports_reasoning_effort=(
allows_reasoning if view is ModelCatalogView.RESPONSES else None
),
@@ -278,58 +244,13 @@ def _build_direct_models_response(
return ModelsListResponse(
data=models,
+ default_model_id=catalog.default_model_id,
first_id=models[0].id if models else None,
has_more=False,
last_id=models[-1].id if models else None,
)
-def _collect_inventory(
- settings: Settings, runtime: ModelCatalogPort
-) -> tuple[_InventoryModel, ...]:
- inventory: list[_InventoryModel] = []
- seen: set[str] = set()
-
- for ref in configured_chat_model_refs(settings):
- if ref.model_ref in seen:
- continue
- seen.add(ref.model_ref)
- model_info = runtime.cached_model_info(ref.provider_id, ref.model_id)
- inventory.append(
- _InventoryModel(
- provider_model_ref=ref.model_ref,
- supports_thinking=(
- model_info.supports_thinking if model_info is not None else None
- ),
- input_modalities=(
- model_info.input_modalities if model_info is not None else None
- ),
- context_window_tokens=(
- model_info.context_window_tokens if model_info is not None else None
- ),
- max_output_tokens=(
- model_info.max_output_tokens if model_info is not None else None
- ),
- )
- )
-
- for model_info in runtime.cached_prefixed_model_infos():
- if model_info.model_id in seen:
- continue
- seen.add(model_info.model_id)
- inventory.append(
- _InventoryModel(
- provider_model_ref=model_info.model_id,
- supports_thinking=model_info.supports_thinking,
- input_modalities=model_info.input_modalities,
- context_window_tokens=model_info.context_window_tokens,
- max_output_tokens=model_info.max_output_tokens,
- )
- )
-
- return tuple(inventory)
-
-
def _serialize_input_modalities(
modalities: frozenset[ModelInputModality] | None,
) -> tuple[ModelInputModality, ...] | None:
@@ -348,38 +269,3 @@ def _discovered_model_response(model_id: str, *, display_name: str) -> ModelResp
display_name=display_name,
created_at=DISCOVERED_MODEL_CREATED_AT,
)
-
-
-def _append_unique_model(
- models: list[ModelResponse], seen: set[str], model: ModelResponse
-) -> None:
- if model.id in seen:
- return
- seen.add(model.id)
- models.append(model)
-
-
-def _append_provider_model_variants(
- models: list[ModelResponse],
- seen: set[str],
- provider_model_ref: str,
- *,
- supports_thinking: bool | None = None,
-) -> None:
- if supports_thinking is not False:
- _append_unique_model(
- models,
- seen,
- _discovered_model_response(
- gateway_model_id(provider_model_ref),
- display_name=provider_model_ref,
- ),
- )
- _append_unique_model(
- models,
- seen,
- _discovered_model_response(
- no_thinking_gateway_model_id(provider_model_ref),
- display_name=f"{provider_model_ref} (no thinking)",
- ),
- )
diff --git a/src/free_claude_code/application/model_catalog.py b/src/free_claude_code/application/model_catalog.py
new file mode 100644
index 00000000..d1646d3f
--- /dev/null
+++ b/src/free_claude_code/application/model_catalog.py
@@ -0,0 +1,95 @@
+"""Application model inventory and presentation order, independent of clients."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from free_claude_code.config.model_refs import (
+ configured_chat_model_refs,
+ split_provider_model_ref,
+)
+from free_claude_code.core.gateway_model_ids import no_thinking_gateway_model_id
+from free_claude_code.core.model_capabilities import ModelInputModality
+
+from .model_metadata import ProviderModelInfo
+
+if TYPE_CHECKING:
+ from free_claude_code.config.settings import Settings
+
+ from .ports import ModelCatalogPort
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogModel:
+ """One exact FCC model identity and its reported capabilities."""
+
+ wire_slug: str
+ provider_model_ref: str
+ display_name: str
+ supports_reasoning: bool | None
+ input_modalities: frozenset[ModelInputModality] | None = None
+ context_window_tokens: int | None = None
+ max_output_tokens: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCatalog:
+ """An ordered inventory with selection independent of list position."""
+
+ models: tuple[CatalogModel, ...]
+ default_model_id: str
+
+
+def model_order_key(provider_model_ref: str) -> tuple[str, str, str, str]:
+ provider, model = split_provider_model_ref(provider_model_ref)
+ return provider.casefold(), model.casefold(), provider, model
+
+
+def read_model_catalog(
+ runtime: ModelCatalogPort, settings: Settings | None = None
+) -> ModelCatalog:
+ """Merge configured and cached models without discovery or provider leases."""
+ settings = settings if settings is not None else runtime.current_settings()
+ models: dict[str, CatalogModel] = {}
+ for ref in configured_chat_model_refs(settings):
+ models[ref.model_ref] = _catalog_model(
+ ref.model_ref, runtime.cached_model_info(ref.provider_id, ref.model_id)
+ )
+ for info in runtime.cached_prefixed_model_infos():
+ if info.model_id not in models:
+ models[info.model_id] = _catalog_model(info.model_id, info)
+ return ModelCatalog(
+ models=tuple(
+ sorted(
+ models.values(),
+ key=lambda model: model_order_key(model.provider_model_ref),
+ )
+ ),
+ default_model_id=models[settings.model].wire_slug,
+ )
+
+
+def _catalog_model(ref: str, info: ProviderModelInfo | None) -> CatalogModel:
+ info = info if info is not None else ProviderModelInfo(ref)
+ no_thinking = info.supports_thinking is False
+ return CatalogModel(
+ wire_slug=no_thinking_gateway_model_id(ref) if no_thinking else ref,
+ provider_model_ref=ref,
+ display_name=f"{ref} (no thinking)" if no_thinking else ref,
+ supports_reasoning=info.supports_thinking,
+ input_modalities=info.input_modalities,
+ context_window_tokens=info.context_window_tokens,
+ max_output_tokens=info.max_output_tokens,
+ )
+
+
+def catalog_wire_slug_for_ref(
+ models: Sequence[CatalogModel], provider_model_ref: str | None
+) -> str | None:
+ """Resolve an explicit selection, retaining a missing or unset reference."""
+ if not provider_model_ref:
+ return provider_model_ref
+ for model in models:
+ if model.provider_model_ref == provider_model_ref:
+ return model.wire_slug
+ return provider_model_ref
diff --git a/src/free_claude_code/cli/launchers/aider.py b/src/free_claude_code/cli/launchers/aider.py
index 8cfdbdda..194d1e6d 100644
--- a/src/free_claude_code/cli/launchers/aider.py
+++ b/src/free_claude_code/cli/launchers/aider.py
@@ -13,9 +13,10 @@ from .runner import HarnessSpec, LaunchContext, launch_harness
def _configure(
ctx: LaunchContext, args: list[str], files: LaunchResources
) -> PreparedLaunch:
+ catalog = ctx.require_catalog()
key_env = f"{AIDER_API_KEY_ENV_PREFIX}{ctx.launch_id.upper()}"
config = build_aider_config(
- ctx.models,
+ catalog.models,
messages_url=f"{ctx.proxy_root_url.rstrip('/')}/v1/messages",
api_key_env=key_env,
launch_id=ctx.launch_id,
@@ -31,7 +32,7 @@ def _configure(
case_sensitive=False,
updates={
key_env: ctx.auth_token,
- "AIDER_MODEL": ctx.models[0].wire_slug,
+ "AIDER_MODEL": catalog.default_model_id,
"AIDER_MODEL_SETTINGS_FILE": str(settings_path),
"AIDER_MODEL_METADATA_FILE": str(metadata_path),
},
diff --git a/src/free_claude_code/cli/launchers/aider_config.py b/src/free_claude_code/cli/launchers/aider_config.py
index eab6ca61..8df335c5 100644
--- a/src/free_claude_code/cli/launchers/aider_config.py
+++ b/src/free_claude_code/cli/launchers/aider_config.py
@@ -3,9 +3,9 @@
import re
from dataclasses import dataclass, field
+from free_claude_code.application.model_catalog import CatalogModel, model_order_key
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
AIDER_API_KEY_ENV_PREFIX = "FCC_AIDER_PROXY_AUTH_"
_AIDER_API_KEY_ENV_PATTERN = re.compile(rf"{AIDER_API_KEY_ENV_PREFIX}[A-Z0-9]+")
@@ -20,7 +20,7 @@ class AiderConfig:
def build_aider_config(
- models: tuple[ClientModel, ...],
+ models: tuple[CatalogModel, ...],
*,
messages_url: str,
api_key_env: str,
@@ -38,7 +38,14 @@ def build_aider_config(
by_name.setdefault(f"anthropic/{model.wire_slug}", model)
settings: list[JsonObject] = []
metadata: JsonObject = {}
- for name, model in by_name.items():
+ for name, model in sorted(
+ by_name.items(),
+ key=lambda item: (
+ model_order_key(item[1].provider_model_ref),
+ item[0] != item[1].wire_slug,
+ item[0],
+ ),
+ ):
entry: JsonObject = {
"name": name,
"weak_model_name": name,
@@ -59,7 +66,7 @@ def build_aider_config(
return AiderConfig(settings=settings, metadata=metadata)
-def _model_metadata(model: ClientModel) -> JsonObject:
+def _model_metadata(model: CatalogModel) -> JsonObject:
metadata: JsonObject = {
"litellm_provider": "anthropic",
"mode": "chat",
diff --git a/src/free_claude_code/cli/launchers/catalog_http.py b/src/free_claude_code/cli/launchers/catalog_http.py
index a1243f24..fa8269ce 100644
--- a/src/free_claude_code/cli/launchers/catalog_http.py
+++ b/src/free_claude_code/cli/launchers/catalog_http.py
@@ -1,20 +1,23 @@
"""Authenticated local catalog acquisition for terminal launchers."""
import json
+from collections.abc import Mapping
from typing import Literal
from urllib.request import Request
+from free_claude_code.application.model_catalog import CatalogModel, ModelCatalog
from free_claude_code.cli.local_http import open_local_request
-from free_claude_code.core.json_types import JsonObject, JsonValue
+from free_claude_code.core.json_types import JsonValue
+from free_claude_code.core.model_capabilities import ModelInputModality
CATALOG_TIMEOUT_SECONDS = 35.0
-def fetch_proxy_models_response(
+def fetch_proxy_model_catalog(
proxy_root_url: str,
auth_token: str,
view: Literal["messages", "responses"] = "responses",
-) -> JsonObject:
+) -> ModelCatalog:
"""Fetch the authenticated FCC-local `/v1/models` response directly."""
url = f"{proxy_root_url.rstrip('/')}/v1/models?view={view}"
@@ -28,4 +31,104 @@ def fetch_proxy_models_response(
if not isinstance(payload, dict):
raise ValueError("model list response was not a JSON object")
- return payload
+ return model_catalog_from_response(payload)
+
+
+def model_catalog_from_response(payload: Mapping[str, JsonValue]) -> ModelCatalog:
+ models = catalog_models_from_response(payload)
+ if not models:
+ raise ValueError("model catalog contains no routable models")
+ default_model_id = _nonempty_string(payload.get("default_model_id"))
+ if default_model_id is None:
+ raise ValueError(
+ "model catalog is missing its default; restart the FCC server after updating"
+ )
+ if not any(model.wire_slug == default_model_id for model in models):
+ raise ValueError("model catalog default is not a routable model")
+ return ModelCatalog(models, default_model_id)
+
+
+def catalog_models_from_response(
+ models_response: Mapping[str, JsonValue],
+) -> tuple[CatalogModel, ...]:
+ """Project an FCC `/v1/models` response into direct client model records."""
+
+ models: list[CatalogModel] = []
+ seen_slugs: set[str] = set()
+
+ for candidate in _catalog_candidates(models_response):
+ if candidate.wire_slug in seen_slugs:
+ continue
+ seen_slugs.add(candidate.wire_slug)
+ models.append(candidate)
+
+ return tuple(models)
+
+
+def _catalog_candidates(
+ models_response: Mapping[str, JsonValue],
+) -> list[CatalogModel]:
+ data = models_response.get("data")
+ if not isinstance(data, list):
+ return []
+
+ candidates: list[CatalogModel] = []
+ for item in data:
+ if not isinstance(item, Mapping):
+ continue
+ model_id = _nonempty_string(item.get("id"))
+ if model_id is None:
+ continue
+ provider_model_ref = _provider_model_ref(item.get("provider_model_ref"))
+ if provider_model_ref is None:
+ continue
+ candidates.append(
+ CatalogModel(
+ wire_slug=model_id,
+ provider_model_ref=provider_model_ref,
+ display_name=_nonempty_string(item.get("display_name")) or model_id,
+ supports_reasoning=_optional_boolean(item.get("supportsReasoning")),
+ input_modalities=_input_modalities(item.get("inputModalities")),
+ context_window_tokens=_optional_positive_int(item.get("contextWindow")),
+ max_output_tokens=_optional_positive_int(
+ item.get("maxCompletionTokens")
+ ),
+ )
+ )
+ return candidates
+
+
+def _nonempty_string(value: object) -> str | None:
+ if not isinstance(value, str):
+ return None
+ return value if value.strip() else None
+
+
+def _optional_boolean(value: object) -> bool | None:
+ return value if isinstance(value, bool) else None
+
+
+def _optional_positive_int(value: object) -> int | None:
+ return value if type(value) is int and value > 0 else None
+
+
+def _input_modalities(value: object) -> frozenset[ModelInputModality] | None:
+ if not isinstance(value, list) or not value:
+ return None
+ try:
+ modalities = frozenset(ModelInputModality(item) for item in value)
+ except TypeError, ValueError:
+ return None
+ if ModelInputModality.TEXT not in modalities:
+ return None
+ return modalities
+
+
+def _provider_model_ref(value: object) -> str | None:
+ ref = _nonempty_string(value)
+ if ref is None:
+ return None
+ provider_id, separator, model_id = ref.partition("/")
+ if not separator or not provider_id or not model_id:
+ return None
+ return ref
diff --git a/src/free_claude_code/cli/launchers/cline.py b/src/free_claude_code/cli/launchers/cline.py
index b50528c0..4520957f 100644
--- a/src/free_claude_code/cli/launchers/cline.py
+++ b/src/free_claude_code/cli/launchers/cline.py
@@ -19,8 +19,10 @@ _VERSION_PATTERN = re.compile(
def _configure(
ctx: LaunchContext, args: list[str], files: LaunchResources
) -> PreparedLaunch:
+ catalog = ctx.require_catalog()
config = build_cline_config(
- ctx.models,
+ catalog.models,
+ default_model_id=catalog.default_model_id,
proxy_root_url=ctx.proxy_root_url,
auth_token=ctx.auth_token,
launch_id=ctx.launch_id,
diff --git a/src/free_claude_code/cli/launchers/cline_config.py b/src/free_claude_code/cli/launchers/cline_config.py
index cc1b317f..e157fadc 100644
--- a/src/free_claude_code/cli/launchers/cline_config.py
+++ b/src/free_claude_code/cli/launchers/cline_config.py
@@ -3,10 +3,10 @@
from dataclasses import dataclass, field
from datetime import UTC, datetime
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.config.server_urls import proxy_v1_url
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
# Cline's released session gateway only instantiates built-in providers. FCC
# replaces this process-local Responses provider's endpoint and catalog instead
@@ -23,8 +23,9 @@ class ClineConfig:
def build_cline_config(
- models: tuple[ClientModel, ...],
+ models: tuple[CatalogModel, ...],
*,
+ default_model_id: str,
proxy_root_url: str,
auth_token: str,
launch_id: str,
@@ -38,12 +39,11 @@ def build_cline_config(
timestamp = (
(now or datetime.now(UTC)).astimezone(UTC).isoformat().replace("+00:00", "Z")
)
- default_model = models[0].wire_slug
provider_settings: JsonObject = {
"provider": CLINE_PROVIDER_ID,
"apiKey": auth_token,
"headers": {"x-fcc-launch-id": launch_id},
- "model": default_model,
+ "model": default_model_id,
"protocol": "openai-responses",
"baseUrl": proxy_v1_url(proxy_root_url),
"capabilities": ["streaming", "tools"],
@@ -72,7 +72,7 @@ def build_cline_config(
"provider": {
"name": "Free Claude Code",
"baseUrl": proxy_v1_url(proxy_root_url),
- "defaultModelId": default_model,
+ "defaultModelId": default_model_id,
"protocol": "openai-responses",
"client": "openai",
"capabilities": ["streaming", "tools"],
@@ -84,7 +84,7 @@ def build_cline_config(
)
-def _model_entry(model: ClientModel) -> JsonObject:
+def _model_entry(model: CatalogModel) -> JsonObject:
supports_reasoning = model.supports_reasoning is not False
supports_vision = (
model.input_modalities is not None
diff --git a/src/free_claude_code/cli/launchers/codex.py b/src/free_claude_code/cli/launchers/codex.py
index 50da51e0..aaa075fe 100644
--- a/src/free_claude_code/cli/launchers/codex.py
+++ b/src/free_claude_code/cli/launchers/codex.py
@@ -18,11 +18,12 @@ from .runner import HarnessSpec, LaunchContext, launch_harness
def _configure(
ctx: LaunchContext, args: list[str], files: LaunchResources
) -> PreparedLaunch:
+ catalog = ctx.require_catalog()
return prepare_codex_launch(
binary_path=ctx.binary_path,
proxy_root_url=ctx.proxy_root_url,
model=ctx.settings.model,
- models=ctx.models,
+ models=catalog.models,
base_env=ctx.base_env,
args=args,
files=files,
diff --git a/src/free_claude_code/cli/launchers/dsh.py b/src/free_claude_code/cli/launchers/dsh.py
index 5c1f499e..f61dbc82 100644
--- a/src/free_claude_code/cli/launchers/dsh.py
+++ b/src/free_claude_code/cli/launchers/dsh.py
@@ -18,10 +18,12 @@ _VERSION_PATTERN = re.compile(
def _configure(
ctx: LaunchContext, args: list[str], files: LaunchResources
) -> PreparedLaunch:
+ catalog = ctx.require_catalog()
settings_path = files.write_json("settings.yaml", {})
credentials_path = files.write_json(".credentials.yaml", {})
config = build_dsh_launch_config(
- ctx.models,
+ catalog.models,
+ default_model_id=catalog.default_model_id,
proxy_root_url=ctx.proxy_root_url,
settings_path=settings_path,
credentials_path=credentials_path,
diff --git a/src/free_claude_code/cli/launchers/dsh_config.py b/src/free_claude_code/cli/launchers/dsh_config.py
index 3b03d303..bd7237a4 100644
--- a/src/free_claude_code/cli/launchers/dsh_config.py
+++ b/src/free_claude_code/cli/launchers/dsh_config.py
@@ -3,10 +3,10 @@
import math
from pathlib import Path
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.config.server_urls import proxy_v1_url
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
DSH_API_KEY_ENV = "FCC_DSH_API_KEY"
DSH_ENV_PREFIX = "FCC_DSH_"
@@ -26,8 +26,9 @@ _REASONING_EFFORTS: JsonObject = {
def build_dsh_launch_config(
- models: tuple[ClientModel, ...],
+ models: tuple[CatalogModel, ...],
*,
+ default_model_id: str,
proxy_root_url: str,
settings_path: Path,
credentials_path: Path,
@@ -39,7 +40,6 @@ def build_dsh_launch_config(
raise ValueError("DeepSeek Harness requires at least one routable FCC model")
stream_idle_timeout_ms = _stream_idle_timeout_ms(provider_progress_timeout)
- selected_model = models[0].wire_slug
provider: JsonObject = {
"displayName": "Free Claude Code",
"apiKeyEnv": DSH_API_KEY_ENV,
@@ -69,7 +69,7 @@ def build_dsh_launch_config(
_configured_row(
"agent-default-model",
"@deepseek-ai/dsh-agent-default-model",
- {"provider": DSH_PROVIDER_ID, "model": selected_model},
+ {"provider": DSH_PROVIDER_ID, "model": default_model_id},
),
_disabled_row("llm-deepseek", "@deepseek-ai/dsh-llm-deepseek"),
_disabled_row(
@@ -95,7 +95,7 @@ def _stream_idle_timeout_ms(provider_progress_timeout: float) -> int:
return timeout_ms
-def _model_profile(model: ClientModel) -> JsonObject:
+def _model_profile(model: CatalogModel) -> JsonObject:
profile: JsonObject = {
"id": model.wire_slug,
"name": model.display_name,
diff --git a/src/free_claude_code/cli/launchers/grok.py b/src/free_claude_code/cli/launchers/grok.py
index df19c5a0..66015d7f 100644
--- a/src/free_claude_code/cli/launchers/grok.py
+++ b/src/free_claude_code/cli/launchers/grok.py
@@ -55,9 +55,10 @@ def _compatible_version(output: str) -> bool:
def _configure(
ctx: LaunchContext, args: list[str], _files: LaunchResources
) -> PreparedLaunch:
+ catalog = ctx.require_catalog()
require_unset_environment(ctx.base_env, _PROCESS_CONFIG_KEYS)
v1_url = proxy_v1_url(ctx.proxy_root_url)
- default_model = ctx.models[0].wire_slug
+ default_model = catalog.default_model_id
env = client_environment(
ctx.base_env,
proxy_root_url=ctx.proxy_root_url,
@@ -76,7 +77,7 @@ def _configure(
"GROK_CONFIG": json.dumps(
{
"models": {
- "allowed_models": [model.wire_slug for model in ctx.models]
+ "allowed_models": [model.wire_slug for model in catalog.models]
},
"shell_environment_policy": {"ignore_default_excludes": False},
},
diff --git a/src/free_claude_code/cli/launchers/hermes.py b/src/free_claude_code/cli/launchers/hermes.py
index 650ab6c3..057f9df1 100644
--- a/src/free_claude_code/cli/launchers/hermes.py
+++ b/src/free_claude_code/cli/launchers/hermes.py
@@ -33,11 +33,15 @@ def _overlay_loaded(output: str, expected_provider: str) -> bool:
def _configure(
ctx: LaunchContext, args: list[str], files: LaunchResources
) -> PreparedLaunch:
+ catalog = ctx.require_catalog()
require_unset_environment(ctx.base_env, ("HERMES_MANAGED_DIR",))
if os.name != "nt" and Path("/etc/hermes").exists():
raise ValueError("An existing Hermes managed policy cannot be replaced by FCC.")
managed = build_hermes_managed_config(
- ctx.models, proxy_root_url=ctx.proxy_root_url, nonce=ctx.launch_id
+ catalog.models,
+ default_model_id=catalog.default_model_id,
+ proxy_root_url=ctx.proxy_root_url,
+ nonce=ctx.launch_id,
)
path = files.write_json("config.yaml", managed.config)
env = client_environment(
diff --git a/src/free_claude_code/cli/launchers/hermes_config.py b/src/free_claude_code/cli/launchers/hermes_config.py
index 9150db5f..95a2e4c1 100644
--- a/src/free_claude_code/cli/launchers/hermes_config.py
+++ b/src/free_claude_code/cli/launchers/hermes_config.py
@@ -2,10 +2,10 @@
from dataclasses import dataclass, field
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.config.server_urls import proxy_v1_url
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
HERMES_PROVIDER_PREFIX = "fcc-"
HERMES_KEY_ENV_PREFIX = "FCC_HERMES_"
@@ -43,8 +43,9 @@ class HermesManagedConfig:
def build_hermes_managed_config(
- models: tuple[ClientModel, ...],
+ models: tuple[CatalogModel, ...],
*,
+ default_model_id: str,
proxy_root_url: str,
nonce: str,
) -> HermesManagedConfig:
@@ -56,7 +57,6 @@ def build_hermes_managed_config(
raise ValueError("Hermes configuration nonce must be alphanumeric")
wire_slugs = tuple(model.wire_slug for model in models)
- active_model = wire_slugs[0]
provider_key = f"{HERMES_PROVIDER_PREFIX}{nonce.lower()}"
provider_ref = f"custom:{provider_key}"
@@ -80,14 +80,14 @@ def build_hermes_managed_config(
"Authorization": f"Bearer ${{{key_env}}}",
},
"transport": "codex_responses",
- "default_model": active_model,
+ "default_model": default_model_id,
"models": {wire_slug: {} for wire_slug in wire_slugs},
"discover_models": False,
}
},
"model": {
"provider": provider_ref,
- "default": active_model,
+ "default": default_model_id,
"base_url": "",
"api_key": "",
"api_mode": "codex_responses",
@@ -103,7 +103,7 @@ def build_hermes_managed_config(
config=config,
provider_ref=provider_ref,
key_env=key_env,
- default_model=active_model,
+ default_model=default_model_id,
)
@@ -121,7 +121,7 @@ def _auxiliary_task_config(task: str, *, provider_ref: str) -> JsonObject:
return config
-def _model_override(model: ClientModel) -> JsonObject:
+def _model_override(model: CatalogModel) -> JsonObject:
override: JsonObject = {}
if model.supports_reasoning is not None:
override["supports_reasoning"] = model.supports_reasoning
diff --git a/src/free_claude_code/cli/launchers/muse.py b/src/free_claude_code/cli/launchers/muse.py
index d5a9f957..4e626cbf 100644
--- a/src/free_claude_code/cli/launchers/muse.py
+++ b/src/free_claude_code/cli/launchers/muse.py
@@ -29,6 +29,7 @@ _ROUTING_ENV_KEYS = frozenset(
def _configure(
ctx: LaunchContext, args: list[str], _files: LaunchResources
) -> PreparedLaunch:
+ catalog = ctx.require_catalog()
connection = ["--provider", "meta", "--base-url", proxy_v1_url(ctx.proxy_root_url)]
if args and args[0] in {"exec", "resume"}:
command = [ctx.binary_path, args[0], *connection, *args[1:]]
@@ -43,7 +44,7 @@ def _configure(
remove_prefixes=("FCC_MUSE_",),
updates={
"META_API_KEY": ctx.auth_token,
- "MUSE_MODEL": ctx.models[0].wire_slug,
+ "MUSE_MODEL": catalog.default_model_id,
},
),
)
diff --git a/src/free_claude_code/cli/launchers/opencode.py b/src/free_claude_code/cli/launchers/opencode.py
index f62841f3..e0f49bbb 100644
--- a/src/free_claude_code/cli/launchers/opencode.py
+++ b/src/free_claude_code/cli/launchers/opencode.py
@@ -24,8 +24,13 @@ _PROCESS_CONFIG_KEYS = ("OPENCODE_CONFIG", "OPENCODE_CONFIG_CONTENT")
def _configure(
ctx: LaunchContext, args: list[str], files: LaunchResources
) -> PreparedLaunch:
+ catalog = ctx.require_catalog()
require_unset_environment(ctx.base_env, _PROCESS_CONFIG_KEYS)
- config = build_opencode_config(ctx.models, proxy_root_url=ctx.proxy_root_url)
+ config = build_opencode_config(
+ catalog.models,
+ default_model_id=catalog.default_model_id,
+ proxy_root_url=ctx.proxy_root_url,
+ )
path = files.write_json("opencode.json", config.file)
return PreparedLaunch(
[ctx.binary_path, *args],
diff --git a/src/free_claude_code/cli/launchers/opencode_config.py b/src/free_claude_code/cli/launchers/opencode_config.py
index c7cddcb1..d041f609 100644
--- a/src/free_claude_code/cli/launchers/opencode_config.py
+++ b/src/free_claude_code/cli/launchers/opencode_config.py
@@ -2,10 +2,10 @@
from dataclasses import dataclass
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.config.server_urls import proxy_v1_url
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
OPENCODE_API_KEY_ENV = "FCC_OPENCODE_API_KEY"
OPENCODE_PROVIDER_ID = "free-claude-code"
@@ -20,7 +20,7 @@ class OpenCodeConfig:
def build_opencode_config(
- models: tuple[ClientModel, ...], *, proxy_root_url: str
+ models: tuple[CatalogModel, ...], *, default_model_id: str, proxy_root_url: str
) -> OpenCodeConfig:
"""Translate a non-empty FCC model snapshot into OpenCode v1 config."""
@@ -38,7 +38,7 @@ def build_opencode_config(
"apiKey": f"{{env:{OPENCODE_API_KEY_ENV}}}",
},
}
- default_model = f"{OPENCODE_PROVIDER_ID}/{models[0].wire_slug}"
+ default_model = f"{OPENCODE_PROVIDER_ID}/{default_model_id}"
return OpenCodeConfig(
file={
@@ -59,7 +59,7 @@ def build_opencode_config(
)
-def _model_config(model: ClientModel) -> JsonObject:
+def _model_config(model: CatalogModel) -> JsonObject:
config: JsonObject = {
"name": model.display_name,
"reasoning": model.supports_reasoning is not False,
diff --git a/src/free_claude_code/cli/launchers/pi_extension.ts b/src/free_claude_code/cli/launchers/pi_extension.ts
index 4be3e1ee..21cd9246 100644
--- a/src/free_claude_code/cli/launchers/pi_extension.ts
+++ b/src/free_claude_code/cli/launchers/pi_extension.ts
@@ -75,9 +75,9 @@ export function projectFccModels(payload: unknown): ProviderModelConfig[] {
const seen = new Set<string>();
for (const entry of payload.data) {
if (!isRecord(entry) || typeof entry.id !== "string" || typeof entry.provider_model_ref !== "string") continue;
- const id = entry.id.trim();
- const providerModel = entry.provider_model_ref.trim();
- if (!id || !providerModel.includes("/") || seen.has(id)) continue;
+ const id = entry.id;
+ const providerModel = entry.provider_model_ref;
+ if (!id.trim() || !providerModel.includes("/") || seen.has(id)) continue;
seen.add(id);
models.push(
modelDefinition(
diff --git a/src/free_claude_code/cli/launchers/runner.py b/src/free_claude_code/cli/launchers/runner.py
index 8f4b175a..16006400 100644
--- a/src/free_claude_code/cli/launchers/runner.py
+++ b/src/free_claude_code/cli/launchers/runner.py
@@ -10,17 +10,14 @@ from contextlib import ExitStack
from dataclasses import dataclass, field
from typing import Literal
+from free_claude_code.application.model_catalog import ModelCatalog
from free_claude_code.config.loader import get_settings
from free_claude_code.config.server_urls import local_proxy_root_url
from free_claude_code.config.settings import Settings
from free_claude_code.harnesses.launch import NativeCheck, PreparedLaunch
-from free_claude_code.harnesses.model_catalog import (
- ClientModel,
- client_models_from_response,
-)
from free_claude_code.harnesses.resources import LaunchResources
-from .catalog_http import fetch_proxy_models_response
+from .catalog_http import fetch_proxy_model_catalog
from .common import preflight_proxy, resolve_client_binary, run_client_process
@@ -31,9 +28,14 @@ class LaunchContext:
proxy_root_url: str
auth_token: str = field(repr=False)
base_env: Mapping[str, str] = field(repr=False)
- models: tuple[ClientModel, ...]
+ catalog: ModelCatalog | None
launch_id: str = field(default_factory=lambda: secrets.token_hex(16))
+ def require_catalog(self) -> ModelCatalog:
+ if self.catalog is None:
+ raise ValueError("harness configuration requires a model catalog")
+ return self.catalog
+
@dataclass(frozen=True, slots=True)
class HarnessSpec:
@@ -117,18 +119,14 @@ def launch_harness(spec: HarnessSpec, argv: Sequence[str] | None = None) -> None
f"Free Claude Code proxy is not reachable at {proxy_root_url}: {error}\n"
"Start it in another terminal with: fcc-server"
)
- models: tuple[ClientModel, ...] = ()
+ catalog = None
if spec.catalog_view is not None:
stage = "prepare model catalog"
- models = client_models_from_response(
- fetch_proxy_models_response(
- proxy_root_url, auth_token, view=spec.catalog_view
- )
+ catalog = fetch_proxy_model_catalog(
+ proxy_root_url, auth_token, view=spec.catalog_view
)
- if not models:
- raise ValueError("model catalog contains no routable models")
context = LaunchContext(
- binary_path, settings, proxy_root_url, auth_token, base_env, models
+ binary_path, settings, proxy_root_url, auth_token, base_env, catalog
)
with ExitStack() as stack:
stage = "prepare configuration"
diff --git a/src/free_claude_code/harnesses/codex.py b/src/free_claude_code/harnesses/codex.py
index d76f8952..6c20e409 100644
--- a/src/free_claude_code/harnesses/codex.py
+++ b/src/free_claude_code/harnesses/codex.py
@@ -3,12 +3,15 @@
import json
from collections.abc import Mapping, Sequence
+from free_claude_code.application.model_catalog import (
+ CatalogModel,
+ catalog_wire_slug_for_ref,
+)
from free_claude_code.config.server_urls import proxy_v1_url
from free_claude_code.harnesses.environment import client_environment
from .codex_model_catalog import build_codex_model_catalog
from .launch import PreparedLaunch
-from .model_catalog import ClientModel, catalog_wire_slug_for_ref
from .resources import LaunchResources
PRINT_PROXY_AUTH_TOKEN_FLAG = "--print-proxy-auth-token"
@@ -62,7 +65,7 @@ def prepare_codex_launch(
binary_path: str,
proxy_root_url: str,
model: str,
- models: Sequence[ClientModel],
+ models: Sequence[CatalogModel],
base_env: Mapping[str, str],
args: Sequence[str],
files: LaunchResources,
diff --git a/src/free_claude_code/harnesses/codex_model_catalog.py b/src/free_claude_code/harnesses/codex_model_catalog.py
index 482ae005..7ee67f3f 100644
--- a/src/free_claude_code/harnesses/codex_model_catalog.py
+++ b/src/free_claude_code/harnesses/codex_model_catalog.py
@@ -1,26 +1,21 @@
-"""Build Codex model catalogs from the FCC model-list route."""
+"""Codex-specific model policy and native catalog serialization."""
from collections.abc import Sequence
+from dataclasses import dataclass
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.model_capabilities import ModelInputModality
-from .model_catalog import ClientModel
+SUPPORTED_REASONING_LEVELS = {
+ "none": "Turn reasoning off",
+ "low": "Fast responses with lighter reasoning",
+ "medium": "Balances speed and reasoning depth for everyday tasks",
+ "high": "Greater reasoning depth for complex problems",
+ "xhigh": "Extra high reasoning depth for complex problems",
+ "max": "Maximum reasoning effort",
+}
-SUPPORTED_REASONING_LEVELS: list[JsonObject] = [
- {"effort": "none", "description": "Turn reasoning off"},
- {"effort": "low", "description": "Fast responses with lighter reasoning"},
- {
- "effort": "medium",
- "description": "Balances speed and reasoning depth for everyday tasks",
- },
- {"effort": "high", "description": "Greater reasoning depth for complex problems"},
- {
- "effort": "xhigh",
- "description": "Extra high reasoning depth for complex problems",
- },
- {"effort": "max", "description": "Maximum reasoning effort"},
-]
CODEX_BASE_INSTRUCTIONS = (
"You are Codex, a coding agent. Help the user understand, modify, test, "
@@ -29,22 +24,45 @@ CODEX_BASE_INSTRUCTIONS = (
)
-def build_codex_model_catalog(models: Sequence[ClientModel]) -> JsonObject:
- """Convert FCC `/v1/models` data into Codex `model_catalog_json` payload."""
+@dataclass(frozen=True, slots=True)
+class CodexModel:
+ model: CatalogModel
+ priority: int
+ reasoning_levels: tuple[str, ...]
+ default_reasoning_level: str | None
+
+def project_codex_models(models: Sequence[CatalogModel]) -> tuple[CodexModel, ...]:
+ return tuple(
+ CodexModel(
+ model=model,
+ priority=priority,
+ reasoning_levels=(
+ tuple(SUPPORTED_REASONING_LEVELS)
+ if model.supports_reasoning is not False
+ else ()
+ ),
+ default_reasoning_level=(
+ "medium" if model.supports_reasoning is not False else None
+ ),
+ )
+ for priority, model in enumerate(models)
+ )
+
+
+def build_codex_model_catalog(models: Sequence[CatalogModel]) -> JsonObject:
+ """Serialize already ordered application records for Codex."""
return {
- "models": [
- _codex_catalog_entry(model, priority=priority)
- for priority, model in enumerate(models)
- ]
+ "models": [codex_model_entry(model) for model in project_codex_models(models)]
}
-def _codex_catalog_entry(candidate: ClientModel, *, priority: int) -> JsonObject:
- supports_reasoning = candidate.supports_reasoning is not False
- input_modalities = candidate.input_modalities or frozenset(
- {ModelInputModality.TEXT}
- )
+def codex_model_entry(model: CodexModel) -> JsonObject:
+ candidate = model.model
+ supports_reasoning = bool(model.reasoning_levels)
+ input_modalities = candidate.input_modalities
+ if input_modalities is None or ModelInputModality.TEXT not in input_modalities:
+ input_modalities = frozenset({ModelInputModality.TEXT})
context_window = (
candidate.context_window_tokens
if candidate.context_window_tokens is not None
@@ -54,13 +72,14 @@ def _codex_catalog_entry(candidate: ClientModel, *, priority: int) -> JsonObject
"slug": candidate.wire_slug,
"display_name": candidate.display_name,
"description": "Free Claude Code provider model",
- "supported_reasoning_levels": (
- SUPPORTED_REASONING_LEVELS if supports_reasoning else []
- ),
+ "supported_reasoning_levels": [
+ {"effort": effort, "description": SUPPORTED_REASONING_LEVELS[effort]}
+ for effort in model.reasoning_levels
+ ],
"shell_type": "shell_command",
"visibility": "list",
"supported_in_api": True,
- "priority": priority,
+ "priority": model.priority,
"additional_speed_tiers": [],
"service_tiers": [],
"base_instructions": CODEX_BASE_INSTRUCTIONS,
@@ -85,6 +104,6 @@ def _codex_catalog_entry(candidate: ClientModel, *, priority: int) -> JsonObject
"use_responses_lite": False,
}
if supports_reasoning:
- entry["default_reasoning_level"] = "medium"
+ entry["default_reasoning_level"] = model.default_reasoning_level
entry["default_reasoning_summary"] = "none"
return entry
diff --git a/src/free_claude_code/harnesses/model_catalog.py b/src/free_claude_code/harnesses/model_catalog.py
deleted file mode 100644
index 8be1168c..00000000
--- a/src/free_claude_code/harnesses/model_catalog.py
+++ /dev/null
@@ -1,127 +0,0 @@
-"""Shared FCC model-catalog projection for native clients."""
-
-from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
-
-from free_claude_code.core.json_types import JsonValue
-from free_claude_code.core.model_capabilities import ModelInputModality
-
-
-@dataclass(frozen=True, slots=True)
-class ClientModel:
- """One direct FCC model reference suitable for a client-side catalog."""
-
- wire_slug: str
- provider_model_ref: str
- display_name: str
- supports_reasoning: bool | None
- input_modalities: frozenset[ModelInputModality] | None = None
- context_window_tokens: int | None = None
- max_output_tokens: int | None = None
-
-
-def client_models_from_response(
- models_response: Mapping[str, JsonValue],
-) -> tuple[ClientModel, ...]:
- """Project an FCC `/v1/models` response into direct client model records."""
-
- models: list[ClientModel] = []
- seen_slugs: set[str] = set()
-
- for candidate in _catalog_candidates(models_response):
- if candidate.wire_slug in seen_slugs:
- continue
- seen_slugs.add(candidate.wire_slug)
- models.append(candidate)
-
- return tuple(models)
-
-
-def catalog_wire_slug_for_ref(
- models: Sequence[ClientModel],
- provider_model_ref: str | None,
-) -> str | None:
- """Return the slug a client catalog advertises for one configured ref.
-
- A model the gateway reports as non-thinking is advertised under its
- no-thinking slug, not its bare provider ref, so a client told to select the
- bare ref would not find it in the catalog it was given.
- """
-
- if not provider_model_ref:
- return provider_model_ref
-
- for model in models:
- if model.provider_model_ref == provider_model_ref:
- return model.wire_slug
- return provider_model_ref
-
-
-def _catalog_candidates(
- models_response: Mapping[str, JsonValue],
-) -> list[ClientModel]:
- data = models_response.get("data")
- if not isinstance(data, list):
- return []
-
- candidates: list[ClientModel] = []
- for item in data:
- if not isinstance(item, Mapping):
- continue
- model_id = _nonempty_string(item.get("id"))
- if model_id is None:
- continue
- provider_model_ref = _provider_model_ref(item.get("provider_model_ref"))
- if provider_model_ref is None:
- continue
- candidates.append(
- ClientModel(
- wire_slug=model_id,
- provider_model_ref=provider_model_ref,
- display_name=_nonempty_string(item.get("display_name")) or model_id,
- supports_reasoning=_optional_boolean(item.get("supportsReasoning")),
- input_modalities=_input_modalities(item.get("inputModalities")),
- context_window_tokens=_optional_positive_int(item.get("contextWindow")),
- max_output_tokens=_optional_positive_int(
- item.get("maxCompletionTokens")
- ),
- )
- )
- return candidates
-
-
-def _nonempty_string(value: object) -> str | None:
- if not isinstance(value, str):
- return None
- stripped = value.strip()
- return stripped or None
-
-
-def _optional_boolean(value: object) -> bool | None:
- return value if isinstance(value, bool) else None
-
-
-def _optional_positive_int(value: object) -> int | None:
- return value if type(value) is int and value > 0 else None
-
-
-def _input_modalities(value: object) -> frozenset[ModelInputModality] | None:
- if not isinstance(value, list) or not value:
- return None
- try:
- modalities = frozenset(ModelInputModality(item) for item in value)
- except TypeError, ValueError:
- return None
- if ModelInputModality.TEXT not in modalities:
- return None
- return modalities
-
-
-def _provider_model_ref(value: object) -> str | None:
- ref = _nonempty_string(value)
- if ref is None:
- return None
- provider_id, separator, model_id = ref.partition("/")
- if not separator or not provider_id or not model_id:
- return None
- return ref
diff --git a/src/free_claude_code/runtime/codex_app_server.py b/src/free_claude_code/runtime/codex_app_server.py
index 1d184f7d..996dcb51 100644
--- a/src/free_claude_code/runtime/codex_app_server.py
+++ b/src/free_claude_code/runtime/codex_app_server.py
@@ -24,6 +24,7 @@ from free_claude_code.application.code_sessions.models import (
NativeThread,
)
from free_claude_code.application.code_sessions.ports import EventSink, HarnessSelection
+from free_claude_code.application.model_catalog import CatalogModel, read_model_catalog
from free_claude_code.application.ports import RequestRuntimePort
from free_claude_code.cli.process_registry import register_pid, unregister_pid
from free_claude_code.config.model_refs import split_provider_model_ref
@@ -31,15 +32,16 @@ from free_claude_code.config.server_urls import local_proxy_root_url
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.version import package_version
from free_claude_code.harnesses.codex import CODEX_INSTALL_HINT, prepare_codex_launch
-from free_claude_code.harnesses.codex_model_catalog import build_codex_model_catalog
-from free_claude_code.harnesses.model_catalog import ClientModel
+from free_claude_code.harnesses.codex_model_catalog import (
+ CodexModel,
+ codex_model_entry,
+ project_codex_models,
+)
from free_claude_code.harnesses.resources import LaunchResources
-from .codex_catalog import current_codex_models
from .codex_protocol import (
CodexProtocol,
NativePrompt,
- array_value,
object_value,
string_value,
)
@@ -578,7 +580,7 @@ class _CodexSelection:
binary_path: str
proxy_root_url: str
base_env: Mapping[str, str] = field(repr=False)
- models: tuple[ClientModel, ...]
+ models: tuple[CatalogModel, ...]
model: str
configuration_key: str
fingerprints: dict[str, str]
@@ -642,17 +644,11 @@ class CodexHarnessFactory:
def catalog(self) -> CodeCatalog:
settings = self._runtime.current_settings()
- models = current_codex_models(self._runtime, settings)
- entries = array_value(build_codex_model_catalog(models).get("models"))
+ catalog = read_model_catalog(self._runtime, settings)
return CodeCatalog(
settings.model,
tuple(
- _model_option(
- model.provider_model_ref,
- object_value(entry),
- context_window_tokens=model.context_window_tokens,
- )
- for model, entry in zip(models, entries, strict=True)
+ _model_option(model) for model in project_codex_models(catalog.models)
),
)
@@ -664,12 +660,13 @@ class CodexHarnessFactory:
raise CodeUnavailableError("Codex is not installed. " + CODEX_INSTALL_HINT)
snapshot = await self._runtime.wait_for_catalog()
settings = snapshot.settings
- models = current_codex_models(snapshot, settings)
+ models = read_model_catalog(snapshot, settings).models
+ projected = project_codex_models(models)
selected = next(
(
candidate
- for candidate in models
- if candidate.provider_model_ref == model
+ for candidate in projected
+ if candidate.model.provider_model_ref == model
),
None,
)
@@ -677,17 +674,7 @@ class CodexHarnessFactory:
raise CodeValidationError(
"This model is unavailable. Choose another model."
)
- catalog = build_codex_model_catalog(models)
- entries = {
- string_value(entry.get("slug")): entry
- for value in array_value(catalog.get("models"))
- if (entry := object_value(value))
- }
- option = _model_option(
- model,
- entries[selected.wire_slug],
- context_window_tokens=selected.context_window_tokens,
- )
+ option = _model_option(selected)
if (
reasoning_effort is not None
and reasoning_effort not in option.reasoning_efforts
@@ -697,8 +684,8 @@ class CodexHarnessFactory:
)
effort = reasoning_effort or option.default_reasoning_effort
fingerprints = {
- model.provider_model_ref: _fingerprint(entries[model.wire_slug])
- for model in models
+ entry.model.provider_model_ref: _fingerprint(codex_model_entry(entry))
+ for entry in projected
}
return _CodexSelection(
binary_path=binary,
@@ -729,26 +716,20 @@ class CodexHarnessFactory:
return connection
-def _model_option(
- model: str, entry: JsonObject, *, context_window_tokens: int | None
-) -> CodeModel:
- provider_id, model_name = split_provider_model_ref(model)
- efforts = tuple(
- string_value(object_value(level).get("effort"))
- for level in array_value(entry.get("supported_reasoning_levels"))
- )
+def _model_option(entry: CodexModel) -> CodeModel:
+ model = entry.model
+ provider_id, model_name = split_provider_model_ref(model.provider_model_ref)
return CodeModel(
- id=model,
- display_name=string_value(entry.get("display_name")) or model,
+ id=model.provider_model_ref,
+ display_name=model.display_name,
provider_id=provider_id,
model_name=model_name,
reasoning_efforts=tuple(
- "off" if effort == "none" else effort for effort in efforts
+ "off" if effort == "none" else effort for effort in entry.reasoning_levels
)
or ("off",),
- default_reasoning_effort=string_value(entry.get("default_reasoning_level"))
- or "off",
- context_window_tokens=context_window_tokens,
+ default_reasoning_effort=entry.default_reasoning_level or "off",
+ context_window_tokens=model.context_window_tokens,
)
diff --git a/src/free_claude_code/runtime/codex_catalog.py b/src/free_claude_code/runtime/codex_catalog.py
index b6683bfb..9db6b0d9 100644
--- a/src/free_claude_code/runtime/codex_catalog.py
+++ b/src/free_claude_code/runtime/codex_catalog.py
@@ -5,35 +5,13 @@ import uuid
from collections.abc import Mapping
from pathlib import Path
-from free_claude_code.api.model_catalog import (
- ModelCatalogView,
- build_models_list_response,
-)
+from free_claude_code.application.model_catalog import read_model_catalog
from free_claude_code.application.ports import ModelCatalogPort
from free_claude_code.config.paths import codex_model_catalog_path
-from free_claude_code.config.settings import Settings
from free_claude_code.core.json_types import JsonValue
from free_claude_code.harnesses.codex_model_catalog import (
build_codex_model_catalog,
)
-from free_claude_code.harnesses.model_catalog import (
- ClientModel,
- client_models_from_response,
-)
-
-
-def current_codex_models(
- runtime: ModelCatalogPort, settings: Settings | None = None
-) -> tuple[ClientModel, ...]:
- """Read the current FCC inventory without a request to the server itself."""
- response = build_models_list_response(
- settings or runtime.current_settings(),
- runtime,
- view=ModelCatalogView.RESPONSES,
- )
- return client_models_from_response(
- response.model_dump(by_alias=True, exclude_none=True)
- )
class CodexModelCatalogPublisher:
@@ -52,7 +30,7 @@ class CodexModelCatalogPublisher:
runtime: ModelCatalogPort,
catalog_path: Path,
) -> None:
- catalog = build_codex_model_catalog(current_codex_models(runtime))
+ catalog = build_codex_model_catalog(read_model_catalog(runtime).models)
models = catalog.get("models")
if not isinstance(models, list) or not models:
raise ValueError("Codex model catalog contains no routable models.")
diff --git a/tests/api/test_model_listing.py b/tests/api/test_model_listing.py
index b86bf670..44331c42 100644
--- a/tests/api/test_model_listing.py
+++ b/tests/api/test_model_listing.py
@@ -1,5 +1,6 @@
import math
+import pytest
from fastapi.testclient import TestClient
from free_claude_code.application.model_metadata import ProviderModelInfo
@@ -38,6 +39,35 @@ def _cache_models(app, provider_id: str, *model_ids: str) -> None:
)
[email protected]("view", ["messages", "responses"])
+def test_sorted_catalog_retains_an_explicit_no_thinking_server_default(view):
+ settings = _settings(
+ model="open_router/Zulu",
+ model_opus=None,
+ model_haiku=None,
+ model_fallbacks=("wafer/z-fallback", "deepseek/a-fallback"),
+ )
+ app = create_test_app(settings)
+ provider_manager_for_app(app).cache_model_infos(
+ "open_router",
+ {
+ ProviderModelInfo("Zulu", supports_thinking=False),
+ ProviderModelInfo("apple"),
+ },
+ )
+ payload = TestClient(app).get(f"/v1/models?view={view}").json()
+ assert [row["provider_model_ref"] for row in payload["data"]] == [
+ "deepseek/a-fallback",
+ "open_router/apple",
+ "open_router/Zulu",
+ "wafer/z-fallback",
+ ]
+ assert payload["default_model_id"] == "claude-3-freecc-no-thinking/open_router/Zulu"
+ assert payload["first_id"] == "deepseek/a-fallback"
+ assert payload["last_id"] == "wafer/z-fallback"
+ assert settings.model_fallbacks == ("wafer/z-fallback", "deepseek/a-fallback")
+
+
def test_models_list_includes_configured_refs_cached_provider_models_and_aliases():
app = create_test_app(_settings())
_cache_models(app, "deepseek", "deepseek-chat")
@@ -53,7 +83,8 @@ def test_models_list_includes_configured_refs_cached_provider_models_and_aliases
assert response.status_code == 200
data = response.json()
ids = [item["id"] for item in data["data"]]
- assert ids[:6] == [
+ assert ids[0] == "claude-fable-5"
+ assert [model_id for model_id in ids if "/" in model_id] == [
"anthropic/deepseek/deepseek-chat",
"claude-3-freecc-no-thinking/deepseek/deepseek-chat",
"anthropic/open_router/anthropic/claude-opus",
@@ -122,7 +153,7 @@ def test_models_list_uses_cached_metadata_for_configured_refs():
ids = [item["id"] for item in response.json()["data"]]
assert "anthropic/open_router/plain-model" not in ids
- assert ids[0] == "claude-3-freecc-no-thinking/open_router/plain-model"
+ assert ids[-1] == "claude-3-freecc-no-thinking/open_router/plain-model"
def test_models_list_includes_cached_wafer_models():
@@ -168,7 +199,8 @@ def test_models_list_works_with_empty_discovery_catalog():
assert response.status_code == 200
ids = [item["id"] for item in response.json()["data"]]
- assert ids[:4] == [
+ assert ids[0] == "claude-fable-5"
+ assert [model_id for model_id in ids if "/" in model_id] == [
"anthropic/deepseek/deepseek-chat",
"claude-3-freecc-no-thinking/deepseek/deepseek-chat",
"anthropic/open_router/anthropic/claude-opus",
@@ -414,3 +446,31 @@ def test_unknown_model_view_is_rejected():
response = TestClient(create_test_app(_settings())).get("/v1/models?view=other")
assert response.status_code == 422
+
+
[email protected]("view", ["messages", "responses"])
+def test_real_json_catalog_agrees_with_application_identity_and_known_metadata(view):
+ from free_claude_code.application.model_catalog import read_model_catalog
+ from free_claude_code.cli.launchers.catalog_http import model_catalog_from_response
+
+ app = create_test_app(
+ _settings(model="open_router/Zulu", model_opus=None, model_haiku=None)
+ )
+ provider_manager_for_app(app).cache_model_infos(
+ "open_router",
+ {
+ ProviderModelInfo(
+ "Zulu", supports_thinking=False, context_window_tokens=32000
+ ),
+ ProviderModelInfo(
+ "vendor/vision ",
+ input_modalities=frozenset(
+ {ModelInputModality.TEXT, ModelInputModality.IMAGE}
+ ),
+ max_output_tokens=4096,
+ ),
+ },
+ )
+ expected = read_model_catalog(app.state.services.requests)
+ payload = TestClient(app).get(f"/v1/models?view={view}").json()
+ assert model_catalog_from_response(payload) == expected
diff --git a/tests/application/test_model_catalog.py b/tests/application/test_model_catalog.py
new file mode 100644
index 00000000..68386023
--- /dev/null
+++ b/tests/application/test_model_catalog.py
@@ -0,0 +1,128 @@
+from dataclasses import replace
+
+from free_claude_code.application.model_catalog import (
+ CatalogModel,
+ catalog_wire_slug_for_ref,
+ read_model_catalog,
+)
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.application.ports import ModelCatalogSnapshot
+from free_claude_code.config.settings import Settings
+
+
+def test_catalog_sorts_components_and_preserves_exact_identity_and_default():
+ settings = Settings.model_construct(
+ model="open_router/Zulu",
+ model_fable=None,
+ model_opus=None,
+ model_sonnet=None,
+ model_haiku=None,
+ model_fallbacks=("wafer/z", "deepseek/a"),
+ )
+ infos = (
+ ProviderModelInfo("alpha-2/model"),
+ ProviderModelInfo("alpha/z"),
+ ProviderModelInfo("alpha/ß"),
+ ProviderModelInfo("alpha/ss"),
+ ProviderModelInfo("alpha/Apple"),
+ ProviderModelInfo("alpha/apple"),
+ ProviderModelInfo("alpha/vendor/nested"),
+ ProviderModelInfo(
+ "open_router/Zulu", supports_thinking=False, context_window_tokens=32000
+ ),
+ )
+ snapshot = ModelCatalogSnapshot(settings, infos)
+ catalog = read_model_catalog(snapshot)
+ assert [model.provider_model_ref for model in catalog.models] == [
+ "alpha/Apple",
+ "alpha/apple",
+ "alpha/ss",
+ "alpha/ß",
+ "alpha/vendor/nested",
+ "alpha/z",
+ "alpha-2/model",
+ "deepseek/a",
+ "open_router/Zulu",
+ "wafer/z",
+ ]
+ assert (
+ read_model_catalog(replace(snapshot, model_infos=tuple(reversed(infos))))
+ == catalog
+ )
+ assert catalog.default_model_id == "claude-3-freecc-no-thinking/open_router/Zulu"
+ selected = next(
+ model for model in catalog.models if model.wire_slug == catalog.default_model_id
+ )
+ assert selected.context_window_tokens == 32000
+ assert settings.model_fallbacks == ("wafer/z", "deepseek/a")
+
+
+def test_catalog_retains_configured_models_and_enriches_each_reference_once():
+ settings = Settings.model_construct(
+ model="open_router/shared",
+ model_opus="open_router/shared",
+ model_fable=None,
+ model_sonnet=None,
+ model_haiku="deepseek/undiscovered",
+ model_fallbacks=("open_router/shared",),
+ )
+ info = ProviderModelInfo("open_router/shared", context_window_tokens=65536)
+ catalog = read_model_catalog(ModelCatalogSnapshot(settings, (info,)))
+ assert [model.provider_model_ref for model in catalog.models] == [
+ "deepseek/undiscovered",
+ "open_router/shared",
+ ]
+ assert catalog.models[0].supports_reasoning is None
+ assert catalog.models[0].context_window_tokens is None
+ assert catalog.models[1].context_window_tokens == 65536
+
+
+def _client_model(wire_slug: str, provider_model_ref: str) -> CatalogModel:
+ return CatalogModel(
+ wire_slug=wire_slug,
+ provider_model_ref=provider_model_ref,
+ display_name=provider_model_ref,
+ supports_reasoning=wire_slug == provider_model_ref,
+ )
+
+
+def test_catalog_wire_slug_prefers_the_advertised_no_thinking_slug() -> None:
+ models = (
+ _client_model(
+ "claude-3-freecc-no-thinking/open_router/vendor/chat-model",
+ "open_router/vendor/chat-model",
+ ),
+ )
+
+ assert (
+ catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
+ == "claude-3-freecc-no-thinking/open_router/vendor/chat-model"
+ )
+
+
+def test_catalog_wire_slug_keeps_a_directly_advertised_ref() -> None:
+ models = (
+ _client_model("open_router/vendor/chat-model", "open_router/vendor/chat-model"),
+ )
+
+ assert (
+ catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
+ == "open_router/vendor/chat-model"
+ )
+
+
+def test_catalog_wire_slug_falls_back_when_the_catalog_omits_the_ref() -> None:
+ models = (_client_model("open_router/vendor/other", "open_router/vendor/other"),)
+
+ assert (
+ catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
+ == "open_router/vendor/chat-model"
+ )
+ assert catalog_wire_slug_for_ref((), "open_router/vendor/chat-model") == (
+ "open_router/vendor/chat-model"
+ )
+
+
+def test_catalog_wire_slug_passes_through_an_unset_model() -> None:
+ assert catalog_wire_slug_for_ref((), None) is None
+ assert catalog_wire_slug_for_ref((), "") == ""
diff --git a/tests/cli/conftest.py b/tests/cli/conftest.py
index 69c9acbc..09fb8349 100644
--- a/tests/cli/conftest.py
+++ b/tests/cli/conftest.py
@@ -27,6 +27,7 @@ class LaunchCapture:
environments: list[dict[str, str]] = field(default_factory=list)
catalog: JsonObject = field(
default_factory=lambda: {
+ "default_model_id": "nvidia_nim/catalog-model:variant",
"data": [
{
"id": "nvidia_nim/catalog-model:variant",
diff --git a/tests/cli/test_aider_config.py b/tests/cli/test_aider_config.py
index 4dae3bec..2bc3b139 100644
--- a/tests/cli/test_aider_config.py
+++ b/tests/cli/test_aider_config.py
@@ -4,14 +4,14 @@ import json
import pytest
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.cli.launchers.aider_config import build_aider_config
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
-def _models() -> tuple[ClientModel, ...]:
+def _models() -> tuple[CatalogModel, ...]:
return (
- ClientModel(
+ CatalogModel(
wire_slug="nvidia_nim/vendor/model",
provider_model_ref="nvidia_nim/vendor/model",
display_name="Nested model",
@@ -22,7 +22,7 @@ def _models() -> tuple[ClientModel, ...]:
context_window_tokens=131072,
max_output_tokens=8192,
),
- ClientModel(
+ CatalogModel(
wire_slug="ollama_cloud/qwen3-coder:480b",
provider_model_ref="ollama_cloud/qwen3-coder:480b",
display_name="Colon model",
@@ -30,7 +30,7 @@ def _models() -> tuple[ClientModel, ...]:
input_modalities=frozenset({ModelInputModality.TEXT}),
max_output_tokens=4096,
),
- ClientModel(
+ CatalogModel(
wire_slug="future_provider/unknown-model",
provider_model_ref="future_provider/unknown-model",
display_name="Unknown model",
@@ -114,8 +114,8 @@ def test_aider_config_rejects_empty_catalog() -> None:
def test_aider_catalog_ids_take_precedence_over_generated_transport_spellings() -> None:
models = (
- ClientModel("provider/model", "provider/model", "First", None),
- ClientModel(
+ CatalogModel("provider/model", "provider/model", "First", None),
+ CatalogModel(
"anthropic/provider/model", "anthropic/provider/model", "Second", None
),
)
diff --git a/tests/cli/test_catalog_http.py b/tests/cli/test_catalog_http.py
index af454a5f..227fa75c 100644
--- a/tests/cli/test_catalog_http.py
+++ b/tests/cli/test_catalog_http.py
@@ -1,8 +1,9 @@
+import json
from unittest.mock import patch
import pytest
-from free_claude_code.cli.launchers.catalog_http import fetch_proxy_models_response
+from free_claude_code.cli.launchers.catalog_http import fetch_proxy_model_catalog
class _ModelsResponse:
@@ -20,13 +21,20 @@ class _ModelsResponse:
def test_fetch_proxy_models_uses_canonical_bearer_request() -> None:
+ body = json.dumps(
+ {
+ "default_model_id": "provider/model",
+ "data": [{"id": "provider/model", "provider_model_ref": "provider/model"}],
+ }
+ ).encode()
with patch(
"free_claude_code.cli.launchers.catalog_http.open_local_request",
- return_value=_ModelsResponse(b'{"data": []}'),
+ return_value=_ModelsResponse(body),
) as open_local_request:
- response = fetch_proxy_models_response("http://127.0.0.1:9191/", "proxy-token")
+ response = fetch_proxy_model_catalog("http://127.0.0.1:9191/", "proxy-token")
- assert response == {"data": []}
+ assert response.default_model_id == "provider/model"
+ assert [model.wire_slug for model in response.models] == ["provider/model"]
request = open_local_request.call_args.args[0]
assert request.full_url == "http://127.0.0.1:9191/v1/models?view=responses"
assert request.get_method() == "GET"
@@ -34,17 +42,24 @@ def test_fetch_proxy_models_uses_canonical_bearer_request() -> None:
def test_fetch_proxy_models_can_request_messages_view() -> None:
+ body = json.dumps(
+ {
+ "default_model_id": "provider/model",
+ "data": [{"id": "provider/model", "provider_model_ref": "provider/model"}],
+ }
+ ).encode()
with patch(
"free_claude_code.cli.launchers.catalog_http.open_local_request",
- return_value=_ModelsResponse(b'{"data": []}'),
+ return_value=_ModelsResponse(body),
) as open_local_request:
- response = fetch_proxy_models_response(
+ response = fetch_proxy_model_catalog(
"http://127.0.0.1:9191/",
"proxy-token",
view="messages",
)
- assert response == {"data": []}
+ assert response.default_model_id == "provider/model"
+ assert [model.wire_slug for model in response.models] == ["provider/model"]
request = open_local_request.call_args.args[0]
assert request.full_url == "http://127.0.0.1:9191/v1/models?view=messages"
assert request.get_method() == "GET"
@@ -59,4 +74,4 @@ def test_fetch_proxy_models_rejects_non_object_json() -> None:
),
pytest.raises(ValueError, match="JSON object"),
):
- fetch_proxy_models_response("http://127.0.0.1:9191", "proxy-token")
+ fetch_proxy_model_catalog("http://127.0.0.1:9191", "proxy-token")
diff --git a/tests/cli/test_cline_launcher.py b/tests/cli/test_cline_launcher.py
index a4c678de..7d2a0c47 100644
--- a/tests/cli/test_cline_launcher.py
+++ b/tests/cli/test_cline_launcher.py
@@ -6,18 +6,18 @@ from pathlib import Path
import pytest
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.cli.launchers.cline_config import (
CLINE_PROVIDER_ID,
build_cline_config,
)
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
def test_cline_config_uses_responses_and_only_known_metadata() -> None:
config = build_cline_config(
(
- ClientModel(
+ CatalogModel(
wire_slug="nvidia_nim/vendor/model",
provider_model_ref="nvidia_nim/vendor/model",
display_name="Nested model",
@@ -28,7 +28,7 @@ def test_cline_config_uses_responses_and_only_known_metadata() -> None:
context_window_tokens=131072,
max_output_tokens=8192,
),
- ClientModel(
+ CatalogModel(
wire_slug="claude-3-freecc-no-thinking/open_router/plain-model",
provider_model_ref="open_router/plain-model",
display_name="No-thinking model",
@@ -36,13 +36,14 @@ def test_cline_config_uses_responses_and_only_known_metadata() -> None:
input_modalities=frozenset({ModelInputModality.TEXT}),
context_window_tokens=65536,
),
- ClientModel(
+ CatalogModel(
wire_slug="future_provider/unknown-model",
provider_model_ref="future_provider/unknown-model",
display_name="Unknown model",
supports_reasoning=None,
),
),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191/",
auth_token="proxy-token",
launch_id="launch-a",
@@ -127,6 +128,7 @@ def test_cline_config_rejects_empty_model_catalog() -> None:
with pytest.raises(ValueError, match="at least one"):
build_cline_config(
(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
auth_token="proxy-token",
launch_id="launch-a",
diff --git a/tests/cli/test_codex_launcher.py b/tests/cli/test_codex_launcher.py
index 868a9a1e..8e12fae9 100644
--- a/tests/cli/test_codex_launcher.py
+++ b/tests/cli/test_codex_launcher.py
@@ -27,13 +27,14 @@ def test_codex_selects_the_advertised_slug_from_opaque_catalog_data(
launch_capture: LaunchCapture,
) -> None:
launch_capture.catalog = {
+ "default_model_id": "arbitrary-wire-id",
"data": [
{
"id": "arbitrary-wire-id",
"provider_model_ref": "nvidia_nim/catalog-model:variant",
"supportsReasoning": False,
}
- ]
+ ],
}
launch("codex", ["exec", "--model", "native-choice", "hello"])
command = launch_capture.commands[0]
diff --git a/tests/cli/test_codex_model_catalog.py b/tests/cli/test_codex_model_catalog.py
index 48684862..f8d99ca9 100644
--- a/tests/cli/test_codex_model_catalog.py
+++ b/tests/cli/test_codex_model_catalog.py
@@ -6,11 +6,11 @@ from pathlib import Path
import pytest
+from free_claude_code.cli.launchers.catalog_http import catalog_models_from_response
from free_claude_code.harnesses.codex import codex_config_args
from free_claude_code.harnesses.codex_model_catalog import (
build_codex_model_catalog,
)
-from free_claude_code.harnesses.model_catalog import client_models_from_response
from free_claude_code.runtime.codex_catalog import write_codex_model_catalog
from tests.harnesses.test_codex_model_catalog import _models_payload
@@ -26,7 +26,7 @@ def test_launcher_config_composes_with_persistent_codex_config(
write_codex_model_catalog(
catalog_path,
build_codex_model_catalog(
- client_models_from_response(_models_payload("nvidia_nim/test-model"))
+ catalog_models_from_response(_models_payload("nvidia_nim/test-model"))
),
)
codex_home = tmp_path / "codex-home"
diff --git a/tests/cli/test_dsh_config.py b/tests/cli/test_dsh_config.py
index 5fe27ba2..d204814c 100644
--- a/tests/cli/test_dsh_config.py
+++ b/tests/cli/test_dsh_config.py
@@ -6,14 +6,14 @@ from pathlib import Path
import pytest
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.cli.launchers.dsh_config import build_dsh_launch_config
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
-def _models() -> tuple[ClientModel, ...]:
+def _models() -> tuple[CatalogModel, ...]:
return (
- ClientModel(
+ CatalogModel(
wire_slug="nvidia_nim/vendor/model",
provider_model_ref="nvidia_nim/vendor/model",
display_name="Nested model",
@@ -24,7 +24,7 @@ def _models() -> tuple[ClientModel, ...]:
context_window_tokens=131072,
max_output_tokens=8192,
),
- ClientModel(
+ CatalogModel(
wire_slug="claude-3-freecc-no-thinking/open_router/plain-model",
provider_model_ref="open_router/plain-model",
display_name="No-thinking model",
@@ -32,7 +32,7 @@ def _models() -> tuple[ClientModel, ...]:
input_modalities=frozenset({ModelInputModality.TEXT}),
max_output_tokens=4096,
),
- ClientModel(
+ CatalogModel(
wire_slug="future_provider/unknown-model",
provider_model_ref="future_provider/unknown-model",
display_name="Unknown model",
@@ -52,6 +52,7 @@ def test_dsh_config_pins_responses_models_retries_and_private_state(
credentials_path = tmp_path / ".credentials.yaml"
launch = build_dsh_launch_config(
_models(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191/",
settings_path=settings_path,
credentials_path=credentials_path,
@@ -149,6 +150,7 @@ def test_dsh_config_pins_responses_models_retries_and_private_state(
def test_dsh_config_rounds_fractional_progress_timeout_up() -> None:
launch = build_dsh_launch_config(
_models(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
settings_path=Path("settings.yaml"),
credentials_path=Path("credentials.yaml"),
@@ -165,6 +167,7 @@ def test_dsh_config_rejects_empty_catalog() -> None:
with pytest.raises(ValueError, match="at least one"):
build_dsh_launch_config(
(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
settings_path=Path("settings.yaml"),
credentials_path=Path("credentials.yaml"),
@@ -177,6 +180,7 @@ def test_dsh_config_rejects_invalid_progress_timeout(timeout: float) -> None:
with pytest.raises(ValueError, match="positive finite"):
build_dsh_launch_config(
_models(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
settings_path=Path("settings.yaml"),
credentials_path=Path("credentials.yaml"),
@@ -188,6 +192,7 @@ def test_dsh_config_rejects_timeout_beyond_node_timer_limit() -> None:
with pytest.raises(ValueError, match="too large"):
build_dsh_launch_config(
_models(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
settings_path=Path("settings.yaml"),
credentials_path=Path("credentials.yaml"),
diff --git a/tests/cli/test_hermes_config.py b/tests/cli/test_hermes_config.py
index f93023f7..3342031a 100644
--- a/tests/cli/test_hermes_config.py
+++ b/tests/cli/test_hermes_config.py
@@ -4,16 +4,16 @@ import json
import pytest
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.cli.launchers.hermes_config import (
build_hermes_managed_config,
)
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
-def _models() -> tuple[ClientModel, ...]:
+def _models() -> tuple[CatalogModel, ...]:
return (
- ClientModel(
+ CatalogModel(
wire_slug="nvidia_nim/vendor/model",
provider_model_ref="nvidia_nim/vendor/model",
display_name="Nested model",
@@ -24,7 +24,7 @@ def _models() -> tuple[ClientModel, ...]:
context_window_tokens=131072,
max_output_tokens=8192,
),
- ClientModel(
+ CatalogModel(
wire_slug="claude-3-freecc-no-thinking/open_router/plain-model",
provider_model_ref="open_router/plain-model",
display_name="No-thinking model",
@@ -32,7 +32,7 @@ def _models() -> tuple[ClientModel, ...]:
input_modalities=frozenset({ModelInputModality.TEXT}),
max_output_tokens=4096,
),
- ClientModel(
+ CatalogModel(
wire_slug="future_provider/unknown-model",
provider_model_ref="future_provider/unknown-model",
display_name="Unknown model",
@@ -43,7 +43,8 @@ def _models() -> tuple[ClientModel, ...]:
def test_hermes_config_pins_responses_catalog_and_fallbacks() -> None:
managed = build_hermes_managed_config(
- (_models()[1], _models()[0], _models()[2]),
+ _models(),
+ default_model_id="claude-3-freecc-no-thinking/open_router/plain-model",
proxy_root_url="http://127.0.0.1:9191/",
nonce="a1b2c3",
)
@@ -139,9 +140,10 @@ def test_hermes_config_pins_responses_catalog_and_fallbacks() -> None:
assert "timeout" not in serialized
-def test_hermes_config_uses_first_model_by_default() -> None:
+def test_hermes_config_uses_explicit_default() -> None:
managed = build_hermes_managed_config(
_models(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
nonce="ABC123",
)
@@ -154,6 +156,7 @@ def test_hermes_config_rejects_empty_catalog() -> None:
with pytest.raises(ValueError, match="at least one"):
build_hermes_managed_config(
(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
nonce="abc123",
)
@@ -164,6 +167,7 @@ def test_hermes_config_rejects_unsafe_nonce(nonce: str) -> None:
with pytest.raises(ValueError, match="alphanumeric"):
build_hermes_managed_config(
_models(),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
nonce=nonce,
)
diff --git a/tests/cli/test_launcher_workflow.py b/tests/cli/test_launcher_workflow.py
index 87feaa8d..05e0021a 100644
--- a/tests/cli/test_launcher_workflow.py
+++ b/tests/cli/test_launcher_workflow.py
@@ -8,9 +8,9 @@ from urllib.error import URLError
import pytest
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.cli.launchers.aider_config import build_aider_config
from free_claude_code.config.paths import codex_model_catalog_path
-from free_claude_code.harnesses.model_catalog import ClientModel
from tests.cli.conftest import LaunchCapture
HARNESSES = (
@@ -34,6 +34,75 @@ def launch(name: str, args: list[str], exit_code: int = 23) -> None:
assert exc.value.code == exit_code
+ "name", ["aider", "cline", "dsh", "grok", "hermes", "muse", "opencode"]
+)
+def test_launch_default_is_server_selection_not_first_row_or_local_settings(
+ name: str,
+ launch_capture: LaunchCapture,
+) -> None:
+ selected = "claude-3-freecc-no-thinking/open_router/Zulu"
+ launch_capture.catalog = {
+ "default_model_id": selected,
+ "data": [
+ {"id": "deepseek/alpha", "provider_model_ref": "deepseek/alpha"},
+ {
+ "id": selected,
+ "provider_model_ref": "open_router/Zulu",
+ "supportsReasoning": False,
+ },
+ ],
+ }
+
+ def inspect(command, env):
+ if name in {"aider", "muse"}:
+ assert env[f"{name.upper()}_MODEL"] == selected
+ elif name == "grok":
+ for key in (
+ "DEFAULT",
+ "IMAGE_DESCRIPTION",
+ "PROMPT_SUGGESTIONS",
+ "SESSION_SUMMARY",
+ "WEB_SEARCH",
+ ):
+ assert env[f"GROK_{key}_MODEL"] == selected
+ elif name == "hermes":
+ config = json.loads(
+ (Path(env["HERMES_MANAGED_DIR"]) / "config.yaml").read_text()
+ )
+ assert (
+ config["model"]["default"] == env["HERMES_INFERENCE_MODEL"] == selected
+ )
+ assert next(iter(config["providers"].values()))["default_model"] == selected
+ elif name == "opencode":
+ config = json.loads(env["OPENCODE_CONFIG_CONTENT"])
+ assert (
+ config["model"]
+ == config["small_model"]
+ == f"free-claude-code/{selected}"
+ )
+ elif name == "cline":
+ path = Path(env["CLINE_PROVIDER_SETTINGS_PATH"])
+ config = json.loads(path.read_text())
+ assert config["providers"]["openai-native"]["settings"]["model"] == selected
+ registry = json.loads(path.with_name("models.json").read_text())
+ assert (
+ registry["providers"]["openai-native"]["provider"]["defaultModelId"]
+ == selected
+ )
+ else:
+ rows = json.loads(Path(command[command.index("--patch") + 1]).read_text())
+ assert (
+ next(row for row in rows if row["id"] == "agent-default-model")[
+ "config"
+ ]["model"]
+ == selected
+ )
+
+ launch_capture.on_start = inspect
+ launch(name, [])
+
+
@pytest.mark.parametrize("name", HARNESSES)
def test_help_receives_normal_fcc_setup(
name: str, launch_capture: LaunchCapture
@@ -126,7 +195,7 @@ def test_aider_native_settings_resolve_bare_and_transport_names_without_rewritin
):
wire_name = "nvidia_nim/catalog-model:variant"
config = build_aider_config(
- (ClientModel(wire_name, wire_name, "Model", False),),
+ (CatalogModel(wire_name, wire_name, "Model", False),),
messages_url="http://localhost:8182/v1/messages",
api_key_env="FCC_AIDER_PROXY_AUTH_TEST123",
launch_id="launch-a",
diff --git a/tests/harnesses/test_model_catalog.py b/tests/cli/test_model_catalog_decoder.py
similarity index 71%
rename from tests/harnesses/test_model_catalog.py
rename to tests/cli/test_model_catalog_decoder.py
index c9d34f6a..8d24ba99 100644
--- a/tests/harnesses/test_model_catalog.py
+++ b/tests/cli/test_model_catalog_decoder.py
@@ -1,14 +1,13 @@
+import pytest
+
+from free_claude_code.application.model_catalog import CatalogModel
+from free_claude_code.cli.launchers.catalog_http import catalog_models_from_response
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import (
- ClientModel,
- catalog_wire_slug_for_ref,
- client_models_from_response,
-)
def test_client_models_project_nested_direct_refs_in_source_order() -> None:
- assert client_models_from_response(
+ assert catalog_models_from_response(
{
"data": [
{
@@ -24,13 +23,13 @@ def test_client_models_project_nested_direct_refs_in_source_order() -> None:
]
}
) == (
- ClientModel(
+ CatalogModel(
wire_slug="nvidia_nim/nvidia/nemotron-3-super",
provider_model_ref="nvidia_nim/nvidia/nemotron-3-super",
display_name="Display 0",
supports_reasoning=None,
),
- ClientModel(
+ CatalogModel(
wire_slug="open_router/meta-llama/llama-3.3-70b",
provider_model_ref="open_router/meta-llama/llama-3.3-70b",
display_name="Display 1",
@@ -40,7 +39,7 @@ def test_client_models_project_nested_direct_refs_in_source_order() -> None:
def test_client_models_keep_no_thinking_direct_route() -> None:
- models = client_models_from_response(
+ models = catalog_models_from_response(
{
"data": [
{
@@ -54,7 +53,7 @@ def test_client_models_keep_no_thinking_direct_route() -> None:
)
assert models == (
- ClientModel(
+ CatalogModel(
wire_slug="claude-3-freecc-no-thinking/nvidia_nim/provider-model",
provider_model_ref="nvidia_nim/provider-model",
display_name="Display 0",
@@ -64,7 +63,7 @@ def test_client_models_keep_no_thinking_direct_route() -> None:
def test_client_models_keep_no_thinking_only_route() -> None:
- assert client_models_from_response(
+ assert catalog_models_from_response(
{
"data": [
{
@@ -76,7 +75,7 @@ def test_client_models_keep_no_thinking_only_route() -> None:
]
}
) == (
- ClientModel(
+ CatalogModel(
wire_slug="claude-3-freecc-no-thinking/open_router/plain-model",
provider_model_ref="open_router/plain-model",
display_name="Display 0",
@@ -88,7 +87,7 @@ def test_client_models_keep_no_thinking_only_route() -> None:
def test_client_models_parse_capabilities_without_deriving_reasoning_from_slug() -> (
None
):
- models = client_models_from_response(
+ models = catalog_models_from_response(
{
"data": [
{
@@ -149,12 +148,12 @@ def test_client_models_ignore_compatibility_unknown_and_malformed_entries() -> N
]
}
- assert client_models_from_response(payload) == ()
- assert client_models_from_response({"data": "not-a-list"}) == ()
+ assert catalog_models_from_response(payload) == ()
+ assert catalog_models_from_response({"data": "not-a-list"}) == ()
def test_client_models_deduplicate_wire_slugs_deterministically() -> None:
- models = client_models_from_response(
+ models = catalog_models_from_response(
{
"data": [
{
@@ -183,52 +182,37 @@ def test_client_models_deduplicate_wire_slugs_deterministically() -> None:
assert models[0].display_name == "Display 0"
-def _client_model(wire_slug: str, provider_model_ref: str) -> ClientModel:
- return ClientModel(
- wire_slug=wire_slug,
- provider_model_ref=provider_model_ref,
- display_name=provider_model_ref,
- supports_reasoning=wire_slug == provider_model_ref,
- )
-
-
-def test_catalog_wire_slug_prefers_the_advertised_no_thinking_slug() -> None:
- models = (
- _client_model(
- "claude-3-freecc-no-thinking/open_router/vendor/chat-model",
- "open_router/vendor/chat-model",
- ),
- )
-
- assert (
- catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
- == "claude-3-freecc-no-thinking/open_router/vendor/chat-model"
- )
-
-
-def test_catalog_wire_slug_keeps_a_directly_advertised_ref() -> None:
- models = (
- _client_model("open_router/vendor/chat-model", "open_router/vendor/chat-model"),
- )
-
- assert (
- catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
- == "open_router/vendor/chat-model"
- )
[email protected]("default", [None, "", 1, "provider/missing"])
+def test_catalog_rejects_missing_or_unroutable_default(default) -> None:
+ from free_claude_code.cli.launchers.catalog_http import model_catalog_from_response
+ payload = {
+ "data": [{"id": "provider/model", "provider_model_ref": "provider/model"}]
+ }
+ if default is not None:
+ payload["default_model_id"] = default
+ with pytest.raises(ValueError, match="default"):
+ model_catalog_from_response(payload)
-def test_catalog_wire_slug_falls_back_when_the_catalog_omits_the_ref() -> None:
- models = (_client_model("open_router/vendor/other", "open_router/vendor/other"),)
-
- assert (
- catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
- == "open_router/vendor/chat-model"
- )
- assert catalog_wire_slug_for_ref((), "open_router/vendor/chat-model") == (
- "open_router/vendor/chat-model"
- )
+def test_http_catalog_preserves_nonblank_identity_and_selects_default_by_id() -> None:
+ from free_claude_code.cli.launchers.catalog_http import model_catalog_from_response
-def test_catalog_wire_slug_passes_through_an_unset_model() -> None:
- assert catalog_wire_slug_for_ref((), None) is None
- assert catalog_wire_slug_for_ref((), "") == ""
+ payload = {
+ "default_model_id": "provider/padded ",
+ "data": [
+ {"id": "provider/padded", "provider_model_ref": "provider/padded"},
+ {
+ "id": "provider/padded ",
+ "provider_model_ref": "provider/padded ",
+ "display_name": " Padded ",
+ },
+ ],
+ }
+ catalog = model_catalog_from_response(payload)
+ assert [model.wire_slug for model in catalog.models] == [
+ "provider/padded",
+ "provider/padded ",
+ ]
+ assert catalog.default_model_id == catalog.models[1].wire_slug
+ assert catalog.models[1].display_name == " Padded "
diff --git a/tests/cli/test_opencode_launcher.py b/tests/cli/test_opencode_launcher.py
index 1e1b2d54..4a6377e5 100644
--- a/tests/cli/test_opencode_launcher.py
+++ b/tests/cli/test_opencode_launcher.py
@@ -5,15 +5,15 @@ from pathlib import Path
import pytest
+from free_claude_code.application.model_catalog import CatalogModel
from free_claude_code.cli.launchers.opencode_config import build_opencode_config
from free_claude_code.core.model_capabilities import ModelInputModality
-from free_claude_code.harnesses.model_catalog import ClientModel
def test_opencode_config_uses_responses_sdk_and_only_known_metadata() -> None:
config = build_opencode_config(
(
- ClientModel(
+ CatalogModel(
wire_slug="nvidia_nim/vendor/model",
provider_model_ref="nvidia_nim/vendor/model",
display_name="Nested model",
@@ -24,7 +24,7 @@ def test_opencode_config_uses_responses_sdk_and_only_known_metadata() -> None:
context_window_tokens=131072,
max_output_tokens=8192,
),
- ClientModel(
+ CatalogModel(
wire_slug="claude-3-freecc-no-thinking/open_router/plain-model",
provider_model_ref="open_router/plain-model",
display_name="No-thinking model",
@@ -32,13 +32,13 @@ def test_opencode_config_uses_responses_sdk_and_only_known_metadata() -> None:
input_modalities=frozenset({ModelInputModality.TEXT}),
context_window_tokens=65536,
),
- ClientModel(
+ CatalogModel(
wire_slug="future_provider/unknown-model",
provider_model_ref="future_provider/unknown-model",
display_name="Unknown model",
supports_reasoning=None,
),
- ClientModel(
+ CatalogModel(
wire_slug="future_provider/output-only",
provider_model_ref="future_provider/output-only",
display_name="Output-only model",
@@ -46,6 +46,7 @@ def test_opencode_config_uses_responses_sdk_and_only_known_metadata() -> None:
max_output_tokens=4096,
),
),
+ default_model_id="nvidia_nim/vendor/model",
proxy_root_url="http://127.0.0.1:9191",
)
@@ -104,7 +105,11 @@ def test_opencode_config_uses_responses_sdk_and_only_known_metadata() -> None:
def test_opencode_config_rejects_empty_model_catalog() -> None:
with pytest.raises(ValueError, match="at least one"):
- build_opencode_config((), proxy_root_url="http://127.0.0.1:9191")
+ build_opencode_config(
+ (),
+ default_model_id="nvidia_nim/vendor/model",
+ proxy_root_url="http://127.0.0.1:9191",
+ )
def test_opencode_child_receives_private_catalog_and_overlay(launch_capture) -> None:
diff --git a/tests/cli/test_pi_extension.py b/tests/cli/test_pi_extension.py
index 8a60a9bd..bbbec6ff 100644
--- a/tests/cli/test_pi_extension.py
+++ b/tests/cli/test_pi_extension.py
@@ -292,8 +292,8 @@ def test_pi_extension_projects_known_capabilities_and_preserves_unknown_defaults
"contextWindow": 65536,
},
{
- "id": "provider/unknown",
- "provider_model_ref": "provider/unknown",
+ "id": "provider/unknown ",
+ "provider_model_ref": "provider/unknown ",
},
],
}
@@ -323,6 +323,12 @@ console.log(JSON.stringify(projectFccModels(payload)));
assert result.returncode == 0, result.stderr
projected = json.loads(result.stdout)
+ assert [model["id"] for model in projected] == [
+ "provider/vision-reasoning",
+ "claude-3-freecc-no-thinking/provider/text-only",
+ "provider/unknown ",
+ ]
+ assert projected[-1]["name"] == "provider/unknown "
assert [(model["reasoning"], model["input"]) for model in projected] == [
(True, ["text", "image"]),
(False, ["text"]),
diff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.py
index 5ac769b7..f0f65d77 100644
--- a/tests/contracts/test_import_boundaries.py
+++ b/tests/contracts/test_import_boundaries.py
@@ -17,8 +17,8 @@ ALLOWED_PACKAGE_DEPENDENCIES: dict[str, set[str]] = {
"messaging": {"core"},
"providers": {"application", "config", "core"},
"api": {"application", "config", "core"},
- "harnesses": {"config", "core"},
- "cli": {"config", "core", "harnesses"},
+ "harnesses": {"application", "config", "core"},
+ "cli": {"application", "config", "core", "harnesses"},
"runtime": {
"api",
"application",
@@ -174,6 +174,26 @@ def test_shared_harness_setup_has_no_terminal_owner() -> None:
assert not offenders and not remaining, "\n".join(offenders + remaining)
+def test_native_model_catalog_has_no_http_formatter_or_decoder_dependency() -> None:
+ callers = {
+ f"{_PACKAGE_NAME}.runtime.codex_app_server",
+ f"{_PACKAGE_NAME}.runtime.codex_catalog",
+ f"{_PACKAGE_NAME}.harnesses.codex_model_catalog",
+ }
+ offenders = [
+ record.describe()
+ for record in _scan_imports(_PACKAGE_ROOT)
+ if record.importer in callers
+ and record.imported.startswith(
+ (f"{_PACKAGE_NAME}.api.", f"{_PACKAGE_NAME}.cli.launchers.")
+ )
+ ]
+ assert not offenders, (
+ "Native catalog policy belongs outside HTTP adapters:\n" + "\n".join(offenders)
+ )
+ assert not (_PACKAGE_ROOT / "harnesses/model_catalog.py").exists()
+
+
def test_package_dependencies_follow_declarative_policy() -> None:
modules = _module_paths(_PACKAGE_ROOT)
records = _scan_imports(_PACKAGE_ROOT)
diff --git a/tests/harnesses/test_codex_model_catalog.py b/tests/harnesses/test_codex_model_catalog.py
index cf3a85df..c03ca18d 100644
--- a/tests/harnesses/test_codex_model_catalog.py
+++ b/tests/harnesses/test_codex_model_catalog.py
@@ -1,10 +1,10 @@
from collections.abc import Mapping
from typing import Any, cast
+from free_claude_code.cli.launchers.catalog_http import catalog_models_from_response
from free_claude_code.harnesses.codex_model_catalog import (
build_codex_model_catalog,
)
-from free_claude_code.harnesses.model_catalog import client_models_from_response
def _models_payload(*model_ids: str) -> dict[str, Any]:
@@ -43,7 +43,7 @@ def _slugs(catalog: Mapping[str, Any]) -> list[str]:
def test_codex_catalog_uses_direct_configured_and_cached_model_slugs() -> None:
catalog = build_codex_model_catalog(
- client_models_from_response(
+ catalog_models_from_response(
_models_payload(
"nvidia_nim/nvidia/nemotron-3-super",
"open_router/meta-llama/llama-3.3-70b",
@@ -73,7 +73,7 @@ def test_codex_catalog_uses_direct_configured_and_cached_model_slugs() -> None:
def test_codex_catalog_ignores_rows_without_direct_provider_identity() -> None:
catalog = build_codex_model_catalog(
- client_models_from_response(
+ catalog_models_from_response(
{
"data": [
{"id": "claude-opus-4-20250514"},
@@ -92,7 +92,7 @@ def test_codex_catalog_ignores_rows_without_direct_provider_identity() -> None:
def test_codex_catalog_deduplicates_direct_wire_ids() -> None:
catalog = build_codex_model_catalog(
- client_models_from_response(
+ catalog_models_from_response(
_models_payload(
"nvidia_nim/provider-model",
"nvidia_nim/provider-model",
@@ -105,7 +105,7 @@ def test_codex_catalog_deduplicates_direct_wire_ids() -> None:
def test_codex_catalog_preserves_no_thinking_only_entries_for_routing() -> None:
catalog = build_codex_model_catalog(
- client_models_from_response(
+ catalog_models_from_response(
_models_payload("claude-3-freecc-no-thinking/open_router/plain-model")
)
)
@@ -115,7 +115,7 @@ def test_codex_catalog_preserves_no_thinking_only_entries_for_routing() -> None:
def test_codex_catalog_ordering_and_priorities_are_deterministic() -> None:
catalog = build_codex_model_catalog(
- client_models_from_response(
+ catalog_models_from_response(
_models_payload(
"anthropic/gemini/models/gemini-test",
"nvidia_nim/nvidia/test",
@@ -138,7 +138,7 @@ def test_codex_catalog_accepts_direct_provider_slugs_without_a_provider_registry
None
):
catalog = build_codex_model_catalog(
- client_models_from_response(
+ catalog_models_from_response(
_models_payload(
"nvidia_nim/provider-model",
"future_provider/provider-model",
@@ -156,7 +156,7 @@ def test_codex_catalog_projects_known_capabilities_and_preserves_unknown_default
None
):
catalog = build_codex_model_catalog(
- client_models_from_response(
+ catalog_models_from_response(
{
"data": [
{
diff --git a/tests/runtime/test_codex_catalog.py b/tests/runtime/test_codex_catalog.py
index f2e2a992..40a7f93b 100644
--- a/tests/runtime/test_codex_catalog.py
+++ b/tests/runtime/test_codex_catalog.py
@@ -11,9 +11,10 @@ from free_claude_code.application.ports import (
RequestRuntimeLease,
RequestRuntimePort,
)
+from free_claude_code.cli.launchers.catalog_http import catalog_models_from_response
from free_claude_code.config.settings import Settings
+from free_claude_code.core.model_capabilities import ModelInputModality
from free_claude_code.harnesses.codex_model_catalog import build_codex_model_catalog
-from free_claude_code.harnesses.model_catalog import client_models_from_response
from free_claude_code.runtime.codex_app_server import CodexHarnessFactory
from free_claude_code.runtime.codex_catalog import (
CodexModelCatalogPublisher,
@@ -69,6 +70,35 @@ def _catalog_slugs(path: Path) -> list[str]:
return [model["slug"] for model in payload["models"]]
+async def test_known_vision_survives_publication_and_browser_preparation(
+ tmp_path: Path,
+):
+ runtime = FakeRequestRuntime(
+ settings=Settings().model_copy(update={"model": "nvidia_nim/configured"}),
+ cached_infos=(
+ ProviderModelInfo(
+ "open_router/vision",
+ input_modalities=frozenset(
+ {ModelInputModality.TEXT, ModelInputModality.IMAGE}
+ ),
+ context_window_tokens=131072,
+ ),
+ ),
+ )
+ path = tmp_path / "catalog.json"
+ CodexModelCatalogPublisher(path).publish(runtime)
+ entries = {row["slug"]: row for row in json.loads(path.read_text())["models"]}
+ assert entries["open_router/vision"]["input_modalities"] == ["text", "image"]
+ selected = await CodexHarnessFactory(runtime, binary="codex").prepare(
+ "open_router/vision", None, "config"
+ )
+ prepared = json.loads(json.dumps(build_codex_model_catalog(selected.models)))
+ assert next(
+ row for row in prepared["models"] if row["slug"] == "open_router/vision"
+ )["input_modalities"] == ["text", "image"]
+
+
def test_publisher_projects_the_application_catalog_without_compatibility_ids(
tmp_path: Path,
) -> None:
@@ -146,10 +176,10 @@ def test_catalog_writer_skips_identical_content_and_replaces_changes(
) -> None:
catalog_path = tmp_path / "codex-model-catalog.json"
first = build_codex_model_catalog(
- client_models_from_response(_models_payload("nvidia_nim/first"))
+ catalog_models_from_response(_models_payload("nvidia_nim/first"))
)
second = build_codex_model_catalog(
- client_models_from_response(_models_payload("nvidia_nim/second"))
+ catalog_models_from_response(_models_payload("nvidia_nim/second"))
)
assert write_codex_model_catalog(catalog_path, first) is True
@@ -177,9 +207,52 @@ def test_catalog_writer_cleans_temporary_file_after_replace_failure(
write_codex_model_catalog(
catalog_path,
build_codex_model_catalog(
- client_models_from_response(_models_payload("nvidia_nim/replacement"))
+ catalog_models_from_response(_models_payload("nvidia_nim/replacement"))
),
)
assert catalog_path.read_text(encoding="utf-8") == "previous\n"
assert list(tmp_path.glob(".codex-model-catalog.json.*.tmp")) == []
+
+
+async def test_catalog_refresh_preserves_selection_and_behavior_fingerprint():
+ runtime = FakeRequestRuntime(
+ settings=Settings().model_copy(update={"model": "open_router/Zulu"}),
+ cached_infos=(
+ ProviderModelInfo("open_router/Zulu", context_window_tokens=32000),
+ ),
+ )
+ factory = CodexHarnessFactory(runtime, binary="codex")
+ before = await factory.prepare("open_router/Zulu", "high", "config")
+ runtime._cached_infos = (
+ ProviderModelInfo("deepseek/alpha"),
+ *runtime._cached_infos,
+ )
+ after = await factory.prepare("open_router/Zulu", "high", "config")
+ assert after.model == before.model
+ assert after.reasoning_effort == before.reasoning_effort
+ assert after.configuration_key == before.configuration_key
+ assert factory.catalog().default_model == "open_router/Zulu"
+ assert factory.catalog().models[0].id == "deepseek/alpha"
+ runtime._cached_infos = (
+ ProviderModelInfo("open_router/Zulu", context_window_tokens=64000),
+ )
+ changed = await factory.prepare("open_router/Zulu", "high", "config")
+ assert changed.configuration_key != before.configuration_key
+
+
+ "modalities", [frozenset(), frozenset({ModelInputModality.IMAGE})]
+)
+def test_non_text_capabilities_retain_the_native_text_fallback(modalities):
+ from free_claude_code.application.model_catalog import read_model_catalog
+
+ snapshot = ModelCatalogSnapshot(
+ Settings().model_copy(update={"model": "open_router/model"}),
+ (ProviderModelInfo("open_router/model", input_modalities=modalities),),
+ )
+ catalog = read_model_catalog(snapshot)
+ assert catalog.models[0].input_modalities == modalities
+ payload = json.loads(json.dumps(build_codex_model_catalog(catalog.models)))
+ assert payload["models"][0]["input_modalities"] == ["text"]
diff --git a/uv.lock b/uv.lock
index 05ebf75c..6864825e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "6.2.30"
+version = "6.2.31"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },