Introducing a new way to review your PRs.

Read the announcement

alishahryar1 / free-claude-code

Use Claude Code, Codex, Antigravity, 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)

View on GitHub

28 documents · Updated Nov 20, 2026

docs / provider-adapter-catalog

Vendor provider adapters

Vendor provider adapters give the product one model and stream experience across upstream services with different rules. They cover OpenAI-compatible Chat Completions, native OpenAI Responses, native Anthropic Messages, Google Gemini, connected accounts, cloud gateways, local servers, and focused vendor bridges. Each adapter keeps vendor rules at the boundary while preserving common reasoning, tool, usage, recovery, and failure behavior. See Provider integration layer for shared provider services, Provider runtime and discovery for selection and lifecycle, and History replay and correction for replay rules used by recovery.

Adapter families

Provider boundary

The provider boundary gives the rest of the product one path for request checks, model metadata, streamed generation, and cleanup. An adapter receives a resolved endpoint and credential context. It then hides the upstream protocol behind the product's public stream shape.

The boundary keeps vendor compatibility separate from provider selection. The runtime selects a provider and model. The adapter decides how that model carries reasoning, tools, usage, and terminal events.

References: src/…/provider.py• L39-89 src/…/behavior.py• L28-103 src/…/transport.py• L549-584 src/…/transport.py• L90-114 src/…/transport.py• L111-143

OpenAI-compatible Chat Completions

The profile-driven Chat Completions adapter serves services that use the OpenAI chat request and stream shape. A provider profile states the service's compatibility rules, while provider behavior supplies only the vendor-specific exceptions. This lets one transport support many hosted gateways, direct vendor APIs, cloud services, and local servers.

The adapter builds a common request, applies vendor rules, and reads text, reasoning, tool calls, and usage from streamed choices. Profiles also describe model-list shapes, input limits, reasoning fields, endpoint normalization, and fields that the service must not receive. Request policy removes unsupported fields from both the main body and caller-supplied extra fields before the request reaches the upstream SDK. Local servers such as Ollama and llama.cpp can therefore use the same request path without hosted account access.

The transport also handles a narrow media compatibility case. It first sends attached image, audio, or video parts as supplied. If the upstream gives a recognized text-only-model rejection, it retries with each media part replaced by a note that tells the model the media was not seen. It remembers that model for the life of the transport, so later turns avoid repeating the same failed request while models that accept media keep receiving the original parts.

Provider policy also normalizes differences in token field names and request cardinality. It applies these rules after common conversion and before vendor post-processing, so the public request stays stable while each upstream receives the shape it supports.

The provider owns its client and model discovery. Discovery can use a profile-selected endpoint or a bounded paged catalog. Profiles can also mark model IDs as non-routable when a service exposes useful metadata but does not support direct routing through the normal model selector. The transport owns each request and stream. This split keeps HTTP resource lifetime separate from compatibility behavior and lets a focused adapter change request or failure rules without copying the common stream path.

Native Chat requests can also pass through this transport without conversion to the product's Messages format. That path preserves the upstream choice stream, including its multi-choice completion contract, while still using the same endpoint, attempt, and cleanup owners. Converted Chat requests instead assemble product text, reasoning, and tool events before they are exposed to the caller.

References: src/…/provider.py• L39-204 src/…/profiles.py• L75-140 src/…/client.py• L13-40 src/…/request_policy.py• L33-144 src/…/media_support.py• L1-125 src/…/transport.py• L191-227 src/…/transport.py• L549-584 src/…/transport.py• L686-767 src/…/transport.py• L923-1018

Native Responses

The Responses adapter serves upstream systems whose main stream is OpenAI Responses rather than Chat Completions. It accepts either the product's Anthropic Messages request or a native Responses request. It then presents the result in the matching downstream protocol.

One transport owns the request attempt and recovery path. A presenter owns the client view. The Messages presenter emits Anthropic events, while the native presenter emits Responses lifecycle events and preserves a failed response when the stream has already become visible.

This diagram shows how one Responses attempt supports two client-facing stream formats.

flowchart LR
    A[Messages or Responses request] --> B[Responses request builder]
    B --> C[Responses upstream stream]
    C --> D{Client protocol}
    D --> E[Messages presenter]
    D --> F[Native Responses presenter]
    E --> G[Anthropic SSE]
    F --> H[Responses SSE]

References: src/…/transport.py• L90-185 src/…/transport.py• L245-524 src/…/stream_output.py• L437-675

Native Anthropic Messages

The native Messages transport serves services that accept Anthropic Messages requests and return Anthropic server-sent events. It keeps the native message and stream contract while using the shared admission, retry, recovery, and failure rules. The Anthropic provider owns the endpoint, HTTP client, and model capability snapshot. It delegates each Messages or Responses stream to the transport with the matching model record.

The provider can apply a product reasoning override to a native request. It validates the existing native thinking and output settings, replaces only the computation controls that the product owns, and retains other native extensions. The selected controls come from the model capability record rather than from a model-name guess.

The transport also accepts product Chat, Gemini, Messages, and Responses requests when an upstream endpoint is Anthropic-shaped. Each request is converted to a native Messages body and each presenter returns the requested client protocol. This gives a native Anthropic endpoint the same product-facing entry points as the other adapter families.

The transport treats the required message_stop event as part of a successful response. A missing stop event or a non-event-stream response becomes a protocol failure instead of a partial success. A passthrough path also supports non-streaming JSON, but it accepts the result only when it is a valid Messages message object.

References: src/…/provider.py• L51-99 src/…/provider.py• L102-201 src/…/provider.py• L203-367 src/…/passthrough.py• L58-181 src/…/transport.py• L111-337 src/…/transport.py• L339-630 src/…/request_policy.py• L19-162

Compatibility behavior

Reasoning controls

Reasoning is a product request intent that vendors express in different wire forms. The compatibility layer maps it to named effort, a reasoning object, a thinking object, a chat-template flag, a numeric budget, or a separate reasoning stream.

The mapping keeps three concerns separate: whether reasoning is requested, how much compute it may use, and whether the result is shown to the client. If a service rejects an optional reasoning control before output starts, the adapter can remove or revise that control once within the request's attempt budget. Profiles can also map the product's effort range to a smaller or differently named vendor set, including adaptive modes.

Some services return both plain reasoning text and structured reasoning details. The stream keeps one visible text source and preserves opaque details for later turns. It joins fragments by their stable detail identity and completes each reasoning record once. This prevents duplicate reasoning while keeping data needed for reasoning replay.

References: src/…/behavior.py• L34-86 src/…/profiles.py• L114-173 src/…/profiles.py• L698-840 src/…/reasoning_details.py• L13-213 src/…/transport.py• L984-1018 src/…/provider.py• L55-99 src/…/transport.py• L145-225 src/…/client.py• L153-176

Stream and tool output

Every converted adapter turns upstream chunks into ordered product events for text, reasoning, tools, usage, and completion. The output boundary tracks open content and tool blocks. It can emit either Anthropic Messages events or one coherent Responses lifecycle. This lets a partial stream close safely or enter recovery without exposing an invalid event sequence.

Tool compatibility covers both request schemas and response syntax. The adapter preserves tool identity across protocol changes, validates completed arguments when needed, and converts structured or text-encoded tool calls into the form expected by the agent loop. A tool fragment must link to one upstream index or ID. An ambiguous fragment becomes a retryable protocol failure instead of being assigned to the wrong call.

Chat output can serve either Anthropic SSE or Responses SSE. The same stream state closes reasoning, text, and tool blocks before it emits the matching terminal event for the selected client protocol. For Responses, a failed stream can retain incomplete output in a failed response so the client sees a valid terminal lifecycle. Native Chat output is the exception: it relays upstream choice events without converting them into Anthropic or Responses blocks, and requires the upstream choices to reach their normal stop state.

References: src/…/stream_output.py• L75-334 src/…/stream_output.py• L437-675 src/…/tool_call_identity.py• L8-74 src/…/tool_calls.py• L43-114 src/…/transport.py• L1335-1374 src/…/stream.py• L115-186

Usage and model metadata

Adapters turn vendor model lists and usage records into product metadata. The metadata can describe context limits, output caps, input types, and reasoning support. Unknown or malformed capability data stays unknown or fails discovery rather than becoming an unsafe assumption.

Usage is normalized for Anthropic and Responses output. Cached input, cache writes, reasoning tokens, and estimated counts are included only when their values fit the target protocol's rules. Invalid or out-of-range nested counts are discarded rather than exposed as misleading usage data.

References: src/…/provider.py• L91-204 src/…/stream_output.py• L678-701 src/…/behavior.py• L106-128 src/…/provider.py• L229-281 src/…/client.py• L90-139

Vendor-specific adapters

Cloud and local endpoints

Cloud and local providers use the shared compatibility families when their endpoints fit those protocols. They keep identity, endpoint, model-list, and field rules at the vendor boundary. Cloud services may use a special model catalog or project scope. Local servers use configurable endpoints and local defaults because they do not use hosted account access.

Recent cloud profiles such as Lightning AI, Experiential Labs, Scaleway, xKiro, and Atlas Cloud use this shared path without a separate transport. Their profile rules provide the model catalog details, reasoning vocabulary, capability data, and endpoint behavior needed by the common discovery and request flow. Atlas Cloud maps the product's effort range to the gateway's broadly accepted high and xhigh values, omits the reasoning field when reasoning is off, and leaves thinking capability unknown when catalog data under-reports it.

Profile rules also capture differences that are easy to miss. Some services use a different token field, some report reasoning in a different delta, and some expose only text input or tool-capable models. Endpoint normalization lets local OpenAI-style servers work with the same request path.

References: src/…/profiles.py• L698-840 src/…/client.py• L13-40 src/…/provider.py• L91-204

Google Gemini

The Gemini adapter connects to Google's native GenerateContent API rather than an OpenAI-shaped endpoint. It discovers models from the provider catalog, keeps only models that support generation, and preserves reported context, output, and thinking capability values for preflight checks.

The adapter accepts product Messages, Chat, Responses, and native Gemini requests. It converts each request to Gemini content and then presents native parts as the selected client stream. Gemini thinking uses model-aware controls. The 2.5 Flash family can use a native zero-budget disable path, while other capability gaps remain explicit instead of being guessed from the model name.

Gemini output can contain text, thought text, and function calls. The adapter checks function names against the declared tools and turns valid calls into product tool blocks. It also retains native thought signatures and model parts for later continuation. Grounding and citation output is rejected when the selected client protocol cannot represent it.

Gemini success requires a finishReason. The stream maps token usage and finish reasons into product usage and stop events. Safety or other non-normal finish reasons become refusal-like terminal results rather than silent success.

References: src/…/client.py• L53-139 src/…/client.py• L141-286 src/…/transport.py• L83-215 src/…/stream.py• L26-58 src/…/stream.py• L89-228 src/…/stream.py• L230-311

OpenAI API compatibility

The OpenAI API adapter uses public API credentials and the Responses transport. It keeps API-key access separate from connected ChatGPT or Codex account access. Model discovery reads the public model catalog and converts it into the same product metadata used by other providers.

Some OpenAI models accept only default sampling values. If the API explicitly rejects the caller's temperature or top_p as unsupported for that model, the adapter removes only that field and retries within the shared attempt budget. It does not hide ordinary invalid values or remove a value that was changed by another request stage. The correction is reported as a named proposal so the common attempt loop applies it with the same recovery accounting as other provider corrections.

References: src/…/provider.py• L35-72 src/…/provider.py• L74-127 src/…/provider.py• L129-212

DeepSeek compatibility

The DeepSeek adapter uses the Chat Completions family but adds rules for DeepSeek's reasoning, tool, attachment, and cache behavior. It keeps tool continuations usable by replaying assistant reasoning in the form DeepSeek expects. It also maps valid cache hit and miss counts into product usage.

