@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,314 lines • 72.2 kB
text/typescript
import type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode, ThinkingDisplayPolicy } from "./wire";
import type { AccountAutoPausePolicy, AccountPauseDetails } from "./account-auto-pause";
import type { AnthropicAccountPoolConfig } from "./anthropic-account-pool";
/**
* Per-provider proactive-refresh policy. The guardian only ever touches a provider whose EFFECTIVE
* policy is "proactive"; "lazy-only" keeps today's on-demand refresh, "disabled" forbids the
* guardian entirely (used for providers whose ToS actively enforces against non-official-client
* token traffic, e.g. Anthropic subscription OAuth). See devlog 260703_oauth-multi-account-refresh-and-tos.
*/
export type RefreshPolicy = "proactive" | "lazy-only" | "disabled";
/**
* Per-provider conversation affinity to the credential that served a conversation's
* last turn, so that credential's upstream prompt cache is read again instead of
* rebuilt on another key. `auto` keeps a binding only while the cache it built is
* measured to be worth keeping and still warm; `session` keeps it while the
* credential stays eligible; `turn` only across immediate continuations; `off`
* disables binding entirely. See src/providers/cache-affinity.ts.
*/
export type CacheAffinityMode = "auto" | "session" | "turn" | "off";
/** Provider cache-affinity outcome recorded on a request-log row. */
export type CacheAffinityOutcome = "kept" | "bound" | "released";
/** Why that outcome happened; mirrors the store's keep reasons plus lifecycle outcomes. */
export type CacheAffinityLogReason = "cache" | "session" | "turn" | "continuation" | "new" | "quota" | "auth";
/** Request-owned identity of the configured key, before env/keychain resolution. */
export interface ProviderApiKeySelection {
entryId?: string;
reference?: string;
revision?: string;
/** Request-local allocation; does not replace the saved active key. */
distributed?: boolean;
/** Request-local cache-affinity pick; survives selection re-reads while its entry stays live. */
cacheAffinity?: boolean;
/** Opaque process-local credential and destination generation for an affinity pick. */
cacheAffinityGeneration?: string;
}
export interface OpenRouterProviderRouting {
/** OpenRouter provider slugs to try first, in priority order. */
order?: string[];
/** Restrict routing to these OpenRouter provider slugs. */
only?: string[];
/** Whether OpenRouter may use providers outside `order`. Defaults to OpenRouter's policy. */
allowFallbacks?: boolean;
}
export interface VercelGatewayRouting {
/** Vercel AI Gateway provider slugs to try first, in priority order. */
order?: string[];
/** Restrict routing to these Vercel AI Gateway provider slugs. */
only?: string[];
/** Sort providers by "cost", "ttft", or "tps". */
sort?: "cost" | "ttft" | "tps";
}
export interface ResponsesItemIdRepairConfig {
/** Exact `message` item ids that the proxy should rewrite to request-local canonical ids. */
message?: string[];
/** Exact `reasoning` item ids that the proxy should rewrite to request-local canonical ids. */
reasoning?: string[];
/** Backfill missing `output_item.done` / terminal snapshot ids from the matching output_index. */
repairMissingTerminalIds?: boolean;
/**
* Treat existing message/reasoning ids without the canonical `msg_`/`rs_` prefix (e.g. bare
* UUIDs from DeepSeek's Responses route) as invalid and mint canonical replacements (#938).
* function_call ids and call_id pairing are never rewritten.
*/
repairInvalidIds?: boolean;
}
/**
* Opt-in retry for pre-stream transient upstream statuses (500/502/503/504/520/521/522) on
* `providers.<name>.transientRetryOn5xx`.
*
* An object opts in for supported key-auth adapters. Canonical ChatGPT forward auth
* requires an explicit send total. Separate from `retryOn429`, which handles rate limiting.
*/
export interface TransientRetryPolicy {
/** Master switch for a qualifying policy (default true). */
enabled?: boolean;
/**
* Total upstream sends allowed for one request, including the first (1..10, key-auth default 3).
*
* Not a per-layer retry count: the connection-reset and transient-status recovery layers
* share this single budget, so `3` means at most three real requests reach the provider.
*/
attempts?: number;
}
/**
* Opt-in replacement of a Responses send whose upstream connection closed while the
* caller had observed nothing (`providers.<name>.retryOnReset`).
*
* Native Responses covers pre-header resets and post-header SSE carrying only control events.
* Generic translated dispatch covers initial and rebuilt pre-header sends, sharing the same
* grant and send budget; adapter-owned transports and translated post-header failures are excluded.
* Disabled unless present; `{}` opts in. Only self-contained requests qualify (see
* `src/server/responses/reset-replay.ts`). Replacement inference may still be billed if the
* origin had already started the first one, so this is opt-in rather than default.
*/
export interface ResetReplayPolicy {
/** Master switch. Presence of the object also enables the policy (default true). */
enabled?: boolean;
/**
* Replacement sends one LOGICAL request may make, across every leg and every combo child
* (1..2, default 1).
*
* Not a per-leg retry count and not a send budget. A request that resets before the head and
* again after it draws on this one number, and each replacement still has to fit inside the
* send allowance the leg already had.
*/
replacements?: number;
}
/**
* Same-target 429 wait-and-retry policy (`providers.<name>.retryOn429`). When present and not
* explicitly disabled, the proxy waits and replays the identical request on the same key before
* any key failover. All fields optional; the runtime applies defaults (attempts=3,
* intervalMs=5000, maxIntervalMs=60000, respectRetryAfter=true, enabled=true).
*/
export interface RateLimitRetryPolicy {
/** Master switch. The presence of the object also enables the policy (default true). */
enabled?: boolean;
/** Extra replay attempts after the first 429 (1..20, default 3). */
attempts?: number;
/** Fixed wait between attempts when the upstream sends no usable Retry-After (default 5000). */
intervalMs?: number;
/** Cap for any single wait, including an upstream Retry-After (default 60000). */
maxIntervalMs?: number;
/** Prefer the upstream Retry-After header when present and parseable (default true). */
respectRetryAfter?: boolean;
}
/**
* Backend ids admitted by `providers.<name>.webSearchBridge.backend`. Each id is explicit-only:
* an omitted backend keeps the bridge disarmed rather than silently falling back to a paid
* Luna or Exa search. `ollama` spends this provider's API key on the search endpoint.
* `openai` / `anthropic` / `xai` / `gemini` / `exa` reuse the matching sidecar executor and
* that executor's own credential; a missing credential leaves the bridge disarmed.
*/
export const PROVIDER_WEB_SEARCH_BRIDGE_BACKENDS = [
"ollama",
"openai",
"anthropic",
"xai",
"gemini",
"exa",
] as const;
export type ProviderWebSearchBridgeBackend = typeof PROVIDER_WEB_SEARCH_BRIDGE_BACKENDS[number];
/**
* Opt-in hosted-web-search bridge for a KEY-auth Responses passthrough provider
* (`providers.<name>.webSearchBridge`), default OFF (#3761).
*
* Codex always declares the hosted `{type:"web_search"}` tool. On the passthrough the proxy
* treats that as "the destination runs search itself" and relays it unchanged, which is true for
* the ChatGPT backend and for xAI but false for an OpenAI-shaped key gateway such as Ollama
* Cloud: the model answers with a `function_call` named `web_search` that nothing executes,
* and the undeclared-tool guard ends the turn. With this block enabled the proxy intercepts that
* call, runs the configured search backend itself, feeds the result back upstream, and shows
* Codex a hosted `web_search_call` cell.
*
* Never armed for `authMode: "forward"` (ChatGPT) or for a provider that executes hosted search
* upstream; see `planPassthroughWebSearchBridge` in `src/web-search/passthrough-bridge.ts`.
* A mixed `web_search` + client tool call still fails closed. Assistant text is not a search call.
*/
export interface ProviderWebSearchBridgeConfig {
/** Master switch. Absent or false keeps today's relay-and-fail behavior exactly. */
enabled?: boolean;
/** Which executor runs the search. Absent disarms the bridge; there is no implicit default. */
backend?: ProviderWebSearchBridgeBackend;
/** Searches executed per turn before the bridge refuses further ones (1..10, default 3). */
maxSearches?: number;
/** Per-search deadline in milliseconds (1000..600000, default 60000). */
timeoutMs?: number;
/**
* Absolute search-API URL. Required to use the `ollama` backend against anything other than
* the canonical `https://ollama.com` origin, which is the only origin derived automatically.
* The bridge sends the PROVIDER's own API key to this URL, so an operator setting it is
* authorizing that key for this destination.
*/
endpoint?: string;
}
/** Optional user-owned prompt-length policy; rates are USD per 1M tokens. */
export type PromptLengthPricing =
| { mode: "automatic" }
| { mode: "flat" }
| {
mode: "custom";
thresholdTokens: number;
comparison: "gt" | "gte";
rates: { input: number; output: number; cacheRead: number; cacheWrite: number };
};
/** Complete base rates for one model, with automatic pricing when policy is absent. */
export interface ProviderCostOverlay {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
/** Absent means automatic vendor prompt-length pricing. */
promptLengthPricing?: PromptLengthPricing;
}
export interface RequestPacingRule {
/** Evenly spread request starts to this many requests per minute. */
requestsPerMinute?: number;
/** Minimum delay between request starts. The slower configured value wins. */
minIntervalMs?: number;
/** Maximum number of requests concurrently in flight. */
maxConcurrentRequests?: number;
}
export interface ProviderRequestPacingConfig extends RequestPacingRule {
/** False preserves legacy behavior with no client-side waiting. */
enabled: boolean;
/** Exact upstream model-id overrides; other models inherit the provider rule. */
models?: Record<string, RequestPacingRule>;
/** Normal request allocation, separate from cooldown recovery ordering. */
keySelection?: "active" | "round-robin";
/** Additional uniform limits per pool credential, across all models. */
keys?: RequestPacingRule;
}
export interface FastWire {
/**
* How the provider expresses Fast on the wire. `service-tier` is OpenAI's
* `service_tier` request field; `cursor-variant` is a MODEL-VARIANT switch, because
* Cursor has no tier field — its fast product is a different model id
* (`claude-opus-5-thinking-high-fast`) or a `{id:"fast"}` request parameter for Grok.
* `model-variant` is internal only (config validation rejects it): the xAI OAuth Fast lane switch in
* src/providers/xai-fast-model.ts, whose only wire value is the serialized model id.
*/
kind: "service-tier" | "anthropic-speed" | "cursor-variant" | "model-variant";
/** Canonical tier name to upstream wire spelling. */
canonicalToWire: Readonly<Record<string, string>>;
/** Policy for non-canonical caller-provided tier values. */
foreignCallerTiers: "verbatim" | "drop";
/** Anthropic speed headers/betas reserved for the later wire implementation. */
betas?: readonly string[];
}
/** Durable per-attempt service-tier fact produced at the adapter serialization boundary. */
export interface AttemptTierOutcome {
canonical?: "priority";
wireKind?: FastWire["kind"] | null;
wireValue?: string | null;
fastOutcome: "not-requested" | "applied" | "downgraded" | "unknown";
fastDowngradeReason?: "route-unsupported" | "wire-unavailable" | "response-declined";
callerTierDropped?: boolean;
callerFastSuppressedByConfig?: boolean;
confirmation: "confirmed" | "assumed" | "downgraded" | "unknown";
responseServiceTier?: string;
/** False retains the raw echo as evidence only, including during cost estimation. */
responseTierAuthoritative?: boolean;
}
/**
* Request-local observation inputs captured before the final tier action mutates the parsed view.
* This is not persisted; the final adapter turns it into AttemptTierOutcome after serialization.
*/
export interface TierObservationContext {
capability: boolean | undefined;
eligibility:
| "eligible"
| "capability-unsupported"
| "unclassified"
| "wire-unavailable"
| "pin-unavailable";
fastWire: FastWire | null;
demandDecision: "force-fast" | "force-default" | "inherit";
callerTier?: string;
/**
* Whether the destination's echoed `service_tier` is authoritative about Fast scheduling.
*
* The ChatGPT-internal Codex backend returns `service_tier: "default"` on turns that were in
* fact scheduled as priority, so treating its echo as a downgrade produced a false
* `response-declined` on every Fast request (#2558). Absent means "assume authoritative",
* preserving the behaviour for the public API where the echo does mean what it says.
*/
responseTierAuthoritative?: boolean;
/**
* Set when the upstream refused the fast wire earlier in this request and the proxy resent at
* standard speed (Anthropic `speed: "fast"` without entitlement). The resend's outcome is then
* a `response-declined` downgrade rather than an unavailable wire.
*/
upstreamDeclinedFast?: boolean;
}
export type TierDecision =
| { readonly kind: "forward-caller" }
| { readonly kind: "drop" }
| { readonly kind: "set"; readonly value: string };
/** Independent reasoning axes. Absence means unknown, not an explicit denial. */
export interface ReasoningCapabilities {
supportsReasoning?: boolean;
supportsThinkingToggle?: boolean;
supportsReasoningEffort?: boolean;
defaultThinkingEnabled?: boolean;
}
/** Explicit per-model operator declarations; absent axes keep legacy behavior. */
export interface ModelCapabilities extends ReasoningCapabilities {
inputModalities?: Array<"text" | "image" | "audio" | "video">;
/** Requested tier only; does not imply an upstream window or activate an unverified wire. */
contextTier?: "default" | "long_context";
video?: { processing?: "static" | "agentic" };
/** Opt in exact first-party DeepSeek models to one-hour image file persistence. */
deepseekImageFiles?: boolean;
/** Images a first-party Mistral Chat request may carry for this model; older ones are pruned. */
mistralMaxImages?: number;
/** Exact-model Responses custom-tool support; absent inherits the provider contract. */
responsesCustomTools?: boolean;
}
/**
* One configured provider entry. `authMode` (default `"key"`) decides whether same-target 429
* retries are allowed; OAuth/forward credentials and local runtimes are never replayed.
*/
export interface OcxProviderConfig {
/** Explicit builtin Pool 2 provenance; endpoints never imply ownership. */
anthropicOAuthInstance?: "anthropic2";
/** Independent Anthropic pool settings; valid only on providers.anthropic2. */
anthropicAccountPool?: AnthropicAccountPoolConfig;
/** Optional browser-compatible outbound TLS profile; disabled by default. */
tlsProfile?: "antigravity-browser";
/** Optional short provider namespace used only at request/catalog presentation time. */
alias?: string;
/** Native model id -> short, slash-free request alias. */
modelAliases?: Record<string, string>;
/**
* Opt-in alias template for models without a manual or built-in alias (#7705), for example
* `{providerAlias}-{modelBasename}`. Derived at resolution time and never written back; only the
* literal `{providerAlias}` and `{modelBasename}` placeholders are allowed.
*/
aliasTemplate?: string;
/** Display-only labels for exact native model ids discovered under this provider. */
modelDisplayNames?: Record<string, string>;
/** Override the global built-in model-alias switch for this provider. */
defaultAliases?: boolean;
adapter: string;
/**
* Codex tool calling mode for routed models.
* "code_mode_only" (default) sets entry.tool_mode = "code_mode_only" (unified exec helper tool).
* "shell" leaves tool_mode unset so Codex declares top-level shell tools (exec_command).
*/
codexToolMode?: "code_mode_only" | "shell";
/** Optional outbound request-start pacing shared by this provider and its model overrides. */
requestPacing?: ProviderRequestPacingConfig;
/**
* Per-provider override of the global `connectTimeoutMs` (response-header arrival deadline) for
* routed HTTP adapter sends, including routed model sends in the image/video and web-search
* bridges. A runTurn owns its transport and uses adapter-specific deadlines.
* A positive value applies verbatim, `0` disables the header deadline on covered paths,
* and an omitted value inherits the global setting.
*/
connectTimeoutMs?: number;
/**
* Per-provider override of the global `stallTimeoutSec` for routed HTTP responses, streaming runTurn
* delivery, and inactivity in the image/video bridge. A positive value sets the inactivity budget,
* `0` disables it on covered paths, and an omitted value inherits the global setting.
* The web-search plan also uses the setting to size its independent bridge watchdog.
*/
stallTimeoutSec?: number;
/** Cursor MCP compatibility bounds; positive integers when configured. */
mcpMaxTools?: number;
mcpMaxSchemaBytes?: number;
mcpMaxResultBytes?: number;
/**
* Per-model wire override, keyed by the upstream native model id (after namespace
* and combo resolution). A single gateway can front models that speak different
* wires — Grok needs the Responses API for hosted web_search while a sibling model
* is fine on chat completions (#404).
*
* Only OpenAI-shaped wires may be selected; see MODEL_ADAPTER_OVERRIDE_ALLOWED.
* Absent or empty means the provider-wide `adapter` applies to everything, exactly
* as before.
*/
modelAdapters?: Record<string, string>;
/**
* Fast-wire declaration. `null` explicitly disables adapter-derived defaults;
* absence derives from the final model adapter.
*/
fastWire?: FastWire | null;
/**
* Whether echoed service_tier can confirm or deny Fast. Set false for a relay whose
* response metadata cannot establish the granted tier. Absence keeps legacy authority;
* canonical ChatGPT Codex forwarding always treats the echo as non-authoritative.
* Observation only: this does not enable Fast or change request serialization.
*/
responseTierAuthoritative?: boolean;
baseUrl: string;
/**
* Optional relative resource path for key-auth openai-responses requests. Must start with `/`
* and must not include a URL scheme, query string, or fragment. When omitted, the adapter keeps
* the legacy `/v1/responses` construction.
*/
responsesPath?: string;
/**
* Optional relative send path for the `openai-chat` wire, mirroring `responsesPath`.
* Same shape rules: must start with `/`, no URL scheme, query string, or fragment.
* When omitted the adapter keeps `openaiChatCompletionsUrl(baseUrl)`.
*
* This exists because a per-model wire override swaps `adapter` and leaves `baseUrl`
* alone, so an upstream that serves Chat Completions and Responses under different
* path prefixes cannot be reached by the adapter swap by itself. Z.AI is that case:
* `/api/v1/responses` and `/api/coding/paas/v4/chat/completions` on one host and one key.
*/
chatCompletionsPath?: string;
/**
* Command Code protocol version sent as `x-command-code-version` on /alpha/generate requests.
* The internal endpoint's schema drifts with the CLI version; operators can pin a known-good
* version here instead of waiting for a code change. Absent uses the adapter's current default.
*/
commandCodeVersion?: string;
/** Include bounded repository context in Command Code envelopes. Default omitted/off sends empty memory/taste/skills. */
projectContext?: "off" | "on";
/**
* Responses upstream that stores nothing server-side (DeepSeek documents "the API
* is stateless"). Stateful request parameters are dropped, `store` is pinned false,
* and missing local continuation history returns previous_response_not_found so
* clients can resend full input. Explicit input still receives orphan-item repair.
*/
statelessResponses?: boolean;
/**
* Responses upstream whose parser requires an unambiguous call batch and its matched
* result batch to remain contiguous. Hook-injected context that splits the batch is
* preserved after it, and parallel calls stay together with the reasoning turn that produced them.
*/
requiresAdjacentResponsesToolResults?: boolean;
/**
* Responses upstream whose parser also rejects a tool call that has no matching output
* anywhere in the replayed input, not merely one whose result sits out of order. A call left
* dangling by an interrupted stream is answered with an explicit unknown-status placeholder
* so the thread can continue.
*
* Separate from `requiresAdjacentResponsesToolResults` on purpose: adjacency reorders items a
* strict parser already accepts in some order, while this synthesizes an item the client never
* sent. Kimi accepts a dangling call (#4726), so it must not inherit the synthesis.
* `statelessResponses` implies this, because an upstream that stores nothing cannot resolve
* the missing half from its own history either.
*/
requiresPairedResponsesToolResults?: boolean;
/**
* When enabled, a tool result that is present but empty (no usable text or content
* part) is rewritten to an explicit annotation before it reaches the upstream wire,
* so models do not silently accept an empty result or re-issue the same call.
* Non-empty results and missing-result placeholders stay byte-identical.
* Seeded true for DeepSeek; absent keeps legacy behavior for every other provider.
* Only the OpenAI-family adapters (openai-chat / openai-responses) read this option;
* other adapters ignore it.
*/
annotateEmptyToolOutputs?: boolean;
/**
* Provider fallback for canonical Fast capability over an OpenAI `service_tier` wire.
* This pure tri-state feeds catalog publication, routing eligibility, compatibility
* fingerprints, and proxy-owned canonical Fast injection on both Responses and Chat routes.
* Tri-state: `true` lets fast mode inject/remove the canonical field; `false` strips it and
* never injects, because an upstream documented as not supporting the parameter
* must not receive it; absent (`undefined`) leaves the provider unclassified — fast mode never
* injects or translates, and caller values pass only under the final wire's forwarding permission.
* On Chat, that CallerTierForward permission is `chatServiceTier`; Responses retains passthrough.
* An explicit config value always wins over the registry default.
*/
supportsServiceTier?: boolean;
/**
* Operator switch for the provider's Fast lane. `false` turns Fast off (no Fast toggle, no
* `--fast` row, no fast wire field) and overrides `supportsServiceTier`; `true` enables a lane the
* registry marks opt-in (Anthropic fast mode, which draws usage credits at 2x price). Absent keeps
* the registry default: off for opt-in entries, unchanged elsewhere.
*/
fastEnabled?: boolean;
/** Exact upstream model ids that override the provider-level service-tier capability. */
modelSupportsServiceTier?: Record<string, boolean>;
/**
* Whether to promote Codex Desktop's `additional_tools` input items into top-level `tools`
* and strip the wrapper from `input`. Enabled automatically for OpenCode Go and xAI
* (`api.x.ai` and `cli-chat-proxy.grok.com`) except on forward-auth routes, which need an
* explicit `true`; other strict gateways that return HTTP 422 for unknown item types in
* `input` can opt in here.
*/
promoteAdditionalTools?: boolean;
/**
* Responses upstream whose native contract accepts plaintext reasoning replay
* (DeepSeek documents reasoning items with plaintext content). When set, the
* passthrough serializer keeps `reasoning_text` content on replayed reasoning
* items instead of blanking it the way the ChatGPT backend requires; proxy-minted
* `ocxr1` envelopes are still stripped because no upstream can decrypt them.
*/
preserveResponsesReasoningContent?: boolean;
/**
* Whether to preserve Codex-private `input[].id` on `store: false` requests.
* Disabled by default: ordinary Responses upstreams interpret input IDs as references
* to nonexistent stored items and return 404. Upstream launcher relays such as
* Codex Web GPT (`chatgpt-web/*`) require the current-turn user message ID for
* browser-session replay (#6220).
*/
preserveResponsesInputItemIds?: boolean;
/**
* Whether to preserve ChatGPT-internal `internal_chat_message_metadata_passthrough`
* on outgoing input messages for noncanonical destinations. Disabled by default:
* public Responses gateways reject the private field as an unknown parameter.
* Upstream launcher relays such as Codex Web GPT require this metadata (or the item ID)
* to extract turn provenance (#6220).
*/
preserveResponsesMessageMetadata?: boolean;
/**
* Opt in to lossy hosted-search history notes on canonical Codex Lite ordinary turns and
* native v2 compaction triggers, even when search is declared. Default off; only literal true
* enables it. History without a search declaration is always projected, independent of this.
*/
projectResponsesLiteHostedSearchHistory?: boolean;
/**
* Treat this provider's `modelReasoningEfforts` as authoritative at the wire, not only in the
* catalog. Adapters that ship their own per-model effort table (currently `command-code`)
* otherwise let that table win for models it knows, so a widened row is advertised in the
* picker and then stripped on the way out. Opt-in because presets are SEEDED with the shipped
* table: without a declared flag there is no way to tell an operator's row from a copy an
* older release persisted. A rung the upstream then refuses is returned as that error rather
* than silently retried without the effort, since the operator asked for it.
*/
modelReasoningEffortsAuthoritative?: boolean;
/**
* Drop replayed Responses `reasoning` items from input history before forwarding.
* Some OpenAI-compatible Responses upstreams accept tool-call replay but reject
* reasoning output items when they are sent back on a continuation.
*/
dropResponsesReasoningItems?: boolean;
/** Exact Ark Kimi endpoint IDs requiring the narrow stateless Responses replay projection. */
arkKimiResponsesModels?: string[];
/**
* Explicit opt-in for a relay that genuinely fronts OpenAI and can decode native
* compaction blobs. Absent or false degrades foreign blobs to an opaque note.
*/
decodesNativeCompactionBlobs?: boolean;
/** Accept native Responses v2 `input` compaction_trigger items. Responses adapter only. */
supportsNativeCompactionTrigger?: boolean;
/** Serve native Responses v1 /responses/compact. Responses adapter only; no auth authority. */
supportsNativeCompactEndpoint?: boolean;
/**
* Trust this direct key-auth Responses provider to consume or relay opaque encrypted
* V2 agent tasks. OpenCodex does not decrypt, translate, or recover an eligible task.
* Absent or false keeps the existing recovery/fail-closed behavior.
*/
allowEncryptedV2AgentTasks?: boolean;
/**
* Explicit opt-in for non-registry private-network destinations such as localhost, RFC1918,
* link-local, or unique-local upstreams. Metadata endpoints remain blocked.
*/
allowPrivateNetwork?: boolean;
/**
* Outbound egress for THIS provider, overriding the process-wide `proxy` decision.
*
* The global `proxy` is one value for every upstream, so it cannot express the split
* operators actually need: reach one gateway through a regional proxy while another stays
* direct on the local network (#2894). Accepted values:
*
* - absent — inherit the global proxy decision. Unchanged behaviour.
* - `"direct"` or `null` — never use the global proxy for this provider.
* - `"http://…"` / `"https://…"` — this provider's own HTTP(S) proxy.
* - `"socks5://…"` / `"socks5h://…"` — this provider's own SOCKS5 proxy.
*
* An empty string is rejected rather than read as DIRECT: a cleared dashboard field must not
* silently switch a provider from inheriting the global proxy to refusing it. A malformed
* value is rejected at configuration time and again at request time; it never degrades to
* either neighbour, because both degradations look like success at the call site.
*
* Not every transport can carry this. `structure/transports/inventory.md` records which
* request paths honour it and which still follow the process-wide value only.
*/
proxy?: string | null;
/**
* Destinations this provider reaches without a proxy, in `NO_PROXY` syntax.
*
* Applied to whichever route `proxy` resolved to, so it carves an exemption out of this
* provider's own proxy AND out of an inherited global one. That second case is how a
* provider exempts a single host without owning a proxy of its own.
*/
noProxy?: string | string[];
/**
* Pin the HTTP version used for upstream provider requests. Bun's fetch negotiates
* HTTP/2 via TLS ALPN by default; some Cloudflare-fronted SSE endpoints hang on
* HTTP/2 streaming responses (issue #1668). "http1.1" / "h1" forces HTTP/1.1,
* "http2" / "h2" forces HTTP/2. Absent or "auto" keeps Bun's default negotiation
* (current behavior unchanged). Only meaningful for https: base URLs.
*/
upstreamHttpVersion?: UpstreamHttpVersion;
/**
* Opt-in upstream Responses WebSocket transport for `openai-responses` requests. When true,
* streaming POST turns use the configured Responses path (default `/v1/responses`): forward
* providers use `{baseUrl}/responses`, while key-auth providers use `responsesPath` or the
* legacy `/v1/responses` fallback. HTTPS providers use wss and are re-encoded to SSE; HTTP
* providers continue using SSE, and `openai-chat` requests stay on HTTP. On a custom provider this
* opt-in is honored only for the first-party `https://api.openai.com/v1` upstream; every other
* endpoint stays on bounded HTTP/SSE. On the canonical ChatGPT `openai` provider the field
* selects the transport instead of opting in: omitted keeps the upstream WebSocket for eligible
* turns, an explicit `false` sends streaming turns over HTTP/SSE, and provider management rejects `true`. Either
* way it is independent of the client-facing `websockets` setting and changes neither the
* endpoint nor the credential; with `false`, native mid-turn steering and injection are
* unavailable.
*/
upstreamWebsocket?: boolean;
/**
* Google only. When `false`, the AI Studio (direct) path sends Gemini Flash ids
* unchanged to the wire instead of applying the `-tiered` suffix (`gemini-3.7-flash`
* -> `gemini-3.7-flash-tiered`). Set this to `false` when the configured upstream still
* serves the bare ids. Absent (default) keeps the rename.
*/
directGeminiWireRenames?: boolean;
/** Keep provider settings on disk but exclude it from routing and model/catalog listings. */
disabled?: boolean;
/**
* Codex account-selection mode. Valid ONLY on the canonical built-in `openai` forward provider.
* "pool" (default) rotates main + added Codex accounts through the affinity/quota/cooldown/
* failover engine; "direct" pins the caller's main Codex login and never touches pool state.
*/
codexAccountMode?: CodexAccountMode;
apiKey?: string;
/**
* Key-auth header style for Anthropic-compatible providers.
* Defaults to the native Anthropic `x-api-key`; gateways may require
* `Authorization: Bearer <key>` instead.
*/
apiKeyTransport?: "x-api-key" | "bearer";
/** Opt-in translated OAuth compatibility: move caller system instructions to user content,
* losing system-role precedence. Default false; API-key and native passthrough are unchanged. */
anthropicOAuthUserInstructions?: boolean;
/**
* Multi-key pool (API-key twin of OAuth multiauth). `apiKey` always mirrors the ACTIVE
* entry so routing stays single-key; managed via /api/providers/keys. A legacy bare
* `apiKey` seeds a one-entry pool on first management touch.
*/
apiKeyPool?: Array<{ id: string; key: string; label?: string; addedAt?: number; disabled?: boolean; pauseDetails?: AccountPauseDetails; pauseRevision?: string }>;
/**
* Permanent account refusal policy. Explicit opt-in; with no key at all, a Cloud Code Assist
* provider still pauses on the first Terms of Service account ban (see `effectiveAccountAutoPause`).
*/
accountAutoPause?: AccountAutoPausePolicy;
/**
* Optional proactive ordering for `apiKeyPool` when the committed key is already
* cooling. Deliberately NOT named like the OAuth `accountPoolStrategy`: an API key
* is a different identity from an OAuth account set, and key rotation is a
* rate-limit scheduling problem rather than a prompt-cache one.
*
* Absent means today's behaviour: no pre-dispatch pick at all, only the reactive
* 429/401 walk in `key-failover`.
*/
apiKeyPoolStrategy?: "round-robin" | "fill-first" | "quota";
/** Changes on manual selection (including re-selection) and committed automatic allocation. */
apiKeySelectionRevision?: string;
/** Runtime only. Never expose in management responses or persist a routed provider. */
_apiKeyAttempt?: ProviderApiKeySelection;
defaultModel?: string;
models?: string[];
/**
* Fetch the provider's live `/models` endpoint. Defaults to true.
* Set false when `models` is an intentional allowlist or a provider's live catalog is too large
* or too flaky for startup/catalog sync.
*/
liveModels?: boolean;
/**
* Per-provider live-discovery compatibility (#7910). `skipInvalidRows: true` skips individual
* `/models` rows whose id is missing, non-string, empty or otherwise invalid (and non-object
* rows) instead of rejecting the whole listing; a listing with no surviving row stays malformed.
* Absent or false keeps strict discovery. Unrelated to the top-level `OcxConfig.modelDiscovery`,
* which is persisted discovery state rather than provider configuration.
*/
modelDiscovery?: { skipInvalidRows?: boolean };
/**
* Per-provider catalog allowlist. When non-empty, ONLY these model ids are emitted to Codex's
* catalog and `/v1/models` — live discovery still runs, this just narrows what ships (so a proxy
* exposing thousands of models, or an aggregator like OpenRouter, doesn't bloat the catalog).
* Empty/undefined = expose all. The admin `/api/models` list is unaffected (it always shows the
* full set so the user can pick). See devlog issue_052_provider-model-allowlist.
*/
selectedModels?: string[];
/** Registration-owned state. Absent means legacy or OAuth-exempt, not uninitialized. */
initialModelSelection?: {
version: 1;
registrationId: string;
status: "pending" | "ready" | "all-off";
modelCount?: number;
};
/**
* Per-provider retention allowlist for authoritative live discovery. When non-empty, any
* model id in this list is preserved in the routed catalog even if the live `/models`
* endpoint omits it (ad-hoc / private providers whose live discovery drops callable ids).
* Mirrors the built-in `kimi`/`xai` compatibility tables — opt-in for every other provider.
* Ids listed here need not be repeated in `models`: discovery folds them into the configured
* seed, so they exist under `liveModels: false` too. `selectedModels` still narrows what is
* visible. Empty/undefined = no opt-in (default behavior). See #1690.
*/
retainModels?: string[];
/**
* Override for newly discovered models. Absent/"inherit" uses the install policy. `admit`
* appends arrivals to a custom `selectedModels` (never a preset-derived one).
*/
newModelPolicy?: "on" | "off" | "admit" | "inherit";
/**
* Model-preset marker for `selectedModels` (#2465). Absent means "all", exactly today's
* semantics — an existing provider is never narrowed by an upgrade.
*
* The preset is a SEED, not a lock: `selectedModels` holds concrete ids materialized from
* the shipped rules, so every existing consumer and older binaries keep working against a
* plain allowlist. Divergence is detected at the WRITE path rather than by diffing — any user
* edit while the mode is "preset" flips it to "custom", after which the proxy never
* re-materializes. That collapses upgrade reconciliation to a version compare.
*
* Deliberately distinct from `deriveProviderPresets`, which curates WHICH PROVIDERS to offer.
* This curates which MODELS a provider exposes; the code says "model preset" throughout.
*/
modelPreset?: {
mode: "preset" | "all" | "custom";
/** MODEL_PRESETS version materialized into `selectedModels`. */
appliedVersion?: number;
appliedAt?: string;
/**
* Set when materialization matched nothing and the provider fell back to "all". A preset
* must never write an empty allowlist, because empty means ALL and would silently
* un-curate; the fallback marker lets the next convergence retry.
*/
fallback?: "preset-empty";
};
/** Provider-wide fallback when context metadata is absent; otherwise caps the reported window. */
contextWindow?: number;
/** Per-model fallback when context metadata is absent; otherwise caps the reported window. */
modelContextWindows?: Record<string, number>;
/**
* Custom providers only, default off: fill a missing context window from bundled model-ID
* metadata before the Context cap / 128k fallback. An estimate, not verified relay capacity.
*/
inferContextWindow?: boolean;
/** Per-model Copilot upstream tier; only the github-copilot route sends it. */
modelContextTiers?: Record<string, "default" | "long_context">;
/** Model-specific Codex catalog input modalities, e.g. ["text"] or ["text", "image"]. */
modelInputModalities?: Record<string, string[]>;
/**
* Provider-wide input modalities, applied to models `modelInputModalities` does not enumerate
* (a live-discovered id, for example). The registry's value is applied at runtime only, for the
* preset's own destination, and never persisted; a per-model declaration still wins.
*/
inputModalities?: string[];
modelCapabilities?: Record<string, ModelCapabilities>;
/** Model-specific max input token limits. Values cap auto_compact_token_limit. */
modelMaxInputTokens?: Record<string, number>;
/**
* Per-model soft compaction budgets. Values may only lower the effective
* context/max-input envelope; they never raise hard admission limits.
*/
modelAutoCompactTokenLimits?: Record<string, number>;
/**
* Provider-wide fallback for chat-completions `max_tokens` when the caller omits
* Responses `max_output_tokens`. Adapters still let an explicit request win.
*/
defaultMaxOutputTokens?: number;
/** Opt-in Azure Responses floor for explicit positive output budgets; may raise the caller cap. */
minMaxOutputTokens?: number;
/** Model-specific fallback output token budgets. Exact/model-pattern entries beat the provider default. */
modelMaxOutputTokens?: Record<string, number>;
/**
* Per-model display prices (USD per 1M tokens) keyed by exact model id —
* opencode-style per-model pricing in ocx's flat `modelXxx` convention:
* `{ "deepseek-v4-flash": { "input": 0.14, "output": 0.28, "cacheRead": 0.0028, "cacheWrite": 0 } }`.
* User-configured prices win over the built-in jawcode/expected catalogs in
* the Logs `~$` estimate. Display-time estimation only; never billing. An
* all-zero entry means "not billable here" and falls through to the catalogs.
*/
modelCosts?: Record<string, ProviderCostOverlay>;
/**
* USD per provider credit (for example Kiro credits). For a model with a matched token price
* and a valid `providerCredits` reading, the estimate uses credits × this price.
*/
creditPriceUsd?: number;
/**
* Provider-wide auto-review (approval) model for routed models of this provider.
*
* The value is a catalog selector: either a bare model id of this provider
* (for example `deepseek-v4-flash`) or a full public slug (for example
* `opencode-go/deepseek-v4-flash`). During catalog synchronization the
* selector is resolved against the final catalog and stamped as
* `auto_review_model_override` on each routed row of this provider that has
* no per-model override. The root Codex `auto_review_model` remains the
* fallback for every row without a provider stamp. Null or blank clears the
* provider-wide stamp; see `autoReviewModelOverrides` for per-model targets.
*/
autoReviewModel?: string;
/**
* Per-model auto-review (approval) overrides for routed models of this
* provider. Keys are exact upstream model ids under this provider (either
* spelling of a slash-containing id is accepted). Each value is a catalog
* selector with the same meaning as `autoReviewModel`; an entry wins over
* the provider-wide value for its model. Null or blank entries remove the
* model from the map while preserving other entries.
*/
autoReviewModelOverrides?: Record<string, string>;
headers?: Record<string, string>;
/** Inbound client metadata headers to copy to this provider when the outbound field is otherwise unset. */
forwardClientHeaders?: string[];
/** Default provider-routing preferences for models sent through the canonical OpenRouter API. */
openRouterRouting?: OpenRouterProviderRouting;
/** Exact model-id overrides for `openRouterRouting`. Each matching entry replaces the default. */
modelOpenRouterRouting?: Record<string, OpenRouterProviderRouting>;
/** Default provider-routing preferences for models sent through Vercel AI Gateway (issue #1406). */
vercelGatewayRouting?: VercelGatewayRouting;
/** Exact model-id overrides for `vercelGatewayRouting`. Each matching entry replaces the default. */
modelVercelGatewayRouting?: Record<string, VercelGatewayRouting>;
/**
* "key" (default): authenticate upstream with `apiKey`.
* "forward": relay the caller's incoming auth headers verbatim (OAuth passthrough; gpt only).
* "oauth": resolve a stored OAuth access token (auto-refreshed) and use it as the Bearer key.
* Only the openai-responses adapter implements "forward"; openai-chat uses its own key/token.
* "local": local runtime (Ollama etc.) — no remote key required. Valid only for
* providers whose registry entry declares authKind "local" (management API enforces).
*/
authMode?: "key" | "forward" | "oauth" | "local";
/**
* Per-provider override for the generic OAuth PROACTIVE account preference (#2568, #695).
*
* Reactive 429 rotation is presence-driven and cannot be refused here — 2+ logged-in accounts
* activate it, and a 429 with an idle second account is a defect rather than a preference.
* Proactive exhaustion avoidance requires explicit `true`; a healthy selected account
* retains priority. This overrides global `oauthAccountFailover` in either direction.
* Reactive 429 rotation remains available even when proactive routing is disabled.
*/
oauthAccountFailover?: {
/** Kiro OAuth only: active serving requests per account, 1..100. */
maxConcurrentPerAccount?: number;
enabled?: boolean;
/** Opt-in process-local conversation ownership; requires proactive enablement. */
sessionAffinity?: "conversation" | "none";
/**
* Generic OAuth pool selection strategy (#695). Persisted through the pool-settings
* contract. Consumed by the selector only while `pool.kernel` is on; with the flag off
* it is still merely persisted, so omitted and set behave the same.
*/
strategy?: "quota" | "round-robin" | "fill-first" | "reset-first" | "least-loaded";
/**
* 0-100 usage percent at which fill-first advances off the active account (#695).
* Read only under `pool.kernel` with `strategy: "fill-first"`; 80 when unset, matching
* the Codex and Anthropic pools.
*/
autoSwitchThreshold?: number;
/**
* Successful dispatches retained on one round-robin selection. Default 1; range 1..100.
* Read only under `pool.kernel` with `strategy: "round-robin"`.
*/
stickyLimit?: number;
};
/** Allow an explicitly key/oauth provider to run without a credential (for keyless local proxies). */
keyOptional?: boolean;
/**
* Free-tier pricing flag for UI/catalog (Free badge, Free filter). Not the same as
* `keyOptional` — free tiers may still require an API key (e.g. NVIDIA NIM free credits).
*/
freeTier?: boolean;
/** Optional human note shown in the providers UI (not used for routing). */
note?: string;
/** Strip one trailing bracketed suffix from model ids before sending them upstream. */
modelSuffixBracketStrip?: boolean;
/**
* Override the guardian's proactive-refresh policy for this provider. When unset, the provider's
* built-in risk-tiered default applies (see OAUTH_PROVIDERS in src/oauth/index.ts). Set "proactive"
* to opt this provider into background refresh; "disabled"/"lazy-only" to forbid/limit it.
*/
refreshPolicy?: RefreshPolicy;
/**
* Provider-wide Codex-visible reasoning tiers for routed models. Use only Codex-supported labels
* here (`low`, `medium`, `high`, `xhigh`, `max`); translate provider aliases with
* `reasoningEffortMap` / `modelReasoningEffortMap` below.
*/
reasoningEfforts?: string[];
/** Model-specific Codex-visible reasoning tiers. An empty array means “do not expose effort”. */
modelReasoningEfforts?: Record<string, string[]>;
/** Catalog-only: do not synthesize a missing max rung for matching routed models. */
modelSuppressSyntheticMax?: Record<string, boolean>;
/** Model-specific default Codex reasoning tier; must also be present in the visible tier list. */
modelDefaultReasoningEfforts?: Record<string, string>;
/** Operator-owned effort override; none omits effort and uses the provider default. */
pinnedReasoningEffort?: string;
/** Per-model operator override, ahead of provider-wide and global pins; caps still apply. */
modelPinnedReasoningEfforts?: Record<string, string>;
/**
* Model-specific Codex reasoning-summary capability. Set false when an OpenAI-compatible
* Responses backend rejects Codex summary-delivery fields for that model.
*/
modelSupportsReasoningSummaries?: Record<string, boolean>;
/**
* Model-specific Codex Responses verbosity capability. Set false when the upstream ignores
* `text.verbosity`; the catalog hides the no-op picker and the Responses adapter strips stale
* or caller-supplied values while preserving other `text` fields.
*/
modelSupportsVerbosity?: Record<string, boolean>;
/**
* Provider-wide Codex Responses verbosity capability, applied to models the per-model map
* does not enumerate (a live-discovered id, for example). Materialized from the registry at
* seed/enrich time so the catalog hint pass never has to read PROVIDER_REGISTRY.
*/
supportsVerbosity?: boolean;
/**
* Per-model wire value for Responses `stream_options.reasoning_summary_delivery`.
* Presence also advertises reasoning-summary support for that routed model.
*/
modelReasoningSummaryDelivery?: Record<string, ReasoningSummaryDelivery>;
/**
* Anthropic adaptive `thinking.display` policy for this provider (#8363). `auto` and omission
* keep the built-in selection: native Opus 5.5 progress updates, summarized thinking elsewhere.
* `updates` is only sendable to native Opus 5.5 and degrades to `auto` for other models.
*/
thinkingDisplay?: ThinkingDisplayPolicy;
/** Per-model override of `thinkingDisplay`, keyed by the exact upstream model id. */
modelThinkingDisplay?: Record<string, ThinkingDisplayPolicy>;
/**
* Exact-model hosted tools that win collisions with Codex client tool declarations.
* Use for non-forward Responses gateways that reserve a hosted tool namespace server-side.
*/
modelPreferHostedTools?: Record<string, string[]>;
/**
* Whether the Responses upstream accepts OpenAI's extended hosted web_search fields.
* Set false only for a provider whose native contract rejects them; absence preserves
* passthrough compatibility for OpenAI and unclassified gateways.
*/
supportsOpenAiWebSearchToolFields?: boolean;
/**
* Opt xAI Responses destinations into the provider-hosted `x_search` declaration when a live
* `web_search` tool survives final request normalization. Disabled by default. This is separate
* from the web-search sidecar's `search.xSearch` options and never widens caller tool selectors.
*/
xaiResponsesXSearch?: boolean;
/** One-time Grok subscription wire upgrade; later explicit Chat choices remain authoritative. */
xaiResponsesDefaultVersion?: number;
/**
* One-time Z.AI coding-plan wire upgrade. The router already canonicalizes the `zai` row onto the
* Responses destination at request time; the marker records that the saved row was rewritten to
* match, so a later explicit Chat choice is not re-migrated on the next boot.
*/
zaiResponsesDefaultVersion?: number;
/**
* Whether the Responses upstream accepts native custom tools and custom_tool_call items.
* Set false only for a provider whose native contract rejects them; absence preserves
* apply_patch passthrough compatibility for OpenAI and unclassified gateways.
*/
supportsResponsesCustomTools?: boolean;
/**
* Hosted tool declarations this Responses destination rejects, so they are stripped from
* the request instead of being forwarded and 400'd.
*
* This is how an OpenAI-compatible gateway with a narrower capability set than OpenAI
* describes itself. Before it existed, a destination that accepted plain Responses and
* `function` tools but rejected hosted `web_search` could only be handled by adding a
* hard-coded baseUrl rule to `src/responses/hosted-tool-policy.ts`, so every such gateway
* needed a proxy release; a text-only prompt like "Reply exactly with OK" failed before
* the model answered because the hosted declaration travelled with it (#5002).
*
* Values come from `DECLARABLE_HOSTED_TOOL_TYPES`. Spelling variants of one capability
* are aliased, so `["web_search"]` also denies `web_search_preview`. Pair this with
* `supportsResponsesCustomTools: false` for a gateway that also rejects native custom
* tools; the two capabilities are independent and denied independently.
*/
unsupportedHostedTools?: string[];
/**
* Hosted tool declarations this Responses destination rejects only in combination with
* client tools, so they are stripped when the same request also declares a `function` or
* `custom` tool, or a namespace with members, in `tools`, a client-loaded
* `additional_tools` catalog, or a `tool_search_output` result. A request that declares
* only hosted tools keeps them.
*
* This describes a gateway that serves hosted `web_search` alone and function calling
* alone, but answers HTTP 400 when one request carries both (#8204). Same vocabulary and
* alias expansion as `unsupportedHostedTools`, which stays authoritative: a tool listed
* there is removed whether or not client tools are present.
*/
unsupportedHostedToolsWithClientTools?: string[];
/**
* Provider-local repair for Responses gateways whose lifecycle snapshots omit canonical
* fields or closing events (#893). Disabled by default and applied only to client-facing
* SSE/JSON; raw inspection state remains authoritative.
*/
responsesSnapshotRepair?: boolean;
/**
* Infer the commentary/final_answer phase on assistant messages for Responses passthrough
* providers whose upstream omits it (e.g. third-party gateways). Codex desktop collapses
* commentary into progress rows; without this every narration renders fully expanded.
* Disabled by default. Applies in the client-facing SSE rewrite chain, including
* buffered JSON reconstructed from upstream SSE; ordinary upstream JSON is unchanged.
*/
messagePhaseInference?: boolean;
/**
* Opt-in (#7427): on a native Responses route, add estimated `usage` to a completed response the
* provider sent without one, marked by `x-opencodex-usage-estimated`. Never used for cost, spend or quota.
*/
estimateMissingUsage?: boolean;
/**
* Opt-in hosted-web-search bridge for this KEY-auth Responses passthrough provider (#3761).
* Absent or disabled leaves the passthrough byte-identical to today.
*/
webSearchBridge?: ProviderWebSearchBridgeConfig;
/**
* Provider-wide mapping from Codex effort labels to upstream `reasoning_effort` values.
* Map a label to the reserved value `"__omit__"` to send no reasoning field at all for that
* effort, so the upstream model's own default applies. The sentinel is
* `REASONING_EFFORT_OMIT_SENTINEL` in `src/reasoning-effort.ts`; it suppresses
* `reasoning_effort` on an OpenAI-compatible wire and Ollama's native `think` field on the
* Ollama native adapter (#2356).
*/
reasoningEffortMap?: Record<string, string>;
/**
* Model-specific mapping from Codex effort labels to upstream `reasoning_effort` values.
* Map a label to the reserved value `"__omit__"` to send no reasoning field at all for that
* effort, so the upstream model's own default applies. Same sentinel as
* `reasoningEffortMap`, resolved per model first.
*/
modelReasoningEffortMap?: Record<string, Record<string, string>>;
/** Chat gateway reasoning object; also opts custom Responses wires into `reasoning.enabled`. */
reasoningWireFormat?: "gateway-object";
/**
* Model ids that do NOT support a reasoning/thinking parameter. The openai-chat adapter drops
* reasoning_effort for these even when Codex selects a reasoning level (e.g. xAI grok-build-0.1).
*/
noReasoningModels?: string[];
/** Model ids that reject caller-specified temperature. */
noTemperatureModels?: string[];
/** Model ids that reject caller-specified top_p. */
noTopPModels?: string[];
/**
* Model ids that reject caller-specified stop sequences. The openai-chat adapter
* drops `stop` for these (xAI grok-4.6 answers 400 invalid-argument
* "Model grok-4.6 does not support parameter stop.", which makes Claude Code's
* auto-mode safety classifier report the model as temporarily unavailable).
*/
noStopModels?: string[];
/** Model ids that reject caller-specified presence/frequency penalty values. */
noPenaltyModels?: string[];
/**
* Model ids whose Chat Completions endpoint rejects `response_format`.
* Structured-output translation remains enabled by default; this is a narrow
* per-model compatibility escape hatch for mixed-capability gateways.
*/
noStructuredOutputModels?: string[];
/**
* Model ids whose Chat Completions endpoint rejects `response_format` of type
* `json_schema` specifically. Such a request is downgraded to
* `{ type: "json_object" }` instead of being dropped, so a client that asked for
* JSON still gets JSON rather than prose — at the cost of the schema itself, which
* the upstream would have rejected anyway.
*
* Deliberately narrower than `noStructuredOutputModels`: that field claims the
* endpoint rejects the whole `response_format` field, which is a strictly stronger
* claim than any reported upstream error supports for these gateways. When a model
* appears in both lists the stronger opt-out wins and the field is omitted entirely.
*/
noJsonSchemaModels?: string[];
/**
* Model ids that accept a reasoning-effort field on an ordinary turn but reject it
* once function tools are present. The model keeps its advertised effort ladder;
* OpenCodex omits the wire field for tool-bearing requests only and lets the
* upstream default apply. Narrower than `noReasoningModels`, which strips reasoning
* from every request and costs the model its picker entirely.
*/
omitReasoningEffortWithToolsModels?: string[];
/**
* Allow multiple tool calls per completion. DEFAULT-ON for openai-chat providers (the
* buffered stream parser assembles interleaved/fragmented multi-call turns safely);
* set `false` to force `parallel_tool_calls:false` upstream and drop the catalog's
* `supports_parallel_tool_calls` bit for that provider. Non-chat adapters advertise
* only on explicit `true`. See devlog/_plan/260709_parallel_tool_calls.
*/
parallelToolCalls?: boolean;
/**
* Opt-in: when `parallelToolCalls` is `false`, actually send `parallel_tool_calls: false`
* on the `/chat/completions` wire for this provider. By default an opted-out provider only
* OMITS the field (strict OpenAI-compatible hosts reject unknown knobs), and the NVIDIA NIM
* baseUrl is the sole built-in exception that pins the wire bit. Some self-hosted gateways
* (Kimi/GLM-family, vLLM, etc.) do honor `parallel_tool_calls` and keep emitting concurrent
* tool calls unless it is present; enable this to pin the bit without hardcoding their URL.
* No effect unless `parallelToolCalls === false`; ignored by non-`openai-chat` adapters.
*/
pinParallelToolCallsFalse?: boolean;
/**
* Opt-in: extend the no-tool-call terminal continuation guard to this provider's
* `openai-chat` routed turns. The guard (originally Anthropic-only, see
* devlog/_fin/260706_previous-response-id-400) issues one bounded internal re-ask when a
* model announces work but ends the turn without emitting a tool call. Self-hosted
* OpenAI-compatible gateways (GLM/Kimi-family, etc.) hit the same premature-completion
* pattern, but the heuristic that decides a "suspicious no-tool stop" was tuned on
* Anthropic turns, so it stays OFF by default for the many registry providers that share
* the `openai-chat` adapter. Enable only for a provider whose models are known to stop
* mid-work; non-`openai-chat` adapters ignore this flag.
*/
terminalContinuationGuard?: boolean;
/**
* Opt-in for OpenAI-compatible chat gateways that may close after emitting a complete
* tool-call delta without `finish_reason` or `[DONE]`. The adapter accepts that EOF only
* when every pending call has a non-empty name and complete JSON-object arguments;
* incomplete JSON, missing arguments, and empty streams remain truncation errors.
*/
openaiChatEofTolerance?: boolean;
/**
* Opt-in: fold a `developer` message into a `system` message instead of forwarding the role.
*
* `developer` is part of the Chat Completions message role set, so forwarding it is the
* default. The role used to be decided by testing the base URL host against
* `api.openai.com`, which assumed every OpenAI-compatible gateway rejects a standard role
* until proven otherwise — including gateways that proxy OpenAI itself — and quietly gave the
* instruction `system` precedence instead (#5213). This flag exists for a destination that
* genuinely rejects the role, so the conversion is a recorded decision about that destination
* rather than an inference from its hostname. Position is unaffected either way: the message
* keeps its slot in the conversation.
*/
foldDeveloperRoleToSystem?: boolean;
/** Merge text-only Chat instruction messages into one leading system message. LM Studio seeds true. */
singleLeadingSystemMessage?: boolean;
/**
* Opt-in: forward `prompt_cache_key` to the upstream `/chat/completions` body.
* OpenAI-specific extension; strict backends (Groq, Cerebras, etc.) reject unknown
* fields. Default off; only enable for providers that document this parameter.
*/
promptCacheKey?: boolean;
/**
* Conversation affinity to the key-pool credential that served a conversation's
* last turn, so its upstream prompt cache is read again on the next turn instead
* of rebuilt on another key. Only affects providers with 2+ key-pool entries;
* eligibility (cooldowns, pacing, disabled keys) always outranks the preference.
* Default `auto`. See src/providers/cache-affinity.ts.
*/
cacheAffinity?: CacheAffinityMode;
/**
* Opt-in: forward caller `service_tier` values to the upstream `/chat/completions` body.
* On a classified route it governs foreign values (for example `flex`), not proxy-owned
* canonical Fast after capability validation. On an unclassified route it governs every caller
* value, including canonical spellings, because no Fast capability has been validated.
* OpenAI-specific extension with the same hazard as `promptCacheKey` — strict backends
* reject unknown fields, and 66 registry providers share the `openai-chat` adapter, so a
* caller-supplied `service_tier` would otherwise turn working requests into upstream 400s.
* Exact-model `true` enables canonical Fast capability but does not grant foreign-tier
* forwarding; provider-level `supportsServiceTier: false` remains a global denial. Default off;
* only enable for providers that document this parameter on the chat wire.
*/
chatServiceTier?: boolean;
/**
* Provider-local passthrough SSE repair for broken openai-responses gateways that reuse exact
* placeholder message/reasoning ids or omit the terminal id after a stable added event.
* Disabled by default; function_call ids and call_id pairing are never rewritten.
*/
responsesItemIdRepair?: ResponsesItemIdRepairConfig;
/** Model ids whose tool_choice only accepts `auto` or `none`; forced/named choices are downgraded. */
autoToolChoiceOnlyModels?: string[];
/** Model ids that expect prior assistant `reasoning_content` to be preserved in chat history. */
preserveReasoningContentModels?: string[];
/**
* Model ids whose upstream hard-rejects a tool_call continuation missing
* `reasoning_content` (DeepSeek thinking mode: HTTP 400). When the replay
* cache misses, the adapter injects a minimal placeholder for these models.
* Defaults to `preserveReasoningContentModels` when unset; set `[]` to opt
* out explicitly (e.g. MiniMax, where low effort disables thinking).
*/
requiresReasoningPlaceholderModels?: string[];
/**
* Default to displaying provider-authored summaries when Responses summary is omitted.
* Explicit wire summary:"none" wins; false disables a seeded provider default.
* Raw reasoning is controlled separately by rawReasoningAsSummary.
*/
showThinkingSummary?: boolean;
/**
* Keep raw content-channel reasoning out of client frames for this provider. Provider-authored
* summaries (thinking_delta) stay visible, so an opted-in operator loses no summary; an explicit
* wire summary:"none" still hides both. This is a display control, not a confidentiality boundary:
* a Responses bridge route still carries the text to the client in the base64 `ocxr1` replay
* envelope; direct Chat/Messages encoders send no copy and replay from the server-side cache.
*/
hideRawReasoning?: boolean;
/**
* Default-off Chat-to-Responses display compatibility: expose raw reasoning on the summary
* channel, verbatim (not a generated summary). hideRawReasoning and wire summary:"none" win.
* Native Responses passthrough and direct Chat/Messages delivery are unchanged.
*/
rawReasoningAsSummary?: boolean;
/**
* Opt-in same-target 429 retry policy. Codex itself never retries 429 (it retries 5xx only,
* openai/codex#30471), and single-key pools have no failover, so the proxy waits and replays
* the identical request on the same key before any failover. Pre-stream only: a 429 arrives
* before any response bytes are relayed, so the replay is lossless.
*/
retryOn429?: RateLimitRetryPolicy;
/**
* Opt-in retry for pre-stream transient upstream statuses
* (`providers.<name>.transientRetryOn5xx`). A bare `{}` opts in with defaults on supported
* key-auth OpenAI adapters. Canonical ChatGPT forward providers require explicit `attempts`.
*/
transientRetryOn5xx?: TransientRetryPolicy;
/**
* Opt-in replacement of self-contained Responses sends (`providers.<name>.retryOnReset`).
* Disabled unless present; `{}` opts in. Native sends and generic translated initial/rebuilt
* pre-header sends share the grant/budget; adapter-owned and translated post-header failures are excluded.
*/
retryOnReset?: ResetReplayPolicy;
/**
* Model ids whose OpenAI-compatible chat endpoint accepts `reasoning_split: true` and returns
* thinking separately in `reasoning_content` / `reasoning_details` instead of visible content.
*/
reasoningSplitModels?: string[];
/**
* Model ids served by a gateway that runs no server-side reasoning parser, so a thinking model
* leaves its chain of thought inline in `content` as `<think>` / `<thinking>` / `<reasoning>`
* blocks and never sends `reasoning_content` or `reasoning_details`. Without this the whole
* chain of thought renders as the answer. The openai-chat adapter then splits those blocks back
* into reasoning. Off by default and narrow on purpose: 66 registry providers share this
* adapter, and a gateway that does parse reasoning must not have its visible content rewritten.
* Prefer a provider-side parser or `reasoningSplitModels` when the upstream supports either.
*/
inlineThinkTagModels?: string[];
/**
* Model ids whose chat endpoint carries thinking as a structured `reasoning_details` array
* (MiniMax M-series with `reasoning_split`): stream deltas repeat each detail's `text` as a
* cumulative snapshot, so the adapter prefix-diffs instead of appending, and preserved
* reasoning replays as a `reasoning_details` array rather than a `reasoning_content` string
* (upstream requires the array back verbatim to keep interleaved thinking intact).
*/
reasoningDetailsModels?: string[];
/**
* Model ids whose reasoning is a vendor `thinking: {type}` toggle on the
* chat-completions wire (MiMo v2.x, GLM 5/5.1 style), NOT an OpenAI `reasoning_effort` ladder.
* The openai-chat adapter translates the mapped effort into the thinking toggle for these.
*/
thinkingToggleModels?: string[];
/**
* Model ids whose reasoning is a `thinking_budget` integer on the chat-completions wire
* (Qwen3.x style), NOT an OpenAI `reasoning_effort` ladder. The openai-chat adapter maps the
* Codex effort to a budget fraction.
*/
thinkingBudgetModels?: string[];
/** Anthropic-compatible gateways that need custom tool names escaped on the wire. */
escapeBuiltinToolNames?: boolean;
/**
* Anthropic-compatible gateways (e.g. AgentRouter) that may close the stream before
* `message_stop`. With this enabled the adapter completes an otherwise-clean EOF only when
* visible text was received or an open tool call has complete JSON-object arguments; all
* other EOFs remain truncation errors. Absent = strict default behavior.
*/
anthropicEofTolerance?: boolean;
/** Opt in to one owner-bound image-context recovery after an upstream 413. */
anthropicImageContextRecovery?: boolean;
/**
* Claude Code's typed Advisor server tool (`advisor_20260301`) on the translated Messages lane.
* Absent: forwarded only to an `anthropic`-adapter provider on first-party `api.anthropic.com`.
* `true`: an Anthropic-compatible gateway that runs it receives the declaration, its history and
* the `advisor-tool-2026-03-01` beta too. `false`: never forwarded, even first-party.
*/
forwardAdvisorTool?: boolean;
/**
* Experimental, default off (#6895). On an `anthropic`-adapter provider that sends to
* `api.anthropic.com` with an API key, a Codex conversation that changes reasoning effort keeps
* the top-level `output_config.effort` at its first turn's value and sends each change as an
* effort-only system message (beta `mid-conversation-output-config-2026-07-01`), so the prompt
* cache survives the change. Any turn the history cannot prove is sent exactly as without it.
*/
perMessageEffort?: boolean;
/**
* Model ids that do NOT accept image inputs. The proxy gives them "eyes" via the vision sidecar:
* attached images are described by a gpt vision model and replaced with text before the call.
*/
noVisionModels?: string[];
/**
* Google adapter mode. "ai-studio" (default) = Generative Language API + x-goog-api-key.
* "vertex" = Vertex AI project/location endpoints with GCP ADC (or x-goog-api-key).
* "cloud-code-assist" = Google Antigravity (Cloud Code Assist) OAuth + CCA envelope.
*/
googleMode?: "ai-studio" | "vertex" | "cloud-code-assist";
/** Google tool-schema compatibility policy. Omitted preserves compatible report-only behavior. */
googleToolSchemaPolicy?: "compatible" | "reject-lossy";
/** Vertex AI GCP project id. API keys use it to select the project endpoint; "auto" resolves each API key's own project. ADC falls back to GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT env. */
project?: string;
/** Vertex AI location, e.g. "us-central1" or "global". API-key project endpoints default to "global"; ADC falls back to GOOGLE_CLOUD_LOCATION env. */
location?: string;
/**
* Cursor adapter only: MCP servers opencodex starts/connects and exposes to the Cursor agent
* as callable tools. Each entry is spawned (stdio `command`) or connected (`url`) lazily per
* stream; their tools are advertised to the Cursor server and executed against the live server.
*/
mcpServers?: Record<string, import("../adapters/cursor/mcp-config").CursorMcpServerConfig>;
/**
* Cursor adapter only: opt-in external executor for computer-use / record-screen. opencodex is
* headless and cannot control a screen itself; provide commands here only when running on a host
* that can. With no executor, these tools honestly report "not supported".
*/
desktopExecutor?: import("../adapters/cursor/desktop-executor-contract").DesktopExecutorConfig;
/**
* Cursor adapter only: unsafe opt-in escape hatch for Cursor server-driven built-in local
* read/write/delete/ls/grep/shell/fetch execution. Prefer `nativeLocalExec: "on"` for new
* configs; this legacy boolean remains a server-local explicit opt-in for existing operators.
* Defaults to false so remote Cursor messages cannot bypass Codex approval/sandbox semantics.
* Explicit MCP and desktop executors remain controlled by their own opt-in config.
*/
unsafeAllowNativeLocalExec?: boolean;
/**
* Cursor adapter only: native local exec policy mode (exec-policy.ts).
* "off" (default) rejects server-driven local exec; "on" always allows it for this
* provider and should be used only for a trusted local experiment on a host where every
* data-plane caller is trusted. "codex-sandbox" is accepted for backwards compatibility
* but is fail-closed like "off": Responses instructions/system/developer text is
* caller-controlled prose, and opencodex has no trustworthy per-request attestation that it
* reflects a real Codex sandbox state. The default loopback bind admits ANY local process
* without auth (including other local users on multi-user machines), and
* isAllowedRequestOrigin blocks non-loopback browser origins by default but not
* loopback-origin or origin-less callers.
*/
nativeLocalExec?: "off" | "codex-sandbox" | "on";
}