@bitkyc08/opencodex 2.19.0 → 2.20.0

package/src/providers/request-pacing.ts

@@ -0,0 +1,310 @@
+import type { OcxProviderConfig, RequestPacingRule } from "../types";
+import type { GenerationContext } from "../lib/state-store-sweeper";
+
+export const REQUEST_PACING_MAX_QUEUE_DEPTH = 256;
+export const REQUEST_PACING_MAX_QUEUE_AGE_MS = 60_000;
+
+let maxQueueDepth = REQUEST_PACING_MAX_QUEUE_DEPTH;
+let maxQueueAgeMs = REQUEST_PACING_MAX_QUEUE_AGE_MS;
+
+export type RequestPacingQueueOverloadReason = "queue_full" | "queue_expired";
+
+export class RequestPacingQueueOverloadError extends Error {
+  constructor(
+    public readonly providerName: string,
+    public readonly reason: RequestPacingQueueOverloadReason,
+    public readonly retryAfterSeconds: number,
+  ) {
+    super(reason === "queue_full"
+      ? `request pacing queue for provider '${providerName}' is full`
+      : `request pacing queue for provider '${providerName}' exceeded the maximum queued age`);
+    this.name = "RequestPacingQueueOverloadError";
+  }
+}
+
+export class RequestPacingProviderRemovedError extends Error {
+  constructor(public readonly providerName: string) {
+    super(`request pacing provider '${providerName}' was removed`);
+    this.name = "RequestPacingProviderRemovedError";
+  }
+}
+
+interface Waiter {
+  modelId?: string;
+  providerIntervalMs: number;
+  modelIntervalMs: number;
+  queuedAt: number;
+  signal?: AbortSignal;
+  resolve: () => void;
+  reject: (reason: unknown) => void;
+  abort?: () => void;
+}
+
+interface ProviderPacer {
+  queue: Waiter[];
+  providerNextStartAt: number;
+  modelNextStartAt: Map<string, number>;
+  timer?: unknown;
+  lastStartedAt?: number;
+  lastModelId?: string;
+}
+
+export interface RequestPacingRuntime {
+  now: () => number;
+  setTimer: (callback: () => void, delayMs: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+  enqueueMicrotask: (callback: () => void) => void;
+}
+
+export interface ProviderRequestPacingStatus {
+  provider: string;
+  enabled: boolean;
+  queued: number;
+  nextSlotInMs: number;
+  lastStartedAt?: number;
+  lastModelId?: string;
+}
+
+const pacers = new Map<string, ProviderPacer>();
+const defaultRuntime: RequestPacingRuntime = {
+  now: Date.now,
+  setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimer: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
+  enqueueMicrotask: queueMicrotask,
+};
+let runtime = defaultRuntime;
+let lastReconciledGeneration = 0;
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+function normalizedInterval(rule: RequestPacingRule | undefined): number {
+  if (!rule) return 0;
+  const rpmInterval = typeof rule.requestsPerMinute === "number" && rule.requestsPerMinute > 0
+    ? 60_000 / rule.requestsPerMinute
+    : 0;
+  const fixedInterval = typeof rule.minIntervalMs === "number" && rule.minIntervalMs > 0
+    ? rule.minIntervalMs
+    : 0;
+  return Math.max(rpmInterval, fixedInterval);
+}
+
+export function requestPacingIntervalMs(provider: OcxProviderConfig, modelId?: string): number {
+  const policy = provider.requestPacing;
+  if (!policy?.enabled) return 0;
+  const override = modelId ? policy.models?.[modelId] : undefined;
+  return Math.max(normalizedInterval(policy), normalizedInterval(override));
+}
+
+function requestPacingIntervals(provider: OcxProviderConfig, modelId?: string): {
+  providerIntervalMs: number;
+  modelIntervalMs: number;
+} {
+  const policy = provider.requestPacing;
+  if (!policy?.enabled) return { providerIntervalMs: 0, modelIntervalMs: 0 };
+  return {
+    providerIntervalMs: normalizedInterval(policy),
+    modelIntervalMs: modelId ? normalizedInterval(policy.models?.[modelId]) : 0,
+  };
+}
+
+function waiterReadyAt(state: ProviderPacer, modelId: string | undefined): number {
+  return Math.max(
+    state.providerNextStartAt,
+    modelId ? (state.modelNextStartAt.get(modelId) ?? 0) : 0,
+  );
+}
+
+function pacingRetryAfterSeconds(state: ProviderPacer, modelId: string | undefined, now: number): number {
+  return Math.max(1, Math.ceil(Math.max(0, waiterReadyAt(state, modelId) - now) / 1000));
+}
+
+function rejectExpiredWaiters(providerName: string, state: ProviderPacer, now: number): void {
+  for (let index = state.queue.length - 1; index >= 0; index -= 1) {
+    const waiter = state.queue[index]!;
+    if (now - waiter.queuedAt < maxQueueAgeMs) continue;
+    state.queue.splice(index, 1);
+    if (waiter.abort) waiter.signal?.removeEventListener("abort", waiter.abort);
+    waiter.reject(new RequestPacingQueueOverloadError(
+      providerName,
+      "queue_expired",
+      pacingRetryAfterSeconds(state, waiter.modelId, now),
+    ));
+  }
+}
+
+function removeProviderPacer(providerName: string, state: ProviderPacer): void {
+  if (state.timer) runtime.clearTimer(state.timer);
+  state.timer = undefined;
+  pacers.delete(providerName);
+  const waiters = state.queue.splice(0);
+  const error = new RequestPacingProviderRemovedError(providerName);
+  for (const waiter of waiters) {
+    if (waiter.abort) waiter.signal?.removeEventListener("abort", waiter.abort);
+    waiter.reject(error);
+  }
+}
+
+function runQueue(providerName: string, state: ProviderPacer): void {
+  if (state.queue.length === 0) {
+    if (state.timer) runtime.clearTimer(state.timer);
+    state.timer = undefined;
+    return;
+  }
+  if (state.timer) return;
+  const now = runtime.now();
+  for (const [modelId, readyAt] of state.modelNextStartAt) {
+    if (readyAt <= now) state.modelNextStartAt.delete(modelId);
+  }
+  rejectExpiredWaiters(providerName, state, now);
+  if (state.queue.length === 0) return;
+
+  const providerReadyAt = Math.max(now, state.providerNextStartAt);
+  const waiterIndex = state.queue.findIndex(waiter => {
+    const modelReadyAt = waiter.modelId ? (state.modelNextStartAt.get(waiter.modelId) ?? 0) : 0;
+    return Math.max(providerReadyAt, modelReadyAt) <= now;
+  });
+  if (waiterIndex < 0) {
+    let earliestAt = Number.POSITIVE_INFINITY;
+    for (const waiter of state.queue) {
+      const modelReadyAt = waiter.modelId ? (state.modelNextStartAt.get(waiter.modelId) ?? 0) : 0;
+      const readyAt = Math.max(providerReadyAt, modelReadyAt);
+      const expiresAt = waiter.queuedAt + maxQueueAgeMs;
+      earliestAt = Math.min(earliestAt, readyAt, expiresAt);
+    }
+    const delayMs = Math.max(0, earliestAt - now);
+    state.timer = runtime.setTimer(() => {
+      state.timer = undefined;
+      runQueue(providerName, state);
+    }, delayMs);
+    return;
+  }
+  const waiter = state.queue[waiterIndex]!;
+  state.queue.splice(waiterIndex, 1);
+  if (waiter.abort) waiter.signal?.removeEventListener("abort", waiter.abort);
+  const startedAt = runtime.now();
+  state.lastStartedAt = startedAt;
+  state.lastModelId = waiter.modelId;
+  state.providerNextStartAt = startedAt + waiter.providerIntervalMs;
+  if (waiter.modelId && waiter.modelIntervalMs > 0) {
+    state.modelNextStartAt.set(waiter.modelId, startedAt + waiter.modelIntervalMs);
+  }
+  waiter.resolve();
+  runtime.enqueueMicrotask(() => runQueue(providerName, state));
+}
+
+export async function waitForProviderRequestSlot(
+  providerName: string,
+  provider: OcxProviderConfig,
+  modelId?: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const intervals = requestPacingIntervals(provider, modelId);
+  if (Math.max(intervals.providerIntervalMs, intervals.modelIntervalMs) <= 0) return;
+  if (signal?.aborted) throw abortReason(signal);
+
+  const state = pacers.get(providerName) ?? {
+    queue: [], providerNextStartAt: 0, modelNextStartAt: new Map<string, number>(),
+  };
+  pacers.set(providerName, state);
+
+  // Give already-eligible or expired waiters a chance to leave before applying the
+  // admission bound to the newest request. This preserves FIFO-ish fairness while
+  // keeping the retained queue strictly bounded under burst load.
+  if (state.timer) {
+    runtime.clearTimer(state.timer);
+    state.timer = undefined;
+  }
+  runQueue(providerName, state);
+  if (state.queue.length >= maxQueueDepth) {
+    throw new RequestPacingQueueOverloadError(
+      providerName,
+      "queue_full",
+      pacingRetryAfterSeconds(state, modelId, runtime.now()),
+    );
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const waiter: Waiter = { modelId, ...intervals, queuedAt: runtime.now(), signal, resolve, reject };
+    waiter.abort = () => {
+      const index = state.queue.indexOf(waiter);
+      if (index >= 0) state.queue.splice(index, 1);
+      if (state.timer) {
+        runtime.clearTimer(state.timer);
+        state.timer = undefined;
+      }
+      reject(abortReason(signal!));
+      runQueue(providerName, state);
+    };
+    signal?.addEventListener("abort", waiter.abort, { once: true });
+    state.queue.push(waiter);
+    // Abort may race between the eager check above and listener registration.
+    if (signal?.aborted) {
+      waiter.abort();
+      return;
+    }
+    if (state.timer) {
+      runtime.clearTimer(state.timer);
+      state.timer = undefined;
+    }
+    runQueue(providerName, state);
+  });
+}
+
+export function providerRequestPacingStatus(
+  providerName: string,
+  provider: OcxProviderConfig,
+  now = runtime.now(),
+): ProviderRequestPacingStatus {
+  const state = pacers.get(providerName);
+  let nextSlotAt = state?.providerNextStartAt ?? 0;
+  if (state && state.queue.length > 0) {
+    let earliestQueuedSlotAt = Number.POSITIVE_INFINITY;
+    for (const waiter of state.queue) {
+      earliestQueuedSlotAt = Math.min(earliestQueuedSlotAt, waiterReadyAt(state, waiter.modelId));
+    }
+    if (Number.isFinite(earliestQueuedSlotAt)) nextSlotAt = earliestQueuedSlotAt;
+  }
+  return {
+    provider: providerName,
+    enabled: provider.requestPacing?.enabled === true,
+    queued: state?.queue.length ?? 0,
+    nextSlotInMs: Math.max(0, Math.ceil(nextSlotAt - now)),
+    ...(state?.lastStartedAt !== undefined ? { lastStartedAt: state.lastStartedAt } : {}),
+    ...(state?.lastModelId ? { lastModelId: state.lastModelId } : {}),
+  };
+}
+
+export function setProviderRequestPacingLimitsForTest(limits: {
+  maxQueueDepth?: number;
+  maxQueueAgeMs?: number;
+}): void {
+  if (limits.maxQueueDepth !== undefined) maxQueueDepth = limits.maxQueueDepth;
+  if (limits.maxQueueAgeMs !== undefined) maxQueueAgeMs = limits.maxQueueAgeMs;
+}
+
+export function setProviderRequestPacingRuntimeForTest(nextRuntime: RequestPacingRuntime): void {
+  runtime = nextRuntime;
+}
+
+export function reconcileProviderRequestPacing(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  let removed = 0;
+  for (const [providerName, state] of pacers) {
+    if (context.providerNames.has(providerName)) continue;
+    removeProviderPacer(providerName, state);
+    removed += 1;
+  }
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
+
+export function resetProviderRequestPacingForTest(): void {
+  for (const state of pacers.values()) if (state.timer) runtime.clearTimer(state.timer);
+  pacers.clear();
+  maxQueueDepth = REQUEST_PACING_MAX_QUEUE_DEPTH;
+  maxQueueAgeMs = REQUEST_PACING_MAX_QUEUE_AGE_MS;
+  runtime = defaultRuntime;
+  lastReconciledGeneration = 0;
+}

package/src/providers/service-tier.ts

@@ -0,0 +1,143 @@
+import type { OcxProviderConfig } from "../types";
+import { MODEL_ADAPTER_OVERRIDE_ALLOWED } from "../types";
+import { getProviderRegistryEntry, providerModelWireDefault, type InboundWire } from "./registry";
+
+/** OpenAI-compatible adapters that can carry the standard `service_tier` field. */
+export const SERVICE_TIER_ADAPTERS = new Set(["openai-chat", "openai-responses"]);
+
+export type CapturedServiceTierAdapterAuthority = Readonly<Record<string, string>>;
+
+const capturedAdapterAuthority = new WeakMap<object, CapturedServiceTierAdapterAuthority>();
+
+type ServiceTierCapabilityProvider = Pick<
+  OcxProviderConfig,
+  "adapter" | "supportsServiceTier" | "modelSupportsServiceTier" | "modelAdapters" | "baseUrl" | "authMode" | "chatServiceTier"
+>;
+
+/**
+ * Read a model map by exact model identity. Service-tier capability is deliberately
+ * stricter than the older model metadata maps: a family key or a colon-qualified
+ * fallback must not silently advertise Fast for a sibling model that was never verified.
+ * A case-insensitive exact match keeps hand-edited ids consistent with the other maps
+ * without widening the model scope.
+ */
+function exactModelValue<T>(
+  record: Record<string, T> | undefined,
+  modelId: string,
+): T | undefined {
+  if (!record) return undefined;
+  if (Object.prototype.hasOwnProperty.call(record, modelId)) return record[modelId];
+  const folded = modelId.toLowerCase();
+  for (const [key, value] of Object.entries(record)) {
+    if (key.toLowerCase() === folded) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the declared provider/model capability. An explicit provider-level false is a
+ * fail-closed boundary and cannot be reopened by a model map. Otherwise an exact model
+ * declaration wins over the provider default, including an explicit false. The resolver is
+ * provider-local: the caller must first resolve the final provider, so identical bare model ids
+ * on two providers cannot share capability state.
+ */
+export function supportsServiceTierForModel(
+  provider: Pick<OcxProviderConfig, "supportsServiceTier" | "modelSupportsServiceTier">,
+  modelId: string,
+): boolean | undefined {
+  if (provider.supportsServiceTier === false) return false;
+  return exactModelValue(provider.modelSupportsServiceTier, modelId)
+    ?? provider.supportsServiceTier;
+}
+
+/** Whether the Chat serializer may emit a tier for this exact model. */
+export function canSerializeServiceTierForChatModel(
+  provider: Pick<OcxProviderConfig, "supportsServiceTier" | "modelSupportsServiceTier" | "chatServiceTier">,
+  modelId: string,
+): boolean {
+  const exact = exactModelValue(provider.modelSupportsServiceTier, modelId);
+  if (provider.supportsServiceTier === false || exact === false) return false;
+  return provider.chatServiceTier === true || exact === true;
+}
+
+/** Capture registry-owned model wire defaults before an asynchronous catalog flight begins. */
+export function captureServiceTierAdapterAuthority(
+  providerName: string,
+  provider: Pick<OcxProviderConfig, "adapter" | "baseUrl" | "authMode">,
+  registryTransportMatch: boolean,
+  inbound: InboundWire = "responses",
+): CapturedServiceTierAdapterAuthority {
+  const authority: Record<string, string> = {};
+  const defaults = registryTransportMatch
+    ? getProviderRegistryEntry(providerName)?.modelWireDefaults
+    : undefined;
+  for (const modelId of Object.keys(defaults ?? {})) {
+    const adapter = providerModelWireDefault(
+      providerName,
+      provider,
+      modelId,
+      MODEL_ADAPTER_OVERRIDE_ALLOWED,
+      inbound,
+    );
+    if (adapter !== undefined) authority[modelId.trim().toLowerCase()] = adapter;
+  }
+  const frozen = Object.freeze(authority);
+  capturedAdapterAuthority.set(provider, frozen);
+  return frozen;
+}
+
+/** Resolve an explicit model wire override for catalog-time capability projection. */
+export function serviceTierAdapterForModel(
+  providerName: string,
+  provider: Pick<OcxProviderConfig, "adapter" | "baseUrl" | "authMode" | "modelAdapters">,
+  modelId: string,
+  inbound: InboundWire = "responses",
+): string {
+  // Keep this lookup identical to resolveWireProtocolOverride(): configured model-adapter
+  // entries are exact-case keys, while registry defaults intentionally normalize ids there.
+  const configured = provider.modelAdapters?.[modelId];
+  if (configured !== undefined && MODEL_ADAPTER_OVERRIDE_ALLOWED.has(configured)) return configured;
+  const captured = capturedAdapterAuthority.get(provider);
+  if (captured !== undefined) {
+    return captured[modelId.trim().toLowerCase()] ?? provider.adapter;
+  }
+  return providerModelWireDefault(
+    providerName,
+    provider,
+    modelId,
+    MODEL_ADAPTER_OVERRIDE_ALLOWED,
+    inbound,
+  ) ?? provider.adapter;
+}
+
+/** Whether the final provider/model pair can actually publish/send OpenAI service tiers. */
+export function canForwardServiceTierForModel(
+  provider: ServiceTierCapabilityProvider,
+  modelId: string,
+  providerName?: string,
+  inbound: InboundWire = "responses",
+): boolean {
+  return serviceTierSupportForModel(provider, modelId, providerName, inbound) === true;
+}
+
+/**
+ * Return the tri-state capability after resolving the model's final wire adapter.
+ * `false` means either an explicit provider/model denial or an adapter that cannot carry the
+ * field; `undefined` keeps the existing conservative contract for an unclassified OpenAI wire.
+ */
+export function serviceTierSupportForModel(
+  provider: ServiceTierCapabilityProvider,
+  modelId: string,
+  providerName?: string,
+  inbound: InboundWire = "responses",
+): boolean | undefined {
+  const adapter = providerName === undefined
+    ? provider.adapter
+    : serviceTierAdapterForModel(providerName, provider, modelId, inbound);
+  if (!SERVICE_TIER_ADAPTERS.has(adapter)) return false;
+  // Treat the Chat serializer decision as authoritative so catalog metadata, routing
+  // evidence, fast-mode injection, and caller-tier stripping cannot claim support that the
+  // final request builder will omit. A provider-wide false and an exact false stay closed.
+  if (adapter === "openai-chat" && !canSerializeServiceTierForChatModel(provider, modelId)) return false;
+  return supportsServiceTierForModel(provider, modelId);
+}

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

@@ -0,0 +1,86 @@
+import type { OcxProviderConfig } from "../types";
+import {
+  getProviderRegistryEntry,
+  providerMatchesRegistryTransport,
+  type ProviderRegistryEntry,
+} from "./registry";
+
+const STATIC_MODEL_CATALOG_PROVIDER_IDS = new Set(["cline-pass", "mimo-free"]);
+
+function normalizedEndpoint(value: string): string {
+  const trimmed = value.trim();
+  try {
+    const parsed = new URL(trimmed);
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return trimmed.replace(/\/+$/, "");
+  }
+}
+
+function exactRegistryTransportMatch(
+  entry: ProviderRegistryEntry,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+  options: { allowLegacyMimoLocal?: boolean } = {},
+): boolean {
+  if (entry.allowBaseUrlOverride || /\{[^}]*\}/.test(entry.baseUrl)) return false;
+  if (typeof provider.baseUrl !== "string" || provider.adapter !== entry.adapter) return false;
+  const legacyMimoLocal = options.allowLegacyMimoLocal === true
+    && entry.id === "mimo-free"
+    && provider.authMode === "local";
+  if (provider.authMode !== undefined && provider.authMode !== "key" && !legacyMimoLocal) return false;
+  return normalizedEndpoint(provider.baseUrl) === normalizedEndpoint(entry.baseUrl);
+}
+
+/** Registry policy for providers whose maintained model list is authoritative. */
+export function registryEntrySupportsLiveModelDiscovery(entry: ProviderRegistryEntry): boolean {
+  return !STATIC_MODEL_CATALOG_PROVIDER_IDS.has(entry.id);
+}
+
+/**
+ * Static-catalog authority is tied to canonical provider identity and exact transport.
+ * Renamed/custom rows stay operator-owned: Cline and ClinePass intentionally share a transport,
+ * so destination matching alone cannot safely identify a renamed ClinePass configuration.
+ */
+export function staticModelCatalogEntryForProvider(
+  name: string,
+  provider: OcxProviderConfig,
+): ProviderRegistryEntry | undefined {
+  const entry = getProviderRegistryEntry(name);
+  if (!entry || !STATIC_MODEL_CATALOG_PROVIDER_IDS.has(entry.id)) return undefined;
+  return exactRegistryTransportMatch(entry, provider, { allowLegacyMimoLocal: true })
+    ? entry
+    : undefined;
+}
+
+export function providerSupportsLiveModelDiscovery(name: string, provider: OcxProviderConfig): boolean {
+  return staticModelCatalogEntryForProvider(name, provider) === undefined;
+}
+
+/**
+ * MiMo Free predates collision preservation in the registry. Keep same-named custom rows out of
+ * registry ownership without broadening the generic transport matcher to other key providers.
+ */
+export function providerMatchesRegistryTransportWithStaticGuards(
+  name: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+): boolean {
+  if (name !== "mimo-free") return providerMatchesRegistryTransport(name, provider);
+  const entry = getProviderRegistryEntry(name);
+  return entry !== undefined
+    && exactRegistryTransportMatch(entry, provider, { allowLegacyMimoLocal: true });
+}
+
+/** Repair only registry-owned legacy state; operator-owned model lists stay untouched. */
+export function repairStaticModelCatalogProvider(name: string, provider: OcxProviderConfig): void {
+  const entry = staticModelCatalogEntryForProvider(name, provider);
+  if (!entry) return;
+  provider.liveModels = false;
+  if (
+    name === "mimo-free"
+    && entry.id === "mimo-free"
+    && (provider.authMode === undefined || provider.authMode === "local")
+  ) {
+    provider.authMode = "key";
+  }
+}

package/src/reasoning-effort.ts

@@ -19,6 +19,30 @@ export function isCodexReasoningEffort(effort: string): boolean {
   return CODEX_REASONING_SET.has(effort);
 }
 
+/**
+ * True for ladder members plus the `none`/`minimal` sentinels. Both are valid declared
+ * efforts (OpenAI accepts `minimal`; Codex validates `none` against
+ * `supported_reasoning_levels` for no-reasoning subagent spawns, #883/#962) but are NOT
+ * part of the low..ultra ladder: they never appear in default ladders, ranks, or clamps
+ * (`minimal` is mapped to `low` on the wire by requestToCodexEffort).
+ */
+export function isDeclaredReasoningEffort(effort: string): boolean {
+  return effort === "none" || effort === "minimal" || CODEX_REASONING_SET.has(effort);
+}
+
+/**
+ * Reorder any declared subset (low..ultra, plus the optional `none`/`minimal` sentinels
+ * first, in that order) into canonical order and drop duplicates. Catalog
+ * `supported_reasoning_levels` follow the input order and the fallback default picks the
+ * first entry, so a caller-chosen order would otherwise leak into the catalog.
+ */
+export function canonicalizeReasoningEfforts(values: readonly string[]): string[] {
+  const seen = new Set(values);
+  const ordered = CODEX_REASONING_ORDER.filter(effort => seen.has(effort));
+  const sentinels = ["none", "minimal"].filter(effort => seen.has(effort));
+  return [...sentinels, ...ordered];
+}
+
 /**
  * Reasoning ladder accepted for the OpenAI vision sidecar. `ultra` is deliberately excluded:
  * the vision describer is a single helper call, and `ultra` would be collapsed to `max` by the
@@ -66,7 +90,9 @@ export function sanitizeCodexReasoningEfforts(efforts: readonly string[] | undef
   const seen = new Set<string>();
   const out: string[] = [];
   for (const effort of efforts) {
-    if (!CODEX_REASONING_SET.has(effort) || seen.has(effort)) continue;
+    // `none`/`minimal` are valid declared sentinels, kept and sorted first (rank -1); they
+    // never appear in the default ladder.
+    if ((effort !== "none" && effort !== "minimal" && !CODEX_REASONING_SET.has(effort)) || seen.has(effort)) continue;
     seen.add(effort);
     out.push(effort);
   }

package/src/router.ts

@@ -11,8 +11,12 @@ import type { NormalizedComboConfig } from "./combos/types";
 import { hasOwnProvider, resolveEnvValue } from "./config";
 import { assertProviderDestinationAllowed } from "./lib/destination-policy";
 import { redactSecretString, redactUrlForLog } from "./lib/redact";
-import { PROVIDER_REGISTRY, providerCodexAccountMode, providerMatchesRegistryTransport } from "./providers/registry";
+import { PROVIDER_REGISTRY, providerCodexAccountMode } from "./providers/registry";
 import { applyDirectReasoningEffortContracts } from "./providers/derive";
+import {
+  providerMatchesRegistryTransportWithStaticGuards,
+  providerSupportsLiveModelDiscovery,
+} from "./providers/static-model-discovery";
 import {
   isCanonicalOpenAiForwardProvider,
   LEGACY_CHATGPT_PROVIDER_ID,
@@ -86,7 +90,7 @@ const MODEL_PROVIDER_PATTERNS: Array<{ providerNames: string[]; prefixes: string
 export function knownModelIdsForProvider(provName: string, prov: OcxProviderConfig): string[] {
   const ids = new Set<string>();
   for (const id of prov.models ?? []) ids.add(id);
-  const registry = providerMatchesRegistryTransport(provName, prov)
+  const registry = providerMatchesRegistryTransportWithStaticGuards(provName, prov)
     ? PROVIDER_REGISTRY.find(entry => entry.id === provName)
     : undefined;
   for (const id of registry?.models ?? []) ids.add(id);
@@ -99,6 +103,7 @@ export function knownModelIdsForProvider(provName: string, prov: OcxProviderConf
     registry?.modelDefaultReasoningEfforts,
     registry?.modelReasoningEffortMap,
     registry?.modelMaxOutputTokens,
+    registry?.modelSupportsServiceTier,
   ]) {
     for (const id of Object.keys(map ?? {})) ids.add(id);
   }
@@ -249,20 +254,26 @@ function usableResolvedApiKey(apiKey: string | undefined): string | undefined {
 
 export function routedProviderConfig(providerName: string, provider: OcxProviderConfig): OcxProviderConfig {
   const registryEntry = PROVIDER_REGISTRY.find(entry => entry.id === providerName);
-  if (!registryEntry || !providerMatchesRegistryTransport(providerName, provider)) {
+  if (!registryEntry || !providerMatchesRegistryTransportWithStaticGuards(providerName, provider)) {
     assertProviderDestinationAllowed(providerName, provider);
     return { ...provider, apiKey: usableResolvedApiKey(provider.apiKey) };
   }
   const resolvedApiKey = usableResolvedApiKey(provider.apiKey);
+  const staticModelCatalog = !providerSupportsLiveModelDiscovery(providerName, provider);
+  const repairLegacyMimoFreeAuth = providerName === "mimo-free"
+    && staticModelCatalog
+    && (provider.authMode === undefined || provider.authMode === "local");
   const explicitKeyOverride = registryEntry.authKind === "oauth"
     && registryEntry.allowKeyAuthOverride === true
     && provider.authMode === "key"
     && resolvedApiKey !== undefined;
   const canonicalAuthMode = explicitKeyOverride
     ? "key"
-    : registryEntry.authKind === "forward" || registryEntry.authKind === "oauth"
-      ? registryEntry.authKind
-    : provider.authMode === "forward" ? undefined : provider.authMode;
+    : repairLegacyMimoFreeAuth
+      ? "key"
+      : registryEntry.authKind === "forward" || registryEntry.authKind === "oauth"
+        ? registryEntry.authKind
+        : provider.authMode === "forward" ? undefined : provider.authMode;
   const reasoningEffortMap = mergeRecord(registryEntry.reasoningEffortMap, provider.reasoningEffortMap);
   const modelReasoningEffortMap = mergeNestedRecord(registryEntry.modelReasoningEffortMap, provider.modelReasoningEffortMap);
   const modelReasoningEfforts = mergeStringArrayRecord(registryEntry.modelReasoningEfforts, provider.modelReasoningEfforts);
@@ -283,6 +294,10 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ? mergePositiveNumberCaps(registryEntry.modelMaxInputTokens, provider.modelMaxInputTokens)
     : mergeRecordFill(registryEntry.modelMaxInputTokens, provider.modelMaxInputTokens);
   const modelMaxOutputTokens = mergeRecordFill(registryEntry.modelMaxOutputTokens, provider.modelMaxOutputTokens);
+  const modelSupportsServiceTier = mergeRecordFill(
+    registryEntry.modelSupportsServiceTier,
+    provider.modelSupportsServiceTier,
+  );
   const noVisionModels = mergeStringArray(registryEntry.noVisionModels, provider.noVisionModels);
   const noReasoningModels = mergeStringArray(registryEntry.noReasoningModels, provider.noReasoningModels);
   const noTemperatureModels = mergeStringArray(registryEntry.noTemperatureModels, provider.noTemperatureModels);
@@ -343,6 +358,7 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
       : {}),
     authMode: canonicalAuthMode,
     apiKey: resolvedApiKey,
+    ...(staticModelCatalog ? { liveModels: false } : {}),
     // Backfill the Google wire mode + Vertex project/location from the registry when the user
     // config omits them, so a minimal `google-vertex`/`google-antigravity` entry still routes
     // through the correct branch (CCA/Vertex) instead of falling back to AI Studio.
@@ -372,6 +388,7 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(modelInputModalities ? { modelInputModalities } : {}),
     ...(modelMaxInputTokens ? { modelMaxInputTokens } : {}),
     ...(modelMaxOutputTokens ? { modelMaxOutputTokens } : {}),
+    ...(modelSupportsServiceTier ? { modelSupportsServiceTier } : {}),
     ...(modelReasoningEfforts ? { modelReasoningEfforts } : {}),
     ...(modelDefaultReasoningEfforts ? { modelDefaultReasoningEfforts } : {}),
     ...(reasoningEffortMap ? { reasoningEffortMap } : {}),