DeepSeek vision models can receive image blocks. Unsupported document content is removed for other models and replaced with a clear placeholder when needed. MCP servers and listed web tools are rejected because DeepSeek cannot provide their required contract. Forced function tool choice is downgraded to automatic selection because the native request shape does not support it.

Reasoning effort is reduced to the forms DeepSeek accepts. A disabled request uses its explicit disabled-thinking field. A requested effort uses the provider's supported effort values instead of sending a generic product value unchanged.

References: src/…/client.py• L20-105 src/…/compat.py• L25-89 src/…/compat.py• L91-169 src/…/compat.py• L172-241

OpenRouter compatibility

OpenRouter presents many upstream models through one OpenAI-compatible gateway. Its adapter advertises only tool-capable models from the gateway catalog and keeps reasoning metadata with those models.

The gateway may reject a request that explicitly disables reasoning. The adapter recognizes that narrow error shape and allows the shared correction path to remove the optional control. Other errors keep the normal provider failure classification.

References: src/…/client.py• L25-75 src/…/transport.py• L863-903 src/…/reasoning_compatibility.py• L1-120

Connected account endpoints

The ChatGPT Codex adapter uses the Responses transport with credentials borrowed from the connected account for each request. The endpoint adds account identity, session headers, and subscription fields required by the backend.

Model discovery also borrows credentials for each catalog request and uses the same admission and request-recovery boundary as generation. The catalog must contain a valid model list and at least one model marked visible. It preserves reasoning, input, and context metadata only when the account supplies valid values. An unauthorized request can trigger one credential recovery before the shared execution budget continues. If the account cannot provide a usable credential, the adapter returns an authentication failure that tells the caller to reconnect rather than treating the request as a generic upstream error.

Each generation call gets its own session identity. This keeps the account context tied to one inference while the shared Responses transport handles stream conversion and cleanup.

References: src/…/endpoint.py• L11-53 src/…/provider.py• L46-162 src/…/provider.py• L164-207 src/…/provider.py• L229-281 src/…/transport.py• L435-475

GitHub Copilot sessions

The GitHub Copilot broker binds a selected account, model, upstream protocol, and temporary endpoint into one lease. Discovery checks the account identity and publishes a complete model set. Generation rechecks identity and model availability before and after it obtains the endpoint.

The lease keeps the selected egress stable for the full inference. It refreshes credentials before expiry and rejects a mid-request protocol change instead of silently switching the request to another transport. The provider tracks active streams and closes only after those streams and SDK session creation drain. This protects both the account lease and the owned HTTP resources during shutdown.

Copilot uses its native CLI profile and official runtime for account access. Device-code login exposes the verification challenge but leaves the resulting credential in the native account system. The adapter verifies the required CLI version and filters token or bring-your-own-provider overrides from the runtime environment.

The selected Copilot egress determines the shared transport: native Messages, Responses, or Chat Completions. The runtime creates inert endpoint sessions for this purpose, so FCC owns request and tool execution while the account service supplies only model access and endpoint data.

References: src/…/broker.py• L28-103 src/…/broker.py• L108-248 src/…/auth.py• L267-304 src/…/login.py• L40-112 src/…/native_cli.py• L14-76 src/…/provider.py• L70-194 src/…/provider.py• L196-338 src/…/sdk.py• L79-220 src/…/types.py• L22-67

OpenCode catalog routes

OpenCode uses a rich catalog to map one public model selector to an upstream model ID and transport. The catalog can select Chat Completions or Responses per model. It also supplies the capability data used for preflight and model display.

The provider loads and validates a complete catalog snapshot before publishing it. It hides inactive models and rejects malformed or empty provider sections. Each generation request resolves its route, replaces the public selector with the upstream model ID, and dispatches to the matching shared transport. This lets one OpenCode provider expose different upstream protocol families without changing the public model selector.

OpenCode supports both product-facing Messages and native Responses streams through the same route decision. It forwards a small set of trusted session headers when present and closes the selected stream when generation ends or fails. This keeps request context and resource cleanup consistent across both upstream transports.

