From b7be9b4f291a4f5542004687bde5e3c050efee10 Mon Sep 17 00:00:00 2001
From: Ali Khokhar <20476625+Alishahryar1@users.noreply.github.com>
Date: Sat, 26 Sep 2026 13:22:04 -0700
Subject: [PATCH] minor: Add custom API providers (#1909)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
## Why
Users need to connect API-compatible endpoints that are not in FCC's
built-in provider catalog. They should be able to configure them from
the Providers page and select their models in the existing pickers.
## How
- Add an alphabetically sorted Custom providers section with Add, Edit,
and Remove actions using the existing card and modal styles.
- Configure a name, API base URL, optional API key, Chat Completions /
Responses / Anthropic Messages format, and compatible reasoning
controls. Reuse FCC's existing transports, admission control, and
provider lifecycle.
- Discover models in the background. Optional manual model IDs replace
discovery. Preserve the supplied API path and append the selected
protocol's endpoint.
- Store definitions in the managed configuration with immutable IDs and
merge individual edits under the existing Apply lock. Renaming preserves
routing references. Removal requires reassigning any default, tier, or
fallback routes first.
- Publish configuration changes through existing runtime generations.
In-flight requests retain their original configuration, changed
endpoints receive fresh model inventories, and requests targeting
removed custom providers fail explicitly.
- Carry the selected model's generation-owned metadata through both
ingress paths. Messages egress applies a request-local output limit to
initial requests and corrective retries, and rejects exact thinking
budgets that cannot fit. Native Provider-default controls remain
distinct from synthesized preset controls.
- Show provider names in model pickers, redact keys in Admin and
fcc-doctor output, and add brief README setup instructions.
Accepted choices: blank or omitted keys preserve an existing key, while
Remove key clears it. Provider-default reasoning preserves native
request controls and adds no cross-protocol computation controls.
Process-environment definitions are read-only in Admin. Custom endpoints
inherit the selected transport's existing compatibility limits,
including Messages egress restrictions on grammar tools, client tool
search, and prompt-cache keys. Codex web-search work is outside this
feature.
Summary
The PR adds custom API providers, model discovery and selection, and
generation-aware routing. The latest changes sort models by provider
display name while preserving model identity. No new issues remain.
Reviews (3) · Last reviewed commit: ["Sort custom provider names
independently..."](https://github.com/alishahryar1/free-claude-code/commit/063ff29c2cb5c7b22bab0e6d0721ab731d1dd12e)
---
README.md | 2 +
e2e/conftest.py | 1 +
e2e/test_custom_providers.py | 122 +++
e2e/test_provider_modals.py | 1 +
src/free_claude_code/api/admin_routes.py | 11 +-
.../api/admin_static/admin.js | 122 ++-
.../api/admin_static/code_sessions.js | 6 +-
.../api/admin_static/model_combobox.js | 6 +-
src/free_claude_code/api/dependencies.py | 3 +-
.../api/handlers/responses.py | 4 +-
src/free_claude_code/api/ports.py | 5 +-
src/free_claude_code/api/routes.py | 1 +
src/free_claude_code/application/execution.py | 3 +
.../application/model_catalog.py | 25 +-
src/free_claude_code/application/ports.py | 1 +
src/free_claude_code/application/routing.py | 27 +-
.../config/admin/custom_providers.py | 101 +++
.../config/admin/persistence.py | 11 +
src/free_claude_code/config/admin/values.py | 11 +
.../config/custom_providers.py | 119 +++
src/free_claude_code/config/env_migrations.py | 2 +-
src/free_claude_code/config/settings.py | 45 +-
.../anthropic_messages/request_policy.py | 8 +
.../providers/anthropic_messages/transport.py | 48 +-
src/free_claude_code/providers/base.py | 1 +
src/free_claude_code/providers/custom.py | 380 +++++++++
.../providers/github_copilot/provider.py | 8 +-
.../providers/lmstudio/client.py | 2 +
.../providers/openai_api/provider.py | 1 +
.../providers/openai_chat/__init__.py | 4 +
.../providers/openai_chat/provider.py | 1 +
.../providers/openai_codex/provider.py | 1 +
.../providers/opencode/provider.py | 1 +
.../providers/runtime/config.py | 19 +
.../providers/runtime/discovery.py | 8 +-
.../providers/runtime/factory.py | 20 +
.../providers/runtime/model_cache.py | 5 +-
.../providers/runtime/runtime.py | 12 +-
src/free_claude_code/runtime/application.py | 6 +-
src/free_claude_code/runtime/configuration.py | 8 +-
src/free_claude_code/runtime/diagnostics.py | 14 +-
.../runtime/provider_manager.py | 27 +-
tests/api/model_fallback_support.py | 1 +
tests/api/test_admin.py | 13 +-
tests/api/test_api_handlers.py | 1 +
tests/api/test_execution_failure_contract.py | 1 +
tests/api/test_openai_responses.py | 39 +-
tests/api/test_request_lifetime.py | 1 +
tests/api/test_web_server_tools.py | 1 +
tests/application/test_execution.py | 47 +-
tests/application/test_model_catalog.py | 36 +
.../config/test_custom_provider_mutations.py | 117 +++
tests/config/test_custom_providers.py | 78 ++
.../test_anthropic_messages_transport.py | 55 +-
tests/providers/test_custom_provider.py | 718 ++++++++++++++++++
.../providers/test_messages_request_policy.py | 6 +-
tests/providers/test_model_discovery.py | 1 +
tests/runtime/test_application_runtime.py | 1 +
.../runtime/test_custom_provider_lifecycle.py | 95 +++
tests/runtime/test_provider_manager.py | 11 +-
60 files changed, 2334 insertions(+), 91 deletions(-)
create mode 100644 e2e/test_custom_providers.py
create mode 100644 src/free_claude_code/config/admin/custom_providers.py
create mode 100644 src/free_claude_code/config/custom_providers.py
create mode 100644 src/free_claude_code/providers/custom.py
create mode 100644 tests/config/test_custom_provider_mutations.py
create mode 100644 tests/config/test_custom_providers.py
create mode 100644 tests/providers/test_custom_provider.py
create mode 100644 tests/runtime/test_custom_provider_lifecycle.py
diff --git a/README.md b/README.md
index d599643393..2dadeb09fa 100644
--- a/README.md
+++ b/README.md
@@ -198,6 +198,8 @@ Optional: add an ordered **Fallback Models** list under **Model Config**. It
applies to every connected client. A failed request may reach and consume usage
from more than one provider before succeeding.
+For another API endpoint, open **Providers → Custom providers → Add provider**. Enter its API base URL, optional key, and API format. Leave **Model IDs** empty to discover models automatically, or enter one upstream model ID per line. Save, then select a model in **Model Config**.
+
Provider catalog 0 " in "".join(output)
assert len(bodies) == 2
- assert bodies[0]["max_tokens"] == 8192
+ assert [body["max_tokens"] for body in bodies] == [cap or 8192, cap or 8192]
assert "thinking" not in bodies[1]
@@ -243,7 +251,9 @@ def _events(text: str = "hello", stop: str = "end_turn") -> list[JsonObject]:
def _transport(
- client: httpx.AsyncClient, admission: ProviderAdmissionController | None = None
+ client: httpx.AsyncClient,
+ admission: ProviderAdmissionController | None = None,
+ capabilities: MessagesModelCapabilities = MessagesModelCapabilities(),
) -> AnthropicMessagesTransport:
return AnthropicMessagesTransport(
client=client,
@@ -251,9 +261,46 @@ def _transport(
provider_name="TEST",
replay_scope="test/messages",
read_timeout_s=3,
+ capabilities=capabilities,
)
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ "profile_cap,model_cap,expected",
+ [(2048, 4096, 2048), (4096, 2048, 2048), (4096, None, 4096)],
+)
+async def test_model_metadata_cannot_relax_declared_profile_cap(
+ profile_cap, model_cap, expected
+):
+ bodies = []
+
+ def reply(request):
+ bodies.append(json.loads(request.content))
+ return httpx.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ stream=Wire([_sse(*_events())]),
+ )
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(reply)) as client:
+ transport = _transport(
+ client,
+ capabilities=MessagesModelCapabilities(max_output_tokens=profile_cap),
+ )
+ assert [
+ item
+ async for item in transport.stream_responses(
+ OpenAIResponsesRequest(
+ model="native", input="hi", max_output_tokens=8192
+ ),
+ endpoint_context=Endpoint(),
+ model_info=ProviderModelInfo("native", max_output_tokens=model_cap),
+ )
+ ]
+ assert bodies[0]["max_tokens"] == expected
+
+
def _stream(
transport: AnthropicMessagesTransport, endpoint: Endpoint, *, responses: bool
) -> AsyncIterator[str]:
@@ -308,7 +355,7 @@ def handler(request: httpx.Request) -> httpx.Response:
)
assert not client.is_closed
assert wire.closed and len(requests) == 1
- assert requests[0].url.path == "/v1/messages"
+ assert requests[0].url.path == ("/v1/messages" if versioned_base else "/messages")
assert requests[0].headers["Authorization"] == "Bearer original"
assert requests[0].headers["anthropic-version"] == "2023-06-01"
assert requests[0].headers.get_list("anthropic-version") == ["2023-06-01"]
diff --git a/tests/providers/test_custom_provider.py b/tests/providers/test_custom_provider.py
new file mode 100644
index 0000000000..78ba6c94dd
--- /dev/null
+++ b/tests/providers/test_custom_provider.py
@@ -0,0 +1,718 @@
+import asyncio
+import json
+
+import httpx
+import httpx2
+import pytest
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.config.custom_providers import CustomProviderDefinition
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic import MessagesRequest
+from free_claude_code.core.model_capabilities import ModelInputModality
+from free_claude_code.core.openai_responses import OpenAIResponsesRequest
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+from free_claude_code.providers.admission import ProviderAdmissionController
+from free_claude_code.providers.custom import CustomProvider
+from free_claude_code.providers.runtime.config import build_custom_provider_config
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest.mark.parametrize(
+ "thinking",
+ [
+ None,
+ {"type": "adaptive", "display": "omitted"},
+ {"type": "enabled", "budget_tokens": 1536},
+ ],
+)
+async def test_native_default_preserves_controls_without_advertised_support(thinking):
+ bodies = []
+
+ def reply(request):
+ bodies.append(json.loads(request.content))
+ return httpx.Response(
+ 200,
+ text=completion("anthropic_messages"),
+ headers={"content-type": "text/event-stream"},
+ )
+
+ instance = provider(
+ definition(api_format="anthropic_messages"), messages_handler=reply
+ )
+ request = MessagesRequest(
+ model="m",
+ max_tokens=4096,
+ messages=[{"role": "user", "content": "Hello"}],
+ thinking=thinking,
+ output_config={
+ "effort": "high",
+ "format": {"type": "json_schema", "schema": {"type": "object"}},
+ },
+ )
+ before = request.model_dump()
+ try:
+ assert [
+ item
+ async for item in instance.stream_messages(
+ request, reasoning=ReasoningPolicy.off()
+ )
+ ]
+ assert bodies[0].get("thinking") == thinking
+ assert bodies[0]["output_config"] == request.output_config
+ assert request.model_dump() == before
+ finally:
+ await instance.cleanup()
+
+
+@pytest.mark.parametrize("ingress", ["messages", "responses"])
+@pytest.mark.parametrize(
+ "limit,cap,expected",
+ [(2048, 4096, 2048), (8192, 4096, 4096), (None, 4096, 4096), (8192, None, 8192)],
+)
+async def test_messages_egress_obeys_request_model_limit(ingress, limit, cap, expected):
+ bodies = []
+
+ def reply(request):
+ bodies.append(json.loads(request.content))
+ return httpx.Response(
+ 200,
+ text=completion("anthropic_messages"),
+ headers={"content-type": "text/event-stream"},
+ )
+
+ instance = provider(
+ definition(api_format="anthropic_messages"), messages_handler=reply
+ )
+ info = ProviderModelInfo("m", max_output_tokens=cap) if cap else None
+ try:
+ if ingress == "messages":
+ request = MessagesRequest(
+ model="m",
+ max_tokens=limit,
+ messages=[{"role": "user", "content": "Hello"}],
+ )
+ stream = instance.stream_messages(request, model_info=info)
+ else:
+ request = OpenAIResponsesRequest(
+ model="m",
+ max_output_tokens=limit,
+ input="Hello",
+ reasoning={"effort": "high"},
+ )
+ stream = instance.stream_responses(request, model_info=info)
+ before = request.model_dump()
+ assert [item async for item in stream]
+ assert bodies[0]["max_tokens"] == expected
+ assert "thinking" not in bodies[0]
+ assert "effort" not in bodies[0].get("output_config", {})
+ assert request.model_dump() == before
+ finally:
+ await instance.cleanup()
+
+
+@pytest.mark.parametrize("ingress", ["messages", "responses"])
+@pytest.mark.parametrize("exact", [False, True])
+@pytest.mark.parametrize("cap", [1024, 4096])
+async def test_manual_preset_respects_cap_before_resolving_budget(ingress, exact, cap):
+ bodies = []
+
+ def reply(request):
+ bodies.append(json.loads(request.content))
+ return httpx.Response(
+ 200,
+ text=completion("anthropic_messages"),
+ headers={"content-type": "text/event-stream"},
+ )
+
+ instance = provider(
+ definition(api_format="anthropic_messages", reasoning_format="messages_manual"),
+ messages_handler=reply,
+ )
+ policy = (
+ ReasoningPolicy.on(budget_tokens=4096)
+ if exact
+ else ReasoningPolicy.on(effort=ReasoningEffort.HIGH)
+ )
+ info = ProviderModelInfo("m", max_output_tokens=cap)
+
+ async def consume():
+ if ingress == "messages":
+ stream = instance.stream_messages(
+ MessagesRequest(
+ model="m",
+ max_tokens=8192,
+ messages=[{"role": "user", "content": "Hello"}],
+ ),
+ reasoning=policy,
+ model_info=info,
+ )
+ else:
+ stream = instance.stream_responses(
+ OpenAIResponsesRequest(
+ model="m", max_output_tokens=8192, input="Hello"
+ ),
+ reasoning=policy,
+ model_info=info,
+ )
+ return [item async for item in stream]
+
+ try:
+ if exact or cap == 1024:
+ with pytest.raises(InvalidRequestError, match="below max_tokens"):
+ await consume()
+ assert not bodies
+ else:
+ assert await consume()
+ assert bodies[0]["max_tokens"] == cap
+ assert 1024 <= bodies[0]["thinking"]["budget_tokens"] < cap
+ finally:
+ await instance.cleanup()
+
+
+@pytest.mark.parametrize(
+ "thinking,error",
+ [
+ ({"type": "enabled"}, "budget"),
+ ({"type": "enabled", "budget_tokens": 6000}, "below max_tokens"),
+ ],
+)
+async def test_native_default_does_not_invent_or_shrink_exact_budget(thinking, error):
+ bodies = []
+ instance = provider(
+ definition(api_format="anthropic_messages"),
+ messages_handler=lambda request: bodies.append(request),
+ )
+ try:
+ with pytest.raises(InvalidRequestError, match=error):
+ stream = instance.stream_messages(
+ MessagesRequest(
+ model="m",
+ max_tokens=8192,
+ thinking=thinking,
+ messages=[{"role": "user", "content": "Hello"}],
+ ),
+ model_info=ProviderModelInfo("m", max_output_tokens=4096),
+ )
+ [item async for item in stream]
+ assert not bodies
+ finally:
+ await instance.cleanup()
+
+
+async def test_concurrent_models_keep_independent_limits():
+ bodies = []
+ both_started = asyncio.Event()
+
+ async def reply(request):
+ bodies.append(json.loads(request.content))
+ if len(bodies) == 2:
+ both_started.set()
+ await asyncio.wait_for(both_started.wait(), timeout=2)
+ return httpx.Response(
+ 200,
+ text=completion("anthropic_messages"),
+ headers={"content-type": "text/event-stream"},
+ )
+
+ instance = provider(
+ definition(api_format="anthropic_messages"), messages_handler=reply
+ )
+
+ async def call(model, cap):
+ stream = instance.stream_messages(
+ MessagesRequest(
+ model=model,
+ max_tokens=8192,
+ messages=[{"role": "user", "content": "Hello"}],
+ ),
+ model_info=ProviderModelInfo(model, max_output_tokens=cap),
+ )
+ return [item async for item in stream]
+
+ try:
+ await asyncio.gather(call("small", 2048), call("large", 6000))
+ assert {body["model"]: body["max_tokens"] for body in bodies} == {
+ "small": 2048,
+ "large": 6000,
+ }
+ finally:
+ await instance.cleanup()
+
+
+def definition(**changes):
+ return CustomProviderDefinition.model_validate(
+ {
+ "provider_id": "custom_" + "a" * 32,
+ "display_name": "Gateway",
+ "base_url": "https://custom.example/team/api",
+ **changes,
+ }
+ )
+
+
+def provider(config, *, openai_handler=None, messages_handler=None):
+ settings = Settings(provider_rate_limit=1000)
+ return CustomProvider(
+ build_custom_provider_config(config, settings),
+ definition=config,
+ admission=ProviderAdmissionController(
+ provider_name=config.provider_id,
+ rate_limit=1000,
+ rate_window=1,
+ max_concurrency=2,
+ ),
+ openai_transport=httpx2.MockTransport(openai_handler)
+ if openai_handler
+ else None,
+ messages_transport=httpx.MockTransport(messages_handler)
+ if messages_handler
+ else None,
+ )
+
+
+def event(name, data):
+ return f"event: {name}\ndata: {json.dumps(data)}\n\n"
+
+
+def completion(api_format):
+ if api_format == "openai_chat":
+ data = {
+ "id": "chat",
+ "object": "chat.completion.chunk",
+ "created": 0,
+ "model": "m",
+ "choices": [
+ {"index": 0, "delta": {"content": "Hello"}, "finish_reason": "stop"}
+ ],
+ }
+ return f"data: {json.dumps(data)}\n\ndata: [DONE]\n\n"
+ if api_format == "openai_responses":
+ message = {
+ "id": "msg",
+ "type": "message",
+ "role": "assistant",
+ "status": "completed",
+ "content": [{"type": "output_text", "text": "Hello", "annotations": []}],
+ }
+ return (
+ event(
+ "response.output_item.added",
+ {
+ "type": "response.output_item.added",
+ "output_index": 0,
+ "item": {**message, "content": []},
+ },
+ )
+ + event(
+ "response.output_text.delta",
+ {
+ "type": "response.output_text.delta",
+ "item_id": "msg",
+ "output_index": 0,
+ "content_index": 0,
+ "delta": "Hello",
+ },
+ )
+ + event(
+ "response.completed",
+ {
+ "type": "response.completed",
+ "response": {
+ "id": "resp",
+ "object": "response",
+ "created_at": 0,
+ "status": "completed",
+ "model": "m",
+ "output": [message],
+ "usage": {
+ "input_tokens": 1,
+ "output_tokens": 1,
+ "total_tokens": 2,
+ },
+ },
+ },
+ )
+ )
+ return "".join(
+ [
+ event(
+ "message_start",
+ {
+ "type": "message_start",
+ "message": {
+ "id": "msg",
+ "type": "message",
+ "role": "assistant",
+ "model": "m",
+ "content": [],
+ "stop_reason": None,
+ "usage": {"input_tokens": 1, "output_tokens": 0},
+ },
+ },
+ ),
+ event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "text", "text": ""},
+ },
+ ),
+ event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "text_delta", "text": "Hello"},
+ },
+ ),
+ event("content_block_stop", {"type": "content_block_stop", "index": 0}),
+ event(
+ "message_delta",
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": "end_turn"},
+ "usage": {"output_tokens": 1},
+ },
+ ),
+ event("message_stop", {"type": "message_stop"}),
+ ]
+ )
+
+
+@pytest.mark.parametrize(
+ "api_format,path",
+ [
+ ("openai_chat", "chat/completions"),
+ ("openai_responses", "responses"),
+ ("anthropic_messages", "messages"),
+ ],
+)
+@pytest.mark.parametrize("ingress", ["messages", "responses"])
+@pytest.mark.parametrize("key", [None, "custom-key"])
+async def test_six_paths_use_exact_endpoint_and_credentials(
+ api_format, path, ingress, key, monkeypatch
+):
+ monkeypatch.setenv("OPENAI_API_KEY", "unrelated-key")
+ monkeypatch.setenv("OPENAI_ORG_ID", "unrelated-org")
+ monkeypatch.setenv("OPENAI_PROJECT_ID", "unrelated-project")
+ requests = []
+
+ def reply(request):
+ requests.append(request)
+ cls = httpx.Response if api_format == "anthropic_messages" else httpx2.Response
+ return cls(
+ 200,
+ text=completion(api_format),
+ headers={"content-type": "text/event-stream"},
+ )
+
+ instance = provider(
+ definition(api_format=api_format, api_key=key),
+ openai_handler=reply if api_format != "anthropic_messages" else None,
+ messages_handler=reply if api_format == "anthropic_messages" else None,
+ )
+ try:
+ policy = ReasoningPolicy.on(effort=ReasoningEffort.MEDIUM)
+ if ingress == "messages":
+ request = MessagesRequest(
+ model="m",
+ max_tokens=100,
+ messages=[{"role": "user", "content": "Hello"}],
+ )
+ stream = instance.stream_messages(request, reasoning=policy)
+ else:
+ request = OpenAIResponsesRequest(
+ model="m", input="Hello", reasoning={"effort": "medium"}
+ )
+ stream = instance.stream_responses(request, reasoning=policy)
+ output = "".join([chunk async for chunk in stream])
+ assert "Hello" in output
+ assert len(requests) == 1
+ sent = requests[0]
+ assert str(sent.url) == f"https://custom.example/team/api/{path}"
+ assert sent.headers.get("x-api-key") == (
+ key if api_format == "anthropic_messages" else None
+ )
+ assert sent.headers.get("authorization") == (
+ f"Bearer {key}" if key and api_format != "anthropic_messages" else None
+ )
+ assert "openai-organization" not in sent.headers
+ assert "openai-project" not in sent.headers
+ body = json.loads(sent.content)
+ if ingress == "responses" and api_format == "openai_responses":
+ assert body["reasoning"]["effort"] == "medium"
+ else:
+ assert "reasoning_effort" not in body
+ assert not body.get("reasoning")
+ assert "thinking" not in body
+ if ingress == "responses":
+ assert isinstance(request, OpenAIResponsesRequest)
+ assert request.reasoning == {"effort": "medium"}
+ finally:
+ await instance.cleanup()
+
+
+@pytest.mark.parametrize(
+ "api_format", ["openai_chat", "openai_responses", "anthropic_messages"]
+)
+async def test_discovery_is_bound_and_manual_inventory_needs_no_network(
+ api_format, monkeypatch
+):
+ monkeypatch.setenv("OPENAI_API_KEY", "do-not-send")
+ requests = []
+
+ def reply(request):
+ requests.append(request)
+ cls = httpx.Response if api_format == "anthropic_messages" else httpx2.Response
+ return cls(200, json={"data": [{"id": "org/model"}], "has_more": False})
+
+ instance = provider(
+ definition(api_format=api_format),
+ openai_handler=reply if api_format != "anthropic_messages" else None,
+ messages_handler=reply if api_format == "anthropic_messages" else None,
+ )
+ try:
+ assert {info.model_id for info in await instance.list_model_infos()} == {
+ "org/model"
+ }
+ assert requests[0].url.path == "/team/api/models"
+ assert "authorization" not in requests[0].headers
+ assert "x-api-key" not in requests[0].headers
+ finally:
+ await instance.cleanup()
+ requests.clear()
+ manual = provider(
+ definition(api_format=api_format, model_ids=["manual"]),
+ openai_handler=reply if api_format != "anthropic_messages" else None,
+ messages_handler=reply if api_format == "anthropic_messages" else None,
+ )
+ try:
+ assert {info.model_id for info in await manual.list_model_infos()} == {"manual"}
+ assert not requests
+ finally:
+ await manual.cleanup()
+
+
+@pytest.mark.parametrize(
+ "api_format,mode,field,expected",
+ [
+ ("openai_chat", "openai_effort", "reasoning_effort", "high"),
+ ("openai_chat", "limited_effort", "reasoning_effort", "high"),
+ ("openai_chat", "reasoning_object", "reasoning", {"effort": "high"}),
+ ("openai_chat", "thinking", "thinking", {"type": "enabled"}),
+ (
+ "openai_chat",
+ "chat_template",
+ "chat_template_kwargs",
+ {"enable_thinking": True},
+ ),
+ (
+ "openai_responses",
+ "native_responses",
+ "reasoning",
+ {"effort": "high", "summary": "auto"},
+ ),
+ (
+ "anthropic_messages",
+ "messages_manual",
+ "thinking",
+ {"type": "enabled", "budget_tokens": 2048},
+ ),
+ ("anthropic_messages", "messages_adaptive", "thinking", {"type": "adaptive"}),
+ ],
+)
+async def test_reasoning_presets_encode_controls_on_the_wire(
+ api_format, mode, field, expected
+):
+ bodies = []
+
+ def reply(request):
+ bodies.append(json.loads(request.content))
+ cls = httpx.Response if api_format == "anthropic_messages" else httpx2.Response
+ return cls(
+ 200,
+ text=completion(api_format),
+ headers={"content-type": "text/event-stream"},
+ )
+
+ instance = provider(
+ definition(api_format=api_format, reasoning_format=mode),
+ openai_handler=reply if api_format != "anthropic_messages" else None,
+ messages_handler=reply if api_format == "anthropic_messages" else None,
+ )
+ try:
+ request = MessagesRequest(
+ model="m", max_tokens=4096, messages=[{"role": "user", "content": "Hello"}]
+ )
+ assert [
+ chunk
+ async for chunk in instance.stream_messages(
+ request, reasoning=ReasoningPolicy.on(effort=ReasoningEffort.HIGH)
+ )
+ ]
+ assert bodies[0][field] == expected
+ finally:
+ await instance.cleanup()
+
+
+@pytest.mark.parametrize(
+ "api_format", ["openai_chat", "openai_responses", "anthropic_messages"]
+)
+@pytest.mark.parametrize("ingress", ["messages", "responses"])
+async def test_tool_continuation_keeps_tool_results_and_images(api_format, ingress):
+ bodies = []
+
+ def reply(request):
+ bodies.append(json.loads(request.content))
+ cls = httpx.Response if api_format == "anthropic_messages" else httpx2.Response
+ return cls(
+ 200,
+ text=completion(api_format),
+ headers={"content-type": "text/event-stream"},
+ )
+
+ instance = provider(
+ definition(api_format=api_format),
+ openai_handler=reply if api_format != "anthropic_messages" else None,
+ messages_handler=reply if api_format == "anthropic_messages" else None,
+ )
+ try:
+ if ingress == "messages":
+ request = MessagesRequest(
+ model="m",
+ max_tokens=100,
+ tools=[
+ {
+ "name": "Read",
+ "input_schema": {"type": "object", "properties": {}},
+ }
+ ],
+ messages=[
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "call_read",
+ "name": "Read",
+ "input": {},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "call_read",
+ "content": [
+ {"type": "text", "text": "tool-result-token"},
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": "aGVsbG8=",
+ },
+ },
+ ],
+ }
+ ],
+ },
+ ],
+ )
+ chunks = instance.stream_messages(request)
+ else:
+ request = OpenAIResponsesRequest(
+ model="m",
+ tools=[
+ {
+ "type": "function",
+ "name": "Read",
+ "parameters": {"type": "object", "properties": {}},
+ }
+ ],
+ input=[
+ {
+ "type": "function_call",
+ "call_id": "call_read",
+ "name": "Read",
+ "arguments": "{}",
+ },
+ {
+ "type": "function_call_output",
+ "call_id": "call_read",
+ "output": [
+ {"type": "input_text", "text": "tool-result-token"},
+ {
+ "type": "input_image",
+ "image_url": "data:image/png;base64,aGVsbG8=",
+ },
+ ],
+ },
+ ],
+ )
+ chunks = instance.stream_responses(request)
+ assert [chunk async for chunk in chunks]
+ body = json.dumps(bodies[0])
+ assert (
+ "tool-result-token" in body and "aGVsbG8=" in body and "call_read" in body
+ )
+ finally:
+ await instance.cleanup()
+
+
+async def test_messages_discovery_rejects_repeating_cursor_without_partial_results():
+ calls = []
+
+ def reply(request):
+ calls.append(request)
+ return httpx.Response(
+ 200, json={"data": [{"id": "same"}], "has_more": True, "last_id": "same"}
+ )
+
+ instance = provider(
+ definition(api_format="anthropic_messages"), messages_handler=reply
+ )
+ try:
+ with pytest.raises(ValueError, match="cursor did not advance"):
+ await instance.list_model_infos()
+ assert len(calls) == 2
+ assert calls[1].url.params["after_id"] == "same"
+ finally:
+ await instance.cleanup()
+
+
+@pytest.mark.parametrize("vision", [True, False])
+async def test_messages_discovery_retains_text_and_advertised_limits(vision):
+ instance = provider(
+ definition(api_format="anthropic_messages"),
+ messages_handler=lambda request: httpx.Response(
+ 200,
+ json={
+ "data": [
+ {
+ "id": "model",
+ "max_input_tokens": 200000,
+ "max_tokens": 32000,
+ "capabilities": {"image_input": {"supported": vision}},
+ }
+ ],
+ "has_more": False,
+ },
+ ),
+ )
+ try:
+ (info,) = await instance.list_model_infos()
+ expected = {ModelInputModality.TEXT}
+ if vision:
+ expected.add(ModelInputModality.IMAGE)
+ assert info.input_modalities == frozenset(expected)
+ assert info.context_window_tokens == 200000
+ assert info.max_output_tokens == 32000
+ finally:
+ await instance.cleanup()
diff --git a/tests/providers/test_messages_request_policy.py b/tests/providers/test_messages_request_policy.py
index 5914f0d9c1..fda7375bb2 100644
--- a/tests/providers/test_messages_request_policy.py
+++ b/tests/providers/test_messages_request_policy.py
@@ -131,7 +131,10 @@ def test_manual_effort_uses_budget_and_minimum() -> None:
@pytest.mark.parametrize("raw", ["bogus", 1, {"mode": "high"}])
-def test_client_on_cannot_hide_invalid_output_effort(raw: object) -> None:
+@pytest.mark.parametrize("preserve_native_controls", [False, True])
+def test_client_on_cannot_hide_invalid_output_effort(
+ raw: object, preserve_native_controls: bool
+) -> None:
with pytest.raises(NativeMessagesError, match="client output effort"):
resolve_messages_options(
model="m",
@@ -139,6 +142,7 @@ def test_client_on_cannot_hide_invalid_output_effort(raw: object) -> None:
output_effort=raw,
reasoning=ReasoningPolicy.on(budget_tokens=1536),
thinking=ThinkingConfig(type="enabled", budget_tokens=1536),
+ preserve_native_controls=preserve_native_controls,
)
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index 5e958e9d9e..3a6565386c 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -393,6 +393,7 @@ async def stream_responses(
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
+ model_info: ProviderModelInfo | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index ff03abc32f..31b1d051cb 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -96,6 +96,7 @@ async def stream_responses(
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
+ model_info: ProviderModelInfo | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
diff --git a/tests/runtime/test_custom_provider_lifecycle.py b/tests/runtime/test_custom_provider_lifecycle.py
new file mode 100644
index 0000000000..96b7835200
--- /dev/null
+++ b/tests/runtime/test_custom_provider_lifecycle.py
@@ -0,0 +1,95 @@
+import asyncio
+
+import pytest
+
+from free_claude_code.application.model_catalog import read_model_catalog
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.config.custom_providers import CustomProviderDefinition
+from free_claude_code.config.settings import Settings
+from free_claude_code.providers.custom import CustomProvider
+from free_claude_code.providers.runtime import ProviderRuntime
+from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
+from tests.runtime.test_provider_manager import FakeRuntime, RuntimeFactory
+
+pytestmark = pytest.mark.asyncio
+ID = "custom_" + "a" * 32
+
+
+def settings(**changes):
+ definition = CustomProviderDefinition.model_validate(
+ {
+ "provider_id": ID,
+ "display_name": "Gateway",
+ "base_url": "https://example.org/v1",
+ **changes,
+ }
+ )
+ return Settings(custom_providers=(definition,))
+
+
+async def commit():
+ pass
+
+
+async def test_runtime_constructs_one_custom_owner_lazily():
+ runtime = ProviderRuntime(settings(model_ids=["manual"]))
+ try:
+ assert not runtime.is_cached(ID)
+ one, two = await asyncio.gather(
+ runtime.resolve_provider(ID), runtime.resolve_provider(ID)
+ )
+ assert one is two and isinstance(one, CustomProvider)
+ assert {info.model_id for info in await one.list_model_infos()} == {"manual"}
+ finally:
+ await runtime.cleanup()
+
+
+async def test_manual_inventory_is_immediate_and_does_not_construct_client():
+ factory = RuntimeFactory()
+ manager = ProviderRuntimeManager(
+ settings(model_ids=["manual"]), runtime_factory=factory
+ )
+ try:
+ catalog = read_model_catalog(manager)
+ assert any(
+ item.provider_model_ref == f"{ID}/manual"
+ and item.display_name == "Gateway/manual"
+ for item in catalog.models
+ )
+ await manager.refresh_provider(ID)
+ factory.runtimes[0].provider.list_model_infos.assert_not_called()
+ finally:
+ await manager.close()
+
+
+async def test_changed_endpoint_cannot_inherit_catalog_but_rename_can():
+ factory = RuntimeFactory()
+ release = asyncio.Event()
+
+ async def wait():
+ await release.wait()
+ return frozenset()
+
+ def blocked(settings):
+ runtime = factory(settings)
+ assert isinstance(runtime, FakeRuntime)
+ runtime.provider.list_model_infos.side_effect = wait
+ return runtime
+
+ manager = ProviderRuntimeManager(settings(), runtime_factory=blocked)
+ manager.cache_model_infos(ID, [ProviderModelInfo("old")])
+ try:
+ await manager.replace(settings(display_name="Renamed"), commit=commit)
+ assert manager.cached_model_info(ID, "old") is not None
+ lease = await manager.acquire()
+ await manager.replace(
+ settings(base_url="https://other.example/v2"), commit=commit
+ )
+ assert manager.cached_model_info(ID, "old") is None
+ retained = lease.settings.custom_provider(ID)
+ assert retained is not None and retained.base_url == "https://example.org/v1"
+ await lease.release()
+ assert factory.runtimes[-2].cleanup_calls == 1
+ finally:
+ release.set()
+ await manager.close()
diff --git a/tests/runtime/test_provider_manager.py b/tests/runtime/test_provider_manager.py
index f336e24ce3..616b977d7c 100644
--- a/tests/runtime/test_provider_manager.py
+++ b/tests/runtime/test_provider_manager.py
@@ -815,16 +815,25 @@ async def test_generation_lease_keeps_its_model_metadata_after_replacement() ->
await lease.resolve_provider("open_router")
await manager.replace(
- _settings("nvidia_nim/two"),
+ first_settings,
commit=AsyncMock(),
)
+ factory.runtimes[-1].provider.list_model_infos.return_value = frozenset(
+ {ProviderModelInfo("old-model", max_output_tokens=16384)}
+ )
+ new_lease = await manager.acquire()
+ await new_lease.resolve_provider("open_router")
+ new_info = new_lease.model_info("open_router", "old-model")
+ assert new_info is not None and new_info.max_output_tokens == 16384
+
assert lease.model_info("open_router", "old-model") == ProviderModelInfo(
"open_router/old-model",
context_window_tokens=32_000,
max_output_tokens=4_096,
)
await lease.release()
+ await new_lease.release()
await manager.close()
