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

Route OpenCode models by catalog transport (#1540)

Ali Khokharcb29263a5f17
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index dbcd4c90..96c331e4 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -47,6 +47,8 @@ flowchart LR
Executor --> Lease[Provider Generation Lease]
Lease --> Providers[ProviderRuntime]
Providers --> OpenAIChat[OpenAI Chat Provider Profiles And Specialized Adapters]
+ Providers --> OpenAIResponses[Standard OpenAI Responses Transport]
+ Providers --> NativeProviders[Native And Private Provider Adapters]
```
## Package Boundaries
@@ -794,7 +796,7 @@ compatibility layer.
`list_model_infos()`. Providers return application-owned `ProviderModelInfo`
values directly; there is no parallel IDs-only catalog contract.
-There are two upstream transport families:
+Provider execution is organized around explicit protocol owners.
[providers/openai_chat/](src/free_claude_code/providers/openai_chat/) implements the concrete
`OpenAIChatProvider` used by every OpenAI-compatible `/chat/completions`
upstream. `OpenAIChatProfile` contains immutable request policy, an explicit
@@ -806,6 +808,27 @@ owns the exactly typed private per-request runner, recovery operations, tool-cal
assembly, and streamed usage handling. No obsolete generic transport namespace
or untyped provider backchannel remains.
+[providers/openai_responses/](src/free_claude_code/providers/openai_responses/)
+owns standard API-key `/responses` execution. Its transport borrows the owning
+provider's configured SDK client and admission controller, builds and parses the
+public protocol through `core.openai_responses`, and owns stream attempts,
+failure classification, recovery holdback, cancellation, and exact closure. It
+owns no credentials, model discovery, provider configuration, or client
+lifecycle. This boundary is deliberately separate from the Codex subscription
+adapter's OAuth and private-backend contract.
+
+[providers/opencode/](src/free_claude_code/providers/opencode/) is specialized
+because OpenCode Zen and Go advertise heterogeneous per-model transports. Each
+provider instance owns a separately proxied, admitted rich-catalog client and
+an immutable last-good route snapshot. The model selector remains the public
+FCC ID while the catalog record's `id` is sent upstream. Exact effective package
+metadata selects standard Responses only for `@ai-sdk/openai`; every other
+accepted package uses the inherited OpenAI Chat path. Listing and direct
+generation resolve from the same status-filtered snapshot, a cold load is
+coalesced, and missing route metadata fails before generation rather than
+probing endpoints or treating HTTP 500 as transport discovery. Both branches
+share the one provider-generation admission controller.
+
[providers/groq/](src/free_claude_code/providers/groq/) is a specialized
`OpenAIChatProvider` because Groq exposes incompatible `reasoning_effort`
vocabularies without publishing that capability in model metadata. The Groq
diff --git a/pyproject.toml b/pyproject.toml
index 1004200e..1c072f2a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.14.0"
+version = "5.14.1"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/providers/openai_chat/profiles.py b/src/free_claude_code/providers/openai_chat/profiles.py
index 3f4b5393..d40aa51a 100644
--- a/src/free_claude_code/providers/openai_chat/profiles.py
+++ b/src/free_claude_code/providers/openai_chat/profiles.py
@@ -424,16 +424,6 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
_policy("CODESTRAL", ReasoningReplayMode.THINK_TAGS),
NO_REASONING,
),
- "opencode_zen": OpenAIChatProfile(
- _policy("OPENCODE_ZEN", ReasoningReplayMode.REASONING_CONTENT),
- NO_REASONING,
- user_agent="opencode",
- ),
- "opencode_go": OpenAIChatProfile(
- _policy("OPENCODE_GO", ReasoningReplayMode.REASONING_CONTENT),
- NO_REASONING,
- user_agent="opencode",
- ),
"vercel": OpenAIChatProfile(
_policy(
"VERCEL",
diff --git a/src/free_claude_code/providers/openai_responses/__init__.py b/src/free_claude_code/providers/openai_responses/__init__.py
new file mode 100644
index 00000000..79eb5d63
--- /dev/null
+++ b/src/free_claude_code/providers/openai_responses/__init__.py
@@ -0,0 +1,5 @@
+"""Standard OpenAI Responses provider transport."""
+
+from .transport import OpenAIResponsesTransport
+
+__all__ = ["OpenAIResponsesTransport"]
diff --git a/src/free_claude_code/providers/openai_responses/transport.py b/src/free_claude_code/providers/openai_responses/transport.py
new file mode 100644
index 00000000..ba5aaa80
--- /dev/null
+++ b/src/free_claude_code/providers/openai_responses/transport.py
@@ -0,0 +1,330 @@
+"""Standard API-key OpenAI Responses execution over the official SDK."""
+
+import asyncio
+import sys
+import uuid
+from collections.abc import AsyncIterator
+from typing import cast
+
+from openai import AsyncOpenAI, AsyncStream
+from openai.types.responses import ResponseStreamEvent
+from openai.types.responses.response_create_params import ResponseCreateParamsStreaming
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.openai_tool_names import OpenAIToolNameCodec
+from free_claude_code.core.diagnostics import extract_upstream_error_detail
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.openai_responses import (
+ ResponsesConversionError,
+ ResponsesProviderStream,
+ ResponsesStreamFailure,
+ build_responses_provider_request,
+)
+from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.core.trace import trace_event
+from free_claude_code.providers.admission import (
+ ProviderAdmissionController,
+ ProviderExecution,
+ ProviderOperationKind,
+)
+from free_claude_code.providers.failure_policy import (
+ RetryableProviderProtocolError,
+ classify_provider_failure,
+ is_retryable_stream_error,
+)
+from free_claude_code.providers.http import ProviderAttemptScope, maybe_await_aclose
+from free_claude_code.providers.stream_recovery import (
+ RecoveryController,
+ RecoveryFailureAction,
+)
+
+
+class _TruncatedResponsesStream(RetryableProviderProtocolError):
+ """A Responses stream ended without a terminal lifecycle event."""
+
+
+class _ClosableResponsesStream(AsyncIterator[ResponseStreamEvent]):
+ """Expose the OpenAI SDK stream through the shared ``aclose`` contract."""
+
+ def __init__(self, stream: AsyncStream[ResponseStreamEvent]) -> None:
+ self._stream = stream
+
+ def __aiter__(self) -> AsyncIterator[ResponseStreamEvent]:
+ return self
+
+ async def __anext__(self) -> ResponseStreamEvent:
+ return await anext(self._stream)
+
+ async def aclose(self) -> None:
+ await self._stream.close()
+
+
+class OpenAIResponsesTransport:
+ """Execute public Responses requests with provider-owned retry semantics."""
+
+ def __init__(
+ self,
+ *,
+ client: AsyncOpenAI,
+ admission: ProviderAdmissionController,
+ provider_name: str,
+ read_timeout_s: float,
+ log_raw_sse_events: bool,
+ ) -> None:
+ self._client = client
+ self._admission = admission
+ self._provider_name = provider_name
+ self._read_timeout_s = read_timeout_s
+ self._log_raw_sse_events = log_raw_sse_events
+
+ def preflight_stream(
+ self,
+ request: MessagesRequest,
+ *,
+ reasoning: ReasoningPolicy,
+ ) -> None:
+ self._build_body(request, reasoning=reasoning)
+
+ def stream_response(
+ self,
+ request: MessagesRequest,
+ *,
+ input_tokens: int,
+ request_id: str | None,
+ response_model: str,
+ reasoning: ReasoningPolicy,
+ ) -> AsyncIterator[str]:
+ body = self._build_body(request, reasoning=reasoning)
+ tool_names = OpenAIToolNameCodec.from_request(request)
+ return self._run_stream(
+ body,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model,
+ tool_names=tool_names,
+ )
+
+ @staticmethod
+ def _build_body(
+ request: MessagesRequest,
+ *,
+ reasoning: ReasoningPolicy,
+ ) -> ResponseCreateParamsStreaming:
+ try:
+ return cast(
+ ResponseCreateParamsStreaming,
+ build_responses_provider_request(request, reasoning=reasoning),
+ )
+ except ResponsesConversionError as exc:
+ raise InvalidRequestError(str(exc)) from exc
+
+ async def _run_stream(
+ self,
+ body: ResponseCreateParamsStreaming,
+ *,
+ input_tokens: int,
+ request_id: str | None,
+ response_model: str,
+ tool_names: OpenAIToolNameCodec,
+ ) -> AsyncIterator[str]:
+ execution = self._admission.start_execution(request_id=request_id)
+ provider_stream = self._run_execution(
+ body,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model,
+ tool_names=tool_names,
+ execution=execution,
+ )
+ try:
+ async for event in provider_stream:
+ yield event
+ except asyncio.CancelledError:
+ raise
+ except Exception as error:
+ execution.fail(error)
+ raise
+ else:
+ execution.succeed()
+ finally:
+ await maybe_await_aclose(provider_stream)
+ execution.abandon()
+
+ async def _run_execution(
+ self,
+ body: ResponseCreateParamsStreaming,
+ *,
+ input_tokens: int,
+ request_id: str | None,
+ response_model: str,
+ tool_names: OpenAIToolNameCodec,
+ execution: ProviderExecution,
+ ) -> AsyncIterator[str]:
+ recovery = RecoveryController()
+ message_id = f"msg_{uuid.uuid4()}"
+ trace_event(
+ stage="provider",
+ event="provider.request.sent",
+ source="provider",
+ provider=self._provider_name,
+ request_id=request_id,
+ execution_id=execution.execution_id,
+ gateway_model=response_model,
+ downstream_model=body.get("model"),
+ transport="responses",
+ )
+
+ while execution.can_attempt:
+ stream_adapter = ResponsesProviderStream(
+ message_id=message_id,
+ model=response_model,
+ input_tokens=input_tokens,
+ tool_names=tool_names,
+ log_raw_events=self._log_raw_sse_events,
+ )
+ for event in stream_adapter.start():
+ for held in recovery.push(event):
+ yield held
+
+ scope: ProviderAttemptScope | None = None
+ stream_opened = False
+ try:
+ attempt = await execution.open_attempt(ProviderOperationKind.GENERATION)
+ scope = ProviderAttemptScope(
+ attempt,
+ provider_name=self._provider_name,
+ request_id=request_id,
+ )
+ sdk_stream = await self._client.responses.create(**body)
+ stream = scope.retain(_ClosableResponsesStream(sdk_stream))
+ stream_opened = True
+
+ async for upstream_event in stream:
+ if not scope.attempt.accepted:
+ await scope.attempt.accept()
+ for event in stream_adapter.feed(
+ upstream_event.type,
+ upstream_event.to_dict(mode="json"),
+ ):
+ for held in recovery.push(event):
+ yield held
+ if not stream_adapter.completed:
+ raise _TruncatedResponsesStream(
+ "Provider Responses stream ended without a terminal event."
+ )
+ for event in recovery.flush():
+ yield event
+ trace_event(
+ stage="provider",
+ event="provider.response.completed",
+ source="provider",
+ provider=self._provider_name,
+ request_id=request_id,
+ transport="responses",
+ )
+ return
+ except asyncio.CancelledError, GeneratorExit:
+ raise
+ except Exception as raw_error:
+ error = _effective_error(raw_error)
+ attempt_failure = None
+ if scope is not None and not scope.attempt.accepted:
+ attempt_failure = await scope.attempt.fail(error)
+ if attempt_failure is not None and attempt_failure.retry_allowed:
+ recovery.discard()
+ _trace_early_retry(
+ provider_name=self._provider_name,
+ request_id=request_id,
+ execution=execution,
+ )
+ continue
+
+ retryable = (
+ attempt_failure.retryable
+ if attempt_failure is not None
+ else is_retryable_stream_error(error)
+ )
+ decision = recovery.advance_failure(
+ retryable=retryable,
+ stream_opened=stream_opened,
+ generated_output=recovery.committed,
+ complete_tool_salvageable=False,
+ attempts_remaining=execution.attempts_remaining,
+ )
+ if decision.action is RecoveryFailureAction.EARLY_RETRY:
+ recovery.discard()
+ _trace_early_retry(
+ provider_name=self._provider_name,
+ request_id=request_id,
+ execution=execution,
+ )
+ continue
+
+ failure = classify_provider_failure(
+ error,
+ provider_name=self._provider_name,
+ read_timeout_s=self._read_timeout_s,
+ request_id=request_id,
+ )
+ trace_event(
+ stage="provider",
+ event="provider.response.error",
+ source="provider",
+ provider=self._provider_name,
+ request_id=request_id,
+ transport="responses",
+ exc_type=type(error).__name__,
+ failure_kind=failure.kind.value,
+ status_code=failure.status_code,
+ provider_retryable=failure.retryable,
+ )
+ if not decision.committed:
+ recovery.discard()
+ raise failure from raw_error
+ for event in stream_adapter.ledger.close_unclosed_blocks():
+ yield event
+ raise failure from raw_error
+ finally:
+ if scope is not None:
+ await scope.aclose(active_error=sys.exception())
+
+ if execution.last_failure is not None:
+ raise execution.last_failure
+ raise RuntimeError("Responses execution ended without a terminal result.")
+
+
+def _effective_error(error: Exception) -> Exception:
+ if not isinstance(error, ResponsesStreamFailure):
+ return error
+ message = (
+ extract_upstream_error_detail(error).exception_text
+ or "Provider response failed."
+ )
+ code = (error.code or "").lower()
+ if "rate" in code or "429" in code:
+ return ExecutionFailure(FailureKind.RATE_LIMIT, 429, message, True)
+ if any(marker in code for marker in ("overload", "capacity", "529")):
+ return ExecutionFailure(FailureKind.OVERLOADED, 529, message, True)
+ retryable = any(
+ marker in code for marker in ("server", "internal", "unavailable", "timeout")
+ )
+ return ExecutionFailure(FailureKind.UPSTREAM, 502, message, retryable)
+
+
+def _trace_early_retry(
+ *,
+ provider_name: str,
+ request_id: str | None,
+ execution: ProviderExecution,
+) -> None:
+ trace_event(
+ stage="provider",
+ event="provider.recovery.early_retry",
+ source="provider",
+ provider=provider_name,
+ request_id=request_id,
+ transport="responses",
+ attempts_started=execution.attempts_started,
+ max_attempts=execution.max_attempts,
+ )
diff --git a/src/free_claude_code/providers/opencode/__init__.py b/src/free_claude_code/providers/opencode/__init__.py
new file mode 100644
index 00000000..302ad435
--- /dev/null
+++ b/src/free_claude_code/providers/opencode/__init__.py
@@ -0,0 +1,5 @@
+"""OpenCode catalog-aware provider family."""
+
+from .provider import OpenCodeProvider, create_opencode_provider
+
+__all__ = ["OpenCodeProvider", "create_opencode_provider"]
diff --git a/src/free_claude_code/providers/opencode/catalog.py b/src/free_claude_code/providers/opencode/catalog.py
new file mode 100644
index 00000000..3bce0943
--- /dev/null
+++ b/src/free_claude_code/providers/opencode/catalog.py
@@ -0,0 +1,315 @@
+"""OpenCode rich-catalog parsing and provider-scoped snapshot ownership."""
+
+import asyncio
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from types import MappingProxyType
+
+import httpx
+
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.providers.admission import (
+ ProviderAdmissionController,
+ ProviderOperationKind,
+)
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.failure_policy import classify_provider_failure
+from free_claude_code.providers.model_listing import ModelListResponseError
+
+OPENCODE_CATALOG_URL = "https://models.opencode.ai/api.json"
+_DEFAULT_PACKAGE = "@ai-sdk/openai-compatible"
+_RESPONSES_PACKAGE = "@ai-sdk/openai"
+_VISIBLE_STATUSES = frozenset({"active", "beta"})
+_HIDDEN_STATUSES = frozenset({"alpha", "deprecated"})
+
+
+class OpenCodeUpstreamTransport(StrEnum):
+ """Standard OpenAI endpoint selected by one catalog route."""
+
+ CHAT_COMPLETIONS = "chat_completions"
+ RESPONSES = "responses"
+
+
+@dataclass(frozen=True, slots=True)
+class OpenCodeModelRoute:
+ """One public selector resolved to its upstream model and transport."""
+
+ selector_id: str
+ upstream_model_id: str
+ transport: OpenCodeUpstreamTransport
+ supports_thinking: bool | None
+
+
+@dataclass(frozen=True, slots=True)
+class OpenCodeCatalogSnapshot:
+ """One fully validated immutable provider-specific catalog view."""
+
+ routes: Mapping[str, OpenCodeModelRoute]
+ model_infos: frozenset[ProviderModelInfo]
+
+ def route(self, selector_id: str) -> OpenCodeModelRoute | None:
+ return self.routes.get(selector_id)
+
+
+def parse_open_code_catalog(
+ payload: object,
+ *,
+ provider_key: str,
+ provider_name: str,
+) -> OpenCodeCatalogSnapshot:
+ """Parse one provider section without publishing a partial snapshot."""
+ root = _mapping(payload, provider_name, "top-level object")
+ provider = _mapping(
+ root.get(provider_key),
+ provider_name,
+ f"provider section {provider_key!r}",
+ )
+ provider_package = _optional_package(
+ provider.get("npm"),
+ provider_name=provider_name,
+ location="provider npm",
+ )
+ models = _mapping(
+ provider.get("models"),
+ provider_name,
+ "models object",
+ )
+
+ routes: dict[str, OpenCodeModelRoute] = {}
+ for raw_selector_id, raw_model in models.items():
+ selector_id = _required_string(
+ raw_selector_id,
+ provider_name=provider_name,
+ location="model selector",
+ )
+ if selector_id in routes:
+ raise _catalog_error(
+ provider_name,
+ f"duplicate normalized model selector {selector_id!r}",
+ )
+ model = _mapping(
+ raw_model,
+ provider_name,
+ f"model {selector_id!r}",
+ )
+ status = _model_status(model, provider_name, selector_id)
+ if status in _HIDDEN_STATUSES:
+ continue
+
+ upstream_model_id = _required_string(
+ model.get("id"),
+ provider_name=provider_name,
+ location=f"model {selector_id!r} id",
+ )
+ model_provider = model.get("provider")
+ model_package = None
+ if model_provider is not None:
+ provider_override = _mapping(
+ model_provider,
+ provider_name,
+ f"model {selector_id!r} provider",
+ )
+ model_package = _optional_package(
+ provider_override.get("npm"),
+ provider_name=provider_name,
+ location=f"model {selector_id!r} provider npm",
+ )
+ supports_thinking = _optional_boolean(
+ model.get("reasoning"),
+ provider_name=provider_name,
+ location=f"model {selector_id!r} reasoning",
+ )
+ effective_package = model_package or provider_package or _DEFAULT_PACKAGE
+ route = OpenCodeModelRoute(
+ selector_id=selector_id,
+ upstream_model_id=upstream_model_id,
+ transport=(
+ OpenCodeUpstreamTransport.RESPONSES
+ if effective_package == _RESPONSES_PACKAGE
+ else OpenCodeUpstreamTransport.CHAT_COMPLETIONS
+ ),
+ supports_thinking=supports_thinking,
+ )
+ routes[selector_id] = route
+
+ if not routes:
+ raise _catalog_error(provider_name, "no active or beta models")
+ model_infos = frozenset(
+ ProviderModelInfo(
+ model_id=route.selector_id,
+ supports_thinking=route.supports_thinking,
+ )
+ for route in routes.values()
+ )
+ return OpenCodeCatalogSnapshot(
+ routes=MappingProxyType(routes),
+ model_infos=model_infos,
+ )
+
+
+class OpenCodeCatalog:
+ """Own one OpenCode provider's catalog client and last-good snapshot."""
+
+ def __init__(
+ self,
+ config: ProviderConfig,
+ *,
+ provider_key: str,
+ provider_name: str,
+ admission: ProviderAdmissionController,
+ client: httpx.AsyncClient | None = None,
+ ) -> None:
+ self._provider_key = provider_key
+ self._provider_name = provider_name
+ self._admission = admission
+ self._client = client or httpx.AsyncClient(
+ proxy=config.proxy,
+ timeout=httpx.Timeout(
+ config.http_read_timeout,
+ connect=config.http_connect_timeout,
+ read=config.http_read_timeout,
+ write=config.http_write_timeout,
+ ),
+ )
+ self._snapshot: OpenCodeCatalogSnapshot | None = None
+ self._lock = asyncio.Lock()
+ self._read_timeout = config.http_read_timeout
+
+ @property
+ def current_snapshot(self) -> OpenCodeCatalogSnapshot | None:
+ return self._snapshot
+
+ async def snapshot(
+ self, *, request_id: str | None = None
+ ) -> OpenCodeCatalogSnapshot:
+ """Return last-good data or coalesce one cold catalog load."""
+ if self._snapshot is not None:
+ return self._snapshot
+ async with self._lock:
+ if self._snapshot is not None:
+ return self._snapshot
+ try:
+ return await self._load_and_publish(request_id=request_id)
+ except Exception as exc:
+ raise classify_provider_failure(
+ exc,
+ provider_name=self._provider_name,
+ read_timeout_s=self._read_timeout,
+ request_id=request_id,
+ ) from exc
+
+ async def refresh(self) -> OpenCodeCatalogSnapshot:
+ """Load and atomically publish one fully validated fresh snapshot."""
+ async with self._lock:
+ return await self._load_and_publish()
+
+ async def cleanup(self) -> None:
+ await self._client.aclose()
+
+ async def _load_and_publish(
+ self, *, request_id: str | None = None
+ ) -> OpenCodeCatalogSnapshot:
+ async def request() -> OpenCodeCatalogSnapshot:
+ response = await self._client.get(
+ OPENCODE_CATALOG_URL,
+ headers={"Accept": "application/json", "User-Agent": "opencode"},
+ )
+ try:
+ response.raise_for_status()
+ try:
+ payload: object = response.json()
+ except ValueError as exc:
+ raise _catalog_error(
+ self._provider_name,
+ "invalid JSON",
+ ) from exc
+ return parse_open_code_catalog(
+ payload,
+ provider_key=self._provider_key,
+ provider_name=self._provider_name,
+ )
+ finally:
+ await response.aclose()
+
+ execution = self._admission.start_execution(request_id=request_id)
+ snapshot = await execution.run_call(
+ request,
+ operation_kind=ProviderOperationKind.MODEL_DISCOVERY,
+ )
+ self._snapshot = snapshot
+ return snapshot
+
+
+def _mapping(
+ value: object,
+ provider_name: str,
+ location: str,
+) -> Mapping[object, object]:
+ if isinstance(value, Mapping):
+ return value
+ raise _catalog_error(provider_name, f"expected {location}")
+
+
+def _required_string(
+ value: object,
+ *,
+ provider_name: str,
+ location: str,
+) -> str:
+ if isinstance(value, str) and (normalized := value.strip()):
+ return normalized
+ raise _catalog_error(provider_name, f"expected non-empty {location}")
+
+
+def _optional_package(
+ value: object,
+ *,
+ provider_name: str,
+ location: str,
+) -> str | None:
+ if value is None:
+ return None
+ return _required_string(
+ value,
+ provider_name=provider_name,
+ location=location,
+ )
+
+
+def _optional_boolean(
+ value: object,
+ *,
+ provider_name: str,
+ location: str,
+) -> bool | None:
+ if value is None or isinstance(value, bool):
+ return value
+ raise _catalog_error(provider_name, f"expected boolean {location}")
+
+
+def _model_status(
+ model: Mapping[object, object],
+ provider_name: str,
+ selector_id: str,
+) -> str:
+ value = model.get("status")
+ if value is None:
+ return "active"
+ status = _required_string(
+ value,
+ provider_name=provider_name,
+ location=f"model {selector_id!r} status",
+ )
+ if status not in _VISIBLE_STATUSES | _HIDDEN_STATUSES:
+ raise _catalog_error(
+ provider_name,
+ f"unknown model {selector_id!r} status {status!r}",
+ )
+ return status
+
+
+def _catalog_error(provider_name: str, detail: str) -> ModelListResponseError:
+ return ModelListResponseError(
+ f"{provider_name} rich catalog is malformed: {detail}"
+ )
diff --git a/src/free_claude_code/providers/opencode/provider.py b/src/free_claude_code/providers/opencode/provider.py
new file mode 100644
index 00000000..9e6e9bd6
--- /dev/null
+++ b/src/free_claude_code/providers/opencode/provider.py
@@ -0,0 +1,239 @@
+"""OpenCode provider with catalog-driven Chat/Responses dispatch."""
+
+import sys
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+
+import httpx
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.core.anthropic import ReasoningReplayMode
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.providers.admission import ProviderAdmissionController
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.http import close_provider_stream
+from free_claude_code.providers.openai_chat import (
+ NO_REASONING,
+ OpenAIChatProfile,
+ OpenAIChatProvider,
+ OpenAIChatRequestPolicy,
+)
+from free_claude_code.providers.openai_responses import OpenAIResponsesTransport
+
+from .catalog import (
+ OpenCodeCatalog,
+ OpenCodeCatalogSnapshot,
+ OpenCodeModelRoute,
+ OpenCodeUpstreamTransport,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class OpenCodeProfile:
+ """Immutable identity and catalog configuration for one OpenCode plan."""
+
+ provider_id: str
+ provider_name: str
+ catalog_key: str
+ chat_profile: OpenAIChatProfile
+
+
+def _profile(
+ provider_id: str,
+ provider_name: str,
+ catalog_key: str,
+) -> OpenCodeProfile:
+ return OpenCodeProfile(
+ provider_id=provider_id,
+ provider_name=provider_name,
+ catalog_key=catalog_key,
+ chat_profile=OpenAIChatProfile(
+ OpenAIChatRequestPolicy(
+ provider_name=provider_name,
+ reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
+ ),
+ NO_REASONING,
+ user_agent="opencode",
+ ),
+ )
+
+
+_PROFILES = {
+ "opencode_zen": _profile("opencode_zen", "OPENCODE_ZEN", "opencode"),
+ "opencode_go": _profile("opencode_go", "OPENCODE_GO", "opencode-go"),
+}
+
+
+class OpenCodeProvider(OpenAIChatProvider):
+ """Route OpenCode models through their catalog-declared OpenAI endpoint."""
+
+ def __init__(
+ self,
+ config: ProviderConfig,
+ *,
+ profile: OpenCodeProfile,
+ admission: ProviderAdmissionController,
+ catalog_client: httpx.AsyncClient | None = None,
+ ) -> None:
+ super().__init__(
+ config,
+ profile=profile.chat_profile,
+ admission=admission,
+ default_headers={"User-Agent": "opencode"},
+ )
+ self._opencode_profile = profile
+ self._catalog = OpenCodeCatalog(
+ config,
+ provider_key=profile.catalog_key,
+ provider_name=profile.provider_name,
+ admission=admission,
+ client=catalog_client,
+ )
+ self._responses = OpenAIResponsesTransport(
+ client=self._client,
+ admission=admission,
+ provider_name=profile.provider_name,
+ read_timeout_s=config.http_read_timeout,
+ log_raw_sse_events=config.log_raw_sse_events,
+ )
+
+ async def cleanup(self) -> None:
+ """Close both owned clients even when one cleanup fails."""
+ errors: list[Exception] = []
+ try:
+ await super().cleanup()
+ except Exception as exc:
+ errors.append(exc)
+ try:
+ await self._catalog.cleanup()
+ except Exception as exc:
+ errors.append(exc)
+ if len(errors) == 1:
+ raise errors[0]
+ if errors:
+ raise ExceptionGroup("OpenCode provider cleanup failed", errors)
+
+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
+ snapshot = await self._catalog.refresh()
+ return snapshot.model_infos
+
+ def preflight_stream(
+ self,
+ request: MessagesRequest,
+ *,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> None:
+ """Validate synchronously when a route snapshot is already warm."""
+ snapshot = self._catalog.current_snapshot
+ if snapshot is None:
+ return
+ route = self._require_route(snapshot, request.model)
+ routed = _routed_request(request, route)
+ if route.transport is OpenCodeUpstreamTransport.RESPONSES:
+ self._responses.preflight_stream(routed, reasoning=reasoning)
+ return
+ super().preflight_stream(routed, reasoning=reasoning)
+
+ def stream_response(
+ self,
+ request: MessagesRequest,
+ input_tokens: int = 0,
+ *,
+ request_id: str | None = None,
+ response_model: str | None = None,
+ reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
+ ) -> AsyncIterator[str]:
+ return self._dispatch_stream(
+ request,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model or request.model,
+ reasoning=reasoning,
+ )
+
+ async def _dispatch_stream(
+ self,
+ request: MessagesRequest,
+ *,
+ input_tokens: int,
+ request_id: str | None,
+ response_model: str,
+ reasoning: ReasoningPolicy,
+ ) -> AsyncIterator[str]:
+ snapshot = await self._catalog.snapshot(request_id=request_id)
+ route = self._require_route(snapshot, request.model)
+ routed = _routed_request(request, route)
+ selected_stream: AsyncIterator[str] | None = None
+ try:
+ if route.transport is OpenCodeUpstreamTransport.RESPONSES:
+ self._responses.preflight_stream(routed, reasoning=reasoning)
+ selected_stream = self._responses.stream_response(
+ routed,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model,
+ reasoning=reasoning,
+ )
+ else:
+ super().preflight_stream(routed, reasoning=reasoning)
+ selected_stream = super().stream_response(
+ routed,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model,
+ reasoning=reasoning,
+ )
+ async for event in selected_stream:
+ yield event
+ finally:
+ if selected_stream is not None:
+ await close_provider_stream(
+ selected_stream,
+ active_error=sys.exception(),
+ provider_name=self._opencode_profile.provider_name,
+ request_id=request_id,
+ )
+
+ def _require_route(
+ self,
+ snapshot: OpenCodeCatalogSnapshot,
+ selector_id: str,
+ ) -> OpenCodeModelRoute:
+ route = snapshot.route(selector_id)
+ if route is not None:
+ return route
+ raise InvalidRequestError(
+ f"{self._opencode_profile.provider_name} does not advertise "
+ f"model {selector_id!r} in its active catalog."
+ )
+
+
+def create_opencode_provider(
+ provider_id: str,
+ config: ProviderConfig,
+ admission: ProviderAdmissionController,
+ *,
+ catalog_client: httpx.AsyncClient | None = None,
+) -> OpenCodeProvider:
+ """Construct one catalog-aware OpenCode provider."""
+ profile = _PROFILES.get(provider_id)
+ if profile is None:
+ raise KeyError(f"No OpenCode profile for {provider_id!r}")
+ return OpenCodeProvider(
+ config,
+ profile=profile,
+ admission=admission,
+ catalog_client=catalog_client,
+ )
+
+
+def _routed_request(
+ request: MessagesRequest,
+ route: OpenCodeModelRoute,
+) -> MessagesRequest:
+ return request.model_copy(
+ update={"model": route.upstream_model_id},
+ deep=True,
+ )
diff --git a/src/free_claude_code/providers/runtime/factory.py b/src/free_claude_code/providers/runtime/factory.py
index 0d8ca145..1434ae3b 100644
--- a/src/free_claude_code/providers/runtime/factory.py
+++ b/src/free_claude_code/providers/runtime/factory.py
@@ -145,6 +145,26 @@ def _create_groq(
return GroqProvider(config, admission=admission)
+def _create_opencode_zen(
+ config: ProviderConfig,
+ _settings: Settings,
+ admission: ProviderAdmissionController,
+) -> BaseProvider:
+ from free_claude_code.providers.opencode import create_opencode_provider
+
+ return create_opencode_provider("opencode_zen", config, admission)
+
+
+def _create_opencode_go(
+ config: ProviderConfig,
+ _settings: Settings,
+ admission: ProviderAdmissionController,
+) -> BaseProvider:
+ from free_claude_code.providers.opencode import create_opencode_provider
+
+ return create_opencode_provider("opencode_go", config, admission)
+
+
_SPECIAL_PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
"nvidia_nim": _create_nvidia_nim,
"open_router": _create_open_router,
@@ -157,6 +177,8 @@ _SPECIAL_PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
"vertex": _create_vertex,
"github_models": _create_github_models,
"groq": _create_groq,
+ "opencode_zen": _create_opencode_zen,
+ "opencode_go": _create_opencode_go,
}
_INJECTED_PROVIDER_IDS = {"openai"}
diff --git a/tests/contracts/test_feature_manifest.py b/tests/contracts/test_feature_manifest.py
index 4493c64e..cb948606 100644
--- a/tests/contracts/test_feature_manifest.py
+++ b/tests/contracts/test_feature_manifest.py
@@ -19,6 +19,7 @@ from free_claude_code.providers.openai_chat import (
OpenAIChatProvider,
)
from free_claude_code.providers.openai_codex import OpenAICodexProvider
+from free_claude_code.providers.opencode import OpenCodeProvider
from free_claude_code.providers.vertex import VertexProvider
from smoke.features import FEATURE_INVENTORY
@@ -65,6 +66,8 @@ def test_product_coverage_is_not_satisfied_by_prereq_probes() -> None:
def test_provider_and_platform_registries_include_builtins() -> None:
specialized_provider_classes = {
"openai": OpenAICodexProvider,
+ "opencode_zen": OpenCodeProvider,
+ "opencode_go": OpenCodeProvider,
"nvidia_nim": NvidiaNimProvider,
"open_router": OpenRouterProvider,
"mistral": MistralProvider,
diff --git a/tests/providers/test_openai_responses_transport.py b/tests/providers/test_openai_responses_transport.py
new file mode 100644
index 00000000..4ad987dc
--- /dev/null
+++ b/tests/providers/test_openai_responses_transport.py
@@ -0,0 +1,433 @@
+"""Contracts for the standard API-key OpenAI Responses transport."""
+
+import asyncio
+import json
+from collections.abc import Callable
+
+import httpx2
+import pytest
+from openai import AsyncOpenAI
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.stream_contracts import (
+ assert_anthropic_stream_contract,
+ parse_sse_text,
+ text_content,
+ thinking_content,
+)
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.providers.openai_responses import OpenAIResponsesTransport
+from tests.providers.support import REASONING_ON, immediate_admission
+
+
+def _request(**overrides: object) -> MessagesRequest:
+ payload: dict[str, object] = {
+ "model": "upstream-model",
+ "messages": [{"role": "user", "content": "hello"}],
+ "max_tokens": 123,
+ "metadata": {"source": "test"},
+ }
+ payload.update(overrides)
+ return MessagesRequest.model_validate(payload)
+
+
+def _completed_response(
+ *,
+ model: str = "upstream-model",
+ input_tokens: int = 8,
+ cached_tokens: int = 3,
+ output_tokens: int = 2,
+) -> dict[str, object]:
+ return {
+ "id": "resp_test",
+ "created_at": 0,
+ "error": None,
+ "incomplete_details": None,
+ "instructions": None,
+ "metadata": None,
+ "model": model,
+ "object": "response",
+ "output": [],
+ "parallel_tool_calls": True,
+ "temperature": None,
+ "tool_choice": "auto",
+ "tools": [],
+ "top_p": None,
+ "background": False,
+ "conversation": None,
+ "max_output_tokens": None,
+ "max_tool_calls": None,
+ "previous_response_id": None,
+ "prompt": None,
+ "prompt_cache_key": None,
+ "reasoning": None,
+ "safety_identifier": None,
+ "service_tier": "default",
+ "status": "completed",
+ "text": {"format": {"type": "text"}, "verbosity": "medium"},
+ "top_logprobs": 0,
+ "truncation": "disabled",
+ "usage": {
+ "input_tokens": input_tokens,
+ "input_tokens_details": {"cached_tokens": cached_tokens},
+ "output_tokens": output_tokens,
+ "output_tokens_details": {"reasoning_tokens": 0},
+ "total_tokens": input_tokens + output_tokens,
+ },
+ "user": None,
+ "store": False,
+ }
+
+
+def _text_delta(text: str, *, sequence: int = 0) -> dict[str, object]:
+ return {
+ "type": "response.output_text.delta",
+ "sequence_number": sequence,
+ "item_id": "item_text",
+ "output_index": 0,
+ "content_index": 0,
+ "delta": text,
+ "logprobs": [],
+ }
+
+
+def _completed_event(*, sequence: int = 1) -> dict[str, object]:
+ return {
+ "type": "response.completed",
+ "sequence_number": sequence,
+ "response": _completed_response(),
+ }
+
+
+def _sse(*events: dict[str, object]) -> str:
+ return "".join(f"data: {json.dumps(event)}\n\n" for event in events)
+
+
+def _client(
+ handler: Callable[[httpx2.Request], httpx2.Response],
+) -> AsyncOpenAI:
+ return AsyncOpenAI(
+ api_key="test-key",
+ base_url="https://provider.invalid/v1",
+ max_retries=0,
+ http_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)),
+ )
+
+
+def _transport(client: AsyncOpenAI, *, max_attempts: int = 5):
+ return OpenAIResponsesTransport(
+ client=client,
+ admission=immediate_admission(
+ provider_name="TEST_RESPONSES",
+ max_attempts=max_attempts,
+ ),
+ provider_name="TEST_RESPONSES",
+ read_timeout_s=120.0,
+ log_raw_sse_events=False,
+ )
+
+
+async def _collect(
+ transport: OpenAIResponsesTransport,
+ request: MessagesRequest | None = None,
+) -> list[str]:
+ return [
+ chunk
+ async for chunk in transport.stream_response(
+ request or _request(),
+ input_tokens=11,
+ request_id="req_responses",
+ response_model="public-model",
+ reasoning=REASONING_ON,
+ )
+ ]
+
+
+async def test_standard_responses_preserves_public_fields_and_usage() -> None:
+ captured: list[dict[str, object]] = []
+
+ def handler(request: httpx2.Request) -> httpx2.Response:
+ payload = json.loads(request.content)
+ assert isinstance(payload, dict)
+ captured.append(payload)
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=_sse(_text_delta("hello"), _completed_event()),
+ )
+
+ client = _client(handler)
+ try:
+ chunks = await _collect(_transport(client))
+ finally:
+ await client.close()
+
+ assert len(captured) == 1
+ assert captured[0]["model"] == "upstream-model"
+ assert captured[0]["max_output_tokens"] == 123
+ assert captured[0]["metadata"] == {"source": "test"}
+ assert captured[0]["store"] is False
+ events = parse_sse_text("".join(chunks))
+ assert_anthropic_stream_contract(events)
+ assert text_content(events) == "hello"
+ final_usage = next(
+ event.data["usage"] for event in events if event.event == "message_delta"
+ )
+ assert final_usage == {
+ "input_tokens": 5,
+ "output_tokens": 2,
+ "cache_read_input_tokens": 3,
+ }
+
+
+async def test_standard_responses_maps_reasoning_and_tool_calls() -> None:
+ events: tuple[dict[str, object], ...] = (
+ {
+ "type": "response.reasoning_summary_text.delta",
+ "sequence_number": 0,
+ "item_id": "reasoning_1",
+ "output_index": 0,
+ "summary_index": 0,
+ "delta": "thinking",
+ },
+ {
+ "type": "response.output_item.added",
+ "sequence_number": 1,
+ "output_index": 1,
+ "item": {
+ "type": "function_call",
+ "id": "item_tool",
+ "call_id": "call_tool",
+ "name": "Read",
+ "arguments": "",
+ "status": "in_progress",
+ },
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "sequence_number": 2,
+ "item_id": "item_tool",
+ "output_index": 1,
+ "delta": '{"path":"README.md"}',
+ },
+ {
+ "type": "response.output_item.done",
+ "sequence_number": 3,
+ "output_index": 1,
+ "item": {
+ "type": "function_call",
+ "id": "item_tool",
+ "call_id": "call_tool",
+ "name": "Read",
+ "arguments": '{"path":"README.md"}',
+ "status": "completed",
+ },
+ },
+ _completed_event(sequence=4),
+ )
+
+ client = _client(
+ lambda _request: httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=_sse(*events),
+ )
+ )
+ try:
+ chunks = await _collect(_transport(client))
+ finally:
+ await client.close()
+
+ parsed = parse_sse_text("".join(chunks))
+ assert_anthropic_stream_contract(parsed)
+ assert thinking_content(parsed) == "thinking"
+ tool_start = next(
+ event.data["content_block"]
+ for event in parsed
+ if event.event == "content_block_start"
+ and event.data["content_block"]["type"] == "tool_use"
+ )
+ assert tool_start == {
+ "type": "tool_use",
+ "id": "call_tool",
+ "name": "Read",
+ "input": {},
+ }
+ tool_delta = next(
+ event.data["delta"]
+ for event in parsed
+ if event.event == "content_block_delta"
+ and event.data["delta"]["type"] == "input_json_delta"
+ )
+ assert tool_delta["partial_json"] == '{"path":"README.md"}'
+
+
+async def test_retryable_open_failure_retries_inside_one_transport() -> None:
+ attempts = 0
+
+ def handler(_request: httpx2.Request) -> httpx2.Response:
+ nonlocal attempts
+ attempts += 1
+ if attempts == 1:
+ return httpx2.Response(
+ 500,
+ json={"error": {"message": "temporary", "type": "server_error"}},
+ )
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=_sse(_text_delta("recovered"), _completed_event()),
+ )
+
+ client = _client(handler)
+ try:
+ chunks = await _collect(_transport(client))
+ finally:
+ await client.close()
+
+ assert attempts == 2
+ parsed = parse_sse_text("".join(chunks))
+ assert_anthropic_stream_contract(parsed)
+ assert text_content(parsed) == "recovered"
+
+
+async def test_early_truncated_retry_has_one_visible_lifecycle() -> None:
+ attempts = 0
+
+ def handler(_request: httpx2.Request) -> httpx2.Response:
+ nonlocal attempts
+ attempts += 1
+ body = (
+ _sse(_text_delta("discarded"))
+ if attempts == 1
+ else _sse(_text_delta("kept"), _completed_event())
+ )
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=body,
+ )
+
+ client = _client(handler)
+ try:
+ chunks = await _collect(_transport(client))
+ finally:
+ await client.close()
+
+ parsed = parse_sse_text("".join(chunks))
+ assert attempts == 2
+ assert text_content(parsed) == "kept"
+ assert "discarded" not in "".join(chunks)
+ assert sum(event.event == "message_start" for event in parsed) == 1
+ assert sum(event.event == "message_stop" for event in parsed) == 1
+ assert_anthropic_stream_contract(parsed)
+
+
+async def test_exhausted_5xx_uses_exact_attempt_budget() -> None:
+ attempts = 0
+
+ def handler(_request: httpx2.Request) -> httpx2.Response:
+ nonlocal attempts
+ attempts += 1
+ return httpx2.Response(
+ 503,
+ json={"error": {"message": "busy", "type": "server_error"}},
+ )
+
+ client = _client(handler)
+ try:
+ with pytest.raises(ExecutionFailure) as exc_info:
+ await _collect(_transport(client))
+ finally:
+ await client.close()
+
+ assert attempts == 5
+ assert exc_info.value.retryable is True
+
+
+async def test_post_commit_truncation_is_not_replayed() -> None:
+ attempts = 0
+ committed = "x" * 70_000
+
+ def handler(_request: httpx2.Request) -> httpx2.Response:
+ nonlocal attempts
+ attempts += 1
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=_sse(_text_delta(committed)),
+ )
+
+ client = _client(handler)
+ chunks: list[str] = []
+ try:
+ with pytest.raises(ExecutionFailure):
+ async for chunk in _transport(client).stream_response(
+ _request(),
+ input_tokens=1,
+ request_id="req_committed",
+ response_model="public-model",
+ reasoning=REASONING_ON,
+ ):
+ chunks.extend((chunk,))
+ finally:
+ await client.close()
+
+ assert attempts == 1
+ assert "".join(chunks).count(committed) == 1
+ assert "".join(chunks).count("event: message_start") == 1
+
+
+class _BlockingBody(httpx2.AsyncByteStream):
+ def __init__(self) -> None:
+ self.entered = asyncio.Event()
+ self.closed = asyncio.Event()
+
+ async def __aiter__(self):
+ self.entered.set()
+ await asyncio.Event().wait()
+ yield b""
+
+ async def aclose(self) -> None:
+ self.closed.set()
+
+
+async def test_cancellation_closes_the_sdk_stream() -> None:
+ body = _BlockingBody()
+ client = _client(
+ lambda _request: httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ stream=body,
+ )
+ )
+ task = asyncio.create_task(_collect(_transport(client)))
+ await asyncio.wait_for(body.entered.wait(), timeout=1)
+ task.cancel()
+ try:
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ await asyncio.wait_for(body.closed.wait(), timeout=1)
+ finally:
+ await client.close()
+
+
+async def test_preflight_rejects_fields_responses_cannot_represent() -> None:
+ client = _client(lambda _request: httpx2.Response(500))
+ transport = _transport(client)
+ request = _request(stop_sequences=["done"])
+
+ try:
+ with pytest.raises(InvalidRequestError, match="stop_sequences"):
+ transport.preflight_stream(request, reasoning=REASONING_ON)
+ finally:
+ await client.close()
diff --git a/tests/providers/test_opencode.py b/tests/providers/test_opencode.py
index f2b663d2..23108b31 100644
--- a/tests/providers/test_opencode.py
+++ b/tests/providers/test_opencode.py
@@ -1,49 +1,630 @@
-"""Tests for the OpenCode OpenAI-compatible provider."""
+"""Tests for catalog-driven OpenCode Chat/Responses routing."""
+import asyncio
+import json
+from collections.abc import Callable
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import httpx2
import pytest
+from openai import AsyncOpenAI
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.stream_contracts import (
+ assert_anthropic_stream_contract,
+ parse_sse_text,
+ text_content,
+)
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.opencode import (
+ OpenCodeProvider,
+ create_opencode_provider,
+)
+from free_claude_code.providers.opencode.catalog import (
+ OPENCODE_CATALOG_URL,
+ OpenCodeCatalog,
+ OpenCodeUpstreamTransport,
+ parse_open_code_catalog,
+)
from tests.providers.support import (
capture_openai_chat_wire_body,
immediate_admission,
make_provider_config,
- profiled_provider,
reasoning_for,
)
+def _config():
+ return make_provider_config(
+ api_key="test_opencode_key",
+ base_url="https://opencode.ai/zen/v1",
+ rate_limit=100,
+ rate_window=1,
+ )
+
+
+def _catalog_payload(
+ models: dict[str, object] | None = None,
+ *,
+ provider_package: str | None = "@ai-sdk/openai-compatible",
+ provider_key: str = "opencode",
+) -> dict[str, object]:
+ provider: dict[str, object] = {
+ "models": models
+ or {
+ "chat-selector": {
+ "id": "chat-upstream",
+ "reasoning": False,
+ },
+ "responses-selector": {
+ "id": "responses-upstream",
+ "provider": {"npm": "@ai-sdk/openai"},
+ "reasoning": True,
+ },
+ }
+ }
+ if provider_package is not None:
+ provider["npm"] = provider_package
+ return {provider_key: provider}
+
+
+def _catalog_client(
+ handler: Callable[[httpx.Request], httpx.Response],
+) -> httpx.AsyncClient:
+ return httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+
+def _request(model: str, **overrides: object) -> MessagesRequest:
+ payload: dict[str, object] = {
+ "model": model,
+ "messages": [{"role": "user", "content": "hello"}],
+ "max_tokens": 128,
+ }
+ payload.update(overrides)
+ return MessagesRequest.model_validate(payload)
+
+
+def _responses_event_stream(text: str) -> str:
+ events: tuple[dict[str, object], ...] = (
+ {
+ "type": "response.output_text.delta",
+ "sequence_number": 0,
+ "item_id": "item_text",
+ "output_index": 0,
+ "content_index": 0,
+ "delta": text,
+ "logprobs": [],
+ },
+ {
+ "type": "response.completed",
+ "sequence_number": 1,
+ "response": {
+ "id": "resp_1",
+ "object": "response",
+ "created_at": 1,
+ "status": "completed",
+ "background": False,
+ "billing": {"payer": "developer"},
+ "error": None,
+ "incomplete_details": None,
+ "instructions": None,
+ "max_output_tokens": 128,
+ "max_tool_calls": None,
+ "model": "responses-upstream",
+ "output": [],
+ "parallel_tool_calls": True,
+ "previous_response_id": None,
+ "prompt_cache_key": None,
+ "prompt_cache_retention": None,
+ "reasoning": {"effort": None, "summary": None},
+ "safety_identifier": None,
+ "service_tier": "default",
+ "store": False,
+ "temperature": 1.0,
+ "text": {"format": {"type": "text"}, "verbosity": "medium"},
+ "tool_choice": "auto",
+ "tools": [],
+ "top_logprobs": 0,
+ "top_p": 1.0,
+ "truncation": "disabled",
+ "usage": {
+ "input_tokens": 2,
+ "input_tokens_details": {"cached_tokens": 0},
+ "output_tokens": 1,
+ "output_tokens_details": {"reasoning_tokens": 0},
+ "total_tokens": 3,
+ },
+ "user": None,
+ },
+ },
+ )
+ return "".join(f"data: {json.dumps(event)}\n\n" for event in events)
+
+
+def _chat_event_stream(text: str) -> str:
+ chunks = (
+ {
+ "id": "chatcmpl_1",
+ "object": "chat.completion.chunk",
+ "created": 1,
+ "model": "chat-upstream",
+ "choices": [
+ {
+ "index": 0,
+ "delta": {"role": "assistant", "content": text},
+ "finish_reason": None,
+ }
+ ],
+ },
+ {
+ "id": "chatcmpl_1",
+ "object": "chat.completion.chunk",
+ "created": 1,
+ "model": "chat-upstream",
+ "choices": [
+ {
+ "index": 0,
+ "delta": {},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 2,
+ "completion_tokens": 1,
+ "total_tokens": 3,
+ },
+ },
+ )
+ return "".join(f"data: {json.dumps(chunk)}\n\n" for chunk in chunks) + (
+ "data: [DONE]\n\n"
+ )
+
+
+def _provider_with_wire_transports(
+ payload: dict[str, object],
+) -> tuple[OpenCodeProvider, list[httpx2.Request], list[httpx.Request]]:
+ generation_requests: list[httpx2.Request] = []
+ catalog_requests: list[httpx.Request] = []
+
+ def generation_handler(request: httpx2.Request) -> httpx2.Response:
+ generation_requests.append(request)
+ if request.url.path.endswith("/responses"):
+ body = _responses_event_stream("responses-ok")
+ elif request.url.path.endswith("/chat/completions"):
+ body = _chat_event_stream("chat-ok")
+ else:
+ raise AssertionError(f"unexpected generation path {request.url.path}")
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=body,
+ )
+
+ def catalog_handler(request: httpx.Request) -> httpx.Response:
+ catalog_requests.append(request)
+ return httpx.Response(200, json=payload)
+
+ generation_client = AsyncOpenAI(
+ api_key="test_opencode_key",
+ base_url="https://opencode.ai/zen/v1",
+ max_retries=0,
+ http_client=httpx2.AsyncClient(
+ transport=httpx2.MockTransport(generation_handler)
+ ),
+ )
+ with patch(
+ "free_claude_code.providers.openai_chat.provider.AsyncOpenAI",
+ return_value=generation_client,
+ ):
+ provider = create_opencode_provider(
+ "opencode_zen",
+ _config(),
+ immediate_admission(provider_name="opencode_zen"),
+ catalog_client=_catalog_client(catalog_handler),
+ )
+ return provider, generation_requests, catalog_requests
+
+
+async def _collect(provider: OpenCodeProvider, model: str, **overrides: object) -> str:
+ return "".join(
+ [
+ chunk
+ async for chunk in provider.stream_response(
+ _request(model, **overrides),
+ input_tokens=2,
+ request_id="req_opencode",
+ )
+ ]
+ )
+
+
@pytest.mark.parametrize("provider_id", ["opencode_zen", "opencode_go"])
def test_client_identifies_as_first_party_opencode_user_agent(
provider_id: str,
) -> None:
- """OpenCode Zen throttles third-party free usage; FCC identifies as ``opencode``."""
- provider = profiled_provider(
- provider_id,
- make_provider_config(
- api_key="test_opencode_key",
- base_url="https://example.invalid/v1",
- rate_limit=1,
- rate_window=1,
+ with (
+ patch(
+ "free_claude_code.providers.openai_chat.provider.AsyncOpenAI"
+ ) as mock_openai,
+ patch("httpx.AsyncClient"),
+ ):
+ create_opencode_provider(
+ provider_id,
+ _config(),
+ immediate_admission(provider_name=provider_id),
+ )
+
+ assert mock_openai.call_args.kwargs["default_headers"] == {"User-Agent": "opencode"}
+
+
+def test_catalog_resolves_package_precedence_status_alias_and_reasoning() -> None:
+ snapshot = parse_open_code_catalog(
+ _catalog_payload(
+ {
+ "provider-default": {"id": "provider-default", "reasoning": False},
+ "responses-alias": {
+ "id": "actual-responses-id",
+ "provider": {"npm": "@ai-sdk/openai"},
+ "status": "beta",
+ "reasoning": True,
+ },
+ "anthropic": {
+ "id": "anthropic-id",
+ "provider": {"npm": "@ai-sdk/anthropic"},
+ },
+ "google": {
+ "id": "google-id",
+ "provider": {"npm": "@ai-sdk/google"},
+ },
+ "unknown-package": {
+ "id": "unknown-id",
+ "provider": {"npm": "@vendor/future"},
+ },
+ "alpha": {"id": "alpha-id", "status": "alpha"},
+ "deprecated": {"id": "old-id", "status": "deprecated"},
+ }
),
- admission=immediate_admission(),
+ provider_key="opencode",
+ provider_name="OPENCODE_ZEN",
)
- assert provider._client.default_headers["User-Agent"] == "opencode"
+
+ assert set(snapshot.routes) == {
+ "provider-default",
+ "responses-alias",
+ "anthropic",
+ "google",
+ "unknown-package",
+ }
+ provider_default = snapshot.route("provider-default")
+ assert provider_default is not None
+ assert provider_default.transport is OpenCodeUpstreamTransport.CHAT_COMPLETIONS
+ responses = snapshot.route("responses-alias")
+ assert responses is not None
+ assert responses.upstream_model_id == "actual-responses-id"
+ assert responses.transport is OpenCodeUpstreamTransport.RESPONSES
+ assert responses.supports_thinking is True
+ for selector in ("anthropic", "google", "unknown-package"):
+ route = snapshot.route(selector)
+ assert route is not None
+ assert route.transport is OpenCodeUpstreamTransport.CHAT_COMPLETIONS
+ assert snapshot.model_infos == frozenset(
+ {
+ ProviderModelInfo("provider-default", supports_thinking=False),
+ ProviderModelInfo("responses-alias", supports_thinking=True),
+ ProviderModelInfo("anthropic"),
+ ProviderModelInfo("google"),
+ ProviderModelInfo("unknown-package"),
+ }
+ )
+
+
+def test_catalog_defaults_missing_package_to_chat_completions() -> None:
+ snapshot = parse_open_code_catalog(
+ _catalog_payload(
+ {"defaulted": {"id": "upstream"}},
+ provider_package=None,
+ ),
+ provider_key="opencode",
+ provider_name="OPENCODE_ZEN",
+ )
+
+ route = snapshot.route("defaulted")
+ assert route is not None
+ assert route.transport is OpenCodeUpstreamTransport.CHAT_COMPLETIONS
+
+
+ "payload,match",
+ [
+ ({}, "provider section"),
+ ({"opencode": {"models": []}}, "models object"),
+ (_catalog_payload({" ": {"id": "x"}}), "model selector"),
+ (_catalog_payload({"x": {"id": " "}}), "model 'x' id"),
+ (_catalog_payload({"x": {"id": "x", "status": "future"}}), "status"),
+ (_catalog_payload({"x": {"id": "x", "reasoning": "yes"}}), "reasoning"),
+ (
+ _catalog_payload({"x": {"id": "x", "provider": {"npm": " "}}}),
+ "provider npm",
+ ),
+ (
+ _catalog_payload({"x": {"id": "x", "status": "deprecated"}}),
+ "no active or beta models",
+ ),
+ ],
+)
+def test_catalog_rejects_malformed_route_critical_data(
+ payload: object,
+ match: str,
+) -> None:
+ with pytest.raises(ModelListResponseError, match=match):
+ parse_open_code_catalog(
+ payload,
+ provider_key="opencode",
+ provider_name="OPENCODE_ZEN",
+ )
+
+
+def test_catalog_rejects_duplicate_normalized_selectors() -> None:
+ with pytest.raises(ModelListResponseError, match="duplicate normalized"):
+ parse_open_code_catalog(
+ _catalog_payload(
+ {
+ "same": {"id": "first"},
+ " same ": {"id": "second"},
+ }
+ ),
+ provider_key="opencode",
+ provider_name="OPENCODE_ZEN",
+ )
+
+
+async def test_cold_catalog_load_is_coalesced_and_never_sends_api_key() -> None:
+ requests: list[httpx.Request] = []
+
+ async def handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ await asyncio.sleep(0)
+ return httpx.Response(200, json=_catalog_payload())
+
+ client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+ catalog = OpenCodeCatalog(
+ _config(),
+ provider_key="opencode",
+ provider_name="OPENCODE_ZEN",
+ admission=immediate_admission(provider_name="opencode_zen"),
+ client=client,
+ )
+ try:
+ first, second = await asyncio.gather(catalog.snapshot(), catalog.snapshot())
+ finally:
+ await catalog.cleanup()
+
+ assert first is second
+ assert len(requests) == 1
+ assert str(requests[0].url) == OPENCODE_CATALOG_URL
+ assert requests[0].headers["user-agent"] == "opencode"
+ assert "authorization" not in requests[0].headers
+ assert "test_opencode_key" not in repr(requests[0].headers)
+
+
+async def test_refresh_atomically_replaces_snapshot_and_retains_last_good_on_error() -> (
+ None
+):
+ payloads: list[object] = [
+ _catalog_payload({"first": {"id": "first-upstream"}}),
+ _catalog_payload({"second": {"id": "second-upstream"}}),
+ _catalog_payload({"broken": {"id": ""}}),
+ ]
+
+ def handler(_request: httpx.Request) -> httpx.Response:
+ return httpx.Response(200, json=payloads.pop(0))
+
+ catalog = OpenCodeCatalog(
+ _config(),
+ provider_key="opencode",
+ provider_name="OPENCODE_ZEN",
+ admission=immediate_admission(provider_name="opencode_zen"),
+ client=_catalog_client(handler),
+ )
+ try:
+ first = await catalog.refresh()
+ second = await catalog.refresh()
+ with pytest.raises(ModelListResponseError):
+ await catalog.refresh()
+ cached = await catalog.snapshot()
+ finally:
+ await catalog.cleanup()
+
+ assert set(first.routes) == {"first"}
+ assert set(second.routes) == {"second"}
+ assert cached is second
+
+
+async def test_cold_catalog_failure_is_canonical_and_never_guesses_transport() -> None:
+ attempts = 0
+
+ def handler(_request: httpx.Request) -> httpx.Response:
+ nonlocal attempts
+ attempts += 1
+ return httpx.Response(503, json={"error": "busy"})
+
+ catalog = OpenCodeCatalog(
+ _config(),
+ provider_key="opencode",
+ provider_name="OPENCODE_ZEN",
+ admission=immediate_admission(
+ provider_name="opencode_zen",
+ max_attempts=2,
+ ),
+ client=_catalog_client(handler),
+ )
+ try:
+ with pytest.raises(ExecutionFailure) as exc_info:
+ await catalog.snapshot(request_id="req_catalog")
+ finally:
+ await catalog.cleanup()
+
+ assert attempts == 2
+ assert exc_info.value.retryable is True
+ assert catalog.current_snapshot is None
+
+
+async def test_direct_inference_routes_responses_without_prior_model_listing() -> None:
+ provider, generation_requests, catalog_requests = _provider_with_wire_transports(
+ _catalog_payload()
+ )
+ try:
+ body = await _collect(provider, "responses-selector")
+ finally:
+ await provider.cleanup()
+
+ assert len(catalog_requests) == 1
+ assert [request.url.path for request in generation_requests] == [
+ "/zen/v1/responses"
+ ]
+ payload = json.loads(generation_requests[0].content)
+ assert payload["model"] == "responses-upstream"
+ events = parse_sse_text(body)
+ assert_anthropic_stream_contract(events)
+ assert text_content(events) == "responses-ok"
+
+
+async def test_chat_catalog_route_uses_existing_chat_transport_and_upstream_id() -> (
+ None
+):
+ provider, generation_requests, _catalog_requests = _provider_with_wire_transports(
+ _catalog_payload()
+ )
+ try:
+ body = await _collect(provider, "chat-selector")
+ finally:
+ await provider.cleanup()
+
+ assert [request.url.path for request in generation_requests] == [
+ "/zen/v1/chat/completions"
+ ]
+ payload = json.loads(generation_requests[0].content)
+ assert payload["model"] == "chat-upstream"
+ events = parse_sse_text(body)
+ assert_anthropic_stream_contract(events)
+ assert text_content(events) == "chat-ok"
+
+
+async def test_unknown_model_rejects_before_either_generation_endpoint() -> None:
+ provider, generation_requests, catalog_requests = _provider_with_wire_transports(
+ _catalog_payload()
+ )
+ try:
+ with pytest.raises(InvalidRequestError, match="does not advertise"):
+ await _collect(provider, "not-advertised")
+ finally:
+ await provider.cleanup()
+
+ assert len(catalog_requests) == 1
+ assert generation_requests == []
+
+
+async def test_model_listing_and_dispatch_use_same_snapshot() -> None:
+ provider, generation_requests, catalog_requests = _provider_with_wire_transports(
+ _catalog_payload()
+ )
+ try:
+ infos = await provider.list_model_infos()
+ body = await _collect(provider, "responses-selector")
+ finally:
+ await provider.cleanup()
+
+ assert infos == frozenset(
+ {
+ ProviderModelInfo("chat-selector", supports_thinking=False),
+ ProviderModelInfo("responses-selector", supports_thinking=True),
+ }
+ )
+ assert len(catalog_requests) == 1
+ assert generation_requests[0].url.path.endswith("/responses")
+ assert text_content(parse_sse_text(body)) == "responses-ok"
+
+
+async def test_cold_route_specific_conversion_failure_precedes_generation() -> None:
+ provider, generation_requests, _catalog_requests = _provider_with_wire_transports(
+ _catalog_payload()
+ )
+ try:
+ with pytest.raises(InvalidRequestError, match="stop_sequences"):
+ await _collect(
+ provider,
+ "responses-selector",
+ stop_sequences=["done"],
+ )
+ finally:
+ await provider.cleanup()
+
+ assert generation_requests == []
+
+
+async def test_warm_preflight_rejects_unknown_and_route_specific_fields() -> None:
+ provider, generation_requests, _catalog_requests = _provider_with_wire_transports(
+ _catalog_payload()
+ )
+ try:
+ await provider.list_model_infos()
+ with pytest.raises(InvalidRequestError, match="does not advertise"):
+ provider.preflight_stream(_request("missing"))
+ with pytest.raises(InvalidRequestError, match="stop_sequences"):
+ provider.preflight_stream(
+ _request("responses-selector", stop_sequences=["done"])
+ )
+ finally:
+ await provider.cleanup()
+
+ assert generation_requests == []
+
+
+async def test_cleanup_attempts_both_owned_clients_when_generation_close_fails() -> (
+ None
+):
+ provider, _generation_requests, _catalog_requests = _provider_with_wire_transports(
+ _catalog_payload()
+ )
+ generation_close = AsyncMock(side_effect=RuntimeError("generation close failed"))
+ catalog_close = AsyncMock()
+ provider._client.close = generation_close
+ provider._catalog._client.aclose = catalog_close
+
+ with pytest.raises(RuntimeError, match="generation close failed"):
+ await provider.cleanup()
+
+ generation_close.assert_awaited_once()
+ catalog_close.assert_awaited_once()
@pytest.mark.parametrize("provider_id", ["opencode_zen", "opencode_go"])
def test_build_request_body_replays_tool_reasoning_natively(
provider_id: str,
) -> None:
- provider = profiled_provider(
- provider_id,
- make_provider_config(
- api_key="test_opencode_key",
- base_url="https://example.invalid/v1",
- rate_limit=1,
- rate_window=1,
- ),
- admission=immediate_admission(),
- )
+ with (
+ patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"),
+ patch("httpx.AsyncClient"),
+ ):
+ provider = create_opencode_provider(
+ provider_id,
+ _config(),
+ immediate_admission(provider_name=provider_id),
+ )
request = MessagesRequest.model_validate(
{
"model": "m",
@@ -98,16 +679,15 @@ def test_build_request_body_replays_tool_reasoning_natively(
async def test_tool_only_history_sends_empty_reasoning_content_on_wire(
provider_id: str,
) -> None:
- provider = profiled_provider(
- provider_id,
- make_provider_config(
- api_key="test_opencode_key",
- base_url="https://example.invalid/v1",
- rate_limit=1,
- rate_window=1,
- ),
- admission=immediate_admission(),
- )
+ with (
+ patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"),
+ patch("httpx.AsyncClient"),
+ ):
+ provider = create_opencode_provider(
+ provider_id,
+ _config(),
+ immediate_admission(provider_name=provider_id),
+ )
request = MessagesRequest.model_validate(
{
"model": "m",
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index 86e39641..ae8f1068 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -57,6 +57,7 @@ from free_claude_code.providers.openai_chat import (
OpenAIChatProvider,
)
from free_claude_code.providers.openai_codex import OpenAICodexProvider
+from free_claude_code.providers.opencode import OpenCodeProvider
from free_claude_code.providers.runtime import (
ProviderRuntime,
build_provider_config,
@@ -721,20 +722,22 @@ def test_opencode_zen_provider_config_uses_explicit_id_and_name():
with patch("httpx.AsyncClient"):
provider = create_provider("opencode_zen", _make_settings())
- assert isinstance(provider, OpenAIChatProvider)
+ assert isinstance(provider, OpenCodeProvider)
assert provider._base_url == "https://opencode.ai/zen/v1"
assert provider._provider_name == "OPENCODE_ZEN"
assert provider._api_key == "test_opencode_key"
+ assert provider._responses._admission is provider._admission
def test_opencode_go_provider_config_uses_correct_base_url_and_name():
with patch("httpx.AsyncClient"):
provider = create_provider("opencode_go", _make_settings())
- assert isinstance(provider, OpenAIChatProvider)
+ assert isinstance(provider, OpenCodeProvider)
assert provider._base_url == "https://opencode.ai/zen/go/v1"
assert provider._provider_name == "OPENCODE_GO"
assert provider._api_key == "test_opencode_key"
+ assert provider._responses._admission is provider._admission
def test_opencode_go_catalog_uses_opencode_api_key() -> None:
@@ -896,10 +899,10 @@ def test_create_provider_instantiates_each_builtin():
"ollama": OpenAIChatProvider,
"ollama_cloud": OpenAIChatProvider,
"wafer": OpenAIChatProvider,
- "opencode_zen": OpenAIChatProvider,
+ "opencode_zen": OpenCodeProvider,
"poolside": OpenAIChatProvider,
"llm7": OpenAIChatProvider,
- "opencode_go": OpenAIChatProvider,
+ "opencode_go": OpenCodeProvider,
"vercel": OpenAIChatProvider,
"bedrock": OpenAIChatProvider,
"huggingface": OpenAIChatProvider,
diff --git a/uv.lock b/uv.lock
index 24f4cb0b..529189fc 100644
--- a/uv.lock
+++ b/uv.lock
@@ -607,7 +607,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.14.0"
+version = "5.14.1"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },