import type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./wire";

/**
 * 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";

/** Request-owned identity of the configured key, before env/keychain resolution. */
export interface ProviderApiKeySelection {
  entryId?: string;
  reference?: string;
  revision?: 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`.
 *
 * Disabled unless the object is present; a bare `{}` opts in with defaults. Separate from
 * `retryOn429`, which handles rate limiting with its own waits.
 */
export interface TransientRetryPolicy {
  /** Master switch. Presence of the object also enables the policy (default true). */
  enabled?: boolean;
  /**
   * TOTAL upstream sends allowed for one request, including the first (1..10, 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 native Responses send whose upstream connection closed while the
 * caller had observed nothing (`providers.<name>.retryOnReset`).
 *
 * Covers both ambiguous stages the proxy can be in: no response head at all, and a head whose
 * SSE body carried only control events. Disabled unless the object is present; a bare `{}`
 * opts in with defaults. Only a request the proxy can judge self-contained is ever replaced;
 * see `src/server/responses/reset-replay.ts`. The replacement inference may still be billed if
 * the origin had already started the first one, which is what makes this 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;
}

/**
 * User-configured display price for one model (USD per 1M tokens).
 * Mirrors the `Cost4` shape used by the usage cost estimator; structurally
 * compatible so config rows can be lifted directly into price overlays.
 */
export interface ProviderCostOverlay {
  input: number;
  output: number;
  cacheRead: number;
  cacheWrite: number;
}

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>;
}

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 };

/**
 * One configured provider entry. `authMode` (default `"key"`) decides whether same-target 429
 * retries are allowed; OAuth/forward credentials and local runtimes are never replayed.
 */
/** Explicit per-model operator declarations; absent axes keep legacy behavior. */
export interface ModelCapabilities {
  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" };
}

export interface OcxProviderConfig {
  /** 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>;
  /** 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;
  /** 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>;
  /**
   * 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;
  /**
   * 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;
  /**
   * 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;
  /**
   * 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";
  /**
   * 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 }>;
  /**
   * 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 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. */
  newModelPolicy?: "on" | "off" | "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>;
  /** 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[]>;
  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;
  /** 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>;
  /**
   * 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>;
  /** 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;
    /**
     * 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" | "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>;
  /**
   * 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[];
  /**
   * 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;
  /**
   * 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>>;
  /** OpenAI-compatible gateway reasoning wire shape. Default sends `reasoning_effort`. */
  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;
  /**
   * 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;
  /**
   * 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 never relabeled as a summary.
   */
  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;
  /**
   * 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`). Disabled unless present; a bare `{}` opts in
   * with defaults. Key-auth `openai-chat` only.
   */
  transientRetryOn5xx?: TransientRetryPolicy;
  /**
   * Opt-in replacement of a native Responses send that died while the caller had observed
   * nothing (`providers.<name>.retryOnReset`). Disabled unless present; a bare `{}` opts in
   * with defaults. Native Responses sends only, and only for self-contained requests.
   */
  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;
  /**
   * 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 (or GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT env). */
  project?: string;
  /** Vertex AI location, e.g. "us-central1" or "global" (or 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";
}
