@iislee/opencodex 2.11.0

package/src/providers/key-failover.ts

@@ -0,0 +1,203 @@
+/**
+ * Multi-key 429 failover for non-OpenAI providers.
+ *
+ * When a provider's upstream returns 429, this module picks the next available key
+ * from `apiKeyPool`, puts the exhausted key into cooldown (respecting Retry-After),
+ * and returns a fresh provider config with the swapped key. If all keys are in
+ * cooldown, returns null so the caller surfaces the 429 to the client.
+ *
+ * Modelled after src/codex/routing.ts cooldown logic but scoped to plain API-key pools.
+ */
+import { saveConfigPreservingClaudeCode } from "../config";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
+import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
+
+// ---- cooldown state (in-memory, same as codex/routing.ts) ----
+
+interface KeyCooldown {
+  cooldownUntil: number;
+}
+
+const DEFAULT_COOLDOWN_MS = 60_000;
+const MAX_COOLDOWN_MS = 10 * 60_000; // cap at 10 min for api-key rotation
+
+/** Map<`${providerName}\0${keyId}`, KeyCooldown> */
+const keyCooldowns = new Map<string, KeyCooldown>();
+
+function cooldownKey(providerName: string, keyId: string): string {
+  return `${providerName}\0${keyId}`;
+}
+
+function parseRetryAfterMs(value: string | null | undefined, now = Date.now()): number | undefined {
+  const text = value?.trim();
+  if (!text) return undefined;
+  if (/^\d+(?:\.\d+)?$/.test(text)) {
+    const seconds = Number(text);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), MAX_COOLDOWN_MS);
+    }
+  }
+  const timestamp = Date.parse(text);
+  if (!Number.isFinite(timestamp)) return undefined;
+  const delay = timestamp - now;
+  return delay > 0 ? Math.min(delay, MAX_COOLDOWN_MS) : undefined;
+}
+
+function isKeyInCooldown(providerName: string, keyId: string, now = Date.now()): boolean {
+  const entry = keyCooldowns.get(cooldownKey(providerName, keyId));
+  if (!entry) return false;
+  if (entry.cooldownUntil <= now) {
+    keyCooldowns.delete(cooldownKey(providerName, keyId));
+    return false;
+  }
+  return true;
+}
+
+// ---- public API ----
+
+/**
+ * Check whether a provider has multiple keys available for failover.
+ * Returns true only for key-auth providers with 2+ pool entries.
+ */
+export function hasKeyPoolFailover(provider: OcxProviderConfig): boolean {
+  if (provider.authMode === "oauth" || provider.authMode === "forward") return false;
+  return (provider.apiKeyPool?.length ?? 0) >= 2;
+}
+
+/**
+ * Record a 429 for the current key and attempt to switch to the next available one.
+ *
+ * @returns A new OcxProviderConfig with the swapped key (and mutated config on disk),
+ *          or `null` when no alternative key is available (all in cooldown or pool < 2).
+ *
+ * The returned object is a snapshot of the PERSISTED config — it carries none of the
+ * registry backfills `routedProviderConfig` merges in at request time. Request paths must
+ * not assign it to an active route wholesale; use `rotateProviderTransportOn429`, which
+ * takes only the swapped key and keeps the routed provider intact.
+ */
+export function rotateKeyOn429(
+  config: OcxConfig,
+  providerName: string,
+  retryAfterHeader: string | null | undefined,
+  now = Date.now(),
+  attemptedKey?: string,
+): OcxProviderConfig | null {
+  const provider = config.providers[providerName];
+  if (!provider) return null;
+  if (provider.authMode === "oauth" || provider.authMode === "forward") return null;
+
+  const pool = provider.apiKeyPool;
+  if (!pool || pool.length < 2) return null;
+
+  // Cool the key that ACTUALLY failed. Under concurrent 429s another request may already have
+  // rotated provider.apiKey — cooling the live key would punish an innocent replacement and can
+  // exhaust a 2-key pool from a single bad key. CAS semantics: callers pass the key they used.
+  const failedKey = attemptedKey ?? provider.apiKey;
+  const currentEntry = pool.find(e => e.key === failedKey);
+  if (currentEntry) {
+    const cooldownMs = parseRetryAfterMs(retryAfterHeader, now) ?? DEFAULT_COOLDOWN_MS;
+    keyCooldowns.set(cooldownKey(providerName, currentEntry.id), {
+      cooldownUntil: now + cooldownMs,
+    });
+    sweepExpiredOnWrite(now);
+  }
+
+  // Lost the race: someone already rotated away from the failed key. If the live key is healthy,
+  // retry with it as-is instead of rotating a second time.
+  if (attemptedKey !== undefined && provider.apiKey !== attemptedKey) {
+    const liveEntry = pool.find(e => e.key === provider.apiKey);
+    if (liveEntry && !isKeyInCooldown(providerName, liveEntry.id, now)) {
+      return { ...provider };
+    }
+  }
+
+  // Pick the next key that is NOT in cooldown
+  const currentIndex = currentEntry ? pool.indexOf(currentEntry) : -1;
+  for (let i = 1; i < pool.length; i++) {
+    const candidate = pool[(currentIndex + i) % pool.length]!;
+    if (!isKeyInCooldown(providerName, candidate.id, now)) {
+      // Swap active key
+      provider.apiKey = candidate.key;
+      saveConfigPreservingClaudeCode(config);
+      console.warn(
+        // Log ids only — labels are user-supplied free text and could carry secret material.
+        `[key-failover] ${providerName}: 429 on key ${currentEntry?.id ?? "?"}; rotating to key ${candidate.id}`,
+      );
+      return { ...provider };
+    }
+  }
+
+  // All keys in cooldown
+  console.warn(`[key-failover] ${providerName}: all ${pool.length} keys in cooldown; returning 429 to client`);
+  return null;
+}
+
+export function sweepExpiredApiKeyCooldowns(now = Date.now()): number {
+  let removed = 0;
+  for (const [key, cooldown] of keyCooldowns) {
+    if (cooldown.cooldownUntil > now) continue;
+    keyCooldowns.delete(key);
+    removed += 1;
+  }
+  return removed;
+}
+
+interface RotateProviderTransportOptions {
+  retryAfter?: string | null;
+  now?: number;
+  attemptedKey?: string;
+  promptCacheKey?: string;
+}
+
+/**
+ * Rotate a failed key and re-apply provider-specific transport metadata to the replacement.
+ *
+ * `routedProvider` is the request's active provider (the `routedProviderConfig` output the
+ * route was built with). The result inherits it and swaps ONLY the API key: the persisted
+ * config that `rotateKeyOn429` snapshots predates registry backfill, so building the retry
+ * provider from that snapshot would silently drop every field the registry merged in at
+ * routing time (scalar flags like `promptCacheKey`/`parallelToolCalls`, merged model
+ * metadata such as `noTemperatureModels`, a pinned baseUrl). Mirrors the OAuth-401 replay
+ * path in src/server/responses/core.ts, which spreads `route.provider` for the same reason.
+ */
+export function rotateProviderTransportOn429(
+  config: OcxConfig,
+  providerName: string,
+  routedProvider: OcxProviderTransport,
+  options: RotateProviderTransportOptions = {},
+): OcxProviderTransport | null {
+  const rotated = rotateKeyOn429(
+    config,
+    providerName,
+    options.retryAfter,
+    options.now,
+    options.attemptedKey,
+  );
+  return rotated
+    ? resolveProviderTransport(
+        providerName,
+        { ...routedProvider, apiKey: rotated.apiKey },
+        options.promptCacheKey,
+      )
+    : null;
+}
+
+/** Clear cooldown state for a provider (e.g. after manual key management). */
+export function clearKeyCooldowns(providerName?: string): void {
+  if (!providerName) {
+    keyCooldowns.clear();
+    return;
+  }
+  const prefix = `${providerName}\0`;
+  for (const key of keyCooldowns.keys()) {
+    if (key.startsWith(prefix)) keyCooldowns.delete(key);
+  }
+}
+
+/** Visible-for-testing: get the cooldown-until timestamp for a key. */
+export function getKeyCooldownUntil(providerName: string, keyId: string, now = Date.now()): number | null {
+  const entry = keyCooldowns.get(cooldownKey(providerName, keyId));
+  if (!entry) return null;
+  return entry.cooldownUntil > now ? entry.cooldownUntil : null;
+}