This diagram shows the route from a public OpenCode model selector to the selected upstream transport.

flowchart LR
    A[OpenCode model selector] --> B[Validated catalog snapshot]
    B --> C[Upstream model ID]
    C --> D{Catalog transport}
    D --> E[Chat Completions adapter]
    D --> F[Responses adapter]
    E --> G[Unified product stream]
    F --> G

References: src/…/catalog.py• L33-63 src/…/catalog.py• L77-180 src/…/catalog.py• L215-273 src/…/provider.py• L77-169 src/…/provider.py• L171-245 src/…/provider.py• L247-332

NVIDIA NIM corrections

NVIDIA NIM uses the Chat Completions family but may reject optional reasoning controls or native reasoning content. Its correction path creates a fresh request with only the rejected control removed. When reasoning content is rejected, it moves that content into readable assistant context so the next request keeps the prior turn's meaning. These corrections preserve the history contract described in History replay and correction.

NIM applies provider settings such as token limits, sampling, stop rules, tool parallelism, and template controls without overwriting fields already supplied by the request. It removes competing reasoning fields before it encodes the selected reasoning mode. It also strips private tool aliases before sending the request and keeps them available for response repair.

NIM can expose MiniMax-M3 tool calls as namespace-delimited text instead of normal tool deltas. The adapter separates visible text from that markup, parses declared tool arguments, checks them against the request schemas, and emits ordinary tool-call chunks. Malformed, incomplete, oversized, or schema-invalid markup becomes a retryable tool protocol failure rather than an executable tool call.

NIM classifies known context-window and degraded-function responses by their meaning instead of treating every 400 or 500 response as the same failure. These corrections and classifications run only for known response shapes and remain inside the shared attempt budget.

For the default hosted NIM endpoint, discovery removes a maintained set of model IDs that are known to be unavailable, retired, or not chat services on the tested hosted routes. Custom NIM endpoints keep their discovered models because the hosted observations do not prove that a model is unavailable everywhere. The exclusion list is therefore a routing safeguard that needs periodic verification, not a global model retirement record.

References: src/…/client.py• L57-181 src/…/client.py• L184-214 src/…/models.py• L1-72 src/…/request_options.py• L24-129 src/…/retry.py• L10-69 src/…/native_tool_stream.py• L32-58 src/…/native_tool_stream.py• L200-283 src/…/native_tool_stream.py• L421-451 src/…/native_tool_stream.py• L629-637

Recovery and failure handling

Attempt recovery

Each logical provider operation owns one bounded admission and recovery budget. The budget covers request corrections, authentication refresh, transient upstream retry, and stream recovery. A compatibility fallback therefore cannot create an untracked retry loop.

The Chat transport learns a lower output-token cap when an upstream model reports one through a clear request error. It reuses that cap for later requests to the same model. It also remembers a model after a recognized media rejection and replaces later image, audio, or video parts before sending them. Other request corrections remain narrow: they remove stream-usage or provider fields only when the error matches a known rejection. Request-scoped endpoint and extra-header context also follows buffered continuation and tool-repair attempts, so recovery keeps the same routing or affinity contract as the original request.

The adapter holds early stream events until the response passes a safe commit point. An early failure can discard those events and retry. A failure after visible output preserves committed content, closes open blocks, and returns a canonical terminal failure or a valid recovered continuation.

For converted Chat Completions, recovery can salvage a complete tool call, repair incomplete tool arguments, continue interrupted text and reasoning, or replace rejected media with explanatory notes. Native Chat preserves its upstream choice-stream contract instead of applying converted tool salvage; all choices must reach their normal stop state before success. For native Responses, Messages, and Gemini, recovery keeps the public lifecycle valid and requires the upstream terminal event before it reports success.

Native Messages and Gemini use the same broad sequence: resolve the endpoint, replay history for the attempt, hold early output, apply one known request correction when possible, then either retry, continue, or classify the failure. Their native terminal markers are message_stop for Messages and finishReason for Gemini.

