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 fs from "node:fs";
import { applyEdits, modify, parse, printParseErrorCode, type ParseError } from "jsonc-parser";
import {
parseOutboundUrl,
isCloudMetadataHost,
OutboundUrlGuardError,
} from "../../../shared/network/outboundUrlGuard";
import { resolveOpencodeConfigPath } from "../../../shared/services/opencodeConfigPath";
import { readPrivateConfigFile } from "../privateConfigFile";
const JSON_FORMATTING_OPTIONS = { insertSpaces: true, tabSize: 2 } as const;
/**
* SSRF guard for the catalog fetch (CodeQL js/request-forgery #326). The catalog
* source is the user's OWN OmniRoute instance, so loopback/private hosts are the
* legitimate default and must stay allowed — we cannot use the public-only guard
* here. What has NO legitimate use as a catalog source is the cloud-metadata /
* link-local pivot (169.254.169.254, metadata.google.internal, …): that is the
* classic SSRF→IAM-credential escalation and is blocked unconditionally, along
* with non-http(s) protocols and embedded credentials (via parseOutboundUrl).
*/
export function assertSafeCatalogUrl(rawUrl: string): URL {
const url = parseOutboundUrl(rawUrl); // throws on bad protocol / embedded creds
if (isCloudMetadataHost(url.hostname)) {
throw new OutboundUrlGuardError("Blocked cloud-metadata catalog URL (SSRF protection)", {
code: "OUTBOUND_URL_GUARD_BLOCKED",
url: url.toString(),
hostname: url.hostname,
});
}
// Return the re-parsed URL so callers fetch the validated value (a `new URL()`
// round-trip is a recognized request-forgery barrier — clears CodeQL #326).
return url;
}
/**
* OpenAI-compatible model entry — subset of fields the /v1/models endpoint
* returns. Only the fields we need to emit `limit.context` / `limit.output`
* are typed.
*/
interface CatalogModelEntry {
id: string;
owned_by?: string;
name?: string;
display_name?: string;
/** OpenAI-compatible field name; some upstreams return this. */
context_length?: number;
max_context_window_tokens?: number;
/** Optional max output tokens; used to populate `limit.output`. */
max_output_tokens?: number;
max_input_tokens?: number;
/** Optional structured capability flags. */
capabilities?: {
attachment?: boolean;
reasoning?: boolean;
temperature?: boolean;
tool_calling?: boolean;
vision?: boolean;
};
/** OpenAI-compatible modality arrays; some upstreams return these. */
input_modalities?: string[];
output_modalities?: string[];
}
/** Per-model override carried over from the user's existing opencode.json. */
interface ExistingModelEntry {
name?: string;
attachment?: boolean;
reasoning?: boolean;
temperature?: boolean;
tool_call?: boolean;
limit?: { context?: number; input?: number; output?: number };
// Allow arbitrary other keys to round-trip through untouched.
[key: string]: unknown;
}
interface ExistingProviderEntry {
name?: string;
npm?: string;
options?: Record<string, unknown>;
models?: Record<string, ExistingModelEntry>;
[key: string]: unknown;
}
interface ExistingConfig {
$schema?: string;
provider?: Record<string, ExistingProviderEntry>;
model?: string;
small_model?: string;
[key: string]: unknown;
}
export interface CatalogFetchResult {
/** Models keyed by id, as returned by /v1/models. */
byId: Map<string, CatalogModelEntry>;
/** Provider ids that had at least one model in the catalog. */
providerIds: Set<string>;
/** Models that have a usable `context_length` (positive finite number). */
modelsWithContext: number;
/** Total models returned by the catalog. */
total: number;
}
/**
* Fetch the live `/v1/models` catalog from OmniRoute. The catalog is the
* single source of truth for context windows — opencode.json must NOT
* hardcode values, otherwise we drift from the provider's actual limits.
*/
export async function fetchOmniRouteCatalog(
baseUrl: string,
apiKey: string,
timeoutMs = 5_000
): Promise<CatalogFetchResult> {
const cleanBase = baseUrl.replace(/\/+$/, "");
const baseURL = cleanBase.endsWith("/v1") ? cleanBase : `${cleanBase}/v1`;
const result: CatalogFetchResult = {
byId: new Map(),
providerIds: new Set(),
modelsWithContext: 0,
total: 0,
};
// SSRF guard (CodeQL #326): baseUrl is user-controlled — block the cloud-metadata
// pivot before issuing the request. Loopback stays allowed. Fetch the VALIDATED,
// re-parsed URL the guard returns (not the raw string) so the taint is severed.
const safeUrl = assertSafeCatalogUrl(`${baseURL}/models`);
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(safeUrl, {
headers: { Authorization: `Bearer ${apiKey}` },
signal: controller.signal,
});
if (!response.ok) {
throw new Error(`OmniRoute /v1/models returned ${response.status} ${response.statusText}`);
}
const body = (await response.json()) as unknown;
const list: unknown[] = Array.isArray(body)
? body
: body && typeof body === "object" && Array.isArray((body as { data?: unknown[] }).data)
? ((body as { data: unknown[] }).data as unknown[])
: [];
for (const raw of list) {
if (!raw || typeof raw !== "object") continue;
const r = raw as CatalogModelEntry;
if (typeof r.id !== "string" || !r.id.trim()) continue;
const id = r.id.trim();
result.byId.set(id, r);
result.total += 1;
if (typeof r.owned_by === "string" && r.owned_by.length > 0) {
result.providerIds.add(r.owned_by);
}
const candidates = [r.context_length, r.max_context_window_tokens];
if (candidates.some((c) => typeof c === "number" && Number.isFinite(c) && c > 0)) {
result.modelsWithContext += 1;
}
}
} finally {
clearTimeout(timer);
}
return result;
}
/**
* Resolve the context length for a single catalog entry.
* Prefers `context_length` (OpenAI-compatible) over `max_context_window_tokens`
* (llama.cpp-style). Returns `undefined` when neither is a positive integer —
* this is intentional: we MUST NOT invent a default, because combos whose
* targets' contexts are unknown to the catalog will mis-report a context
* window. The user can override per-model via `limit.context` in their
* existing opencode.json, or fix the upstream catalog.
*/
/**
* Map catalog capabilities/modalities to OpenCode model capability fields.
* Preserves explicit user-set booleans (including `false`) over any catalog
* value -- a deliberate local restriction must never be overwritten.
*
* Mapping rules per field:
* - `attachment`: explicit user flag; then catalog `capabilities.attachment`;
* then `capabilities.vision`; then `input_modalities` containing `image`.
* - `reasoning`: explicit user flag; then `capabilities.reasoning`.
* - `temperature`: explicit user flag; then `capabilities.temperature`.
* - `tool_call`: explicit user flag; then `capabilities.tool_calling`.
*/
function deriveOpenCodeCapabilities(
catalog: CatalogModelEntry | undefined,
existing: ExistingModelEntry | undefined
): Pick<ExistingModelEntry, "attachment" | "reasoning" | "temperature" | "tool_call"> {
const result: Pick<ExistingModelEntry, "attachment" | "reasoning" | "temperature" | "tool_call"> =
{};
// attachment: explicit user flag wins, then catalog attachment, then vision, then image modality.
if (typeof existing?.attachment === "boolean") {
result.attachment = existing.attachment;
} else if (catalog?.capabilities) {
if (typeof catalog.capabilities.attachment === "boolean") {
result.attachment = catalog.capabilities.attachment;
} else if (catalog.capabilities.vision === true) {
result.attachment = true;
} else if (
Array.isArray(catalog.input_modalities) &&
catalog.input_modalities.includes("image")
) {
result.attachment = true;
}
}
// reasoning: explicit user flag wins, then catalog reasoning.
if (typeof existing?.reasoning === "boolean") {
result.reasoning = existing.reasoning;
} else if (catalog?.capabilities?.reasoning === true) {
result.reasoning = true;
}
// temperature: explicit user flag wins, then catalog temperature.
if (typeof existing?.temperature === "boolean") {
result.temperature = existing.temperature;
} else if (catalog?.capabilities?.temperature === true) {
result.temperature = true;
}
// tool_call: explicit user flag wins, then catalog tool_calling.
if (typeof existing?.tool_call === "boolean") {
result.tool_call = existing.tool_call;
} else if (catalog?.capabilities?.tool_calling === true) {
result.tool_call = true;
}
return result;
}
function resolveContextLength(entry: CatalogModelEntry): number | undefined {
const candidates = [entry.context_length, entry.max_context_window_tokens];
for (const c of candidates) {
if (typeof c === "number" && Number.isFinite(c) && c > 0) return c;
}
return undefined;
}
/**
* Build the entry that ends up under `provider.<name>.models[id]` in the
* emitted opencode.json. Precedence:
*
* 1. Existing manual override in the user's opencode.json (`limit.context`).
* 2. Catalog `context_length` / `max_context_window_tokens`.
*
* If neither is available, `limit.context` is simply omitted and OpenCode's
* own heuristics apply — we never fabricate a default context window. The
* entry ALWAYS carries a `limit` block, though: `limit.output` is a
* required field in OpenCode's v1 provider schema, so it is always emitted
* (falling back to 8K when nothing else is known) — see #10940.
*/
function buildModelEntry(
id: string,
catalog: CatalogModelEntry | undefined,
existing: ExistingModelEntry | undefined
): ExistingModelEntry {
// Carry over user-set names first, then native catalog display metadata.
// Technical ids remain map keys; names are presentation only.
const catalogName = catalog?.display_name ?? catalog?.name;
const nativeName = typeof catalogName === "string" ? catalogName.trim() : "";
const providerPrefix = catalog?.owned_by ? `${catalog.owned_by}/` : "";
const modelName = nativeName.startsWith(providerPrefix)
? nativeName.slice(providerPrefix.length)
: nativeName;
const autoName = id.startsWith("auto/")
? `Auto ${id.slice("auto/".length).replace(/(^|[-_])([a-z])/g, (_, separator, letter) => `${separator === "" ? "" : " "}${letter.toUpperCase()}`)}`
: "";
const name =
(typeof existing?.name === "string" && existing.name.trim() !== id && existing.name.trim()) ||
autoName ||
modelName ||
id;
const entry: ExistingModelEntry = { name };
// Derive capability flags from the catalog, preserving explicit user overrides.
// Explicit user booleans (including `false`) always win; catalog capabilities
// fill in missing values so newly discovered models are not presented as
// text-only to OpenCode clients.
const caps = deriveOpenCodeCapabilities(catalog, existing);
if (typeof caps.attachment === "boolean") entry.attachment = caps.attachment;
if (typeof caps.reasoning === "boolean") entry.reasoning = caps.reasoning;
if (typeof caps.temperature === "boolean") entry.temperature = caps.temperature;
if (typeof caps.tool_call === "boolean") entry.tool_call = caps.tool_call;
// Preserve any extra top-level keys the user set (variants, headers, etc.)
// that we don't model explicitly.
if (existing) {
for (const [k, v] of Object.entries(existing)) {
if (k === "name" || k === "limit") continue;
if (v === undefined) continue;
if (!(k in entry)) entry[k] = v;
}
}
// Resolve the context window. Honor an explicit user override, then fall
// back to the catalog. If the catalog is unaware of a model's window, we
// fall back to a safe default (128K) so OpenCode's v1 provider schema
// validator never rejects the config with a missing key error (#11035).
const userLimit = existing?.limit?.context;
const catalogLimit = catalog ? resolveContextLength(catalog) : undefined;
const context = typeof userLimit === "number" && userLimit > 0 ? userLimit : catalogLimit;
// `limit.output` is REQUIRED by OpenCode's v1 provider schema (configV1).
// Use the catalog's max_output_tokens when available; otherwise fall
// back to the user's existing `limit.output` and finally to a small
// default (8K) so OpenCode never errors on a totally missing output cap.
const userOutput = existing?.limit?.output;
const catalogOutput =
catalog && typeof catalog.max_output_tokens === "number" && catalog.max_output_tokens > 0
? catalog.max_output_tokens
: undefined;
const output =
typeof userOutput === "number" && userOutput > 0 ? userOutput : (catalogOutput ?? 8_192);
// Both `limit.context` and `limit.output` are REQUIRED by OpenCode's v1 provider schema
// regardless of whether the catalog (or the user's existing config) knows the model's
// context window — a model with no catalog metadata at all must still get both
// `limit.context` and `limit.output`, or OpenCode rejects the whole config with "Missing key
// provider.omniroute.models.{model}.limit.context" (#11035) or ".limit.output" (#10940, #11032).
// `output` above resolves to a safe fallback (8K) and `context` resolves to a safe fallback (128K)
// when nothing else is known, so we always emit both fields.
const resolvedContext = typeof context === "number" && context > 0 ? context : 128_000;
const limit: { context: number; input?: number; output: number } = {
context: resolvedContext,
output,
};
const userInput = existing?.limit?.input;
if (typeof userInput === "number" && userInput > 0) {
limit.input = userInput;
} else if (catalog) {
const maxInput = catalog.max_input_tokens;
if (typeof maxInput === "number" && maxInput > 0) limit.input = maxInput;
}
entry.limit = limit;
return entry;
}
/**
* Load the user's current OpenCode config so we can preserve names,
* capability flags, explicit `limit.context` overrides, and JSONC source text.
* Existing invalid files are a hard stop: replacing one with a regenerated
* document would silently lose comments, unrelated providers, and settings.
*/
function loadExistingConfig(configPath: string): { config: ExistingConfig; source: string | null } {
if (!fs.existsSync(configPath)) return { config: {}, source: null };
let source: string;
try {
source = readPrivateConfigFile(configPath);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
throw new Error(`Failed to read existing OpenCode config at ${configPath}: ${message}`);
}
const errors: ParseError[] = [];
const parsed = parse(source, errors, { allowTrailingComma: true, disallowComments: false });
if (errors.length > 0 || !parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
const detail = errors[0] ? printParseErrorCode(errors[0].error) : "root must be an object";
throw new Error(
`Existing OpenCode config at ${configPath} is invalid JSONC (${detail}); refusing to overwrite it.`
);
}
return { config: parsed as ExistingConfig, source };
}
/**
* Patch the generated values into an existing JSONC document without replacing
* its comments or unrelated keys. The generated object is authoritative for
* the fields the generator manages; everything else remains byte-for-byte
* unless jsonc-parser must adjust nearby whitespace for an edit.
*/
function mergeGeneratedConfigText(
existingSource: string | null,
existingConfig: ExistingConfig,
generatedConfig: Record<string, unknown>,
providerId: string
): string {
if (existingSource === null) return JSON.stringify(generatedConfig, null, 2);
let nextText = existingSource;
const schemaEdits = modify(nextText, ["$schema"], generatedConfig.$schema, {
formattingOptions: JSON_FORMATTING_OPTIONS,
});
nextText = applyEdits(nextText, schemaEdits);
const generatedProvider = (
generatedConfig.provider as Record<string, ExistingProviderEntry> | undefined
)?.[providerId];
const providerEdits = modify(nextText, ["provider", providerId], generatedProvider, {
formattingOptions: JSON_FORMATTING_OPTIONS,
});
nextText = applyEdits(nextText, providerEdits);
if (generatedConfig.model !== existingConfig.model) {
const modelEdits = modify(nextText, ["model"], generatedConfig.model, {
formattingOptions: JSON_FORMATTING_OPTIONS,
});
nextText = applyEdits(nextText, modelEdits);
}
return nextText;
}
export interface GenerateOpencodeOptions {
baseUrl: string;
apiKey: string;
model?: string;
/**
* Pre-resolved destination used by the API generator/apply pipeline so the
* file read for merging is guaranteed to be the file later written.
*/
configPath?: string;
/**
* Override the default `provider.id` used in the generated config.
* Defaults to `"omniroute"`.
*/
providerId?: string;
/**
* If `true` (default), the generator fetches the live `/v1/models` catalog
* so every model entry has an explicit `limit.context`. The catalog is the
* primary source of truth for context windows, falling back to 128K when unknown.
*
* When the catalog request fails, the generator throws — opencode.json must
* not be emitted with stale or fabricated values. The CLI can catch the
* error and decide whether to surface it to the user.
*/
fetchCatalog?: boolean;
/**
* Request timeout for the catalog fetch, in milliseconds. Defaults to 5s.
*/
catalogTimeoutMs?: number;
}
/**
* Generate a full `opencode.json` document for OmniRoute. The catalog is the
* primary source of truth for context windows, with a 128K fallback when unknown.
*
* Behavior:
* - Preserves the user's existing provider name, npm, options, and
* per-model names / capability flags.
* - For each existing model id, the catalog's `context_length` wins
* unless the user already set an explicit `limit.context` in the file.
* - For each catalog model id the user did NOT have, a new entry is
* added with `limit.context` populated when the catalog has it.
* - If the catalog has no context for a model AND the user has no
* override, a safe default (128K) is emitted so OpenCode's schema validator
* does not reject the model.
* - Throws if the catalog fetch fails — the user must fix the upstream
* before we can generate a reliable opencode.json.
*/
export async function generateOpencodeConfig(options: GenerateOpencodeOptions): Promise<string> {
const cleanBase = options.baseUrl.replace(/\/+$/, "");
const baseURL = cleanBase.endsWith("/v1") ? cleanBase : `${cleanBase}/v1`;
const providerId = options.providerId?.trim() || "omniroute";
const fetchCatalog = options.fetchCatalog !== false;
const timeoutMs = options.catalogTimeoutMs ?? 5_000;
const configPath = options.configPath ?? resolveOpencodeConfigPath();
const { config: existing, source: existingSource } = loadExistingConfig(configPath);
// Fetch live catalog. The catalog is the source of truth — if it fails,
// we refuse to write an opencode.json that could mislead OpenCode into
// picking the wrong context window.
let catalogById = new Map<string, CatalogModelEntry>();
if (fetchCatalog) {
const result = await fetchOmniRouteCatalog(baseURL, options.apiKey, timeoutMs);
catalogById = result.byId;
} else {
throw new Error(
"fetchCatalog=false is not supported. The catalog is the single source " +
"of truth for context windows — without it, opencode.json would carry " +
"fabricated or stale values."
);
}
// Load existing config so we preserve names, capability flags, and any
// explicit `limit.context` overrides the user has set.
const existingProvider = existing.provider?.[providerId];
const existingModels = (existingProvider?.models ?? {}) as Record<string, ExistingModelEntry>;
// Build the merged model map: catalog first, then existing (so existing
// values can win for matching ids).
const mergedIds = new Set<string>([...catalogById.keys(), ...Object.keys(existingModels)]);
const mergedModels: Record<string, ExistingModelEntry> = {};
for (const id of mergedIds) {
mergedModels[id] = buildModelEntry(id, catalogById.get(id), existingModels[id]);
}
const provider: Record<string, unknown> = {
name: existingProvider?.name ?? "OmniRoute",
npm: existingProvider?.npm ?? "@ai-sdk/openai-compatible",
options: {
baseURL,
apiKey: options.apiKey,
...(existingProvider?.options ?? {}),
},
models: mergedModels,
};
// Carry over any other provider-level keys the user set (e.g. headers).
if (existingProvider) {
for (const [k, v] of Object.entries(existingProvider)) {
if (k === "name" || k === "npm" || k === "options" || k === "models") continue;
provider[k] = v;
}
}
const config: Record<string, unknown> = {
$schema: existing.$schema ?? "https://opencode.ai/config.json",
provider: { ...(existing.provider ?? {}), [providerId]: provider },
};
// Carry over top-level keys the user may have set (compaction, plugins,
// permission, mcp, etc.). We intentionally do NOT preserve `model` /
// `small_model` unless the generator was given an explicit model — the
// user's top-level model selection may point at a model that no longer
// exists, so we require an explicit value via `options.model`.
for (const [k, v] of Object.entries(existing)) {
if (k === "$schema" || k === "provider" || k === "model" || k === "small_model") continue;
config[k] = v;
}
if (typeof options.model === "string" && options.model.trim()) {
config.model = `${providerId}/${options.model.trim()}`;
} else if (typeof existing.model === "string" && existing.model.trim()) {
// Preserve the user's previous top-level `model` so a re-run doesn't
// silently drop their selection.
config.model = existing.model;
}
if (typeof existing.small_model === "string" && existing.small_model.trim()) {
config.small_model = existing.small_model;
}
return mergeGeneratedConfigText(existingSource, existing, config, providerId);
}
/**
* Synchronous variant used by the legacy CLI path. Emits a minimal
* `opencode.json` (just provider options + top-level model) without a
* catalog fetch. Kept for back-compat with the previous `config set
* opencode` command; the async variant above is what callers should use
* for the full, context-window-aware flow.
*/
export function generateOpencodeConfigSync(options: {
baseUrl: string;
apiKey: string;
model?: string;
}): string {
const cleanBase = options.baseUrl.replace(/\/+$/, "");
const base = cleanBase.endsWith("/v1") ? cleanBase.slice(0, -3) : cleanBase;
const config = {
provider: "omniroute",
baseURL: `${base}/v1`,
apiKey: options.apiKey,
model: options.model || "opencode",
};
return JSON.stringify(config, null, 2);
}
// Backwards-compatible default export: keeps the existing call sites in
// `config.mjs` working. The async variant above is the preferred entry
// point for new callers.
export default generateOpencodeConfigSync;