package/src/providers/kiro-models.ts

@@ -0,0 +1,67 @@
+export const KIRO_MODELS = [
+  "kiro-auto",
+  // OpenAI GPT-5.6 (Kiro experimental, us-east-1) — added to official catalog 2026-07-13
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
+  "claude-sonnet-5",
+  "claude-opus-5",
+  "claude-opus-4.8",
+  "claude-opus-4.7",
+  "claude-opus-4.6",
+  "claude-opus-4.5",
+  "claude-sonnet-4.6",
+  "claude-sonnet-4.5",
+  "claude-sonnet-4.0",
+  "claude-haiku-4.5",
+  "deepseek-3.2",
+  "minimax-m2.5",
+  "minimax-m2.1",
+  "glm-5",
+  "qwen3-coder-next",
+];
+
+// Per-model context windows as documented on Kiro's official model catalog
+// (https://kiro.dev/docs/models/ — "Quick comparison", page updated 2026-07-14).
+// "Auto" is a router with no fixed window on Kiro's table, so it is intentionally omitted.
+export const KIRO_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  "gpt-5.6-sol": 272_000,
+  "gpt-5.6-terra": 272_000,
+  "gpt-5.6-luna": 272_000,
+  "claude-sonnet-5": 1_000_000,
+  "claude-opus-5": 1_000_000,
+  "claude-opus-4.8": 1_000_000,
+  "claude-opus-4.7": 1_000_000,
+  "claude-opus-4.6": 1_000_000,
+  "claude-opus-4.5": 200_000,
+  "claude-sonnet-4.6": 1_000_000,
+  "claude-sonnet-4.5": 200_000,
+  "claude-sonnet-4.0": 200_000,
+  "claude-haiku-4.5": 200_000,
+  "deepseek-3.2": 128_000,
+  "minimax-m2.5": 200_000,
+  "minimax-m2.1": 200_000,
+  "glm-5": 200_000,
+  "qwen3-coder-next": 256_000,
+};
+
+const KIRO_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+
+// gpt-5.6-sol and claude-opus-5 send these values through Kiro's verified native effort fields
+// (`reasoning.effort` and `output_config.effort` respectively). Other models map them to bounded
+// thinking instructions until their native effort support is verified.
+export const KIRO_MODEL_REASONING_EFFORTS: Record<string, string[]> = Object.fromEntries(
+  KIRO_MODELS.map(id => [id, KIRO_REASONING_EFFORTS]),
+);
+
+export function normalizeKiroModelId(id: string): string {
+  let model = id.trim().toLowerCase();
+  model = model.replace(/^kiro\//, "").replace(/^kiro-/, "");
+  if (model === "auto") return "auto";
+
+  model = model.replace(/-\d{8}$/, "");
+  model = model.replace(/-(low|medium|high|xhigh|max)$/, "");
+  model = model.replace(/(\d+)-(\d+)/g, "$1.$2");
+  model = model.replace(/^claude-([\d.]+)-(sonnet|opus|haiku)$/, "claude-$2-$1");
+  return model;
+}

package/src/providers/label.ts

@@ -0,0 +1,19 @@
+import { CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
+
+function canonicalUsageProviderLabel(provider: string): string {
+  return provider === "chatgpt" || provider === "openai-multi" ? "openai" : provider;
+}
+
+export function baseProviderLabel(provider: string): string {
+  const canonical = canonicalUsageProviderLabel(provider);
+  if (canonical !== provider) return canonical;
+  const cut = provider.lastIndexOf("-");
+  if (cut <= 0) return canonicalUsageProviderLabel(provider);
+  const suffix = provider.slice(cut + 1);
+  // `-main` is the legacy log label for the main Codex account (MAIN_CODEX_ACCOUNT_ID). New entries
+  // log under the base provider name, but historical `<provider>-main` entries must still collapse.
+  // ChatGPT auth-pool and OpenAI passthrough are the same Codex/OpenAI usage surface, so display
+  // summaries normalize them to one `openai` row after recognized main/pool suffixes are removed.
+  if (suffix === "main") return canonicalUsageProviderLabel(provider.slice(0, cut));
+  return CODEX_ACCOUNT_LOG_LABEL_RE.test(suffix) ? canonicalUsageProviderLabel(provider.slice(0, cut)) : provider;
+}

package/src/providers/model-discovery.ts

@@ -0,0 +1,356 @@
+import type { OcxProviderConfig } from "../types";
+import {
+  getProviderRegistryEntry,
+  providerMatchesRegistryTransport,
+  type ProviderModelDiscoveryFilter,
+  type ProviderModelDiscoveryPredicate,
+  type ProviderModelDiscoveryScalar,
+  type ProviderModelDiscoverySpec,
+} from "./registry";
+
+/** Hard process-wide limits. Registry entries may lower, but never raise, these ceilings. */
+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_MAX_FILTER_VALUES = 256;
+const MODEL_DISCOVERY_MAX_FILTER_STRING_LENGTH = 1_024;
+const MODEL_DISCOVERY_MODEL_ID_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+
+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 {
+  const entry = providerMatchesRegistryTransport(providerName, provider)
+    ? getProviderRegistryEntry(providerName)
+    : undefined;
+  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 (typeof id !== "string") return { ok: false, reason: "invalid_shape" };
+    const normalizedId = id.trim();
+    if (
+      !normalizedId
+      || normalizedId !== id
+      || normalizedId.length > MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH
+      || MODEL_DISCOVERY_MODEL_ID_CONTROL_CHARS.test(normalizedId)
+    ) {
+      return { ok: false, reason: "invalid_shape" };
+    }
+    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 };
+}