References: src/…/media_support.py• L45-125 src/…/stream_output.py• L75-334 src/…/stream_output.py• L437-675 src/…/transport.py• L191-227 src/…/transport.py• L686-767 src/…/transport.py• L1056-1137 src/…/transport.py• L1170-1317 src/…/transport.py• L399-630 src/…/passthrough.py• L184-287 src/…/transport.py• L148-369

Failure classification

Adapters map vendor status codes, stream events, and error bodies to stable product failure kinds. These include authentication, permission, invalid request, context limit, rate limit, overload, timeout, unavailable, and upstream failure.

A stream without its required terminal event is a protocol failure, not a successful answer. Native Messages requires message_stop. Gemini requires finishReason. Responses requires a terminal lifecycle event. Converted Chat requires finish_reason, while native Chat requires normal stops for all choices. Error detail is bounded and redacted before it reaches the caller.

Responses can expose a failed response after the client has seen output. The execution result remains failed even when the presenter emits a valid terminal failure event. The presenter retains incomplete output items so caller state and provider monitoring stay aligned.

Messages error events and HTTP responses preserve bounded upstream evidence for diagnosis. The evidence is redacted before display and status mapping stays separate from the raw provider body.

References: src/…/wire.py• L29-59 src/…/wire.py• L62-129 src/…/passthrough.py• L257-285 src/…/stream.py• L64-88 src/…/stream.py• L230-245 src/…/transport.py• L380-424 src/…/transport.py• L491-517 src/…/stream_output.py• L650-675 src/…/transport.py• L586-627

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep a provider's request mapping, stream mapping, model metadata, and failure mapping aligned. A request can succeed while its output remains unusable.
  • When a reasoning field changes, check the matching disable path, output parser, replay path, and one-shot rejection correction.
  • When a stream presenter changes, check both Anthropic Messages and native Responses terminal behavior.
  • When model capability metadata changes, check preflight validation and model discovery. Unknown support must not become an implicit capability.
  • When a model catalog route changes, check the public selector, upstream model ID, transport choice, and capability data as one contract.
  • When account or endpoint rules change, check generation and model discovery because they can use different upstream paths.
  • When retry behavior changes, keep compatibility correction, authentication refresh, holdback commit, recovery, and final failure inside one execution budget.
  • When content filtering changes, check whether the model sees a placeholder, a rejected request, or the original attachment. This affects tool results and future turns.
  • When media rejection matching changes, check stream errors and HTTP errors, the no-media path, the learned text-only model state, and history markers for later turns.
  • When Copilot egress or session rules change, check identity validation, lease refresh, protocol stability, active-stream draining, and shutdown cleanup together.
  • When a provider client is split between behavior and transport, keep provider-owned client cleanup and per-request stream cleanup separate.
  • When OpenAI API sampling correction changes, check that only an explicitly rejected caller value can be removed and that other invalid values still fail.
  • When OpenAI Chat recovery changes, check learned output caps, learned text-only models, stream-usage correction, provider-specific correction, held-event commit, continuation suffix handling, incomplete tool repair, tool identity resolution, and request-scoped endpoint or header context together.
  • When a Chat profile changes, check its reasoning vocabulary, delta field, model-list filters, capability paths, endpoint normalization, and request-field restrictions together.
  • When Chat request policy changes, check unsupported fields in both the top-level body and extra-body path. Also check token-field normalization and tool-name encoding.
  • When structured reasoning changes, check detail identity merging, visible-text selection, opaque replay, and both client stream formats together.
  • When native Chat changes, check the direct relay path, multi-choice stop handling, SDK field shaping, tool buffering, and the distinction from converted Chat recovery.
  • When native Messages changes, check non-stream JSON validation, SSE content-type checks, message_stop capture, error evidence, and continuation handling together.
  • When Gemini changes, check all four request formats, model discovery filters, thinking disable rules, thought-signature replay, function declarations, usage mapping, and finishReason handling together.
  • When Codex account handling changes, check request-scoped credentials, per-request session identity, model-list visibility filtering, capability validation, and authentication recovery together.
  • When OpenCode routing changes, check selector resolution, upstream model replacement, forwarded session context, both stream entry points, and selected-stream cleanup together.
  • When NIM native tool parsing changes, check visible text framing, schema validation, tool identity, stream closure, and retryable protocol failure together.
  • When hosted NIM exclusions change, check default-endpoint scope, exact model IDs, the evidence date and route, and the rule that custom endpoints retain their own discovery results.

