@remodex/rmx 1.0.2

package/src/providers/model-discovery-limits.ts

@@ -0,0 +1,16 @@
+/** Hard process-wide limits shared by all live model-discovery parsers. */
+export const MODEL_DISCOVERY_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+export const MODEL_DISCOVERY_MAX_MODELS = 2_000;
+export const MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH = 1_024;
+
+const MODEL_DISCOVERY_MODEL_ID_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+
+/** Reject model IDs that cannot safely be published as callable catalog selectors. */
+export function isValidModelDiscoveryModelId(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const normalized = value.trim();
+  return Boolean(normalized)
+    && normalized === value
+    && normalized.length <= MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH
+    && !MODEL_DISCOVERY_MODEL_ID_CONTROL_CHARS.test(normalized);
+}

package/src/providers/model-discovery.ts

@@ -0,0 +1,361 @@
+import type { OcxProviderConfig } from "../types";
+import {
+  isValidModelDiscoveryModelId,
+  MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH,
+  MODEL_DISCOVERY_MAX_MODELS,
+  MODEL_DISCOVERY_MAX_RESPONSE_BYTES,
+} from "./model-discovery-limits";
+export {
+  isValidModelDiscoveryModelId,
+  MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH,
+  MODEL_DISCOVERY_MAX_MODELS,
+  MODEL_DISCOVERY_MAX_RESPONSE_BYTES,
+} from "./model-discovery-limits";
+import {
+  getProviderRegistryEntry,
+  providerMatchesRegistryTransport,
+  registryEntryForProviderDestination,
+  type ProviderModelDiscoveryFilter,
+  type ProviderModelDiscoveryPredicate,
+  type ProviderModelDiscoveryScalar,
+  type ProviderModelDiscoverySpec,
+} from "./registry";
+
+const MODEL_DISCOVERY_MAX_FILTER_VALUES = 256;
+const MODEL_DISCOVERY_MAX_FILTER_STRING_LENGTH = 1_024;
+
+export interface ResolvedProviderModelDiscovery {
+  spec?: ProviderModelDiscoverySpec;
+  maxResponseBytes: number;
+  maxModels: number;
+}
+
+export type ProviderModelsApiItem = Record<string, unknown> & { id: string };
+
+export type ModelDiscoveryResponseFailure =
+  | "response_too_large"
+  | "invalid_json"
+  | "invalid_shape"
+  | "too_many_models";
+
+export type BoundedDiscoveryJsonResult =
+  | { ok: true; value: unknown }
+  | { ok: false; reason: "response_too_large" | "invalid_json" };
+
+export type ProviderModelItemsResult =
+  | { ok: true; items: ProviderModelsApiItem[]; rawCount: number }
+  | { ok: false; reason: "invalid_shape" | "too_many_models" };
+
+export type ModelEnvelopeRowsResult =
+  | { ok: true; rows: unknown[] }
+  | { ok: false; reason: "invalid_shape" | "too_many_models" };
+
+function positiveIntegerAtMost(value: number | undefined, hardLimit: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return hardLimit;
+  return Math.min(Math.floor(value), hardLimit);
+}
+
+function discoveryPredicateError(predicate: ProviderModelDiscoveryPredicate): string | null {
+  if (!Array.isArray(predicate.path) || predicate.path.length === 0 || predicate.path.length > 8) {
+    return "predicate path must contain 1-8 segments";
+  }
+  if (predicate.path.some(segment => typeof segment !== "string" || !segment.trim() || segment.length > 64)) {
+    return "predicate path segments must be nonblank strings up to 64 characters";
+  }
+  const values = "equalsAny" in predicate
+    ? predicate.equalsAny
+    : "containsAny" in predicate
+      ? predicate.containsAny
+      : predicate.containsAll;
+  if (!Array.isArray(values) || values.length === 0 || values.length > 32) {
+    return "predicate values must contain 1-32 scalars";
+  }
+  if (values.some(value => (
+    (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean")
+    || (typeof value === "string" && (!value.trim() || value.length > 128))
+    || (typeof value === "number" && !Number.isFinite(value))
+  ))) {
+    return "predicate values must be finite booleans/numbers or nonblank strings up to 128 characters";
+  }
+  return null;
+}
+
+/** Static registry validation used by parity tests; discovery metadata never comes from config. */
+export function providerModelDiscoverySpecError(spec: ProviderModelDiscoverySpec): string | null {
+  if (spec.url && spec.path) return "url and path are mutually exclusive";
+  if (spec.url !== undefined) {
+    try {
+      const parsed = new URL(spec.url);
+      if (parsed.protocol !== "https:") return "absolute discovery url must use https";
+      if (parsed.username || parsed.password || parsed.hash) return "absolute discovery url must not contain credentials or a fragment";
+    } catch {
+      return "absolute discovery url must be valid";
+    }
+  }
+  if (spec.path !== undefined) {
+    const path = spec.path.trim();
+    if (!path || path.length > 512) return "discovery path must be 1-512 characters";
+    if (/^[a-z][a-z\d+.-]*:/i.test(path) || path.startsWith("//") || path.includes("?") || path.includes("#")) {
+      return "discovery path must be a query-free relative/origin path";
+    }
+    if (path.includes("\\")) return "discovery path must use forward slashes";
+    if (path.split("/").some(segment => segment.replace(/%2e/gi, ".") === "..")) {
+      return "discovery path must not contain parent-directory segments";
+    }
+  }
+  const queryEntries = Object.entries(spec.query ?? {});
+  if (queryEntries.length > 32) return "discovery query may contain at most 32 entries";
+  if (queryEntries.some(([key, value]) => !key.trim() || key.length > 128 || typeof value !== "string" || value.length > 512)) {
+    return "discovery query keys/values exceed their bounds";
+  }
+  for (const [field, value, hardLimit] of [
+    ["maxResponseBytes", spec.maxResponseBytes, MODEL_DISCOVERY_MAX_RESPONSE_BYTES],
+    ["maxModels", spec.maxModels, MODEL_DISCOVERY_MAX_MODELS],
+  ] as const) {
+    if (value !== undefined && (!Number.isInteger(value) || value <= 0 || value > hardLimit)) {
+      return `${field} must be a positive integer no greater than ${hardLimit}`;
+    }
+  }
+  for (const [group, predicates] of Object.entries(spec.filter ?? {})) {
+    if (!Array.isArray(predicates) || predicates.length === 0 || predicates.length > 32) {
+      return `${group} must contain 1-32 predicates`;
+    }
+    for (const predicate of predicates) {
+      const error = discoveryPredicateError(predicate);
+      if (error) return `${group}: ${error}`;
+    }
+  }
+  return null;
+}
+
+export function resolveProviderModelDiscovery(
+  providerName: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+): ResolvedProviderModelDiscovery {
+  // The dashboard permits a canonical preset to be saved under a different name. Recover its
+  // registry-owned discovery policy by transport in that case. The destination helper is limited
+  // to exact fixed-key baseUrl + adapter matches, so custom endpoints, OAuth rows, templates, and
+  // overridable destinations cannot acquire another provider's discovery URL or filter.
+  const namedEntry = getProviderRegistryEntry(providerName);
+  const entry = namedEntry
+    ? (providerMatchesRegistryTransport(providerName, provider) ? namedEntry : undefined)
+    : registryEntryForProviderDestination(provider);
+  const spec = entry?.modelDiscovery;
+  return {
+    ...(spec ? { spec } : {}),
+    maxResponseBytes: positiveIntegerAtMost(spec?.maxResponseBytes, MODEL_DISCOVERY_MAX_RESPONSE_BYTES),
+    maxModels: positiveIntegerAtMost(spec?.maxModels, MODEL_DISCOVERY_MAX_MODELS),
+  };
+}
+
+function appendDiscoveryQuery(url: URL, query: Readonly<Record<string, string>> | undefined): URL {
+  for (const [key, value] of Object.entries(query ?? {})) url.searchParams.set(key, value);
+  return url;
+}
+
+/** Apply a registry-owned URL/path/query policy to the adapter's normal discovery endpoint. */
+export function resolveProviderModelDiscoveryUrl(
+  providerName: string,
+  configuredProvider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+  effectiveBaseUrl: string,
+  defaultUrl: string,
+): string {
+  const { spec } = resolveProviderModelDiscovery(providerName, configuredProvider);
+  if (!spec) return defaultUrl;
+
+  let resolved: URL;
+  if (spec.url) {
+    resolved = new URL(spec.url);
+  } else if (spec.path) {
+    const base = new URL(effectiveBaseUrl.endsWith("/") ? effectiveBaseUrl : `${effectiveBaseUrl}/`);
+    resolved = spec.path.startsWith("/")
+      ? new URL(spec.path, base.origin)
+      : new URL(spec.path, base);
+  } else {
+    resolved = new URL(defaultUrl);
+  }
+  return appendDiscoveryQuery(resolved, spec.query).toString();
+}
+
+function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, reason: unknown): void {
+  try {
+    void reader.cancel(reason).catch(() => undefined);
+  } catch {
+    // A non-conforming stream may throw synchronously from cancel().
+  }
+}
+
+/** Read a discovery response under a strict byte ceiling before JSON.parse can allocate freely. */
+export async function readBoundedDiscoveryJson(
+  response: Response,
+  maxResponseBytes: number,
+): Promise<BoundedDiscoveryJsonResult> {
+  const limit = positiveIntegerAtMost(maxResponseBytes, MODEL_DISCOVERY_MAX_RESPONSE_BYTES);
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > limit) {
+    try {
+      void response.body?.cancel(new DOMException("Model discovery response is too large", "QuotaExceededError"))
+        .catch(() => undefined);
+    } catch {
+      // Best-effort cancellation only.
+    }
+    return { ok: false, reason: "response_too_large" };
+  }
+
+  if (!response.body) return { ok: false, reason: "invalid_json" };
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (!value || value.byteLength === 0) continue;
+      if (value.byteLength > limit - total) {
+        cancelWithoutWaiting(
+          reader,
+          new DOMException("Model discovery response is too large", "QuotaExceededError"),
+        );
+        return { ok: false, reason: "response_too_large" };
+      }
+      chunks.push(value);
+      total += value.byteLength;
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // Cancellation may keep the lock briefly.
+    }
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return { ok: true, value: JSON.parse(text) as unknown };
+  } catch {
+    return { ok: false, reason: "invalid_json" };
+  }
+}
+
+function valueAtPath(item: Record<string, unknown>, path: readonly string[]): unknown {
+  let current: unknown = item;
+  for (const segment of path) {
+    if (current === null || typeof current !== "object" || Array.isArray(current)) return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function comparableScalar(value: unknown, caseInsensitive: boolean): ProviderModelDiscoveryScalar | undefined {
+  if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return undefined;
+  if (typeof value === "string" && value.length > MODEL_DISCOVERY_MAX_FILTER_STRING_LENGTH) return undefined;
+  return caseInsensitive && typeof value === "string" ? value.toLowerCase() : value;
+}
+
+function comparableNeedles(
+  values: readonly ProviderModelDiscoveryScalar[],
+  caseInsensitive: boolean,
+): ProviderModelDiscoveryScalar[] {
+  return values.map(value => caseInsensitive && typeof value === "string" ? value.toLowerCase() : value);
+}
+
+function predicateMatches(item: ProviderModelsApiItem, predicate: ProviderModelDiscoveryPredicate): boolean {
+  const caseInsensitive = predicate.caseInsensitive === true;
+  const raw = valueAtPath(item, predicate.path);
+  if ("equalsAny" in predicate) {
+    const value = comparableScalar(raw, caseInsensitive);
+    return value !== undefined && comparableNeedles(predicate.equalsAny, caseInsensitive).includes(value);
+  }
+
+  const collection = Array.isArray(raw);
+  const values: ProviderModelDiscoveryScalar[] = [];
+  if (collection) {
+    for (let i = 0; i < raw.length && i < MODEL_DISCOVERY_MAX_FILTER_VALUES; i += 1) {
+      const value = comparableScalar(raw[i], caseInsensitive);
+      if (value !== undefined) values.push(value);
+    }
+  } else if (typeof raw === "string") {
+    values.push(caseInsensitive ? raw.toLowerCase() : raw);
+  }
+  const needles = comparableNeedles(
+    "containsAny" in predicate ? predicate.containsAny : predicate.containsAll,
+    caseInsensitive,
+  );
+  if ("containsAny" in predicate) {
+    return needles.some(needle => values.some(value => (
+      !collection && typeof value === "string" && typeof needle === "string" ? value.includes(needle) : value === needle
+    )));
+  }
+  return needles.every(needle => values.some(value => (
+    !collection && typeof value === "string" && typeof needle === "string" ? value.includes(needle) : value === needle
+  )));
+}
+
+export function providerModelMatchesDiscoveryFilter(
+  item: ProviderModelsApiItem,
+  filter: ProviderModelDiscoveryFilter | undefined,
+): boolean {
+  if (!filter) return true;
+  if (filter.allOf && !filter.allOf.every(predicate => predicateMatches(item, predicate))) return false;
+  if (filter.anyOf && filter.anyOf.length > 0 && !filter.anyOf.some(predicate => predicateMatches(item, predicate))) return false;
+  if (filter.noneOf?.some(predicate => predicateMatches(item, predicate))) return false;
+  return true;
+}
+
+/** Extract one allowlisted array envelope while enforcing the raw-row ceiling. */
+export function extractModelEnvelopeRows(
+  value: unknown,
+  maxModels: number,
+  envelopeKeys: readonly string[],
+): ModelEnvelopeRowsResult {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, reason: "invalid_shape" };
+  }
+  const record = value as Record<string, unknown>;
+  const rows = envelopeKeys.map(key => record[key]).find(Array.isArray);
+  if (!rows) return { ok: false, reason: "invalid_shape" };
+  const limit = positiveIntegerAtMost(maxModels, MODEL_DISCOVERY_MAX_MODELS);
+  if (rows.length > limit) return { ok: false, reason: "too_many_models" };
+  return { ok: true, rows };
+}
+
+/** Validate, bound, deduplicate, and declaratively filter OpenAI `{data:[...]}` or top-level arrays (Together `#617`). */
+export function extractProviderModelItems(
+  value: unknown,
+  discovery: ResolvedProviderModelDiscovery,
+): ProviderModelItemsResult {
+  const limit = positiveIntegerAtMost(discovery.maxModels, MODEL_DISCOVERY_MAX_MODELS);
+  let data: unknown[];
+  if (Array.isArray(value)) {
+    // Together-style top-level /models arrays. Catalog discovery must not treat a stray
+    // `models` key on openai-chat responses as valid — only `data` envelopes or top-level arrays.
+    if (value.length > limit) return { ok: false, reason: "too_many_models" };
+    data = value;
+  } else {
+    const envelope = extractModelEnvelopeRows(value, discovery.maxModels, ["data"]);
+    if (!envelope.ok) return envelope;
+    data = envelope.rows;
+  }
+
+  const items: ProviderModelsApiItem[] = [];
+  const seen = new Set<string>();
+  for (const raw of data) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      return { ok: false, reason: "invalid_shape" };
+    }
+    const id = (raw as { id?: unknown }).id;
+    if (!isValidModelDiscoveryModelId(id)) return { ok: false, reason: "invalid_shape" };
+    const normalizedId = id;
+    const item = raw as ProviderModelsApiItem;
+    if (!providerModelMatchesDiscoveryFilter(item, discovery.spec?.filter) || seen.has(normalizedId)) continue;
+    seen.add(normalizedId);
+    items.push(item);
+  }
+  return { ok: true, items, rawCount: data.length };
+}

