@iislee/opencodex 2.11.0 → 2.31.0

package/src/types.ts

@@ -1,1237 +1,105 @@
-import type { KiroOAuthMetadata } from "./oauth/types";
+// AUTO-SPLIT barrel: src/types.ts re-exports every historical name; bodies live in src/types/*.
+// Values (runtime): tools + wire. Types (erased): request + config + provider + accounts.
+
+export type { OcxTool, OcxToolChoice } from "./types/tools";
+export {
+  namespacedToolName,
+  toolChoiceAliases,
+  toolChoiceCandidates,
+  toolAllowedByChoice,
+  resolveToolChoiceWireName,
+  modelInList,
+  isAllowedToolChoice,
+  toolChoiceToolPredicate,
+} from "./types/tools";
+
+export type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./types/wire";
+export {
+  UPSTREAM_HTTP_VERSION_VALUES,
+  REASONING_SUMMARY_DELIVERY_VALUES,
+  OPENAI_PROVIDER_TIER_VERSION,
+  MODEL_ADAPTER_OVERRIDE_ALLOWED,
+  captureWireAdapterHardPins,
+  isWirePinnedModel,
+  pinnedWireAdapter,
+} from "./types/wire";
+
+export type {
+  OcxReasoningReplayIdentity,
+  OcxReasoningReplayScopeRef,
+  OcxParsedRequest,
+  OcxContext,
+  OcxMessage,
+  OcxUserMessage,
+  OcxAssistantMessage,
+  OcxDeveloperMessage,
+  OcxToolResultMessage,
+  OcxTextContent,
+  OcxImageContent,
+  OcxContentPart,
+  OcxThinkingContent,
+  OcxToolCall,
+  OcxProviderOpaqueToolCallMetadata,
+  OcxAssistantContentPart,
+  OcxRequestOptions,
+  OcxMessagePhase,
+  OcxProviderContinuationOwner,
+  OcxProviderContinuationState,
+  AdapterEvent,
+  OcxUrlCitation,
+  OcxUsage,
+} from "./types/request";
+
+export type {
+  OcxClaudeCodeConfig,
+  OcxClaudeDesktopFamily,
+  OcxClaudeDesktopAssignment,
+  OcxClaudeDesktopProfile,
+  StorageCleanupPolicy,
+  OcxCustomModel,
+  OcxApiKeyEntry,
+  OcxClientIntegrationsConfig,
+  OcxConfig,
+  OcxAccountPoolRotationStrategy,
+  OcxComboStrategy,
+  OcxComboDefaultEffort,
+  OcxComboTarget,
+  OcxComboConfig,
+  OcxRoutingUnknownEvidenceMode,
+  OcxRoutingProfileCandidate,
+  OcxRoutingProfileRequirements,
+  OcxRoutingProfileOptimize,
+  OcxRoutingUnknownCostCapMode,
+  OcxRoutingProfileLimits,
+  OcxRoutingProfileUnknownEvidence,
+  OcxRoutingProfileCompatibilitySuite,
+  OcxRoutingProfileCompatibility,
+  OcxRoutingProfileConfig,
+  OcxTokenGuardianConfig,
+  OcxImagesConfig,
+  OcxSearchConfig,
+  OcxVisionSidecarConfig,
+  OcxWebSearchSidecarConfig,
+} from "./types/config";
+
+export type {
+  RefreshPolicy,
+  OpenRouterProviderRouting,
+  ResponsesItemIdRepairConfig,
+  RateLimitRetryPolicy,
+  ProviderCostOverlay,
+  RequestPacingRule,
+  ProviderRequestPacingConfig,
+  FastWire,
+  AttemptTierOutcome,
+  TierObservationContext,
+  TierDecision,
+  OcxProviderConfig,
+} from "./types/provider";
+
+export type {
+  CodexAccount,
+  CodexAccountCredentials,
+  CodexAccountCredentialRecord,
+} from "./types/accounts";
 