Important failure modes

TriggerConsequenceGuard
A vendor reasoning field is accepted in the request but not understood in the streamThe client receives missing or duplicated reasoning contentPaired reasoning encoding, delta selection, and structured-detail reconciliation
Structured reasoning fragments reuse an index or ID without stable mergingThe client sees repeated text or the next turn loses opaque reasoning dataPer-detail identity tracking and one completion record for each detail
A stream ends without its required terminal eventPartial output can look like a complete agent turnTerminal-event checks and held-event recovery
A native Chat choice stream ends before every choice has a normal stopA direct relay can report incomplete output as successPer-choice stop tracking and native stream truncation failure
A tool fragment has no usable index or ID, or matches more than one callTool content can be assigned to the wrong callPer-attempt identity resolution and retryable ambiguity failure
A tool call is only partly emitted or has invalid argumentsThe agent cannot safely execute the requested toolTool block tracking, completed-argument validation, and bounded tool repair
An optional vendor field is rejected before output startsA compatible model fails for a correct product requestOne bounded provider correction before normal retry handling
Unsupported media survives after a recognized text-only-model rejectionThe same conversation fails again on every later turnReplace each media part with a clear note and remember the rejected model
A media rejection is inferred from a model name or an unrelated errorA media-capable model loses input or an invalid request is retriedMatch only known upstream error phrases and only when the request contains media
An unsupported field survives in caller-supplied extra body dataThe upstream rejects a request that passed top-level conversionApply provider field policy to both request levels
A model rejects its output-token limitA request fails even though the model can generate within a smaller limitLearn the explicit upstream cap and clamp later requests for that model
OpenAI rejects a model-incompatible sampling settingA valid model request fails before generationRemove only the explicitly rejected temperature or top_p value when the error is a default-only incompatibility
A connected account token is rejectedGeneration or discovery fails until the account is refreshed or reconnectedRequest-scoped credential recovery and authentication classification
Codex discovery returns no visible models or malformed capability valuesThe account can appear connected but cannot provide a safe model catalogRequire a valid model list, publish visible models only, and preserve unknown capability values
A Copilot identity or egress changes during lease creationThe request may use the wrong account or protocolIdentity checks and stable egress leases
Active Copilot streams are not drained before cleanupA lease or HTTP resource can close while generation is still using itActive-operation tracking and ordered shutdown
The required Copilot CLI is missing or has the wrong versionLogin and endpoint discovery cannot use the native accountVerified CLI lookup and version checks before runtime use
A rich model catalog is malformed or emptyThe provider can expose stale or unusable model routesFull snapshot validation before publication
A model lacks required capability dataAn unsupported model may become selectableCapability-aware discovery and explicit unknown values
Gemini emits grounding, citations, or unsupported native parts to a client that cannot represent themThe adapter can produce an invalid client stream or lose model outputReject unrepresentable output as a protocol failure
Gemini emits a function call for an undeclared toolThe agent may execute a tool that was not requestedDeclared-function checks before tool event emission
Gemini ends without finishReasonPartial native output can look completeRequired terminal-reason check and bounded recovery
Unsupported DeepSeek attachments or server tools pass conversionThe model receives content or tools it cannot useAttachment filtering and request validation
NIM native tool markup is incomplete or schema-invalidText can be mistaken for a tool call or a bad call can reach the agentStrict framing, size and depth limits, declared-tool checks, and schema validation
A known-unavailable hosted NIM model remains in the default catalogSelection can reach a 404, retired route, or non-chat serviceDefault-endpoint-only exclusions that are rechecked against observed routes
A Messages response is JSON when streaming is required, or lacks message_stopThe caller receives an invalid or partial Messages turnContent-type validation, native message validation, and stop-event checks
A Responses failure is consumed as a terminal event but execution is marked successfulMonitoring and caller state disagree about the resultRetained execution outcome and presenter terminal-failure contract
An OpenCode route is missing or its stream is not closedA valid public model can fail before generation or leak request resourcesActive-catalog route checks and cleanup of the selected stream