package/src/providers/openai-sidecar.ts

@@ -0,0 +1,235 @@
+import { resolveEnvValue } from "../config";
+import {
+  CodexPoolAuthenticationError,
+  headersForCodexAuthContext,
+  hasCallerCodexBearer,
+  isCodexAuthContextUsable,
+  resolveCodexAuthContext,
+  type CodexAccountSelectionAdmission,
+  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;
+}
+
+/**
+ * Server-resolved exact account selection for a ChatGPT sidecar call.
+ * `accountId` must come from a validated account-qualified route; request headers
+ * are never trusted as account ids. `modelId` is the sidecar's actual upstream
+ * model so cooldown admission and outcome recording use the correct quota scope.
+ */
+export interface ExactOpenAiSidecarAccount {
+  accountId: string;
+  modelId: string;
+}
+
+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) return [];
+  // The built-in registry defaults an omitted authMode to forward. Normalize only that
+  // missing field before the strict adapter/destination check; explicit key mode and
+  // noncanonical destinations remain ineligible for ChatGPT credential injection.
+  const canonicalProvider = provider.authMode === undefined
+    ? { ...provider, authMode: "forward" as const }
+    : provider;
+  if (!isCanonicalOpenAiForwardProvider(canonicalProvider)) return [];
+  return [{
+    providerName: OPENAI_CODEX_PROVIDER_ID,
+    provider: canonicalProvider,
+    accountMode: providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, canonicalProvider) ?? "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,
+  options: {
+    exactAccount?: ExactOpenAiSidecarAccount;
+    beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
+  } = {},
+): Promise<ResolvedOpenAiForwardSidecar | undefined> {
+  const { exactAccount } = options;
+  let callerBearerMayBeForwarded = true;
+  try {
+    validateForwardAdmissionCredential(incomingHeaders, config);
+  } catch (error) {
+    if (!(error instanceof ForwardAdmissionCredentialError)) throw error;
+    callerBearerMayBeForwarded = false;
+  }
+  for (const candidate of candidates) {
+    if (exactAccount) {
+      // An account-qualified model is an explicit user choice. Resolve the stored
+      // credential directly even when the provider is globally Direct, and never
+      // consult Pool active state, affinity, probes, or alternates.
+      const authContext = await resolveCodexAuthContext(incomingHeaders, config, "pool", {
+        accountId: exactAccount.accountId,
+        modelId: exactAccount.modelId,
+        beginCodexAccountSelection: options.beginCodexAccountSelection,
+      });
+      if ((authContext.kind !== "pool" && authContext.kind !== "main-pool")
+        || !isCodexAuthContextUsable(authContext, config)) {
+        // Exact selection is fail-closed. A generation/runtime-state race must not fall through
+        // to the caller-bearer error or let a later candidate select another account.
+        throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+      }
+      return {
+        ...candidate,
+        authContext,
+        headers: headersForCodexAuthContext(incomingHeaders, authContext),
+        recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
+          config,
+          authContext.accountId,
+          outcome,
+          {
+            modelId: exactAccount.modelId,
+            fixedAccount: true,
+            probeLeaseId: authContext.probeLeaseId,
+            probeQuotaScope: authContext.probeQuotaScope,
+            writerGeneration: authContext.writerGeneration,
+          },
+        ),
+      };
+    }
+    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, {
+      beginCodexAccountSelection: options.beginCodexAccountSelection,
+    });
+    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;
+}