Provider compat reference: OpenAI compat flags, reasoning levels, and tool handling

Reference for four subsystems of packages/ai (with type definitions in packages/catalog):

1. OpenAI compat flags — every compat field and its wire effect
2. Reasoning levels — how efforts/thinking budgets flow to each provider
3. Tool handling per provider — schema conversion, streaming, result encoding
4. Forced tool choice — toolChoice semantics, wire mapping, emulation

Related references:

• Provider endpoint constraints — where a new constraint should live
• Provider streaming internals — stream event normalization
• Provider quirks — per-provider special casings, stream behavior, auth/usage, catalog handling
• Model and Provider Configuration — models.yml and user-facing compat overrides

1. OpenAI compat flags

Architecture

Compat flags are resolved in two phases:

1. Catalog build time (packages/catalog/src/compat/openai.ts): buildOpenAICompat(spec) / buildOpenAIResponsesCompat(spec) run once per model inside buildModel. Defaults are auto-detected from provider, baseUrl, model id/name, and spec.reasoning; explicit spec.compat overrides are merged via applyCompatOverrides (packages/catalog/src/compat/apply.ts). If a whenThinking variant applies (explicit override, direct DeepSeek reasoning, OpenCode reasoning gateways), a complete alternate resolved compat object is pre-built and attached as compat.whenThinking. OpenRouter is a pseudo-API: buildOpenRouterCompat merges the full chat-completions view with the Responses-only fields into ResolvedOpenRouterCompat, so the same model object satisfies both runtime handlers (PI_OPENROUTER_RESPONSES picks the dispatch).

2. Request time (packages/ai/src/providers/openai-shared.ts): resolveOpenAICompatPolicy(model, options) combines the resolved compat with per-request options (reasoning, disableReasoning, toolChoice, …) into an OpenAICompatPolicy with reasoning, tools, messages, and stream sub-policies. When thinking is active and whenThinking exists, the policy pointer-swaps to the pre-built variant — no per-request spreading or allocation:

   const compat = enabled && baseCompat.whenThinking ? baseCompat.whenThinking : baseCompat;
   

Consumers: applyChatCompletionsCompatPolicy + buildParams in openai-completions.ts, buildResponsesInput in openai-responses.ts, message transforms in transform-messages.ts, stream watchdogs in stream.ts.

Every flag declared in packages/catalog/src/types.ts is consumed somewhere in packages/ai; there are no dead flags.

Shared flags (chat-completions + responses)

Types: OpenAICompat / ResolvedOpenAISharedCompat in packages/catalog/src/types.ts.

“Shared” means the field exists on both resolved views with the same wire contract — not that both builders detect the same default. buildOpenAICompat and buildOpenAIResponsesCompat each compute their own defaults; rows below use Chat: / Responses: where they diverge (single detection = identical on both surfaces).

Message shaping

Reasoning wire format

Tool choice / strict interaction

Sampling, tokens, caching, routing

Stream parsing / watchdogs

Chat-completions-only flags (ResolvedOpenAICompat)

Responses-only flags (ResolvedOpenAIResponsesCompat)

2. Reasoning levels

The effort model

The canonical intensity scale is the Effort enum (packages/catalog/src/effort.ts): minimal, low, medium, high, xhigh, max.

Per-model capabilities live in ThinkingConfig (packages/catalog/src/types.ts), resolved once at model build time by resolveModelThinking (packages/catalog/src/model-thinking.ts):

• mode — transport mechanism: effort (OpenAI-style), budget (token budget), google-level (enum levels), anthropic-adaptive, anthropic-budget-effort
• efforts — supported levels in canonical order
• effortMap — baked remap to upstream wire strings (e.g. xhigh → high on models without xhigh)
• effortRouting — effort (or "off") → dynamic model-id variants (resolveWireModelId picks the wire id)
• effortBudgets — pre-computed token budgets for collapsed effort tiers
• requiresEffort — thinking cannot be disabled
• suppressWhenOff — “off” must be sent explicitly on the wire (includeThoughts: false / thinkingBudget: 0), not just omitted

