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.mdindex dbcd4c90..96c331e4 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -47,6 +47,8 @@ flowchart LRExecutor --> 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-calassembly, and streamed usage handling. No obsolete generic transport namespaceor 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 Groqdiff --git a/pyproject.toml b/pyproject.tomlindex 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.pyindex 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__.pynew file mode 100644index 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.pynew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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.pyindex 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 OpenCodeProviderfrom free_claude_code.providers.vertex import VertexProviderfrom 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.pynew file mode 100644index 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.pyindex 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 httpx2import pytest+from openai import AsyncOpenAI+from free_claude_code.application.errors import InvalidRequestError+from free_claude_code.application.model_metadata import ProviderModelInfofrom 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.pyindex 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 OpenCodeProviderfrom 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._admissiondef 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._admissiondef 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.lockindex 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" },