@iislee/opencodex 2.11.0

package/src/providers/openai-sidecar.ts

@@ -0,0 +1,175 @@
+import { resolveEnvValue } from "../config";
+import {
+  headersForCodexAuthContext,
+  hasCallerCodexBearer,
+  isCodexAuthContextUsable,
+  resolveCodexAuthContext,
+  type CodexAuthContext,
+} from "../codex/auth-context";
+import { recordCodexUpstreamOutcome, type CodexUpstreamOutcome } from "../codex/routing";
+import { extractAccountId } from "../oauth/chatgpt";
+import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "../server/auth-cors";
+import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
+import {
+  isCanonicalOpenAiForwardProvider,
+  OPENAI_API_PROVIDER_ID,
+  OPENAI_CODEX_PROVIDER_ID,
+} from "./openai-tiers";
+import { getProviderRegistryEntry, providerCodexAccountMode } from "./registry";
+
+export interface OpenAiForwardSidecarCandidate {
+  providerName: typeof OPENAI_CODEX_PROVIDER_ID;
+  provider: OcxProviderConfig;
+  accountMode: CodexAccountMode;
+}
+
+export interface ResolvedOpenAiForwardSidecar extends OpenAiForwardSidecarCandidate {
+  authContext: CodexAuthContext;
+  headers: Headers;
+  recordOutcome?: (outcome: CodexUpstreamOutcome) => void;
+}
+
+export interface OpenAiImagesProviderSelection {
+  forwardCandidates: OpenAiForwardSidecarCandidate[];
+  keyed?: {
+    providerName: string;
+    provider: OcxProviderConfig;
+    apiKey: string;
+  };
+  error?: string;
+}
+
+export function listOpenAiForwardSidecarCandidates(config: OcxConfig): OpenAiForwardSidecarCandidate[] {
+  const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  if (!provider || provider.disabled === true || !isCanonicalOpenAiForwardProvider(provider)) return [];
+  return [{
+    providerName: OPENAI_CODEX_PROVIDER_ID,
+    provider,
+    accountMode: providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, provider) ?? "pool",
+  }];
+}
+
+function directSidecarHeaders(
+  incomingHeaders: Headers,
+): Headers | undefined {
+  const bearer = incomingHeaders.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  if (!bearer) return undefined;
+  const derivedAccountId = extractAccountId(undefined, bearer);
+  if (!derivedAccountId) return undefined;
+  const requestedAccountId = incomingHeaders.get("chatgpt-account-id")?.trim();
+  // JWT payloads are decoded locally but not signature-verified. Requiring the caller's
+  // explicit account header, and checking it against the token claim, makes forwarding an
+  // intentional ChatGPT-auth operation instead of silently reclassifying any JWT-shaped
+  // provider credential as a Codex bearer.
+  if (!requestedAccountId || requestedAccountId !== derivedAccountId) return undefined;
+  const selected = headersForCodexAuthContext(incomingHeaders, { kind: "main", accountId: null });
+  return selected;
+}
+
+export async function resolveFirstUsableOpenAiSidecar(
+  candidates: readonly OpenAiForwardSidecarCandidate[],
+  incomingHeaders: Headers,
+  config: OcxConfig,
+): Promise<ResolvedOpenAiForwardSidecar | undefined> {
+  let callerBearerMayBeForwarded = true;
+  try {
+    validateForwardAdmissionCredential(incomingHeaders, config);
+  } catch (error) {
+    if (!(error instanceof ForwardAdmissionCredentialError)) throw error;
+    callerBearerMayBeForwarded = false;
+  }
+  for (const candidate of candidates) {
+    if (candidate.accountMode === "direct") {
+      if (!callerBearerMayBeForwarded || !hasCallerCodexBearer(incomingHeaders)) continue;
+      const headers = directSidecarHeaders(incomingHeaders);
+      if (!headers) continue;
+      return {
+        ...candidate,
+        authContext: { kind: "main", accountId: null },
+        headers,
+      };
+    }
+    const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode);
+    if (!isCodexAuthContextUsable(authContext, config)) continue;
+    return {
+      ...candidate,
+      authContext,
+      headers: headersForCodexAuthContext(incomingHeaders, authContext),
+      ...(authContext.kind === "pool" || authContext.kind === "main-pool"
+        ? {
+          recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
+            config,
+            authContext.accountId,
+            outcome,
+            {
+              probeLeaseId: authContext.probeLeaseId,
+              writerGeneration: authContext.writerGeneration,
+            },
+          ),
+        }
+        : {}),
+    };
+  }
+  return undefined;
+}
+
+export function selectOpenAiImagesProvider(config: OcxConfig): OpenAiImagesProviderSelection {
+  const selection: OpenAiImagesProviderSelection = {
+    forwardCandidates: listOpenAiForwardSidecarCandidates(config),
+  };
+  const provider = config.providers[OPENAI_API_PROVIDER_ID];
+  if (
+    provider
+    && provider.disabled !== true
+    && provider.adapter === "openai-responses"
+    && provider.authMode !== "forward"
+    && provider.baseUrl.replace(/\/+$/, "") === "https://api.openai.com/v1"
+  ) {
+    const apiKey = resolveEnvValue(provider.apiKey)?.trim();
+    if (apiKey) selection.keyed = { providerName: OPENAI_API_PROVIDER_ID, provider, apiKey };
+  }
+  return selection;
+}
+
+/** Resolve an explicit custom Images provider, otherwise preserve the existing OpenAI fallback. */
+export function selectImagesProvider(config: OcxConfig): OpenAiImagesProviderSelection {
+  const configuredProvider = config.images?.provider;
+  if (configuredProvider === undefined) return selectOpenAiImagesProvider(config);
+  if (typeof configuredProvider !== "string" || !configuredProvider.trim()) {
+    return { forwardCandidates: [], error: "images.provider must be a nonblank provider name" };
+  }
+  const providerName = configuredProvider.trim();
+
+  if (getProviderRegistryEntry(providerName)) {
+    return {
+      forwardCandidates: [],
+      error: `images.provider "${providerName}" must name a custom provider; omit it to use built-in OpenAI tiers`,
+    };
+  }
+
+  const provider = Object.prototype.hasOwnProperty.call(config.providers, providerName)
+    ? config.providers[providerName]
+    : undefined;
+  if (!provider) {
+    return { forwardCandidates: [], error: `images.provider "${providerName}" is not configured` };
+  }
+  if (provider.disabled === true) {
+    return { forwardCandidates: [], error: `images.provider "${providerName}" is disabled` };
+  }
+  if (provider.adapter !== "openai-responses" || (provider.authMode !== undefined && provider.authMode !== "key")) {
+    return {
+      forwardCandidates: [],
+      error: `images.provider "${providerName}" must be an API-key openai-responses provider`,
+    };
+  }
+
+  const apiKey = resolveEnvValue(provider.apiKey)?.trim();
+  if (!apiKey) {
+    return { forwardCandidates: [], error: `images.provider "${providerName}" has no usable API key` };
+  }
+
+  return {
+    forwardCandidates: [],
+    keyed: { providerName, provider, apiKey },
+  };
+}

