Skip to content

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

22.8 KB
Raw Blame
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;