Key files

FileWhy to read it
src/…/provider.pyShows provider ownership, profile-driven discovery, pagination, and composition of the Chat transport.
src/…/profiles.pyShows the declarative catalog of vendor request, reasoning, model-list, capability, and endpoint rules.
src/…/behavior.pyShows the boundary for provider-specific request, stream, usage, and failure behavior.
src/…/request_policy.pyShows common request filtering, token-field normalization, extra-body handling, and tool-name preparation.
src/…/media_support.pyShows how recognized media rejection becomes a safe text note and a learned text-only model rule.
src/…/transport.pyShows the shared Chat request, native and converted stream paths, correction, output-cap learning, media fallback, tool identity, request context, and recovery lifecycle.
src/…/reasoning_details.pyShows structured reasoning identity, visible text selection, and opaque replay.
src/…/stream_output.pyShows how converted Chat output becomes Anthropic or Responses events, how incomplete blocks close on failure, and how usage is normalized.
src/…/tool_call_identity.pyShows how partial tool fragments keep a stable upstream identity or fail safely when identity is ambiguous.
src/…/tool_calls.pyShows tool-call assembly, schema checks, private name and argument restoration, and recovery emission.
src/…/transport.pyShows the shared Responses request, event, recovery, and failure path.
src/…/provider.pyShows native Anthropic endpoint ownership, model capability snapshots, reasoning control application, and delegation to Messages transport.
src/…/passthrough.pyShows the direct native Messages execution path for streaming and non-streaming responses.
src/…/transport.pyShows native Messages conversion for multiple request protocols, streaming, request correction, and terminal failure handling.
src/…/wire.pyShows Messages event framing, stop detection, status mapping, and bounded upstream error evidence.
src/…/client.pyShows Gemini model discovery and conversion from the product's four request formats.
src/…/transport.pyShows native GenerateContent request attempts, history replay, holdback, recovery, and endpoint cleanup.
src/…/stream.pyShows Gemini part conversion, tool checks, thought-signature replay, usage mapping, and terminal handling.
src/…/provider.pyShows public API credentials, Responses execution, model discovery, and narrow sampling correction.
src/…/compat.pyShows a focused vendor bridge for reasoning, attachments, tools, and request validation.
src/…/client.pyShows gateway model filtering and narrow reasoning rejection handling.
src/…/endpoint.pyShows request-scoped subscription credentials and unauthorized-token recovery.
src/…/provider.pyShows account-scoped Codex discovery, visible-model filtering, capability validation, and delegation to Responses execution.
src/…/broker.pyShows account identity, model discovery, endpoint leases, refresh, and shutdown behavior.
src/…/native_cli.pyShows native CLI verification and the environment boundary for Copilot account access.
src/…/provider.pyShows dispatch from a Copilot egress to Messages, Chat, or Responses transport and ordered cleanup.
src/…/sdk.pyShows the narrow official runtime boundary and inert endpoint-session model.
src/…/catalog.pyShows rich-catalog validation, route metadata, and last-good snapshot ownership.
src/…/provider.pyShows dispatch from a public OpenCode selector to Chat or Responses generation, session-header forwarding, and stream cleanup.
src/…/client.pyShows NIM-specific request correction, hosted discovery filtering, tool normalization, and failure semantics.
src/…/models.pyShows the maintained default-hosted model exclusion set and its route-scoped meaning.
src/…/native_tool_stream.pyShows conversion of MiniMax-M3 text markup into validated tool-call events.
src/…/request_options.pyShows NIM request settings and reasoning-field normalization.
src/…/retry.pyShows bounded request downgrades and preservation of rejected reasoning in assistant context.