From da638b65f50deda04da8fa1e52fb9f9639825c48 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Tue, 27 Oct 2026 00:02:55 -0500 Subject: [PATCH] docs: document model compatibility settings (#59509) --- packages/schema/src/model-compatibility.ts | 15 ++++--- services/www/src/docs/content/models.mdx | 45 ++++++++++++++++++++- services/www/src/docs/content/providers.mdx | 4 +- 3 files changed, 55 insertions(+), 9 deletions(-) diff --git a/packages/schema/src/model-compatibility.ts b/packages/schema/src/model-compatibility.ts index cbb9e620c3f..93990c96a09 100644 --- a/packages/schema/src/model-compatibility.ts +++ b/packages/schema/src/model-compatibility.ts @@ -24,22 +24,27 @@ export type CacheFormat = typeof CacheFormat.Type export interface Compatibility extends Schema.Schema.Type {} export const Compatibility = Schema.Struct({ + /** OpenAI Chat: assistant-message field that carries reasoning. Unset uses the streamed field, else `reasoning_content`. */ reasoningField: ReasoningField.pipe(optional), - /** Require every assistant message to include its reasoning field, even when empty. */ + /** OpenAI Chat: send the reasoning field on every prior assistant message, even when empty. */ requireReasoning: Schema.Boolean.pipe(optional), + /** OpenAI Chat: body field for the output token limit. Unset detects it from the provider. */ maxTokensField: MaxTokensField.pipe(optional), + /** OpenAI Chat: fail a stream that ends without `finish_reason`. Defaults to true. */ requireFinishReason: Schema.Boolean.pipe(optional), + /** OpenAI Chat: insert an assistant message between a tool result and the next user message. */ requireAssistantAfterTool: Schema.Boolean.pipe(optional), + /** OpenAI Chat, OpenAI Responses and Mistral: whether the endpoint accepts `prompt_cache_key`. */ supportsPromptCacheKey: Schema.Boolean.pipe(optional), - /** Request usage in the stream with `stream_options.include_usage`. Defaults to true. */ + /** OpenAI Chat: request usage in the stream with `stream_options.include_usage`. Defaults to true. */ streamUsage: Schema.Boolean.pipe(optional), /** Prompt-cache marker syntax the endpoint accepts. Overrides the route default; both send `cache_control`, and `alibaba` skips tool definitions. */ cacheFormat: CacheFormat.pipe(optional), - /** Supports Anthropic's thinking-prefix mismatch controls. Overrides model-ID detection. */ + /** Anthropic Messages and Bedrock Converse: supports Anthropic's thinking-prefix mismatch controls. Overrides model-ID detection. */ supportsThinkingBlockBinding: Schema.Boolean.pipe(optional), - /** Supports per-message effort updates. Overrides model-ID detection. */ + /** Anthropic Messages and OpenAI Responses: supports per-message effort updates. Overrides model-ID detection. */ supportsEffortUpdates: Schema.Boolean.pipe(optional), - /** Where a System One decision host reads media. Unset keeps the route default. */ + /** System One: where the decision host reads media. Unset keeps the route default. */ mediaInput: MediaInput.pipe(optional), }).annotate({ identifier: "Model.Compatibility" }) diff --git a/services/www/src/docs/content/models.mdx b/services/www/src/docs/content/models.mdx index 64cb618b97d..99b9589c000 100644 --- a/services/www/src/docs/content/models.mdx +++ b/services/www/src/docs/content/models.mdx @@ -273,7 +273,7 @@ For an OpenAI-compatible model that streams reasoning in a custom assistant-mess OpenCode recognizes `reasoning`, `reasoning_content`, and `reasoning_text`, and also accepts another provider-specific string. It reads streamed reasoning from that field and restores the field when sending prior assistant messages back to -the model. +the model. See [Compatibility](#compatibility) for the related `requireReasoning` field. ## Prompt caching @@ -305,7 +305,48 @@ Anthropic-style `cache_control` breakpoints. Set `compatibility.cacheFormat` on OpenCode then marks the last tool definition, the system prompt, and the latest message with `cache_control: { "type": "ephemeral" }`, which uses the endpoint's default five-minute cache lifetime. Use `"alibaba"` for Alibaba Model Studio models, which accept the same markers but ignore them on tool definitions. Set -`compatibility.cacheFormat` on the provider instead when every model it serves accepts the same format. +`compatibility.cacheFormat` on the provider instead when every model it serves accepts the same format. See +[Compatibility](#compatibility) for the other fields. + +## Compatibility + +`compatibility` describes request and response quirks of the API a model is served through, such as which field carries +reasoning or whether the endpoint accepts `prompt_cache_key`. Each model is served through one API, and a field only +takes effect when that API reads it. Other fields are ignored. + +```jsonc title="opencode.jsonc" +{ + "providers": { + "local": { + "compatibility": { "streamUsage": false }, + "models": { + "reasoner": { + "compatibility": { "reasoningField": "reasoning_content", "maxTokensField": "max_tokens" }, + }, + }, + }, + }, +} +``` + +Provider `compatibility` applies to every model of that provider. A model's own `compatibility` overrides it field by +field: OpenCode starts from the values [models.dev](https://models.dev) publishes for the model's API (`reasoningField`, +`maxTokensField`, and `mediaInput`), then applies the model's configuration. Unset fields keep the provider package's +built-in default or detection. `supportsThinkingBlockBinding` and `supportsEffortUpdates` are model-only. + +| Field | What it does | Read by | Values and default | +| --- | --- | --- | --- | +| `reasoningField` | Assistant-message field that carries reasoning. Checked first when reading streamed reasoning and used when sending prior reasoning back. | OpenAI Chat | Any field name except `role`, `content`, `refusal`, or `tool_calls`. Unset uses the field seen in the stream, else `reasoning_content`. | +| `requireReasoning` | Sends the reasoning field on every prior assistant message, as an empty string when there was no reasoning. | OpenAI Chat | `true` or `false`. Defaults to `true` when `reasoningField` is set or the model is DeepSeek, otherwise `false`. | +| `maxTokensField` | Body field that carries the output token limit. | OpenAI Chat | `max_completion_tokens` or `max_tokens`. Unset detects `max_tokens` for providers that need it, such as DeepSeek, Moonshot, Together AI, Z.AI, and Cerebras, otherwise `max_completion_tokens`. | +| `requireFinishReason` | Treats a stream that ends without `finish_reason` as an incomplete response error. `false` accepts it as finished. | OpenAI Chat | `true` or `false`. Defaults to `true`. | +| `requireAssistantAfterTool` | Inserts an assistant message between a tool result and the next user message, for endpoints that reject that order. | OpenAI Chat | `true` or `false`. Defaults to `true` for Mistral-family model IDs, otherwise `false`. | +| `supportsPromptCacheKey` | Whether the endpoint accepts the `prompt_cache_key` body field. | OpenAI Chat, OpenAI Responses, Mistral | `true` or `false`. OpenAI Chat only sends the key when `true`, which some provider packages set by default. Other APIs send it unless `false`. | +| `streamUsage` | Requests token usage in the stream with `stream_options.include_usage`. | OpenAI Chat | `true` or `false`. Defaults to `true`. | +| `cacheFormat` | Prompt-cache marker syntax the endpoint accepts. Overrides the provider's automatic breakpoint placement. `alibaba` skips tool definitions. | Every API with prompt-cache markers, including OpenAI Chat, Anthropic Messages, and Bedrock Converse | `anthropic` or `alibaba`. Unset uses the provider default. See [Prompt caching](#prompt-caching). | +| `supportsThinkingBlockBinding` | Asks the API to drop thinking blocks whose earlier context changed instead of rejecting the request. | Anthropic Messages, Bedrock Converse | `true` or `false`. Unset detects Claude 5.1 and later. | +| `supportsEffortUpdates` | Sends reasoning effort changes as per-message updates, which keep the prompt cache. Otherwise the effort changes for the whole request. | Anthropic Messages, OpenAI Responses | `true` or `false`. Unset detects Claude Opus 5, Claude 5.1 and later, and GPT-6 and later. | +| `mediaInput` | Where images and other media go in a decision request. | System One | `assets` (images referenced from the state), `state` (inline in the state), or `root` (top-level `images`, `audio`, and `videos` lists). Unset uses the provider default. | ## Local diff --git a/services/www/src/docs/content/providers.mdx b/services/www/src/docs/content/providers.mdx index b0de5785e5b..0d93bcb15b1 100644 --- a/services/www/src/docs/content/providers.mdx +++ b/services/www/src/docs/content/providers.mdx @@ -90,7 +90,7 @@ The `providers` object is keyed by the provider ID used in model references, suc | `env` | Ordered environment variable names that can provide the credential. | | `package` | Runtime provider package. | | `canonical` | Built-in provider ID whose catalog defaults this provider inherits. | -| `compatibility` | Request and response compatibility overrides for every model of this provider. Model `compatibility` overrides individual fields. `supportsThinkingBlockBinding` and `supportsEffortUpdates` are model-only. | +| `compatibility` | API quirks shared by every model of this provider. See [Compatibility](/models#compatibility). | | `settings` | Typed OpenCode controls and JSON options passed to the runtime package. | | `headers` | String-valued HTTP headers added to requests. | | `body` | JSON fields merged into request bodies. | @@ -300,7 +300,7 @@ ID sent to the provider. | `headers` | Additional string-valued request headers. | | `body` | Additional JSON request body fields. | | `capabilities` | Tool support, accepted input and output media types, temperature support, and reasoning controls. | -| `compatibility` | Request and response compatibility overrides. | +| `compatibility` | API quirks for this model, overriding the provider's. See [Compatibility](/models#compatibility). | | `variants` | Named variants with their own `settings`, `headers`, and `body`. | | `cost` | Input, output, and optional cache pricing per million tokens. | | `limit` | Context, input, and output token limits. |