Runtime helpers: clampThinkingLevelForModel (clamps a requested effort to what the model supports), mapEffortToGoogleThinkingLevel, mapEffortToAnthropicAdaptiveEffort.

Per-provider wire mapping

The OpenAI-compat resolution pipeline

resolveOpenAICompatPolicy (providers/openai-shared.ts) decides per request:

1. Enabled/disabled — requested effort vs model reasoning support, minus suppression rules (disableReasoningOnForcedToolChoice, disableReasoningOnToolChoice, none-effort handling).
2. whenThinking swap — enabled + variant present → active compat becomes the pre-built variant.
3. Wire effort — requested Effort mapped through compat.reasoningEffortMap / model.thinking.effortMap; omitReasoningEffort suppresses the field while keeping the thinking toggle.
4. Disable encoding — when reasoning is off but the wire needs an explicit off-signal, encodeChatCompletionsDisabledReasoning emits the format from reasoningDisableMode.

If a host rejects the emitted effort with 400/422, resolveOpenAIReasoningEffortFallback (providers/openai-reasoning-fallback.ts) parses the error text to extract accepted values or drop the parameter, then retries.

Getting thinking back out of the stream

• Structured deltas: providers emit thinking_start / thinking_delta / thinking_end stream events.
• History replay: prior thinking is replayed via reasoningContentField on assistant messages (KV-cache preservation on DeepSeek/Z.AI/Qwen/local backends); models that demand reasoning content on tool-call turns get real content or a "." placeholder per allowsSyntheticReasoningContentForToolCalls.
• Leaked thinking healing: wrapLeakedThinkingStream (utils/leaked-thinking-stream.ts) converts in-band ` ```thinking ` / <think> fences from misbehaving hosts into structured thinking blocks live.
• Loop guard: withThinkingLoopGuard (utils/thinking-loop.ts) detects runaway reasoning (verbatim repeats, near-duplicate trigram clusters, progress-lexicon stalls) and kills the stream with a retryable AIError.Flag.ThinkingLoop.

Interactions

• Sampling clamps: models with active reasoning (Opus 4.7+, Fable/Mythos 5, o-series/GPT-5) reject explicit temperature/top_p; anthropic.ts and the compat policy (supportsSamplingParams) suppress them.
• Forced tool choice: see §4; several providers must drop thinking when a tool call is forced.

3. Tool handling per provider

All providers start from the same neutral wire schema — toolWireSchema(tool) (utils/schema/wire.ts) — and diverge in normalization, streaming shape, and result encoding.

Anthropic (providers/anthropic.ts)

• Schemas: buildAnthropicToolSchemaPlans decides strictness per tool: allowlist (ANTHROPIC_STRICT_TOOL_ALLOWLIST), no incompatible keywords (oneOf/allOf/$ref/patternProperties/propertyNames), and budget caps (MAX_ANTHROPIC_STRICT_TOOLS, optional/union parameter limits). Strict schemas get normalizeAnthropicStrictSchema (additionalProperties: false); open maps stay non-strict to preserve map semantics. Wire: { name, description, input_schema, eager_input_streaming?, strict? }.
• Streaming: content_block_start (tool_use, carries id+name) → input_json_delta fragments → parse via parseStreamingJson at content_block_stop. Envelope anomalies are logged (reportAnthropicEnvelopeAnomaly), not fatal.
• Results: user message with tool_result blocks (tool_use_id). Images embed inside tool_result.content; on error results Anthropic rejects embedded images, so text stays in the block and images are hoisted after the tool_result run. Z.AI’s Anthropic-shaped endpoint additionally needs id on the block (requiresToolResultId).
• Replay quirk: assistant turns are stably partitioned [...non_tool_use, ...tool_use] so tool_use blocks sit at the tail — otherwise Anthropic 400s with “tool_use ids were found without tool_result blocks immediately after”.
• Strict fallback: a 400 strict rejection sets providerSessionState.strictToolsDisabled and retries without strict.

OpenAI Chat Completions (providers/openai-completions.ts)

• Schemas: convertTools + adaptSchemaForStrict; strictness from toolStrictMode (all_strict / mixed / none) gated by supportsStrictMode and per-tool strict. Moonshot hosts additionally pass the MFJS subset check. Wire: { type: "function", function: { name, description, parameters, strict? } }.
• Streaming: choice.delta.tool_calls (index, id, function.name, function.arguments fragments). MiniMax streams arguments as a raw JSON object instead of a string — both shapes are merged (mergeStreamingArgumentObjects). Leaked DeepSeek template tokens are stripped per stripDeepseekSpecialTokens. finish_reason: "stop" is promoted to "tool_calls" when structured calls were seen.
• Results: { role: "tool", tool_call_id, content }; Mistral ids normalized; assistant replay sets tool_calls array and content "" (or "." under requiresAssistantContentForToolCalls). Non-vision models get image placeholders via partitionVisionContent.

OpenAI Responses (providers/openai-responses.ts)

• Schemas: sanitizeSchemaForOpenAIResponses + adaptSchemaForStrict. Supports function tools, freeform custom tools, and native computer tools (model.supportsComputerUse). Wire: flat { type: "function", name, description, parameters, strict? }.
• Streaming: response.output_item.added → response.function_call_arguments.delta / response.custom_tool_call_input.delta → response.output_item.done. Tool call ids are composite callId|itemId (normalizeResponsesToolCallId).
• Results: input items of type: "function_call_output" with call_id (the callId half of the composite). Stateful previous_response_id chaining across turns.

Google Gemini / Vertex (providers/google-shared.ts, google.ts)

• Schemas: functions wrapped in { functionDeclarations }. Gemini API/Vertex use parametersJsonSchema: normalizeSchemaForGoogle(...) (strips $schema, additionalProperties, converts type arrays to nullable); Cloud Code Assist / Antigravity / Gemini CLI use parameters: normalizeSchemaForCCA(...).
• Streaming: part.functionCall arrives with name and a complete args object (no argument-fragment streaming). Google omits call ids → synthesized via nextToolCallId(name).
• Vertex quirk: Vertex GenerateContent rejects id on functionCall/functionResponse parts; they are deleted when model.provider === "google-vertex".
• Results: user message with functionResponse parts. All parallel responses must be merged into a single contiguous user message or Google errors with “number of function response parts is not equal to number of function call parts”. Images: Gemini 3+ supports multimodal functionResponse.parts; older Gemini gets images buffered (pendingToolImageParts) and flushed as a separate user turn after the response.

Amazon Bedrock (providers/amazon-bedrock.ts)

• Schemas: convertToolSpec → { toolSpec: { name, description, inputSchema: { json } } }.
• Streaming: start.toolUse (toolUseId, name) then delta.toolUse.input fragments.
• Results: all consecutive tool results grouped into one user message with a toolResult array (Converse API requirement); images embed in the content array.
• Sentinel quirk: Converse validates that any request whose history contains toolUse/toolResult must supply a toolConfig. With no active tools (or toolChoice: "none"), planToolConfig injects NO_TOOLS_SENTINEL (__no_tools__, “do not call” description) with toolChoice: { auto: {} }; a call to the sentinel is dropped from the stream (sentinelInjected check).

Differences summary

Strict tools lifecycle

OpenAIStrictToolsState (providers/openai-shared.ts) tracks strict-mode failures per scope ${provider}:${baseUrl}:${modelId}: a 400 strict-schema rejection calls disableStrictToolsForScope, and isStrictToolsDisabledForScope makes all subsequent requests for that scope run non-strict — one retry, then remembered, no per-turn 400 tax. Anthropic has the analogous per-session strictToolsDisabled flag.

Text-based tool-call dialects (src/dialect/)

Used when native tool APIs are unavailable, or when history must be re-encoded for a different model family:

1. In-band tool calling: renderInbandToolPrompt(tools, dialect) injects the tool inventory into the prompt; InbandScanner / wrapInbandToolStream parse streamed text back into structured tool calls. Dialects: harmony, gemini, qwen3, deepseek, kimi, glm, gemma, hermes, minimax, xml, anthropic.
2. Cross-model history replay: switching models mid-session re-renders prior thinking/tool turns in the target’s preferredDialect(modelId) (renderDemotedThinking, encodeInbandToolHistory).
3. Harmony (dialect/harmony.ts): GPT-5/Codex control tokens (<|start|>, <|call|>, <|channel|>, <|return|>); utils/harmony-leak.ts escapes them when replaying through non-Harmony endpoints.
4. Healing: StreamMarkupHealing (utils/stream-markup-healing.ts) uses the same scanners to reconstruct tool calls and thinking from markup leaked into visible text by hosted models.

Edge guards

• utils/tool-call-loop-guard.ts: ToolCallLoopGuard canonicalizes arguments (sorted keys, intent stripped), hashes ${name}:${canonicalArgs}, and on repeated identical calls returns a RepeatedToolCallDetection used to steer the model out of the loop.
• utils/deterministic-id.ts: deterministicUuid(seed) (SHA-256 → UUID shape) backs ensureToolCallId wherever a provider omits or mangles wire ids (Google, Bedrock, degenerate completions).
• providers/transform-messages.ts: shared pre-flight pass — tool-call dedup, sanitization, id normalization — before provider-specific conversion.

4. Forced tool choice

Unified ToolChoice (src/types.ts)

type ToolChoice =
  | "auto" | "none" | "any" | "required"
  | { type: "function"; name: string }
  | { type: "function"; function: { name: string } }
  | { type: "tool"; name: string }
  | { type: "computer" };

• auto — model decides (default when tools are present)
• none — no tool calls this turn
• required / any — at least one tool call (OpenAI vs Anthropic spelling; interchangeable)
• named pin — call exactly this tool
• { type: "computer" } — dispatch to the native computer-use tool

toolChoice is one-shot per request inside packages/ai — no stickiness; the caller decides each turn.

Mapping utilities (src/utils/tool-choice.ts)

Per-provider wire mapping

Emulation and fallback paths

1. String-only hosts (supportsNamedToolChoice: false — LM Studio, llama.cpp, Ollama): object pins are rejected by the host, so the provider advertises only the pinned tool and sends tool_choice: "required" — with one tool offered, required is equivalent to a pin.
2. Bedrock sentinel: see §3.
3. Computer pin fallback: { type: "computer" } without native support degrades to a named function pin.
4. Stale pin pruning: a forced tool missing from the final tool list (active-tool filtering, schema quarantine) silently drops tool_choice rather than emitting an invalid request.

Interaction with reasoning

Several backends reject thinking + forced tool choice together:

• Anthropic: disableThinkingIfToolChoiceForced deletes params.thinking; adaptive-only models pin output_config.effort = "low" so default adaptive thinking doesn’t kick back in.
• Bedrock: forced any/tool clears additionalModelRequestFields (where thinking config lives).
• OpenAI compat: resolveOpenAICompatPolicy honors disableReasoningOnForcedToolChoice / disableReasoningOnToolChoice. Exception: Kimi K3 keeps reasoning effort with forced "required" (hasActiveNativeKimiK3Reasoning in openai-completions.ts).

How the agent loop drives it (packages/agent)

• Per-turn resolution: agent-loop.ts resolves config.getToolChoice() at the start of every turn:

  const effectiveToolChoice = ownedDialect ? undefined : (hostToolChoice ?? forcedToolChoice ?? config.toolChoice);
  

  When an owned in-band dialect is active, native tools are stripped, so tool_choice must be undefined (native tool_choice without native tools 400s).

• Soft requirements (SoftToolRequirement, packages/agent/src/types.ts): forcing tool_choice every turn would churn the provider prompt cache. A soft requirement ({ soft: true, toolName, reminder }) first injects the reminder text with toolChoice left at auto; only if the model fails to call toolName does the next turn escalate to a hard { type: "tool", name } for a single turn.
• Active-tool refresh: refreshToolChoiceForActiveTools (packages/agent/src/agent.ts) drops a queued forced choice whose tool is no longer in the active set.
• Compaction/handoff: run with toolChoice: "none" to keep the prompt-cache prefix while forcing text-only output; an auto-only 400 gets one retry with "auto" (packages/agent/src/compaction/compaction.ts).