-export interface OcxParsedRequest {
-  modelId: string;
-  previousResponseId?: string;
-  context: OcxContext;
-  stream: boolean;
-  options: OcxRequestOptions;
-  _rawBody?: unknown;
-  /** Number of leading raw input items restored from local previous_response_id state. */
-  _replayPrefixLen?: number;
-  /** True when the proxy expanded a previous_response_id request into a full input replay. */
-  _previousResponseInputExpanded?: boolean;
-  /** Provider-private stable Cursor conversation id resolved from the Responses previous_response_id chain. */
-  _cursorConversationId?: string;
-  /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
-  _clientThreadId?: string;
-  /**
-   * Optional authenticated tenant/operator namespace for Cursor thread→conversation derivation.
-   * When absent (single-operator local proxy), derivation stays local-scoped.
-   */
-  _cursorIdentityScope?: string;
-  /**
-   * True for helper/shadow/compaction turns that must not append into the main Cursor conversation
-   * derived from the parent thread id.
-   */
-  _cursorIsolateConversation?: boolean;
-  /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */
-  _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion">;
-  /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
-  _providerContinuation?: OcxProviderContinuationState;
-  /**
-   * The hosted `{type:"web_search", ...}` tool config, stashed when Codex enables web search. Routed
-   * (non-OpenAI) providers can't run it server-side, so the proxy re-exposes it as a function tool and
-   * executes searches via the gpt-5.4-mini sidecar (see src/web-search). Absent when not requested.
-   */
-  _webSearch?: Record<string, unknown>;
-  /** Hosted image_generation tool config stashed for the image bridge sidecar (see src/images). */
-  _imageGeneration?: { toolNames: Set<string>; originalTool?: Record<string, unknown> };
-  /**
-   * True when Codex requested structured output (`text.format` = json_schema/json_object). The
-   * web-search tool_result is then rendered as compact JSON instead of markdown prose, so its
-   * answer/"Sources:" text can't bleed into and corrupt the model's schema-constrained output.
-   */
-  _structuredOutput?: boolean;
-  /**
-   * True when the input carried `{type:"compaction_trigger"}` — Codex remote compaction v2 asking
-   * this turn to produce a `{type:"compaction"}` output item. Routed adapters can't natively;
-   * the server runs the model as a summarizer and the bridge emits a synthetic compaction item
-   * (see src/responses/compaction.ts).
-   */
-  _compactionRequest?: boolean;
-  /**
-   * True when the current request newly introduced a stored compaction summary/marker. Historical
-   * markers restored by previous_response_id expansion were already acknowledged and do not reset
-   * provider-private continuation caches again on every later turn.
-   */
-  _contextCompactionBoundary?: boolean;
-}
-
-export interface OcxContext {
-  systemPrompt?: string[];
-  messages: OcxMessage[];
-  tools?: OcxTool[];
-}
-
-export type OcxMessage =
-  | OcxUserMessage
-  | OcxAssistantMessage
-  | OcxDeveloperMessage
-  | OcxToolResultMessage;
-
-export interface OcxUserMessage {
-  role: "user";
-  content: string | OcxContentPart[];
-  timestamp: number;
-}
-
-export interface OcxAssistantMessage {
-  role: "assistant";
-  content: OcxAssistantContentPart[];
-  /** Responses message phase, preserved when replaying translated provider output. */
-  phase?: OcxMessagePhase;
-  model?: string;
-  timestamp: number;
-}
-
-export interface OcxDeveloperMessage {
-  role: "developer";
-  content: string | OcxContentPart[];
-  timestamp: number;
-}
-
-export interface OcxToolResultMessage {
-  role: "toolResult";
-  toolCallId: string;
-  toolName: string;
-  /** MCP namespace from the originating tool call, if any. */
-  toolNamespace?: string;
-  /** Text, or content parts when a tool (e.g. Codex view_image) returns an image in its output. */
-  content: string | OcxContentPart[];
-  /** True when the Responses result contained opaque encrypted output Kiro cannot translate. */
-  containsEncryptedContent?: boolean;
-  isError: boolean;
-  timestamp: number;
-}
-
-export interface OcxTextContent {
-  type: "text";
-  text: string;
-}
-
-export interface OcxImageContent {
-  type: "image";
-  /** A `data:` URL (base64) or a remote https URL — passed through from Codex verbatim, NEVER inlined as text. */
-  imageUrl: string;
-  /** Fidelity hint from Codex: "low" | "high" | "auto". */
-  detail?: string;
-}
-
-/** A user/developer message content part: text or an image (vision). */
-export type OcxContentPart = OcxTextContent | OcxImageContent;
-
-export interface OcxThinkingContent {
-  type: "thinking";
-  thinking: string;
-  signature?: string;
-  itemId?: string;
-  /** Raw Anthropic redacted_thinking block payloads to replay verbatim (order preserved). */
-  redacted?: string[];
-}
-
-export interface OcxToolCall {
-  type: "toolCall";
-  id: string;
-  name: string;
-  arguments: Record<string, unknown>;
-  customWireName?: string;
-  thoughtSignature?: string;
-  /** MCP namespace (e.g. "mcp__context7") when this call targets a namespaced tool. */
-  namespace?: string;
-}
-
-export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall;
-
-export interface OcxTool {
-  name: string;
-  description: string;
-  parameters: Record<string, unknown>;
-  strict?: boolean;
-  /** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
-  namespace?: string;
-  /** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
-  freeform?: boolean;
-  /** Client-executed tool discovery (tool_search): the model's call must be relayed as a tool_search_call. */
-  toolSearch?: boolean;
-  /** Tool definition restored from a prior tool_search output; transports may prioritize it when catalogs are bounded. */
-  loadedFromToolSearch?: boolean;
-  /** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
-  webSearch?: boolean;
-  /** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
-  imageGeneration?: boolean;
-  /** Synthetic video_gen tool: executed by the xAI video bridge sidecar. */
-  videoGeneration?: boolean;
-}
-
-/**
- * Wire name a chat model sees for a tool. Namespaced (MCP) tools are flattened to
- * "<namespace>__<name>" so they survive the chat-completions function-tool format;
- * the proxy maps this back to {namespace, name} on the return trip (Codex routes MCP
- * calls by an explicit `namespace` field, not by parsing the name).
- */
-export function namespacedToolName(namespace: string | undefined, name: string): string {
-  return namespace ? `${namespace}__${name}` : name;
-}
-
-export function toolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
-  const wireName = namespacedToolName(tool.namespace, tool.name);
-  return tool.namespace ? [wireName, `${tool.namespace}.${tool.name}`] : [wireName];
-}
-
-export function toolAllowedByChoice(tool: Pick<OcxTool, "namespace" | "name">, allowedTools: ReadonlySet<string>): boolean {
-  return toolChoiceAliases(tool).some(name => allowedTools.has(name));
-}
-
-export function resolveToolChoiceWireName(tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined, name: string): string {
-  const match = tools?.find(tool => toolChoiceAliases(tool).includes(name));
-  return match ? namespacedToolName(match.namespace, match.name) : name;
-}
-
-/**
- * Whether `modelId` is in a per-provider classification list (e.g. `noVisionModels`). Matches the full
- * id, OR — for Ollama-style ids — the family before the ":size" tag, so a `gpt-oss` entry covers
- * `gpt-oss:120b`/`gpt-oss:20b`. Colon-less ids (e.g. `grok-build-0.1`) still match exactly only.
- */
-export function modelInList(list: string[] | undefined, modelId: string): boolean {
-  if (!list || list.length === 0) return false;
-  if (list.includes(modelId)) return true;
-  const colon = modelId.indexOf(":");
-  return colon > 0 && list.includes(modelId.slice(0, colon));
-}
-
-export type OcxToolChoice =
-  | "auto"
-  | "none"
-  | "required"
-  | { name: string }
-  | { allowedTools: string[]; mode: "auto" | "required" };
-
-export function isAllowedToolChoice(value: OcxToolChoice | undefined): value is { allowedTools: string[]; mode: "auto" | "required" } {
-  return typeof value === "object" && value !== null && "allowedTools" in value;
-}
-
-export interface OcxRequestOptions {
-  maxOutputTokens?: number;
-  temperature?: number;
-  topP?: number;
-  stopSequences?: string[];
-  toolChoice?: OcxToolChoice;
-  parallelToolCalls?: boolean;
-  reasoning?: string;
-  hideThinkingSummary?: boolean;
-  serviceTier?: string;
-  presencePenalty?: number;
-  frequencyPenalty?: number;
-  /** Responses prompt-cache affinity key. Passthrough preserves it via _rawBody; routed adapters do not consume it unless their upstream wire supports it. */
-  promptCacheKey?: string;
-}
-
-export type OcxMessagePhase = "commentary" | "final_answer";
-
-/**
- * Provider-private state that must follow a locally expanded `previous_response_id` chain.
- * Kept out of public Responses output and persisted only in the bounded local continuation cache.
- */
-export interface OcxProviderContinuationState {
-  cursor?: {
-    conversationId?: string;
-    checkpointUsable?: boolean;
-  };
-  kiro?: {
-    conversationId?: string;
-  };
-  [provider: string]: Record<string, unknown> | undefined;
-}
-
-export type AdapterEvent =
-  | { type: "heartbeat" }
-  | { type: "text_delta"; text: string; phase?: OcxMessagePhase }
-  | { type: "thinking_delta"; thinking: string }
-  // Anthropic extended-thinking round-trip: signature_delta for the current thinking block, and
-  // opaque redacted_thinking blocks. Both must be replayed verbatim or tool-use turns 400.
-  | { type: "thinking_signature"; signature: string }
-  | { type: "redacted_thinking"; data: string }
-  | { type: "reasoning_raw_delta"; text: string }
-  | { type: "tool_call_start"; id: string; name: string }
-  | { type: "tool_call_delta"; arguments: string }
-  | { type: "tool_call_end" }
-  /** Internal boundary between a guarded first pass and its one-shot continuation. */
-  | { type: "assistant_boundary" }
-  // Native web-search activity surfaced by the web-search sidecar so Codex renders a "Searched the
-  // web" cell. Emitted as a lifecycle PAIR at real wall-clock moments by src/web-search/loop.ts
-  // (routed adapters never emit these): `begin` right before the sidecar runs so Codex shows the
-  // "Searching the web" spinner, then `end` once it resolves. The bridge maps begin → an
-  // output_item.added(in_progress) and end → the matching output_item.done(completed|failed) under
-  // the SAME output index, so the activity animates instead of flashing completed instantly.
-  | { type: "web_search_call_begin"; id: string }
-  | { type: "web_search_call_end"; id: string; queries: string[]; status?: "completed" | "failed"; sources?: OcxUrlCitation[] }
-  | {
-      type: "done";
-      usage?: OcxUsage;
-      stopReason?: string;
-      endTurn?: boolean;
-      providerState?: OcxProviderContinuationState;
-    }
-  | {
-      type: "incomplete";
-      reason: string;
-      message?: string;
-      usage?: OcxUsage;
-      retryable?: boolean;
-      endTurn?: boolean;
-      providerState?: OcxProviderContinuationState;
-    }
-  // `usage` carries best-effort partial consumption when a turn dies before a clean done
-  // (e.g. cursor upstream 502 mid-stream), so failed requests can log real token counts.
-  | {
-      type: "error";
-      message: string;
-      usage?: OcxUsage;
-      /** Authoritative upstream/proxy status when known; avoids message-based classification. */
-      status?: number;
-      /** Responses error type and code when the adapter has a structured provider failure. */
-      errorType?: string;
-      code?: string;
-      retryable?: boolean;
-    };
-
-/**
- * A web source backing a search answer. Surfaced on the search-end event and rendered by the bridge
- * as a `url_citation` annotation on the following assistant message (the desktop app's Sources chip
- * reads these; the TUI ignores annotations, so this is additive).
- */
-export interface OcxUrlCitation {
-  url: string;
-  title?: string;
-}
-
-/**
- * Canonical usage convention (devlog/260711_claude_inbound/070):
- * - `inputTokens` is the TOTAL prompt size, INCLUDING cache reads and cache writes
- *   (OpenAI Responses convention). Anthropic parse sites normalize into this shape.
- * - `cachedInputTokens` is cache READ tokens only (a subset of `inputTokens`).
- * - `cacheReadInputTokens`/`cacheCreationInputTokens` carry the read/write split when
- *   the provider reports both; reads mirror `cachedInputTokens`.
- * - `totalTokens` = inputTokens + outputTokens. Never re-add cache detail on top.
- */
-export interface OcxUsage {
-  inputTokens: number;
-  outputTokens: number;
-  /**
-   * Absolute active-context size after the response. Stateful providers can expose this separately
-   * from their per-attempt usage. Responses serialization derives the input side from
-   * `contextTotalTokens - outputTokens` so output is never added to an absolute checkpoint twice.
-   */
-  contextTotalTokens?: number;
-  totalTokens?: number;
-  cachedInputTokens?: number;
-  cacheReadInputTokens?: number;
-  cacheCreationInputTokens?: number;
-  reasoningOutputTokens?: number;
-  estimated?: boolean;
-}
-
-/**
- * Claude Code inbound settings (devlog/260711_claude_inbound). Consumed by the
- * /v1/messages surface, the `ocx claude` launcher, and the GUI Claude page.
- */
-export interface OcxClaudeCodeConfig {
-  /** Kill switch for the /v1/messages inbound (GUI "Claude ON" toggle). Default: enabled. */
-  enabled?: boolean;
-  /**
-   * Verbatim passthrough of unmapped claude/anthropic models to api.anthropic.com with the
-   * caller's own sk-ant-* credential (Claude Code subscription OAuth). Default: enabled.
-   */
-  nativePassthrough?: boolean;
-  /** Upstream for the native passthrough (tests/enterprise gateways). Default: https://api.anthropic.com */
-  anthropicBaseUrl?: string;
-  /**
-   * Native passthrough body inactivity budget in SECONDS — raw upstream-byte silence
-   * while a read is pending, NOT total duration (slow-but-alive streams never trip it;
-   * devlog 260716_passthrough_followups/010). Default 90. Min 1. Exactly 0 disables;
-   * negative/non-finite values fall back to the default.
-   */
-  bodyStallSec?: number;
-  /**
-   * Native passthrough cumulative body byte cap (streamed SSE and buffered non-stream
-   * alike) — an OOM/occupancy guard, not a correctness limit. Default 67108864 (64 MiB).
-   * Exactly 0 disables; negative/non-finite values fall back to the default.
-   */
-  bodyMaxBytes?: number;
-  /** Default model slot injected as ANTHROPIC_MODEL by `ocx claude`. */
-  model?: string;
-  /** Haiku/small-fast slot injected as ANTHROPIC_DEFAULT_HAIKU_MODEL (+ legacy SMALL_FAST). */
-  smallFastModel?: string;
-  /** Inbound model id remaps: exact id first, then date-stripped (`-\d{8}$`). */
-  modelMap?: Record<string, string>;
-  /**
-  * Inject ANTHROPIC_BASE_URL etc. into the macOS user domain via `launchctl setenv`
-  * so plain `claude` commands route through the proxy without `ocx claude`. Reverted
-   * on stop/shutdown. Default: false (opt-in). macOS only.
-   */
-  systemEnv?: boolean;
-  /**
-   * Auth mode for Claude Code inbound requests — a THREE-state intent.
-   *
-   * "proxy": inject the dummy ANTHROPIC_AUTH_TOKEN so Claude Code routes through the
-   * proxy without a real Anthropic key. "subscription": never inject it. UNSET means
-   * AUTO: the mode is resolved from detected Claude auth on every launch and every
-   * status read (src/claude/auth-mode.ts), so registering a Claude login switches the
-   * behaviour with no migration and no stored state.
-   *
-   * An explicit value always wins over detection and is never rewritten by the auto
-   * logic — that is what makes a manual choice stick (devlog 260726_claude_auth_auto).
-   */
-  authMode?: "proxy" | "subscription";
-  /**
-   * ISO timestamp of the one-time authMode migration. Before auto existed, choosing
-   * "Subscription" DELETED the key, so a pre-upgrade config cannot distinguish an
-   * explicit subscription choice from "never chose". Its ABSENCE identifies a
-   * pre-upgrade block; the migration writes it once and never re-runs, so a user who
-   * later picks Auto (which deletes authMode) is not silently converted back.
-   */
-  authModeMigratedAt?: string;
-  /**
-   * Context-window override for Claude Code/Desktop clients (devlog 136 B6):
-   * injected as CLAUDE_CODE_MAX_CONTEXT_TOKENS + DISABLE_COMPACT=1 (the official
-   * env pair — recognized claude-shaped ids need both). WARNING: DISABLE_COMPACT
-   * turns off auto-compaction. Unset = client defaults.
-   */
-  maxContextTokens?: number;
-  /**
-   * Opt-in CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 injection. Default OFF: opus-shaped
-   * aliases already carry output_config.effort on the wire (devlog 136 실측), and
-   * forcing effort on every request can leak reasoning params to non-reasoning routes.
-   */
-  alwaysEnableEffort?: boolean;
-  /**
-   * Subagent tier slots (devlog 260712 B2): injected as ANTHROPIC_DEFAULT_*_MODEL so
-   * Claude Code's Agent-tool aliases (opus/sonnet/haiku/fable + parent-inherit) route
-   * to proxy models. haiku falls back to smallFastModel (one effective value feeds
-   * both ANTHROPIC_DEFAULT_HAIKU_MODEL and legacy ANTHROPIC_SMALL_FAST_MODEL).
-   */
-  tierModels?: { opus?: string; sonnet?: string; haiku?: string; fable?: string };
-  /**
-   * Auto-context (devlog 260712 020): when not false, routed/native models whose
-   * authoritative window is > 200k AND >= the compact window get the [1m] marker
-   * (Claude Code then accounts 1M) and CLAUDE_CODE_AUTO_COMPACT_WINDOW is injected
-   * so compaction fires at the real budget. 2.1.207 semantics (binary-verified):
-   * effective compact window = min(believed window, env) — one global env behaves
-   * like a per-model floor. Default: enabled. Inert while maxContextTokens is set
-   * (the legacy DISABLE_COMPACT pair takes rule-1 precedence in the CLI).
-   */
-  autoContext?: boolean;
-  /** Compact-window tokens for auto-context. Default 350_000. */
-  autoCompactWindow?: number;
-  /**
-   * Bundled-skill content elision for ROUTED (non-Anthropic) models (devlog 260712
-   * 060): Skill-tool results whose skill name matches an entry here are replaced
-   * with a short stub in the anthropic->responses translation. Third-party models
-   * are not trained on these Anthropic doc bundles, and claude-api alone injects
-   * ~136k tokens (GitHub anthropics/claude-code#74473). Native Anthropic
-   * passthrough never goes through the translation, so Claude models keep the
-   * full content. Default: ["claude-api"]. Empty array = explicitly off.
-   */
-  blockedSkills?: string[];
-  /**
-   * Sync the featured subagent roster (config.subagentModels + main model) into
-   * ~/.claude/agents/ocx-*.md custom agent definitions at launch (devlog 260712
-   * 070) so any routed model is dispatchable as a subagent_type — the Agent
-   * tool's model argument is a hard 4-alias enum, but definition frontmatter is
-   * free. Only ocx-*.md files are owned/pruned. Default: enabled.
-   */
-  injectAgents?: boolean;
-  /**
-   * Optional Claude Code effort pinned in every generated ocx-* subagent
-   * definition. Unset inherits the parent session effort.
-   */
-  subagentEffort?: "low" | "medium" | "high" | "xhigh" | "max";
-  /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
-  webSearchSidecar?: { backend?: "openai" | "anthropic"; model?: string };
-  /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
-  visionSidecar?: { backend?: "openai" | "anthropic"; model?: string };
-  /** Persisted Claude Desktop four-family routing profile. */
-  desktopProfile?: OcxClaudeDesktopProfile;
-  /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
-  desktopAutoApply?: boolean;
-  /**
-   * When false, omit `native/*` rows from Claude Desktop show/export/apply. Default: enabled.
-   * Routing-sidecar alias decoding is unchanged — only the Desktop model list writer.
-   */
-  desktopNativeModels?: boolean;
-}
-
-export type OcxClaudeDesktopFamily = "opus" | "fable" | "sonnet" | "haiku";
-
-export interface OcxClaudeDesktopAssignment {
-  family: OcxClaudeDesktopFamily;
-  alias: string;
-}
-
-export interface OcxClaudeDesktopProfile {
-  version: 1;
-  assignments: Record<string, OcxClaudeDesktopAssignment>;
-  defaults: Record<OcxClaudeDesktopFamily, string | null>;
-  /** SHA-256 fingerprint of the last successfully applied 3P config content. */
-  appliedFingerprint?: string;
-  /** ISO timestamp of the last successful apply. */
-  appliedAt?: string;
-}
-
-/**
- * Opt-in archived-session auto-cleanup policy (issue #42 Phase 3).
- * Persisted under `OcxConfig.storageCleanupPolicy`. Default `enabled: false`.
- */
-export interface StorageCleanupPolicy {
-  /** When false/unset, the engine never mutates. Default false. */
-  enabled: boolean;
-  /** Run when archived session bytes exceed this threshold. */
-  trigger: { archivedBytesOver: number };
-  /** Either shrink archives toward a byte floor, or remove the oldest N%. */
-  target: { reduceToBytes?: number } | { removeOldestPercent?: number };
-  schedule: "startup" | "daily" | "weekly" | "manual";
-  /** Default quarantine. Permanent only when explicitly set. */
-  mode: "quarantine" | "permanent";
-  lastRun?: { at: number; freedBytes: number; removed: number };
-  /** Epoch ms when the next scheduled evaluation is due. */
-  nextRun?: number;
-}
-
-/** 사용자가 대시보드에서 직접 추가한 커스텀 모델 정의. */
-export interface OcxCustomModel {
-  /** 고유 ID (crypto.randomUUID()) */
-  id: string;
-  /** 프로바이더 키 (기존 providers[name]) */
-  provider: string;
-  /** 모델 슬러그 (프로바이더 접두사 없는 bare id) */
-  modelId: string;
-  /** 인간 가독 표시명 (선택, 슬래시 불가) */
-  displayName?: string;
-  /** 컨텍스트 윈도우 (토큰) */
-  contextWindow?: number;
-  /** 입력 모달리티 (선택, 기본 ["text"]) */
-  inputModalities?: string[];
-  /** 추가 시각 (ISO 8601) */
-  addedAt?: string;
-}
-
-/**
- * A generated `ocx_` data-plane key. `key` is the secret itself and never leaves
- * the server except in the one-time POST /api/keys response; every other surface
- * sees only the masked prefix.
- */
-export interface OcxApiKeyEntry {
-  id: string;
-  name: string;
-  key: string;
-  createdAt: string;
-}
-
-export interface OcxConfig {
-  port: number;
-  /** Maximum usage-log bytes read for one management snapshot. */
-  managementUsageMaxReadBytes?: number;
-  providers: Record<string, OcxProviderConfig>;
-  defaultProvider: string;
-  /** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
-  openaiProviderTierVersion?: 1 | 2;
-  /** One-time migration marker for Antigravity's static catalog default. */
-  googleAntigravityStaticCatalogVersion?: 1;
-  /** Claude Code inbound + launcher settings. */
-  claudeCode?: OcxClaudeCodeConfig;
-  /**
-   * Up to 5 routed model ids ("<provider>/<model>") to feature FIRST in the injected Codex catalog.
-   * Codex's spawn_agent only advertises the first 5 routed models, so this picks which 5 appear.
-   */
-  subagentModels?: string[];
-  /**
-   * Priority-ordered fallback models for spawned sub-agents. When the requested
-   * model is quota-exhausted or recently failed, opencodex rewrites the child
-   * turn to the next available entry before routing.
-   */
-  subagentModelFallback?: string[];
-  /**
-   * TTL (ms) for cached sub-agent model availability probes. Default 60_000.
-   */
-  subagentModelFallbackPollMs?: number;
-  injectionModel?: string;
-  /**
-   * Opt in to synchronizing the selected injection model into Codex's native
-   * sub-agent defaults. Only meaningful while `injectionModel` is set.
-   */
-  syncCodexSubagentDefaults?: boolean;
-  /**
-   * Optional reasoning effort the delegation prompt tells the agent to pass in spawn_agent calls
-   * (`reasoning_effort` argument). Only meaningful while `injectionModel` is set; validated against
-   * the Codex ladder (src/reasoning-effort.ts CODEX_REASONING_LEVELS) at the API boundary.
-   */
-  injectionEffort?: string;
-  /**
-   * Explicit sideband websocket base for realtime/live joins, mirroring upstream's
-   * `experimental_realtime_ws_base_url`. The value is a ROOT (or a recognized
-   * `/realtime`, `/realtime/calls/<id>`, `/live/<id>` endpoint form, which is
-   * stripped back to the root); `/v1` is appended during normalization. Intended
-   * for local development against a fake realtime server — plaintext `http`/`ws`
-   * is accepted only for loopback hosts, and URL userinfo is rejected; both
-   * failures close to the canonical `https://api.openai.com/v1`. Configured by
-   * editing this file; there is deliberately no management-API or GUI surface.
-   */
-  experimentalRealtimeWsBaseUrl?: string;
-  /**
-   * Model ids the user has EXCLUDED from the Grok Build managed block. Absent or empty
-   * means "everything visible", which is the historical behaviour — so an existing
-   * config keeps the fence it already had.
-   *
-   * Exclusion list rather than an inclusion list on purpose: a newly added provider
-   * model should appear in Grok by default, exactly as it does today. An inclusion list
-   * would silently hide every future model behind a switch nobody knew to flip.
-   */
-  grokExcludedModels?: string[];
-  /**
-   * When true, OpenAI-routed requests include `service_tier: "priority"` (fast inference).
-   * When false, service_tier is stripped so requests use default speed.
-   * Undefined = passthrough (don't modify what the client sends).
-   */
-  fastMode?: boolean;
-  /**
-   * Windows/macOS SSE passthrough stream shape (#314 mitigation).
-   * On Windows, "auto" (default) selects eager relay only on a runtime proven
-   * to carry the Bun#32111 fix. On macOS, "auto" always stays on legacy tee and
-   * eager relay is explicit-only. "eager-relay" opts into the new relay (and
-   * accepts #32111 crash risk on Bun 1.3.14); "legacy-tee" pins the tee path.
-   * Persisted in config.json so service users can select the stream shape.
-   * See src/lib/bun-stream-caps.ts.
-   */
-  streamMode?: "auto" | "legacy-tee" | "eager-relay";
-  /**
-   * Custom override for the injected multi-agent guidance body (the text inside the
-   * <multi_agent_mode> tags). When set, it replaces the built-in prompt on whichever
-   * collab surface would have fired; firing gates are unchanged. Placeholders:
-   * `{{model}}` -> injectionModel, `{{effort}}` -> injectionEffort, `{{roster}}` ->
-   * the resolved sub-agent roster block ("" when nothing resolves), `{{fallback}}` ->
-   * the configured subagent model fallback guidance block ("" when unset).
-   */
-  injectionPrompt?: string;
-  /**
-   * Proxy-authored multi-agent developer guidance. Undefined/true = enabled for
-   * backward compatibility; false suppresses both v1 and v2 guidance injection.
-   */
-  multiAgentGuidanceEnabled?: boolean;
-  /**
-   * Global hard ceiling for the reasoning effort of EVERY proxied turn (main agent AND
-   * sub-agents). Ladder value "low".."max"; incoming efforts ranking above it are rewritten
-   * in both request shapes before any adapter or clamp. Unset = no cap. codex-rs converts
-   * ultra -> max client-side, so e.g. a "high" cap sends ultra/max-tier turns as high.
-   */
-  effortCap?: string;
-  /**
-   * Hard ceiling applied ONLY to sub-agent turns — requests carrying codex-rs's spawned-child
-   * markers (`x-openai-subagent` header, or `subagent_kind` inside `x-codex-turn-metadata`).
-   * Lets the main agent keep its tier while delegated children are capped. When both caps are
-   * set, the lower one wins for sub-agents. See src/server/effort-policy.ts.
-   */
-  subagentEffortCap?: string;
-  /**
-   * Models hidden from Codex. Routed ids are namespaced ("<provider>/<model>") and are excluded
-   * from the catalog + /v1/models entirely. BARE ids (no "/") are native GPT passthrough slugs:
-   * their catalog entries flip to visibility "hide" (entry preserved, picker-hidden) and they
-   * are omitted from the bare /v1/models list.
-   */
-  disabledModels?: string[];
-  /** 사용자가 대시보드에서 직접 추가한 커스텀 모델 목록. */
-  customModels?: OcxCustomModel[];
-  /**
-   * Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
-   * commit messages, skill orchestration) to a user-chosen model. Default intercepted
-   * source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
-   * Opt-in; disabled by default. When enabled, effort is forced to low.
-   */
-  shadowCallIntercept?: {
-    /** When true, requests for known shadow/helper source models are rewritten to the configured model. */
-    enabled?: boolean;
-    /** Replacement model id (e.g. "gpt-5.5"). */
-    model?: string;
-    /** Optional override of intercepted source-model prefixes (default: gpt-5.4-mini, gpt-5.6-luna). */
-    sourceModels?: string[];
-  };
-  /**
-   * 3-state multi-agent surface override:
-   * - "v1": force ALL models to v1 surface (override upstream pins)
-   * - "default" | undefined: respect upstream model pins (sol/terra=v2, luna=v1, rest=codex flag)
-   * - "v2": force ALL models to v2 surface (override upstream pins)
-   */
-  multiAgentMode?: "v1" | "default" | "v2";
-  /** Provider-level Codex-visible context caps. Values only lower known model context windows. */
-  providerContextCaps?: Record<string, number>;
-  /** Global Codex-visible context cap value (tokens). Falls back to DEFAULT_PROVIDER_CONTEXT_CAP. */
-  contextCapValue?: number;
-  /** Bind hostname. Default "127.0.0.1" (loopback only). Set "0.0.0.0" to expose on all interfaces. */
-  hostname?: string;
-  /**
-   * Outbound HTTP(S) proxy URL for provider requests (e.g. "http://user:pass@proxy:8080", or
-   * "${HTTPS_PROXY}"-style env reference). Mirrored into HTTP_PROXY/HTTPS_PROXY at startup when
-   * those are unset — Bun's fetch honors them for all outbound calls; localhost is excluded.
-   */
-  proxy?: string;
-  /**
-   * Upstream stall timeout (seconds). After this many seconds of no upstream data, emits
-   * response.incomplete. Default 300. Min 1.
-   */
-  stallTimeoutSec?: number;
-  /** Connect timeout (ms) for upstream fetch — covers DNS, TCP, TLS, and response header. Default 200000. */
-  connectTimeoutMs?: number;
-  /** Graceful shutdown drain timeout (ms). Active turns are aborted after this deadline. Default 5000. */
-  shutdownTimeoutMs?: number;
-  /** Advertise supports_websockets so Codex opens the WS endpoint. Default false; set true to opt in. */
-  websockets?: boolean;
-  /**
-   * Opt-in auto-cleanup policy for archived Codex sessions (issue #42 Phase 3).
-   * Default OFF (`enabled` false / unset). Never enabled implicitly.
-   * See `src/storage/policy.ts`.
-   */
-  storageCleanupPolicy?: StorageCleanupPolicy;
-  /** Generated API keys for external access to the proxy's /v1/responses endpoint. */
-  apiKeys?: OcxApiKeyEntry[];
-  /** Auto-start/sync the proxy from the Codex shim before launching Codex. Default true. */
-  codexAutoStart?: boolean;
-  /** Restore an installed shim after a stable external Codex update replaces it. Default true. */
-  codexShimAutoRestore?: boolean;
-  /**
-   * Compatibility mode: temporarily rewrite Codex resume-history metadata while the proxy is active
-   * so Codex App can show old OpenAI chats and opencodex-created exec chats under its default
-   * interactive-source/provider filters. Default true; originals are backed up and restored by
-   * `ocx stop` / `ocx restore`. Set false to opt out of history remapping.
-   */
-  syncResumeHistory?: boolean;
-  /** Freshness window (ms) for the per-provider live `/models` cache. Defaults to 5 min. */
-  modelCacheTtlMs?: number;
-  /** Evictable retained app-state budget in MiB. Default 256; valid 64..4096. */
-  appOwnedMemoryBudgetMb?: number;
-  /** Anthropic prompt-cache retention: "short" = 5-min ephemeral (default), "long" = 1-hour extended, "none" = disabled. */
-  cacheRetention?: "none" | "short" | "long";
-  /** Web-search sidecar: route web_search for non-OpenAI models through a gpt-mini via ChatGPT passthrough. */
-  webSearchSidecar?: OcxWebSearchSidecarConfig;
-  /** Vision sidecar: describe images via a gpt vision model so text-only models can "see" them. */
-  visionSidecar?: OcxVisionSidecarConfig;
-  /** /v1/images relay for codex's built-in image_gen tool. */
-  images?: OcxImagesConfig;
-  /** /v1/alpha/search relay for codex's built-in web search client. */
-  search?: OcxSearchConfig;
-  /** Codex multi-account pool. */
-  codexAccounts?: CodexAccount[];
-  /** Account ids administratively excluded from future pool selection until resumed. */
-  pausedCodexAccountIds?: string[];
-  /**
-   * Public model-selector namespaces bound to one Codex account. Values are stored account ids;
-   * `"@main"` selects the Codex Desktop/main auth.json account. Account display aliases
-   * are intentionally separate from these selectors.
-   */
-  codexAccountNamespaces?: Record<string, string>;
-  /** Active pool account id for next session. undefined = main (passthrough as-is). */
-  activeCodexAccountId?: string;
-  /** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
-  autoSwitchThreshold?: number;
-  /** New-session account rotation strategy for the Codex pool. Default quota (today's behaviour). */
-  accountPoolStrategy?: OcxAccountPoolRotationStrategy;
-  /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
-  accountPoolStickyLimit?: number;
-  /** Consecutive non-2xx upstream responses before switching future new threads. Default 3. 0 = disabled. */
-  upstreamFailoverThreshold?: number;
-  /**
-   * Opt-in Anthropic OAuth account pool (#294). Default OFF.
-   * Failover on 429 + sticky affinity; new sessions may pick lowest known 5h usage.
-   * Experimental — see docs and GUI warning before enabling.
-   */
-  anthropicAccountPool?: {
-    enabled?: boolean;
-    /** Usage % threshold for new-session auto-pick. Default 80. 0 = disabled (affinity/active only). */
-    autoSwitchThreshold?: number;
-    /** New-session rotation strategy. Default quota (today's behaviour). */
-    strategy?: OcxAccountPoolRotationStrategy;
-    /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
-    stickyLimit?: number;
-  };
-  /** Virtual `combo/<id>` models spanning concrete provider/model targets (issue #133). */
-  combos?: Record<string, OcxComboConfig>;
-  /** Background proactive token refresh ("Token Guardian"). Off by default; see OcxTokenGuardianConfig. */
-  tokenGuardian?: OcxTokenGuardianConfig;
-  /** Additional origins allowed for CORS (e.g. ["https://clisu-oracle.tail19a2d7.ts.net"]). Loopback origins are always allowed. */
-  corsAllowOrigins?: string[];
-}
-
-export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
-
-export type OcxComboStrategy = "failover" | "round-robin";
-export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
-
-export interface OcxComboTarget {
-  provider: string;
-  model: string;
-  /** Relative SWRR batch weight. Default 1; valid range 1..10000. */
-  weight?: number;
-}
-
-export interface OcxComboConfig {
-  targets: OcxComboTarget[];
-  /** Ordered failover (default) or deterministic smooth weighted round-robin. */
-  strategy?: OcxComboStrategy;
-  /** Successful requests retained on one RR selection batch. Default 1; range 1..100. */
-  stickyLimit?: number;
-  /** Used when the client omits reasoning.effort. null/omitted leaves the target default unchanged. */
-  defaultEffort?: OcxComboDefaultEffort | null;
-  /**
-   * Optional public model name replacing the default `combo/<id>` slug. Bare names
-   * without "/" are allowed (e.g. "deepseek-v4-flash") so the combo can answer to a
-   * mandated model id; exact-match requests route here before any provider resolution.
-   */
-  alias?: string;
-}
-
-/**
- * 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";
-
-export interface OcxTokenGuardianConfig {
-  /** Global kill-switch. Default false — the guardian does nothing unless explicitly enabled. */
-  enabled?: boolean;
-  /** Seconds between refresh sweeps. Default 21600 (6h). Min 60. */
-  tickSeconds?: number;
-  /** Random 0..jitterSeconds added before each sweep to de-synchronize. Default 300. */
-  jitterSeconds?: number;
-  /** Max concurrent refreshes per sweep. Default 3. Min 1. */
-  concurrency?: number;
-  /** Extra lead (seconds) beyond one tick when deciding a token is "expiring soon". Default 900. */
-  leadSeconds?: number;
-  /** First backoff (seconds) after a permanent refresh failure. Default 300. */
-  failureBackoffBaseSeconds?: number;
-  /** Backoff ceiling (seconds). Default 3600. */
-  failureBackoffMaxSeconds?: number;
-  /** Optional Codex pool session warmup sweep. Default false to avoid background synthetic traffic. */
-  codexWarmupEnabled?: boolean;
-  /** Max age before a Codex pool account is revalidated via `/codex/responses`. Default 691200 (8d). */
-  codexWarmupMaxAgeSeconds?: number;
-  /** Model used for optional Codex pool warmup. Default gpt-5.4-mini. */
-  codexWarmupModel?: string;
-}
-
-export interface OcxImagesConfig {
-  /** Optional custom API-key provider for /v1/images relays. Built-in OpenAI tiers remain automatic. */
-  provider?: string;
-  /** Upstream timeout (ms) for one image generation/edit call (bridge xAI + /v1/images relay). Default 60000 for the bridge; relay may use a higher default (300000). */
-  timeoutMs?: number;
-  /** Master switch for the image bridge. Default false — set true to enable paid xAI Grok Imagine generation. */
-  bridgeEnabled?: boolean;
-  /** xAI image model id. Default "grok-imagine-image-quality" (see DEFAULT_MODEL in images/plan.ts). */
-  bridgeModel?: string;
-  /** Max image-generation loop iterations before forced-final. Default 3; clamped to [0, 10]. */
-  maxRounds?: number;
-  /** Max files retained under artifacts/. Oldest deleted when exceeded. Default 200. */
-  artifactsKeepCount?: number;
-  /** Master switch for the video bridge. Default false — must be explicitly opted in. */
-  videoBridgeEnabled?: boolean;
-  /** Model for xAI video generation. Default "grok-imagine-video". */
-  videoBridgeModel?: string;
-  /** Max video-gen rounds before forced-final. Default 2 (video is slower than image). */
-  videoMaxRounds?: number;
-  /** Per-video generation timeout (ms) including polling. Default 300000 (5 min). */
-  videoTimeoutMs?: number;
-}
-
-export interface OcxSearchConfig {
-  /**
-   * Total upstream deadline (ms) for one /v1/alpha/search relay. Default 200000. The endpoint
-   * is non-streaming JSON (headers arrive only when the search completes), so this is a whole-
-   * request budget — deliberately NOT connectTimeoutMs, which is a header-arrival budget.
-   */
-  timeoutMs?: number;
-}
-
-export interface OcxVisionSidecarConfig {
-  /** Master switch. Default: enabled when the selected backend has a usable credential. */
-  enabled?: boolean;
-  /** Description backend. Unset prefers a usable stored Anthropic OAuth credential, else OpenAI. */
-  backend?: "openai" | "anthropic";
-  /** Vision model that describes images. */
-  model?: string;
-  /** Max description cache misses admitted in one main-model turn. Zero disables description calls. */
-  maxDescriptionsPerTurn?: number;
-  /** Sidecar fetch timeout (ms). */
-  timeoutMs?: number;
-}
-
-export interface OcxWebSearchSidecarConfig {
-  /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
-  enabled?: boolean;
-  /**
-   * Which backend actually runs the server-side search. "openai" replays the hosted web_search via
-   * the ChatGPT forward provider (gpt-mini sidecar); "anthropic" runs web_search_20250305 on a Claude
-   * model authenticated by the STORED anthropic OAuth credential. Unset resolves to "anthropic" when a
-   * usable anthropic OAuth credential exists, else "openai".
-   */
-  backend?: "openai" | "anthropic";
-  /** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
-  model?: string;
-  /** Reasoning effort for the sidecar — "minimal" (non-thinking) keeps it fast/cheap. */
-  reasoning?: string;
-  /** Max searches executed per main-model turn (loop guard). */
-  maxSearchesPerTurn?: number;
-  /** Sidecar fetch timeout (ms). */
-  timeoutMs?: number;
-  /**
-   * Config-file-only deadline (ms) for continuous routed-model response-body raw-byte inactivity
-   * during a web-search turn. Default 200000. Must be an integer from 1 through 2147483647.
-   */
-  routedModelStallTimeoutMs?: number;
-}
-
-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 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;
-}
-
-export interface OcxProviderConfig {
-  adapter: string;
-  /** 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>;
-  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;
-  /**
-   * Responses upstream that stores nothing server-side (DeepSeek documents "the API
-   * is stateless"). Stateful request parameters are dropped, `store` is pinned false,
-   * and orphaned tool results left by a replay miss are repaired rather than
-   * forwarded to an upstream that cannot resolve their pair.
-   */
-  statelessResponses?: 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;
-  /** 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 }>;
-  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[];
-  /** Provider-wide Codex-visible context-window cap for routed catalog entries. */
-  contextWindow?: number;
-  /** Model-specific Codex-visible context-window caps. Values cap live metadata, never raise it. */
-  modelContextWindows?: Record<string, number>;
-  /** Model-specific Codex catalog input modalities, e.g. ["text"] or ["text", "image"]. */
-  modelInputModalities?: Record<string, string[]>;
-  /** Model-specific max input token limits. Values cap auto_compact_token_limit. */
-  modelMaxInputTokens?: 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>;
-  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>;
-  /**
-   * "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";
-  /** 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[]>;
-  /** Model-specific default Codex reasoning tier; must also be present in the visible tier list. */
-  modelDefaultReasoningEfforts?: 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>;
-  /**
-   * 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>;
-  /** Provider-wide mapping from Codex effort labels to upstream `reasoning_effort` values. */
-  reasoningEffortMap?: Record<string, string>;
-  /** Model-specific mapping from Codex effort labels to upstream `reasoning_effort` values. */
-  modelReasoningEffortMap?: Record<string, Record<string, string>>;
-  /**
-   * 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 presence/frequency penalty values. */
-  noPenaltyModels?: 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: 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;
-  /**
-   * 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 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 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;
-  /**
-   * 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";
-  /** 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/native-exec-desktop").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";
-}
-
-export const REASONING_SUMMARY_DELIVERY_VALUES = [
-  "sequential",
-  "sequential_cutoff",
-  "concurrent",
-  "concurrent_cutoff",
-] as const;
-
-export type ReasoningSummaryDelivery = typeof REASONING_SUMMARY_DELIVERY_VALUES[number];
-
-/** Trusted runtime ownership for Codex-account credentials. Never persisted per provider. */
-export type CodexAccountMode = "direct" | "pool";
-
-export const OPENAI_PROVIDER_TIER_VERSION = 2 as const;
-
-/**
- * Wires that a per-model `modelAdapters` override may select.
- *
- * Deliberately narrow: provider-specific adapters (cursor, kiro, google, ...) carry
- * their own credential and base-URL semantics, so exposing them here would widen the
- * auth boundary rather than pick a wire. Widening this set needs a per-adapter
- * credential threat model first (#404).
- */
-export const MODEL_ADAPTER_OVERRIDE_ALLOWED: ReadonlySet<string> = new Set([
-  "openai-chat",
-  "openai-responses",
-]);
-
-/**
- * Providers whose listed model ids must be driven over the Anthropic wire even when
- * the provider's configured adapter says otherwise — the upstream only speaks
- * Anthropic for these models.
- */
-const ANTHROPIC_WIRE_MODELS: Record<string, ReadonlySet<string>> = {
-  "opencode-go": new Set(["minimax-m2.5", "minimax-m2.7", "minimax-m3"]),
-};
-
-/**
- * True when the upstream speaks exactly one wire for this model, so a configured
- * override must not apply.
- *
- * Deliberately independent of the provider's current adapter: the wire resolver runs
- * more than once per request, and a check phrased as "pin differs from the current
- * adapter" would pass on the first pass and then let the override win on the second.
- */
-export function isWirePinnedModel(providerName: string, modelId: string): boolean {
-  return ANTHROPIC_WIRE_MODELS[providerName]?.has(modelId) ?? false;
-}
-
-/** The wire a pinned model must use, or undefined when the model is not pinned. */
-export function pinnedWireAdapter(providerName: string, modelId: string): string | undefined {
-  return isWirePinnedModel(providerName, modelId) ? "anthropic" : undefined;
-}
-
-export interface CodexAccount {
-  id: string;
-  email: string;
-  /** User-owned display label; never participates in routing or identity checks. */
-  alias?: string;
-  plan?: string;
-  chatgptAccountId?: string;
-  logLabel?: string;
-  isMain: boolean;
-}
-
-export interface CodexAccountCredentials {
-  accessToken: string;
-  refreshToken: string;
-  expiresAt: number;
-  chatgptAccountId: string;
-}
-
-export interface CodexAccountCredentialRecord {
-  credential?: CodexAccountCredentials;
-  generation: number;
-  refreshGrantFingerprint?: string;
-  deletedAt?: number;
-  replacedAt?: number;
-  lastCodexValidatedAt?: number;
-  lastCodexValidationStatus?: "ok" | "failed";
-  lastCodexValidationError?: string;
-}