Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
import { execFile } from "child_process";
import { promisify } from "util";
import { resolveProviderId } from "@/shared/constants/providers";
import {
getCliToolCommandCandidates,
getLookupEnv,
locateCommandCandidate,
shouldUseShellForCommand,
} from "@/shared/services/cliRuntime";
const execFileAsync = promisify(execFile);
// Codex validates `model_catalog_json` entries strictly, and every bundled entry
// carries a version-specific system prompt (base_instructions / model_messages).
// OmniRoute entries are therefore cloned from the installed Codex's own bundled
// catalog, never synthesized.
const BUNDLED_CATALOG_ARGS = ["debug", "models", "--bundled"];
const BUNDLED_CATALOG_TIMEOUT_MS = 15_000;
// The bundled dump is ~450 KB and grows with every Codex release.
const BUNDLED_CATALOG_MAX_BUFFER = 16 * 1024 * 1024;
// Each listed entry carries a full system prompt (~60 KB with Codex 0.162), so the
// picker is capped to keep the catalog file bounded on deployments with thousands of
// models. Callers order their input so the models the user selected come first.
export const MAX_LISTED_CATALOG_MODELS = 300;
// Preferred fallback template: a plain shell-tool entry. Code-mode entries expose
// tools that Codex rejects as "unsupported call" when a non-Codex model uses them.
const DEFAULT_TEMPLATE_SLUG = "gpt-5.5";
// Code-mode / responses-lite behavior only the Codex upstream understands.
const CODE_MODE_OVERRIDES = {
tool_mode: null,
use_responses_lite: false,
multi_agent_version: null,
multi_agent_reasoning_effort: null,
experimental_supported_tools: [],
};
export type CodexCatalogEntry = Record<string, unknown> & {
slug: string;
priority?: number;
visibility?: string;
};
export type CodexModelCatalog = { models: CodexCatalogEntry[] };
export type CatalogModelInput = string | { id?: unknown; context_length?: unknown } | null;
const isValidEntry = (entry: unknown): entry is CodexCatalogEntry =>
!!entry &&
typeof entry === "object" &&
typeof (entry as { slug?: unknown }).slug === "string" &&
(entry as { slug: string }).slug !== "";
const isCodeModeEntry = (entry: CodexCatalogEntry) =>
entry.tool_mode === "code_mode_only" || entry.use_responses_lite === true;
const priorityOf = (entry: CodexCatalogEntry) =>
typeof entry.priority === "number" && Number.isFinite(entry.priority) ? entry.priority : Infinity;
// gpt-5.5 if bundled, else the first plain listed entry, else the entry Codex itself
// leads its picker with (lowest-priority listed), else the lowest-priority entry.
const pickDefaultTemplate = (entries: CodexCatalogEntry[]): CodexCatalogEntry | null => {
const preferred = entries.find((e) => e.slug === DEFAULT_TEMPLATE_SLUG);
if (preferred) return preferred;
const byPriority = (a: CodexCatalogEntry, b: CodexCatalogEntry) => priorityOf(a) - priorityOf(b);
const listed = entries.filter((e) => e.visibility === "list").sort(byPriority);
const plain = listed.find((e) => !isCodeModeEntry(e));
if (plain) return plain;
if (listed.length) return listed[0];
return [...entries].sort(byPriority)[0] || null;
};
// Only `codex/…` (or one of its registry aliases, e.g. `cx/…`) reaches the real Codex
// upstream; unprefixed ids (combos) and every other provider are non-Codex.
const isCodexProviderModel = (id: string) => {
const slash = id.indexOf("/");
return slash > 0 && resolveProviderId(id.slice(0, slash)) === "codex";
};
const normalizeModel = (model: CatalogModelInput) => {
if (typeof model === "string") return { id: model.trim(), contextLength: null };
if (model && typeof model === "object" && typeof model.id === "string") {
const contextLength =
typeof model.context_length === "number" &&
Number.isFinite(model.context_length) &&
model.context_length > 0
? model.context_length
: null;
return { id: model.id.trim(), contextLength };
}
return null;
};
/**
* Build a Codex `model_catalog_json` document listing OmniRoute models.
*
* Each OmniRoute model clones the bundled entry whose slug matches the part after the
* last "/" (`cx/gpt-5.5` ← `gpt-5.5`), else a default template. Bundled entries are
* kept but hidden so Codex's internal slugs still resolve.
*/
export function buildCodexModelCatalog(
bundledCatalog: unknown,
models: CatalogModelInput[]
): CodexModelCatalog {
const rawBundled = (bundledCatalog as { models?: unknown } | null)?.models;
const bundled = (Array.isArray(rawBundled) ? rawBundled : []).filter(isValidEntry);
const defaultTemplate = pickDefaultTemplate(bundled);
if (!defaultTemplate) return { models: [] };
const bySlug = new Map(bundled.map((e) => [e.slug, e]));
const listedEntries: CodexCatalogEntry[] = [];
const seen = new Set<string>();
for (const raw of Array.isArray(models) ? models : []) {
if (listedEntries.length >= MAX_LISTED_CATALOG_MODELS) break;
const model = normalizeModel(raw);
if (!model?.id || seen.has(model.id)) continue;
seen.add(model.id);
const baseSlug = model.id.slice(model.id.lastIndexOf("/") + 1);
const matched = bySlug.get(baseSlug);
const entry = structuredClone(matched || defaultTemplate);
entry.slug = model.id;
entry.display_name = model.id;
entry.description = matched
? `${model.id} via OmniRoute`
: `${model.id} via OmniRoute (Codex profile: ${defaultTemplate.slug})`;
entry.visibility = "list";
entry.priority = listedEntries.length + 1;
// Retirement notices point at bare OpenAI slugs; an inherited upgrade would push
// the user off a working prefixed model.
entry.upgrade = null;
entry.availability_nux = null;
// Non-Codex upstreams get the plain shell toolset even when the name matches a
// code-mode bundled model.
if (!isCodexProviderModel(model.id)) {
Object.assign(entry, structuredClone(CODE_MODE_OVERRIDES));
}
if (!matched) {
// OpenAI service tiers (Fast/priority) do not exist on arbitrary upstreams.
entry.service_tiers = [];
entry.additional_speed_tiers = [];
// The template's window belongs to a GPT model; prefer OmniRoute's own figure so
// Codex compacts at the right point instead of overflowing upstream.
if (model.contextLength) {
entry.context_window = model.contextLength;
entry.max_context_window = model.contextLength;
}
}
listedEntries.push(entry);
}
// Shift hidden entries past the OmniRoute block, keeping their relative order.
const offset = listedEntries.length + 1;
const hiddenBundled = bundled
.filter((e) => !seen.has(e.slug))
.map((e) => {
const priority =
typeof e.priority === "number" && Number.isFinite(e.priority) ? e.priority : 0;
return {
...structuredClone(e),
visibility: "hide",
priority: offset + Math.max(0, priority),
};
});
return { models: [...listedEntries, ...hiddenBundled] };
}
/**
* Load Codex's bundled model catalog by running the installed CLI
* (`codex debug models --bundled`). Throws when Codex is not runnable, is too old to
* have the subcommand, or prints something that is not a catalog.
*
* `codexHome` pins `CODEX_HOME` for the child so it reads the same directory OmniRoute
* writes the config into.
*/
export async function loadBundledCodexCatalog(codexHome: string): Promise<CodexModelCatalog> {
const env = getLookupEnv();
const commands = getCliToolCommandCandidates("codex");
const hasEnvOverride = !!String(process.env.CLI_CODEX_BIN || "").trim();
const located = await locateCommandCandidate(commands, env, hasEnvOverride ? undefined : "codex");
if (!located.installed || !located.commandPath || located.reason === "not_executable") {
throw new Error(`Codex CLI not available (${located.reason || "not_found"})`);
}
// Hard Rule #13: argv array, no shell string. Windows .cmd/.bat wrappers still need
// cmd.exe, which Node quotes itself when `shell` is set.
const { stdout } = await execFileAsync(located.commandPath, BUNDLED_CATALOG_ARGS, {
windowsHide: true,
env: { ...env, CODEX_HOME: codexHome },
timeout: BUNDLED_CATALOG_TIMEOUT_MS,
maxBuffer: BUNDLED_CATALOG_MAX_BUFFER,
...(shouldUseShellForCommand(located.commandPath) ? { shell: true } : {}),
});
const parsed = JSON.parse(String(stdout));
if (!Array.isArray(parsed?.models) || parsed.models.length === 0) {
throw new Error("Codex bundled catalog has no models");
}
return parsed as CodexModelCatalog;
}