package/src/providers/openai-tier-startup.ts

@@ -0,0 +1,27 @@
+import { backupConfigBeforeOpenAiTierMigration, saveConfig } from "../config";
+import type { OcxConfig } from "../types";
+import { projectOpenAiTierMigration } from "./openai-tiers";
+
+export interface OpenAiTierStartupDeps {
+  project: typeof projectOpenAiTierMigration;
+  backup: () => void;
+  save: (config: OcxConfig) => void;
+}
+
+const DEFAULT_DEPS: OpenAiTierStartupDeps = {
+  project: projectOpenAiTierMigration,
+  backup: backupConfigBeforeOpenAiTierMigration,
+  save: saveConfig,
+};
+
+export function runOpenAiTierStartupMigration(
+  config: OcxConfig,
+  deps: OpenAiTierStartupDeps = DEFAULT_DEPS,
+): OcxConfig {
+  const projection = deps.project(config);
+  if (!projection.changed) return projection.config;
+  deps.backup();
+  deps.save(projection.config);
+  for (const warning of projection.warnings) console.warn(`[openai-provider-migration] ${warning}`);
+  return projection.config;
+}

package/src/providers/openai-tiers.ts

@@ -0,0 +1,301 @@
+import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
+import { OPENAI_PROVIDER_TIER_VERSION } from "../types";
+
+export const OPENAI_CODEX_PROVIDER_ID = "openai";
+export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
+export const OPENAI_API_PROVIDER_ID = "openai-apikey";
+export const LEGACY_CHATGPT_PROVIDER_ID = "chatgpt";
+
+export const CODEX_FORWARD_BASE_URL = "https://chatgpt.com/backend-api/codex";
+const LEGACY_OPENAI_MULTI_PREFIX = `${LEGACY_OPENAI_MULTI_PROVIDER_ID}/`;
+
+function canonicalCodexForwardProvider(mode: CodexAccountMode): OcxProviderConfig {
+  return {
+    adapter: "openai-responses",
+    baseUrl: CODEX_FORWARD_BASE_URL,
+    authMode: "forward",
+    codexAccountMode: mode,
+  };
+}
+
+function normalizedBaseUrl(value: string): string | undefined {
+  try {
+    const url = new URL(value.trim());
+    if (url.username || url.password || url.search || url.hash) return undefined;
+    const path = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}${path}`;
+  } catch {
+    return undefined;
+  }
+}
+
+export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): boolean {
+  return provider.adapter === "openai-responses"
+    && provider.authMode === "forward"
+    && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
+}
+
+const OPENAI_API_BASE_URL = "https://api.openai.com/v1";
+
+/**
+ * Whether this provider can serve `POST /responses/compact`. The canonical ChatGPT
+ * backend can, and so can the official OpenAI API — but an arbitrary gateway that
+ * merely speaks the Responses wire cannot, and calling it there fails compaction
+ * with an unhelpful error instead of falling back to a routed summary (#422).
+ */
+export function supportsNativeResponsesCompactEndpoint(
+  providerName: string,
+  provider: OcxProviderConfig,
+): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return providerName === OPENAI_API_PROVIDER_ID
+    && provider.adapter === "openai-responses"
+    && normalizedBaseUrl(provider.baseUrl) === OPENAI_API_BASE_URL;
+}
+
+export interface OpenAiTierMigrationProjection {
+  config: OcxConfig;
+  changed: boolean;
+  resolvedMode: CodexAccountMode;
+  warnings: string[];
+}
+
+export class OpenAiTierMigrationCollisionError extends Error {
+  readonly providerName = LEGACY_OPENAI_MULTI_PROVIDER_ID;
+
+  constructor() {
+    super(`Reserved provider id "${LEGACY_OPENAI_MULTI_PROVIDER_ID}" is already configured with a noncanonical shape`);
+    this.name = "OpenAiTierMigrationCollisionError";
+  }
+}
+
+function managedLegacyMultiOverlay(provider: OcxProviderConfig): Pick<OcxProviderConfig, "disabled" | "selectedModels"> | null {
+  const allowed = new Set(["adapter", "authMode", "baseUrl", "disabled", "selectedModels"]);
+  if (!Object.keys(provider).every(key => allowed.has(key))) return null;
+  if (!isCanonicalOpenAiForwardProvider(provider)) return null;
+  if (provider.disabled !== undefined && typeof provider.disabled !== "boolean") return null;
+  if (provider.selectedModels !== undefined && (
+    !Array.isArray(provider.selectedModels)
+    || provider.selectedModels.some(model => typeof model !== "string")
+  )) return null;
+  return {
+    ...(provider.disabled !== undefined ? { disabled: provider.disabled } : {}),
+    ...(provider.selectedModels !== undefined ? { selectedModels: [...provider.selectedModels] } : {}),
+  };
+}
+
+function rewriteLegacyOpenAiSelectedId(value: string): string {
+  return value.startsWith(LEGACY_OPENAI_MULTI_PREFIX)
+    ? value.slice(LEGACY_OPENAI_MULTI_PREFIX.length)
+    : value;
+}
+
+function rewriteLegacyOpenAiModelList(values: string[] | undefined): string[] | undefined {
+  if (!values) return undefined;
+  return [...new Set(values.map(rewriteLegacyOpenAiSelectedId))];
+}
+
+function mergeLegacyOpenAiProviderRows(
+  openai: OcxProviderConfig | undefined,
+  legacyMulti: OcxProviderConfig | undefined,
+  mode: CodexAccountMode,
+): OcxProviderConfig {
+  const selectedModels = rewriteLegacyOpenAiModelList([
+    ...(openai?.selectedModels ?? []),
+    ...(legacyMulti?.selectedModels ?? []),
+  ]);
+  const formerRows = [openai, legacyMulti].filter((row): row is OcxProviderConfig => row !== undefined);
+  const disabled = formerRows.length > 0 && formerRows.every(row => row.disabled === true);
+  return {
+    ...canonicalCodexForwardProvider(mode),
+    ...(disabled ? { disabled: true } : {}),
+    ...(selectedModels && selectedModels.length > 0 ? { selectedModels } : {}),
+  };
+}
+
+function hasKnownLegacyOpenAiReference(config: OcxConfig): boolean {
+  const matches = (value: unknown): boolean => typeof value === "string" && value.startsWith(LEGACY_OPENAI_MULTI_PREFIX);
+  const matchesList = (value: unknown): boolean => Array.isArray(value) && value.some(matches);
+  const claude = config.claudeCode;
+  return config.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || matchesList(config.disabledModels)
+    || matchesList(config.subagentModels)
+    || matches(config.injectionModel)
+    || matches(config.shadowCallIntercept?.model)
+    || matches(config.webSearchSidecar?.model)
+    || matches(config.visionSidecar?.model)
+    || matches(claude?.webSearchSidecar?.model)
+    || matches(claude?.visionSidecar?.model)
+    || matches(claude?.model)
+    || matches(claude?.smallFastModel)
+    || Object.values(claude?.tierModels ?? {}).some(matches)
+    || Object.values(claude?.modelMap ?? {}).some(matches)
+    || matchesList(config.providers[OPENAI_CODEX_PROVIDER_ID]?.selectedModels)
+    || matchesList(config.providers[LEGACY_OPENAI_MULTI_PROVIDER_ID]?.selectedModels)
+    || config.providerContextCaps?.[LEGACY_OPENAI_MULTI_PROVIDER_ID] !== undefined;
+}
+
+function rewriteLegacyOpenAiReferences(config: OcxConfig, warnings: string[]): void {
+  config.disabledModels = rewriteLegacyOpenAiModelList(config.disabledModels);
+  config.subagentModels = rewriteLegacyOpenAiModelList(config.subagentModels);
+  if (config.injectionModel) config.injectionModel = rewriteLegacyOpenAiSelectedId(config.injectionModel);
+  if (config.shadowCallIntercept?.model) {
+    config.shadowCallIntercept.model = rewriteLegacyOpenAiSelectedId(config.shadowCallIntercept.model);
+  }
+  if (config.webSearchSidecar?.model) config.webSearchSidecar.model = rewriteLegacyOpenAiSelectedId(config.webSearchSidecar.model);
+  if (config.visionSidecar?.model) config.visionSidecar.model = rewriteLegacyOpenAiSelectedId(config.visionSidecar.model);
+
+  const claude = config.claudeCode;
+  if (claude?.webSearchSidecar?.model) claude.webSearchSidecar.model = rewriteLegacyOpenAiSelectedId(claude.webSearchSidecar.model);
+  if (claude?.visionSidecar?.model) claude.visionSidecar.model = rewriteLegacyOpenAiSelectedId(claude.visionSidecar.model);
+  if (claude?.model) claude.model = rewriteLegacyOpenAiSelectedId(claude.model);
+  if (claude?.smallFastModel) claude.smallFastModel = rewriteLegacyOpenAiSelectedId(claude.smallFastModel);
+  if (claude?.tierModels) {
+    for (const tier of ["opus", "sonnet", "haiku", "fable"] as const) {
+      const value = claude.tierModels[tier];
+      if (value) claude.tierModels[tier] = rewriteLegacyOpenAiSelectedId(value);
+    }
+  }
+  if (claude?.modelMap) {
+    for (const key of Object.keys(claude.modelMap)) {
+      claude.modelMap[key] = rewriteLegacyOpenAiSelectedId(claude.modelMap[key]!);
+    }
+  }
+
+  const caps = config.providerContextCaps;
+  const legacyCap = caps?.[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  if (caps && legacyCap !== undefined) {
+    const currentCap = caps[OPENAI_CODEX_PROVIDER_ID];
+    if (currentCap !== undefined) {
+      caps[OPENAI_CODEX_PROVIDER_ID] = Math.min(currentCap, legacyCap);
+      warnings.push("providerContextCaps.openai + providerContextCaps.openai-multi: kept lower positive cap");
+    } else {
+      caps[OPENAI_CODEX_PROVIDER_ID] = legacyCap;
+    }
+    delete caps[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  }
+}
+
+function isKnownLegacyValuePath(path: readonly string[]): boolean {
+  const joined = path.join(".");
+  if (joined === "defaultProvider") return true;
+  if (/^(disabledModels|subagentModels)\.\d+$/.test(joined)) return true;
+  if (/^providers\.(openai|openai-multi)\.selectedModels\.\d+$/.test(joined)) return true;
+  return new Set([
+    "injectionModel",
+    "shadowCallIntercept.model",
+    "webSearchSidecar.model",
+    "visionSidecar.model",
+    "claudeCode.webSearchSidecar.model",
+    "claudeCode.visionSidecar.model",
+    "claudeCode.model",
+    "claudeCode.smallFastModel",
+    "claudeCode.tierModels.opus",
+    "claudeCode.tierModels.sonnet",
+    "claudeCode.tierModels.haiku",
+    "claudeCode.tierModels.fable",
+  ]).has(joined) || /^claudeCode\.modelMap\..+$/.test(joined);
+}
+
+function unknownLegacyOpenAiWarnings(config: OcxConfig): string[] {
+  const warnings = new Set<string>();
+  const visit = (value: unknown, path: string[]): void => {
+    if (typeof value === "string") {
+      if (value.includes(LEGACY_OPENAI_MULTI_PROVIDER_ID) && !isKnownLegacyValuePath(path)) {
+        warnings.add(`${path.join(".")}: legacy OpenAI provider id left unchanged`);
+      }
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => visit(item, [...path, String(index)]));
+      return;
+    }
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      visit(item, [...path, key]);
+    }
+  };
+  visit(config, []);
+  return [...warnings];
+}
+
+function resolvedOpenAiMode(
+  config: OcxConfig,
+  openai: OcxProviderConfig | undefined,
+  legacyMulti: OcxProviderConfig | undefined,
+  knownLegacyReference: boolean,
+): CodexAccountMode {
+  if (openai?.codexAccountMode === "pool" || openai?.codexAccountMode === "direct") {
+    return openai.codexAccountMode;
+  }
+  if (
+    (legacyMulti && legacyMulti.disabled !== true)
+    || config.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || knownLegacyReference
+  ) return "pool";
+  if (config.openaiProviderTierVersion === 1 && openai) return "direct";
+  if (config.openaiProviderTierVersion === 1 && legacyMulti) return "pool";
+  return "pool";
+}
+
+export function projectOpenAiTierMigration(config: OcxConfig): OpenAiTierMigrationProjection {
+  const projected = structuredClone(config);
+  const legacyMulti = projected.providers[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  if (legacyMulti && !managedLegacyMultiOverlay(legacyMulti)) {
+    throw new OpenAiTierMigrationCollisionError();
+  }
+
+  const openai = projected.providers[OPENAI_CODEX_PROVIDER_ID];
+  const knownLegacyReference = hasKnownLegacyOpenAiReference(projected);
+  const resolvedMode = resolvedOpenAiMode(projected, openai, legacyMulti, knownLegacyReference);
+  if (
+    projected.openaiProviderTierVersion === OPENAI_PROVIDER_TIER_VERSION
+    && !legacyMulti
+    && !Object.hasOwn(projected.providers, LEGACY_CHATGPT_PROVIDER_ID)
+    && projected.defaultProvider !== LEGACY_OPENAI_MULTI_PROVIDER_ID
+    && !knownLegacyReference
+  ) {
+    return { config: projected, changed: false, resolvedMode, warnings: [] };
+  }
+
+  const warnings = unknownLegacyOpenAiWarnings(projected);
+  const referencesCodexForward = !!openai
+    || !!legacyMulti
+    || Object.hasOwn(projected.providers, LEGACY_CHATGPT_PROVIDER_ID)
+    || projected.defaultProvider === OPENAI_CODEX_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_CHATGPT_PROVIDER_ID
+    || knownLegacyReference;
+  const mergedOpenAi = referencesCodexForward
+    ? mergeLegacyOpenAiProviderRows(openai, legacyMulti, resolvedMode)
+    : undefined;
+
+  const nextProviders: Array<[string, OcxProviderConfig]> = [];
+  let inserted = false;
+  for (const [name, provider] of Object.entries(projected.providers)) {
+    if (name === OPENAI_CODEX_PROVIDER_ID) {
+      if (mergedOpenAi && !inserted) nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+      inserted = true;
+      continue;
+    }
+    if (name === LEGACY_OPENAI_MULTI_PROVIDER_ID || name === LEGACY_CHATGPT_PROVIDER_ID) {
+      if (mergedOpenAi && !inserted && !openai) {
+        nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+        inserted = true;
+      }
+      continue;
+    }
+    nextProviders.push([name, provider]);
+  }
+  if (mergedOpenAi && !inserted) nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+  projected.providers = Object.fromEntries(nextProviders);
+
+  if (
+    projected.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_CHATGPT_PROVIDER_ID
+  ) projected.defaultProvider = OPENAI_CODEX_PROVIDER_ID;
+
+  rewriteLegacyOpenAiReferences(projected, warnings);
+  projected.openaiProviderTierVersion = OPENAI_PROVIDER_TIER_VERSION;
+  return { config: projected, changed: true, resolvedMode, warnings: [...new Set(warnings)] };
+}

package/src/providers/openai-virtual-models.ts

@@ -0,0 +1,82 @@
+import { PROVIDER_REGISTRY } from "./registry";
+import { OPENAI_API_PROVIDER_ID } from "./openai-tiers";
+import type { OcxParsedRequest } from "../types";
+import type { RouteResult } from "../router";
+import type { RequestLogContext } from "../server/request-log";
+
+export interface OpenAiVirtualModelResolution {
+  selectedModelId: string;
+  wireModelId: string;
+  reasoningMode: "pro";
+}
+
+export class InvalidOpenAiVirtualModelRegistryError extends Error {
+  constructor(selectedModelId: string) {
+    super(`Invalid OpenAI virtual model registry definition: ${selectedModelId}`);
+    this.name = "InvalidOpenAiVirtualModelRegistryError";
+  }
+}
+
+export function validateOpenAiVirtualModelDefinition(
+  selectedModelId: string,
+  definition: unknown,
+): OpenAiVirtualModelResolution {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new InvalidOpenAiVirtualModelRegistryError(selectedModelId);
+  }
+  const raw = definition as { wireModelId?: unknown; reasoningMode?: unknown };
+  if (
+    typeof raw.wireModelId !== "string"
+    || raw.wireModelId.trim() !== raw.wireModelId
+    || raw.wireModelId.length === 0
+    || raw.wireModelId.includes("/")
+    || raw.wireModelId === selectedModelId
+    || raw.reasoningMode !== "pro"
+  ) {
+    throw new InvalidOpenAiVirtualModelRegistryError(selectedModelId);
+  }
+  return { selectedModelId, wireModelId: raw.wireModelId, reasoningMode: "pro" };
+}
+
+export function resolveOpenAiVirtualModel(
+  providerName: string,
+  selectedModelId: string,
+): OpenAiVirtualModelResolution | undefined {
+  if (providerName !== OPENAI_API_PROVIDER_ID) return undefined;
+  const entry = PROVIDER_REGISTRY.find(row => row.id === OPENAI_API_PROVIDER_ID);
+  if (!entry?.virtualModels || !Object.hasOwn(entry.virtualModels, selectedModelId)) return undefined;
+  const definition = entry.virtualModels[selectedModelId];
+  return validateOpenAiVirtualModelDefinition(selectedModelId, definition);
+}
+
+export function applyOpenAiVirtualModel(
+  parsed: OcxParsedRequest,
+  route: RouteResult,
+  logCtx: RequestLogContext,
+): OpenAiVirtualModelResolution | undefined {
+  const selectedModelId = logCtx.model && logCtx.model !== route.modelId ? logCtx.model : route.modelId;
+  const resolution = resolveOpenAiVirtualModel(route.providerName, selectedModelId);
+  if (!resolution) return undefined;
+
+  logCtx.model = resolution.selectedModelId;
+  logCtx.resolvedModel = resolution.wireModelId;
+  route.modelId = resolution.wireModelId;
+  parsed.modelId = resolution.wireModelId;
+
+  if (parsed._rawBody && typeof parsed._rawBody === "object" && !Array.isArray(parsed._rawBody)) {
+    const raw = parsed._rawBody as Record<string, unknown>;
+    raw.model = resolution.wireModelId;
+    const existing = raw.reasoning;
+    raw.reasoning = existing && typeof existing === "object" && !Array.isArray(existing)
+      ? { ...(existing as Record<string, unknown>), mode: resolution.reasoningMode }
+      : { mode: resolution.reasoningMode };
+  }
+  return resolution;
+}
+
+export function resolveOpenAiCompactModel(
+  providerName: string,
+  selectedModelId: string,
+): OpenAiVirtualModelResolution | undefined {
+  return resolveOpenAiVirtualModel(providerName, selectedModelId);
+}

package/src/providers/openrouter-routing.ts

@@ -0,0 +1,102 @@
+import type { OcxProviderConfig, OpenRouterProviderRouting } from "../types";
+
+const ROUTING_KEYS = new Set(["order", "only", "allowFallbacks"]);
+const MAX_PROVIDER_SLUGS = 64;
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function isCanonicalOpenRouterTarget(baseUrl: string): boolean {
+  try {
+    const url = new URL(baseUrl);
+    return url.origin === "https://openrouter.ai"
+      && !url.username
+      && !url.password
+      && !url.search
+      && !url.hash
+      && url.pathname.replace(/\/+$/, "") === "/api/v1";
+  } catch {
+    return false;
+  }
+}
+
+function routingPreferenceError(value: unknown, field: string): string | null {
+  if (!isPlainRecord(value)) return `${field} must be a plain object`;
+  const unknown = Object.keys(value).find(key => !ROUTING_KEYS.has(key));
+  if (unknown) return `${field} contains unknown field "${unknown}"`;
+
+  for (const listField of ["order", "only"] as const) {
+    const list = value[listField];
+    if (list === undefined) continue;
+    if (!Array.isArray(list) || list.length === 0 || list.length > MAX_PROVIDER_SLUGS) {
+      return `${field}.${listField} must contain 1-${MAX_PROVIDER_SLUGS} provider slugs`;
+    }
+    const seen = new Set<string>();
+    for (const slug of list) {
+      if (typeof slug !== "string" || !slug.trim() || slug !== slug.trim() || slug.length > 128) {
+        return `${field}.${listField} must contain nonblank trimmed provider slugs up to 128 characters`;
+      }
+      if (seen.has(slug)) return `${field}.${listField} must not contain duplicate provider slugs`;
+      seen.add(slug);
+    }
+  }
+  if (value.allowFallbacks !== undefined && typeof value.allowFallbacks !== "boolean") {
+    return `${field}.allowFallbacks must be a boolean`;
+  }
+  if (value.order === undefined && value.only === undefined && value.allowFallbacks === undefined) {
+    return `${field} must define order, only, or allowFallbacks`;
+  }
+  return null;
+}
+
+export function openRouterRoutingConfigError(provider: OcxProviderConfig): string | null {
+  const hasDefault = provider.openRouterRouting !== undefined;
+  const hasModels = provider.modelOpenRouterRouting !== undefined;
+  if (!hasDefault && !hasModels) return null;
+  if (provider.adapter !== "openai-chat") {
+    return "OpenRouter routing preferences require the openai-chat adapter";
+  }
+  if (!isCanonicalOpenRouterTarget(provider.baseUrl)) {
+    return "OpenRouter routing preferences require the canonical https://openrouter.ai/api/v1 baseUrl";
+  }
+  if (hasDefault) {
+    const error = routingPreferenceError(provider.openRouterRouting, "openRouterRouting");
+    if (error) return error;
+  }
+  if (hasModels) {
+    const routes = provider.modelOpenRouterRouting;
+    if (!isPlainRecord(routes)) return "modelOpenRouterRouting must be a plain object";
+    for (const [modelId, preference] of Object.entries(routes)) {
+      if (!modelId.trim() || modelId !== modelId.trim()) {
+        return "modelOpenRouterRouting keys must be nonblank trimmed model ids";
+      }
+      const error = routingPreferenceError(preference, `modelOpenRouterRouting.${modelId}`);
+      if (error) return error;
+    }
+  }
+  return null;
+}
+
+export function resolveOpenRouterRouting(
+  provider: OcxProviderConfig,
+  modelId: string,
+): OpenRouterProviderRouting | undefined {
+  if (!isCanonicalOpenRouterTarget(provider.baseUrl)) return undefined;
+  const modelRoutes = provider.modelOpenRouterRouting;
+  return modelRoutes && Object.hasOwn(modelRoutes, modelId)
+    ? modelRoutes[modelId]
+    : provider.openRouterRouting;
+}
+
+export function openRouterProviderPayload(
+  preference: OpenRouterProviderRouting,
+): Record<string, unknown> {
+  return {
+    ...(preference.order ? { order: [...preference.order] } : {}),
+    ...(preference.only ? { only: [...preference.only] } : {}),
+    ...(preference.allowFallbacks !== undefined ? { allow_fallbacks: preference.allowFallbacks } : {}),
+  };
+}