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
/**
* OpenCode plugin for the OmniRoute AI Gateway.
*
* Implements the official `@opencode-ai/plugin` Plugin contract (auth +
* provider + config hooks) to drive a running OmniRoute instance from
* OpenCode without hand-curated `provider.<id>.models` blocks in
* opencode.json[c]:
*
* - `auth` — registers `/connect <providerId>` flow (API key prompt)
* - `provider` — dynamic `/v1/models` fetch with TTL cache, capabilities
* pass-through (OmniRoute is the source of truth — no
* client-side variant synthesis)
* - `config` — backward-compat shim for OC versions that predate the
* `provider.models` hook (≤ 1.14.48)
*
* Two ways to consume the plugin:
*
* 1. Single-instance (default `providerId: "omniroute"`):
*
* ```json
* {
* "$schema": "https://opencode.ai/config.json",
* "plugin": ["@omniroute/opencode-plugin"]
* }
* ```
*
* 2. Multi-instance via plugin options (prod + preprod side by side):
*
* ```json
* {
* "$schema": "https://opencode.ai/config.json",
* "plugin": [
* ["@omniroute/opencode-plugin", { "providerId": "omniroute" }],
* ["@omniroute/opencode-plugin", { "providerId": "omniroute-preprod" }]
* ]
* }
* ```
*
* Then `opencode connect <providerId>` to provision the API key per instance.
*
* Companion library: `@omniroute/opencode-provider` (build-time config generator)
* remains supported for users who can't run plugins (CI, scripted scaffolding).
*
* @see https://opencode.ai/docs/plugins for the OpenCode plugin contract.
* @see https://github.com/diegosouzapw/OmniRoute for the AI Gateway.
*/
import { createHash } from "node:crypto";
import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
import * as os from "node:os";
import * as path from "node:path";
import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { randomUUID } from "node:crypto";
import type { AuthHook, Config, Plugin, PluginOptions, ProviderHook } from "@opencode-ai/plugin";
import { tool } from "@opencode-ai/plugin";
import type { Model as ModelV2 } from "@opencode-ai/sdk/v2";
import { z } from "zod";
import {
createLogger,
logger as _logger,
type Logger as _Logger,
type LogLevel as _LogLevel,
} from "./logger.js";
import {
PROVIDER_TAG_SEPARATOR as _PROVIDER_TAG_SEPARATOR,
shortProviderLabel as _shortProviderLabel,
normaliseFreeLabel as _normaliseFreeLabel,
formatFreeBudget,
type FreeModelFreeType,
} from "./naming.js";
import { applyOmniRouteInferenceTelemetry } from "./telemetry.js";
/**
* Minimal leveled logger sink accepted by the default fetchers and the static
* catalog builder. A full `Logger` satisfies it structurally; the config hook
* injects the same partial shape (see `createOmniRouteConfigHook` deps).
*/
type OmniRouteLoggerSink = {
error?: (message: string, ...args: unknown[]) => void;
warn: (message: string, ...args: unknown[]) => void;
debug?: (message: string, ...args: unknown[]) => void;
};
/**
* Zod schema for plugin options accepted as the second element of the
* `plugin: [name, opts]` tuple in opencode.json. Strict by design — unknown
* keys are rejected so typos in opencode.json surface immediately at plugin
* construction time instead of silently being dropped.
*
* Doc per field:
*
* - `providerId` OpenCode provider id this plugin instance binds to.
* Multiple plugin instances coexist by giving each a
* different `providerId` ("omniroute", "omniroute-preprod",
* "omniroute-local"). Maps to `ProviderHook.id` and
* `AuthHook.provider` in the @opencode-ai/plugin contract.
* Default: "omniroute".
* - `displayName` Label rendered in the OpenCode UI. Default derives
* from providerId.
* - `modelCacheTtl` `/v1/models` TTL cache duration in milliseconds.
* Default: 300_000 (5 min).
* - `autoSyncIntervalMs` Background catalog re-discovery while OpenCode is
* running. Default: 300_000 (5 min). Minimum: 60_000.
* Set `0` to disable background auto-sync (TTL on-demand
* discovery still applies via `modelCacheTtl`).
* - `baseURL` Override base URL for this OmniRoute instance. When
* absent, the loader falls back to a credential-attached
* baseURL set by `/connect`.
* - `managementReadToken` Optional read-only management-plane bearer token.
* Used only for catalog GETs under `/api/*`; `/v1/*`
* inference continues to use the connected `apiKey`.
* Falls back to `apiKey` when unset.
*/
/**
* Optional feature toggles. Every field is opt-in/out per call; defaults
* mirror the v0.1.0 behaviour so existing opencode.json files do not need
* to change.
*
* - `combos` Discover `/api/combos` and surface them as
* pseudo-models with LCD capabilities. Default true.
* - `enrichment` Pull display names + pricing from
* `/api/pricing/models` and overlay them onto the
* ModelV2 entries derived from `/v1/models`. Solves
* the "raw id in UI" complaint without client-side
* heuristics. Default true.
* - `compressionMetadata` Pull `/api/context/combos` so combo entries can
* be tagged with their compression pipeline
* (e.g. `rtk:standard → caveman:full`). Off by
* default — adds one network call per refresh and
* the data is only useful for combo entries.
* - `geminiSanitization` Strip `$schema`/`$ref`/`additionalProperties`
* from `tools[].function.parameters` when the
* model id contains "gemini". Default true.
* - `mcpAutoEmit` Auto-write an `mcp.<providerId>` remote entry
* into the OC config pointing at
* `<baseURL>/api/mcp/stream` with the resolved
* Bearer token. Default false — keeps opencode.json
* in control unless explicitly opted in.
* - `mcpToken` Optional separate Bearer token to use in the
* auto-emitted MCP entry. Falls back to the
* provider's API key (from auth.json) when unset.
* Useful when a narrower-scoped MCP-only key is
* preferred over the chat/inference key.
* - `fetchInterceptor` Inject Authorization: Bearer + Content-Type only
* on same-origin `/v1/chat/completions` and
* `/v1/models` requests. Default true.
* - `debugLog` Capture every outbound request + response to a
* JSONL file at
* `~/.local/share/opencode/plugins/omniroute-debug-{providerId}.jsonl`.
* Each line: `{ reqId, ts, url, method, reqBody,
* resStatus, resBody, durationMs }`.
* Default false. Opt-in.
* - `apiFormat` Per-provider-prefix API format routing. Model IDs
* whose prefix (the part before `/`) matches an entry
* in `anthropicPrefixes` are served via the Anthropic
* SDK (`@ai-sdk/anthropic`, sends to `/v1/messages`
* with native cache_control, tool_choice, etc.).
* All other models fall back to `openai-compatible`.
*
* Default `anthropicPrefixes`:
* ["cc", "claude", "anthropic", "kiro", "kr"]
* (covers OmniRoute's canonical Anthropic aliases).
*
* Set `anthropicPrefixes: []` to disable and force
* everything through OpenAI-compat.
*
* Example:
* ```json
* "apiFormat": { "anthropicPrefixes": ["cc","claude","anthropic","kiro"] }
* ```
*/
const apiFormatSchema = z
.object({
anthropicPrefixes: z.array(z.string()).optional(),
})
.strict()
.optional();
const featuresSchema = z
.object({
combos: z.boolean().optional(),
autoCombos: z.boolean().optional(),
enrichment: z.boolean().optional(),
compressionMetadata: z.boolean().optional(),
geminiSanitization: z.boolean().optional(),
mcpAutoEmit: z.boolean().optional(),
mcpToken: z.string().min(1).optional(),
fetchInterceptor: z.boolean().optional(),
usableOnly: z.boolean().optional(),
visibleModels: z.array(z.string().min(1)).optional(),
hiddenModels: z.array(z.string().min(1)).optional(),
diskCache: z.boolean().optional(),
/**
* Opt-in max age for a disk-cache fallback snapshot, in milliseconds.
* Unset or `0` keeps the historical unbounded default: a stale snapshot
* is still served. A positive bound does not refuse the snapshot; the
* fallback log escalates from warn to error once the snapshot is older.
*/
diskCacheMaxAgeMs: z.number().nonnegative().optional(),
providerTag: z.boolean().optional(),
debugLog: z.boolean().optional(),
startupDebug: z.boolean().optional(),
logLevel: z.enum(["error", "warn", "info", "debug"]).optional(),
apiFormat: apiFormatSchema,
})
.strict();
const optionsSchema = z
.object({
providerId: z
.string()
.min(1)
.regex(/^[a-z0-9-]+$/i, "providerId must be a slug")
.optional(),
displayName: z.string().min(1).optional(),
modelCacheTtl: z.number().positive().optional(),
/**
* Background auto-discovery interval while the harness is running.
* `0` disables background polling. Values in (0, 60000) are clamped up
* to 60000. Default when unset: 300000.
*/
autoSyncIntervalMs: z.number().int().nonnegative().optional(),
baseURL: z
.string()
.trim()
.refine(isHttpUrl, "baseURL must be an http(s) URL, for example http://localhost:20128")
.optional(),
managementReadToken: z.string().min(1).optional(),
features: featuresSchema.optional(),
})
.strict();
/**
* Plugin options shape — inferred directly from the Zod schema so the
* validator and the static type can never drift. Replaces the standalone
* interface previously declared here (T-02). Every consumer continues to
* import `OmniRoutePluginOptions` as before; only the source of truth
* shifted from a hand-written interface to `z.infer<typeof optionsSchema>`.
*/
export type OmniRoutePluginOptions = z.infer<typeof optionsSchema>;
/**
* Explicit default state for every boolean `features.*` toggle.
*
* #7624: `featuresSchema` marks every flag `.optional()` with no default, and
* the effective value is applied implicitly at each read site (default-ON flags
* use the `features.X !== false` convention, default-OFF flags use
* `features.X === true`). That implicit convention is scattered across the file,
* so an operator who omits the `features` block cannot tell whether
* combos / enrichment are enabled — they think features are
* disabled when they are actually on. Centralising the declared defaults here
* (mirroring the read-site conventions exactly, so runtime behaviour is
* unchanged) makes the effective flags introspectable and self-documenting.
*
* `features.autoCombos` is accepted but ignored: it stays in the schema (and
* in the defaults below) so existing configurations still validate, but no
* read site consults it anymore and it is hidden from startup diagnostics.
*/
export const OMNIROUTE_FEATURE_DEFAULTS = {
// default-ON (read sites use `features.X !== false`)
combos: true,
autoCombos: true,
enrichment: true,
diskCache: true,
providerTag: true,
fetchInterceptor: true,
geminiSanitization: true,
// default-OFF (read sites use `features.X === true`)
compressionMetadata: false,
usableOnly: false,
// Array flags: unset/empty = no filter. These are not boolean toggles —
// they are operator-curated model-ID lists applied in the dynamic and static
// hooks alongside usableOnly (all filters AND together).
// visibleModels: undefined, // allowlist — only listed IDs pass
// hiddenModels: undefined, // blocklist — listed IDs are dropped
mcpAutoEmit: false,
debugLog: false,
startupDebug: false,
} as const;
/** Union of the boolean feature-flag keys declared in `OMNIROUTE_FEATURE_DEFAULTS`. */
export type OmniRouteFeatureFlag = keyof typeof OMNIROUTE_FEATURE_DEFAULTS;
/**
* Resolve the EFFECTIVE boolean state of every feature toggle, applying the
* declared default for any flag the operator omitted. A missing `features`
* block (or an empty one) yields the full default set — so callers and the
* startup diagnostics can surface exactly which features are active instead of
* relying on the implicit `!== false` / `=== true` conventions. Purely
* derived: it does not mutate options nor change any read-site behaviour.
*/
export function resolveEffectiveFeatureFlags(
features?: OmniRoutePluginOptions["features"]
): Record<OmniRouteFeatureFlag, boolean> {
const f: Partial<Record<OmniRouteFeatureFlag, boolean>> = features ?? {};
const out = {} as Record<OmniRouteFeatureFlag, boolean>;
for (const key of Object.keys(OMNIROUTE_FEATURE_DEFAULTS) as OmniRouteFeatureFlag[]) {
const val = f[key];
out[key] = typeof val === "boolean" ? val : OMNIROUTE_FEATURE_DEFAULTS[key];
}
return out;
}
export const OMNIROUTE_PROVIDER_KEY = "omniroute" as const;
/** Deployed plugin version (injected at build time by tsup define). */
export const PLUGIN_VERSION: string =
((globalThis as Record<string, unknown>).__PLUGIN_VERSION__ as string) ?? "dev";
/** Deployed plugin git commit hash (injected at build time by tsup define). */
export const PLUGIN_GIT_HASH: string =
((globalThis as Record<string, unknown>).__PLUGIN_GIT_HASH__ as string) ?? "unknown";
export const DEFAULT_MODEL_CACHE_TTL_MS = 300_000 as const;
/** Default background auto-discovery interval (matches modelCacheTtl default). */
export const DEFAULT_AUTO_SYNC_INTERVAL_MS = 300_000 as const;
/** Minimum positive background auto-discovery interval. */
export const MIN_AUTO_SYNC_INTERVAL_MS = 60_000 as const;
/**
* Sanitize background auto-sync interval.
* - unset/invalid → default 300_000
* - explicit 0 → disabled
* - (0, 60000) → clamped to 60000
* - ≥ 60000 → kept as integer ms
*/
export function sanitizeAutoSyncIntervalMs(value: unknown): number {
if (value === undefined || value === null) return DEFAULT_AUTO_SYNC_INTERVAL_MS;
if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_AUTO_SYNC_INTERVAL_MS;
const n = Math.trunc(value);
if (n === 0) return 0;
if (n < 0) return DEFAULT_AUTO_SYNC_INTERVAL_MS;
if (n < MIN_AUTO_SYNC_INTERVAL_MS) return MIN_AUTO_SYNC_INTERVAL_MS;
return n;
}
// Manual trim helpers avoid polynomial-regex CodeQL warnings on
// user-supplied baseURL strings (string.replace(/\/+$/, "")). The same
// behaviour, no backtracking.
function trimTrailingSlashes(value: string): string {
let i = value.length;
while (i > 0 && value.charCodeAt(i - 1) === 0x2f /* "/" */) i--;
return i === value.length ? value : value.slice(0, i);
}
function trimTrailingDashes(value: string): string {
let i = value.length;
while (i > 0 && value.charCodeAt(i - 1) === 0x2d /* "-" */) i--;
return i === value.length ? value : value.slice(0, i);
}
function trimLeadingDashes(value: string): string {
let i = 0;
while (i < value.length && value.charCodeAt(i) === 0x2d /* "-" */) i++;
return i === 0 ? value : value.slice(i);
}
/**
* Resolve effective options from the optional plugin-options object,
* applying defaults. Centralises the providerId fallback so every hook
* sees a consistent identifier.
*/
export function resolveOmniRoutePluginOptions(opts?: OmniRoutePluginOptions): Required<
Pick<
OmniRoutePluginOptions,
"providerId" | "displayName" | "modelCacheTtl" | "autoSyncIntervalMs"
>
> & {
/**
* #6859: the UNPREFIXED provider id ("omniroute", "omniroute-preprod", …).
* `providerId` above is auto-prefixed with "opencode-" ONLY to satisfy OC
* 1.17.8+'s native-adapter gate ({openai, anthropic, opencode*}) — that
* prefixed value is OC-internal and must be used ONLY for AuthHook.provider
* and provider-registration keys (the OC config-hook top-level
* `provider.<id>` block). `omnirouteProviderId` MUST be used everywhere an
* identifier reaches or represents something OmniRoute's own server parses
* (model `id` prefix, `ModelV2.providerID`, combo catalog keys in the
* dynamic provider hook) — OmniRoute's `parseModel()` has no alias for
* "opencode-<x>", so a prefixed id there is unrecoverable and credential
* lookup fails with "No credentials for opencode-<x>".
*/
omnirouteProviderId: string;
} & Pick<OmniRoutePluginOptions, "baseURL" | "managementReadToken" | "features"> {
const rawProviderId = opts?.providerId ?? OMNIROUTE_PROVIDER_KEY;
const omnirouteProviderId = trimLeadingOpencodePrefix(rawProviderId);
// OC 1.17.8+ native-adapter gate rejects providerID not in
// {openai, anthropic, opencode*}. Silently prefix so existing
// configs (providerId: "omniroute") keep working.
const providerId = rawProviderId.startsWith("opencode-")
? rawProviderId
: `opencode-${rawProviderId}`;
const displayName =
opts?.displayName ??
(providerId === `opencode-${OMNIROUTE_PROVIDER_KEY}`
? "OmniRoute"
: `OmniRoute (${providerId})`);
const modelCacheTtl =
typeof opts?.modelCacheTtl === "number" && opts.modelCacheTtl > 0
? opts.modelCacheTtl
: DEFAULT_MODEL_CACHE_TTL_MS;
const autoSyncIntervalMs = sanitizeAutoSyncIntervalMs(opts?.autoSyncIntervalMs);
return {
providerId,
omnirouteProviderId,
displayName,
modelCacheTtl,
autoSyncIntervalMs,
baseURL: opts?.baseURL,
managementReadToken: opts?.managementReadToken,
features: opts?.features,
};
}
/** Fully resolved plugin options (defaults applied). */
export type ResolvedOmniRoutePluginOptions = ReturnType<typeof resolveOmniRoutePluginOptions>;
/**
* Strip a leading "opencode-" prefix (added only for the OC native-adapter
* gate — see `resolveOmniRoutePluginOptions`) so the returned id is safe to
* embed in anything OmniRoute's own server parses. A user-supplied
* `providerId: "opencode-omniroute"` (already prefixed) resolves to the same
* unprefixed "omniroute" as the default, matching `providerId`'s own
* idempotent-prefix handling above.
*/
function trimLeadingOpencodePrefix(rawProviderId: string): string {
return rawProviderId.startsWith("opencode-")
? rawProviderId.slice("opencode-".length)
: rawProviderId;
}
/**
* Strict parse of raw plugin options (as received from opencode.json or a
* direct factory call) into the validated `OmniRoutePluginOptions` shape.
*
* - `null` / `undefined` → `{}` (no opts is valid, defaults take over).
* - Unknown keys → throws (strict schema catches typos in opencode.json).
* - Empty / malformed values (e.g. empty providerId, non-URL baseURL,
* negative modelCacheTtl) → throws.
*
* Validation happens at plugin invocation time (inside `OmniRoutePlugin`),
* NOT at module import — so a bad opencode.json fails the affected plugin
* instance with an actionable message instead of crashing the whole TUI on
* startup.
*
* Exported so callers and tests can validate options independent of the
* full plugin factory invocation.
*/
export function parseOmniRoutePluginOptions(opts: unknown): OmniRoutePluginOptions {
if (opts === null || opts === undefined) return {};
const result = optionsSchema.safeParse(opts);
if (!result.success) {
const errs = result.error.issues
.map((i) => {
const path = i.path.length > 0 ? i.path.join(".") : "<root>";
return `${path}: ${i.message}`;
})
.join("; ");
throw new Error(`Invalid @omniroute/opencode-plugin options: ${errs}`);
}
return result.data;
}
/**
* Internal coercion shim. Delegates to `parseOmniRoutePluginOptions` to keep
* the public surface stable while routing all validation through the Zod
* schema. Always returns an object (never undefined) so downstream hooks see
* the same shape regardless of whether opencode.json passed `null`,
* `undefined`, or an empty bag.
*/
function coercePluginOptions(opts?: PluginOptions): OmniRoutePluginOptions {
return parseOmniRoutePluginOptions(opts);
}
// ────────────────────────────────────────────────────────────────────────────
// Per-prefix API format routing (apiFormat feature)
// ────────────────────────────────────────────────────────────────────────────
/**
* Default provider-prefix list that triggers the Anthropic SDK format.
* Covers OmniRoute's canonical Anthropic aliases: `cc/`, `claude/`,
* `anthropic/`, plus the user-configured `kiro/` and `kr/` upstream
* connections that proxy Anthropic models.
*/
export const DEFAULT_ANTHROPIC_PREFIXES = ["cc", "claude", "anthropic", "kiro", "kr"];
/**
* First-class OmniRoute catalog suffixes (`GET /v1/models`). The Anthropic
* Messages translator looks these up as `claude-<model>` on provider
* `claude` and 404s. Keep them on openai-compatible `/v1` so the full
* catalog id (`cc/claude-haiku-4-5-20251001-low`) is sent unchanged.
*/
export const OPENAI_COMPAT_EFFORT_TIER_SUFFIXES = [
"-low",
"-medium",
"-high",
"-xhigh",
"-thinking",
"-minimal",
"-max",
] as const;
function hasOpenAiCompatEffortTierSuffix(modelId: string): boolean {
const lower = modelId.toLowerCase();
return OPENAI_COMPAT_EFFORT_TIER_SUFFIXES.some((suffix) => lower.endsWith(suffix));
}
/**
* Ensure a baseURL ends with `/v1` so the OpenAI-compat SDK constructs
* `/v1/chat/completions` correctly. The Anthropic SDK does NOT want `/v1`
* (it appends `/v1/messages` automatically), so callers should branch on
* format first.
*/
/**
* A url the AI SDK can actually call. `new URL()` alone is not enough: it
* parses `localhost:20128` as the scheme `localhost:` and `ftp://host` as ftp,
* both of which reach `fetch` and fail there. Mirrors the `isHttpUrl` guard the
* settings schema applies to `headroomUrl`.
*/
export function isHttpUrl(value: unknown): boolean {
if (typeof value !== "string") return false;
try {
const { protocol } = new URL(value);
return protocol === "http:" || protocol === "https:";
} catch {
return false;
}
}
export function ensureV1Suffix(url: string): string {
const trimmed = trimTrailingSlashes(url);
return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
}
/**
* Resolve the API block (id + url + npm package) for a given model id.
*
* Decision matrix:
* - If the model id ends with a first-class OmniRoute effort-tier suffix
* (`-low` / `-medium` / `-high` / `-xhigh` / `-thinking` / `-minimal` /
* `-max`), return the OpenAI-compat block even when the prefix is
* Anthropic. Those ids exist only in `GET /v1/models`; the Anthropic
* Messages path 404s them as `claude-<name>` on provider `claude`.
* - Else if the model id's prefix (the substring before the first `/`) is in
* `apiFormat.anthropicPrefixes` (or the default list), return the
* Anthropic SDK block: `id: "anthropic"`, `url: baseURL` (no `/v1`),
* `npm: "@ai-sdk/anthropic"`.
* - Otherwise return the OpenAI-compat block: `id: "openai-compatible"`,
* `url: baseURL + "/v1"`, `npm: "@ai-sdk/openai-compatible"`.
*
* Combos span multiple providers. Callers should pass each combo member's
* id through this function and pick the LCD format (lowest common
* denominator that every upstream actually understands).
*/
export function resolveApiBlock(
modelId: string,
baseURL: string,
apiFormat?: { anthropicPrefixes?: string[] }
): { id: string; url: string; npm: string } {
const prefixes = apiFormat?.anthropicPrefixes ?? DEFAULT_ANTHROPIC_PREFIXES;
const slash = modelId.indexOf("/");
const prefix = slash === -1 ? modelId : modelId.slice(0, slash);
const isAnthropic = prefixes.includes(prefix) && !hasOpenAiCompatEffortTierSuffix(modelId);
return isAnthropic
? {
id: "anthropic",
url: trimTrailingSlashes(baseURL),
npm: "@ai-sdk/anthropic",
}
: {
id: "openai-compatible",
url: ensureV1Suffix(baseURL),
npm: "@ai-sdk/openai-compatible",
};
}
/**
* Build the AuthHook portion of the plugin for a given options bag. Exported
* standalone so the auth contract can be unit-tested without faking the full
* PluginInput / Hooks surface.
*
* Contract notes:
* - `provider` binds to `providerId` (NOT a hardcoded module constant — fixes
* the multi-instance bug in [email protected] which pinned
* `OMNIROUTE_PROVIDER_ID = "omniroute"` at module scope).
* - `methods[0]` is the `api` flavor (no OAuth flow; OmniRoute issues bearer
* keys directly). Label includes the resolved displayName so multi-instance
* setups stay distinguishable in the OC TUI.
* - `methods[0].prompts` uses the official `{type:"text", key, message}`
* shape from `@opencode-ai/[email protected]`. The contract does NOT expose
* a `mask: true` flag on text prompts — the OC TUI is expected to handle
* credential masking by itself (per OC's `auth login` UX).
* - `loader` reads the stored credentials via `getAuth()` and projects them
* into the AI-SDK `openai-compatible` options shape (`apiKey`, `baseURL`).
* The fetch interceptor (`fetch`) is wired in T-04; left absent here so
* downstream code falls back to the SDK default fetch.
* - The loader rejects non-`api` auth flavors (oauth / wellknown) and empty
* keys by returning `{}` — OC then surfaces the `/connect` flow to the
* user instead of dispatching a request with bogus credentials.
*/
export function createOmniRouteAuthHook(opts?: OmniRoutePluginOptions): AuthHook {
const { providerId, displayName, baseURL, features } = resolveOmniRoutePluginOptions(opts);
// Both fetch-layer features default ON (parity with the rest of the plugin's
// `features.X !== false` convention). Honoring them here lets users disable
// the interceptor/sanitizer from opencode.json — previously these flags were
// documented and schema-validated but silently ignored.
const wantFetchInterceptor = (features ?? {}).fetchInterceptor !== false;
const wantGeminiSanitization = (features ?? {}).geminiSanitization !== false;
const wantDebugLog = (features ?? {}).debugLog === true;
const hook: AuthHook = {
provider: providerId,
methods: [
{
type: "api",
label: `${displayName} API Key`,
prompts: [
{
type: "text",
key: "apiKey",
message: `OmniRoute API key (${providerId})`,
},
],
},
],
loader: async (getAuth, _provider) => {
const auth = await getAuth();
if (
auth &&
typeof auth === "object" &&
(auth as { type?: unknown }).type === "api" &&
typeof (auth as { key?: unknown }).key === "string" &&
(auth as { key: string }).key.length > 0
) {
const apiKey = (auth as { key: string }).key;
// baseURL resolution: plugin opts win, then a credential-attached
// baseURL (some auth backends stash it alongside the key), else empty.
// Re-cast through `unknown` first: Auth is a discriminated union
// (api | oauth | wellknown) and TS refuses a direct narrowing to a
// hypothetical `{ baseURL: string }` shape because WellKnownAuth has
// no `baseURL`. We've already checked the runtime type via typeof so
// the unknown-bridge is a safe assertion, not a lie.
const authBaseURL = (auth as unknown as { baseURL?: unknown }).baseURL;
const resolvedBaseURL = baseURL ?? (typeof authBaseURL === "string" ? authBaseURL : "");
// Without a baseURL the interceptor can't tell which requests to
// intercept (it would either gate-keep nothing or, worse, all
// outbound traffic). Fall back to apiKey-only and let the SDK use
// its default fetch. The /connect flow + plugin opts should make
// this branch unreachable in practice.
if (!resolvedBaseURL) {
return { apiKey };
}
// Composition: sanitise Gemini tool schemas FIRST (T-06), then inject
// Bearer (T-04). Both layers are pure with respect to the other's
// concern (body vs headers) so order is logically free; wrapping the
// pure body-transform around the header-injecting interceptor reads
// cleaner and keeps T-06 testable in isolation against any inner fetch
// (real or stub). Each layer is gated by its feature flag; when both
// are disabled we fall back to the SDK's default fetch (apiKey only).
let composedFetch: typeof fetch | undefined;
if (wantFetchInterceptor) {
composedFetch = createOmniRouteFetchInterceptor({
apiKey,
baseURL: resolvedBaseURL,
});
}
if (wantGeminiSanitization) {
composedFetch = createGeminiSanitizingFetch(composedFetch ?? fetch);
}
if (wantDebugLog || debugLogEnabled(providerId)) {
composedFetch = createDebugLoggingFetch(composedFetch ?? fetch, providerId, wantDebugLog);
}
return composedFetch
? { apiKey, baseURL: resolvedBaseURL, fetch: composedFetch }
: { apiKey, baseURL: resolvedBaseURL };
}
return {};
},
};
return hook;
}
/**
* Plugin factory. Returns the OpenCode Plugin object wired with the three
* hooks. Concrete hook bodies land in subsequent tickets (T-03 provider.models,
* T-04 fetch interceptor, T-06 Gemini sanitization, T-07 config backward-compat).
*
* Per `@opencode-ai/[email protected]`, the Plugin signature is
* `(input: PluginInput, options?: PluginOptions) => Promise<Hooks>` — opts
* arrive as the SECOND argument (from the `[name, opts]` tuple in
* opencode.json), NOT as a closure binding. Multi-instance support follows
* from each plugin tuple invoking the factory with its own opts.
*/
/**
* Invalidate in-memory fetch cache entries for a baseURL (all credential keys).
* Returns number of entries removed.
*/
export function invalidateOmniRouteFetchCache(
cache: OmniRouteFetchCache,
baseURL?: string
): number {
if (!baseURL) {
const n = cache.size;
cache.clear();
return n;
}
const prefix = `${baseURL}::`;
let removed = 0;
for (const key of [...cache.keys()]) {
if (key.startsWith(prefix) || key === baseURL) {
cache.delete(key);
removed += 1;
}
}
return removed;
}
/**
* Resolve API credentials for force-sync / background refresh without
* depending on the provider.models auth context.
*/
export async function resolveOmniRouteRuntimeAuth(
resolved: ResolvedOmniRoutePluginOptions,
readAuthJson?: OmniRouteReadAuthJson
): Promise<{ apiKey: string; baseURL: string; managementReadToken: string } | null> {
const reader = readAuthJson ?? defaultReadAuthJson;
let authJson: AuthJsonShape | undefined | null;
try {
authJson = await reader();
} catch {
authJson = undefined;
}
if (authJson === null) authJson = undefined;
const bareKey = resolved.providerId.startsWith("opencode-")
? resolved.providerId.slice("opencode-".length)
: resolved.providerId;
const lookupKeys = [resolved.providerId];
if (bareKey !== resolved.providerId) lookupKeys.push(bareKey);
if (resolved.omnirouteProviderId && !lookupKeys.includes(resolved.omnirouteProviderId)) {
lookupKeys.push(resolved.omnirouteProviderId);
}
let entry: AuthJsonApiEntry | undefined;
for (const k of lookupKeys) {
const e = authJson?.[k];
if (
e &&
(e as { type?: unknown }).type === "api" &&
typeof (e as { key?: unknown }).key === "string" &&
(e as { key: string }).key.length > 0
) {
entry = e as AuthJsonApiEntry;
break;
}
}
const apiKey = entry?.key ?? "";
if (!apiKey) return null;
const authBaseURL =
entry && typeof (entry as { baseURL?: unknown }).baseURL === "string"
? (entry as { baseURL: string }).baseURL
: "";
const baseURL = resolved.baseURL ?? (authBaseURL || "");
if (!baseURL) return null;
const managementReadToken = resolved.managementReadToken ?? apiKey;
return { apiKey, baseURL, managementReadToken };
}
/**
* Force-refresh OmniRoute catalog: re-fetch /v1/models (and optional management
* endpoints) and, only once the models fetch succeeds, replace the memory and
* disk caches. A failed models fetch leaves both caches untouched (#14926).
* OpenCode equivalent of Pi `/omni sync`.
*/
export async function forceSyncOmniRouteModels(args: {
resolved: ResolvedOmniRoutePluginOptions;
cache: OmniRouteFetchCache;
readAuthJson?: OmniRouteReadAuthJson;
fetcher?: OmniRouteModelsFetcher;
combosFetcher?: OmniRouteCombosFetcher;
enrichmentFetcher?: OmniRouteEnrichmentFetcher;
compressionMetaFetcher?: OmniRouteCompressionMetaFetcher;
providersFetcher?: OmniRouteProvidersFetcher;
now?: () => number;
logger?: _Logger;
}): Promise<{
ok: boolean;
count: number;
combos: number;
provider: string;
baseURL?: string;
clearedMemory: number;
clearedDisk: boolean;
error?: string;
}> {
const resolved = args.resolved;
const cache = args.cache;
const now = args.now ?? Date.now;
const fetcher = args.fetcher ?? defaultOmniRouteModelsFetcher;
const combosFetcher = args.combosFetcher ?? defaultOmniRouteCombosFetcher;
const enrichmentFetcher = args.enrichmentFetcher ?? defaultOmniRouteEnrichmentFetcher;
const compressionMetaFetcher =
args.compressionMetaFetcher ?? defaultOmniRouteCompressionMetaFetcher;
const providersFetcher = args.providersFetcher ?? defaultOmniRouteProvidersFetcher;
const logger =
args.logger ??
createLogger(
resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")
);
const features = resolved.features ?? {};
const wantCombos = features.combos !== false;
const wantEnrichment = features.enrichment !== false;
const wantCompressionMeta = features.compressionMetadata === true;
const wantUsableOnly = features.usableOnly === true;
const wantDiskCache = features.diskCache !== false;
const auth = await resolveOmniRouteRuntimeAuth(
resolved,
args.readAuthJson ?? defaultReadAuthJson
);
if (!auth) {
return {
ok: false,
count: 0,
combos: 0,
provider: resolved.omnirouteProviderId,
clearedMemory: 0,
clearedDisk: false,
error:
"No OmniRoute credentials/baseURL available. Run `opencode connect omniroute` or set plugin baseURL.",
};
}
// The models fetch is the only required call. Run it BEFORE touching any
// cache: invalidating memory or unlinking the disk snapshot first meant a
// single transient failure (e.g. the 10s abort) destroyed the last good
// catalog and left every later read hitting a server that was already
// slow (#14926). On failure both caches stay exactly as they were.
let rawModels: OmniRouteRawModelEntry[];
try {
rawModels = await fetcher(auth.baseURL, auth.apiKey, 10_000);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
logger.warn(
`force sync: /v1/models fetch failed providerId=${resolved.providerId}; ` +
`keeping existing memory and disk cache: ${message}`
);
return {
ok: false,
count: 0,
combos: 0,
provider: resolved.omnirouteProviderId,
baseURL: auth.baseURL,
clearedMemory: 0,
clearedDisk: false,
error: message,
};
}
let clearedMemory = 0;
let clearedAll = 0;
let clearedDisk = false;
try {
let rawCombos: OmniRouteRawCombo[] = [];
if (wantCombos) {
try {
rawCombos = await combosFetcher(auth.baseURL, auth.managementReadToken, 10_000);
} catch (err) {
logger.warn("force sync: combos fetch failed", err);
}
}
let rawEnrichment: OmniRouteEnrichmentMap = new Map();
if (wantEnrichment) {
try {
rawEnrichment = await enrichmentFetcher(auth.baseURL, auth.managementReadToken, 10_000);
} catch {
rawEnrichment = new Map();
}
}
let rawCompressionCombos: OmniRouteCompressionCombo[] = [];
if (wantCompressionMeta) {
try {
rawCompressionCombos = await compressionMetaFetcher(
auth.baseURL,
auth.managementReadToken,
10_000
);
} catch {
rawCompressionCombos = [];
}
}
let rawConnections: OmniRouteProviderConnection[] = [];
if (wantUsableOnly) {
try {
rawConnections = await providersFetcher(auth.baseURL, auth.managementReadToken, 10_000);
} catch {
rawConnections = [];
}
}
const t = now();
const entry = {
rawModels,
rawCombos,
rawEnrichment,
rawCompressionCombos,
rawConnections,
expiresAt: t + resolved.modelCacheTtl,
};
const cacheKey = modelsCacheKey(auth.baseURL, `${auth.apiKey}\0${auth.managementReadToken}`);
// Only now, with a fresh catalog in hand, drop the old entries.
clearedMemory = invalidateOmniRouteFetchCache(cache, auth.baseURL);
// Clear residual entries from prior baseURL history as well.
clearedAll = invalidateOmniRouteFetchCache(cache);
cache.set(cacheKey, entry);
if (wantDiskCache) {
// Overwrite the snapshot instead of unlinking it first, so the old file
// is only replaced once a fresh catalog exists. The writer soft-fails.
try {
const fingerprint = diskSnapshotIdentityFingerprint(
auth.baseURL,
auth.apiKey,
auth.managementReadToken
);
const { expiresAt: _expiresAt, ...diskEntry } = entry;
await defaultDiskSnapshotWriter(resolved.providerId, diskEntry, fingerprint);
clearedDisk = true;
} catch {
/* soft-fail disk write */
}
if (resolved.omnirouteProviderId !== resolved.providerId) {
clearedDisk = (await clearDiskSnapshot(resolved.omnirouteProviderId)) || clearedDisk;
}
}
logger.info(
`force sync ok providerId=${resolved.providerId} ` +
`models=${rawModels.length} combos=${rawCombos.length} ` +
`clearedMemory=${clearedMemory + clearedAll} disk=${clearedDisk}`
);
return {
ok: true,
count: rawModels.length,
combos: rawCombos.length,
provider: resolved.omnirouteProviderId,
baseURL: auth.baseURL,
clearedMemory: clearedMemory + clearedAll,
clearedDisk,
};
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
return {
ok: false,
count: 0,
combos: 0,
provider: resolved.omnirouteProviderId,
baseURL: auth.baseURL,
clearedMemory: clearedMemory + clearedAll,
clearedDisk,
error: message,
};
}
}
export function createOmniRouteSyncModelsTool(args: {
resolved: ResolvedOmniRoutePluginOptions;
cache: OmniRouteFetchCache;
logger?: _Logger;
}): ReturnType<typeof tool> {
const { resolved, cache } = args;
return tool({
description:
"Force-refresh the OmniRoute model catalog (OpenCode equivalent of Pi `/omni sync`). " +
"Re-fetches GET /v1/models (and combos when enabled), then replaces the in-memory and disk " +
"caches; a failed fetch keeps the existing caches.",
args: {
reason: tool.schema
.string()
.optional()
.describe("Optional reason for the sync (logging only)"),
},
async execute(toolArgs) {
const result = await forceSyncOmniRouteModels({ resolved, cache, logger: args.logger });
const reason = toolArgs.reason ? ` reason=${toolArgs.reason}` : "";
if (!result.ok) {
return {
title: "OmniRoute sync failed",
output:
`OmniRoute model sync failed for provider=${result.provider}.${reason}\n` +
`${result.error ?? "unknown error"}`,
metadata: result,
};
}
return {
title: `OmniRoute sync: ${result.count} models`,
output:
`OmniRoute models synced.` +
`\nprovider: ${result.provider}` +
`\nbaseURL: ${result.baseURL}` +
`\nmodels: ${result.count}` +
`\ncombos: ${result.combos}` +
`\nclearedMemoryEntries: ${result.clearedMemory}` +
`\nclearedDiskSnapshot: ${result.clearedDisk}` +
`\nTTL: ${resolved.modelCacheTtl}ms` +
`\nautoSyncIntervalMs: ${resolved.autoSyncIntervalMs}` +
reason,
metadata: result,
};
},
});
}
/**
* Start background auto-discovery while the harness is running.
* Quiet: only logs when the model count changes or on errors.
* Returns a stop function.
*/
export function startOmniRouteAutoSync(args: {
resolved: ResolvedOmniRoutePluginOptions;
cache: OmniRouteFetchCache;
intervalMs?: number;
logger?: _Logger;
}): () => void {
const resolved = args.resolved;
const cache = args.cache;
const intervalMs = args.intervalMs ?? resolved.autoSyncIntervalMs;
const logger =
args.logger ??
createLogger(
resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")
);
if (!intervalMs || intervalMs <= 0) {
return () => {};
}
let stopped = false;
let inFlight: Promise<void> | null = null;
let lastCount: number | undefined;
const tick = () => {
if (stopped) return;
if (inFlight) return;
inFlight = (async () => {
const result = await forceSyncOmniRouteModels({ resolved, cache, logger });
if (!result.ok) {
logger.error(`auto-sync failed providerId=${resolved.providerId}: ${result.error}`);
return;
}
if (lastCount === undefined) {
lastCount = result.count;
return;
}
if (result.count !== lastCount) {
logger.info(
`auto-sync catalog size changed ${lastCount} → ${result.count} ` +
`(providerId=${resolved.providerId})`
);
lastCount = result.count;
}
})()
.catch((err) => {
logger.error(`auto-sync tick error: ${err instanceof Error ? err.message : String(err)}`);
})
.finally(() => {
inFlight = null;
});
};
// Delay first background tick by one interval so session start is not doubled
// with the normal provider.models cold fetch. Manual tool remains immediate.
const timer = setInterval(tick, intervalMs);
if (typeof timer === "object" && timer && "unref" in timer && typeof timer.unref === "function") {
timer.unref();
}
logger.info(`auto-sync enabled intervalMs=${intervalMs} providerId=${resolved.providerId}`);
return () => {
stopped = true;
clearInterval(timer);
};
}
export const OmniRoutePlugin: Plugin = async (_input, options) => {
const resolved = resolveOmniRoutePluginOptions(coercePluginOptions(options));
const logger = createLogger(
resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")
);
// T-07: a single per-plugin-instance cache shared between the provider
// hook (T-03/T-05) and the config-shim hook (T-07). On OC ≥1.14.49 both
// hooks fire within the same Plugin invocation, so a shared cache keeps
// /v1/models + /api/combos at exactly one round-trip per TTL refresh
// instead of two. On OC ≤1.14.48 only the config hook runs; the cache
// still works (single producer + single consumer through the same map).
// Each `OmniRoutePlugin(...)` invocation gets its OWN cache via closure,
// so prod + preprod side-by-side instances do NOT collide.
const sharedCache: OmniRouteFetchCache = new Map();
// Debug breadcrumb: confirm server() invocation + resolved options.
// Useful when diagnosing "is the plugin even running" from OC logs.
const _ver: string =
((globalThis as Record<string, unknown>).__PLUGIN_VERSION__ as string) ?? "dev";
const _hash: string =
((globalThis as Record<string, unknown>).__PLUGIN_GIT_HASH__ as string) ?? "unknown";
const _prefixes = resolved.features?.apiFormat?.anthropicPrefixes ?? DEFAULT_ANTHROPIC_PREFIXES;
logger.info(
`v${_ver} (${_hash}) initialized` +
` providerId=${resolved.providerId}` +
` baseURL=${resolved.baseURL ?? "(from auth.json)"}` +
` modelCacheTtl=${resolved.modelCacheTtl}ms` +
` apiFormat=anthropic:[${_prefixes.join(",")}]` +
` debugLog=${resolved.features?.debugLog ?? false}` +
` logLevel=${resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")}`
);
// Background auto-discovery while the harness is running (Pi parity).
// Interval 0 disables. TTL on-demand discovery still works via modelCacheTtl.
startOmniRouteAutoSync({ resolved, cache: sharedCache, logger });
const syncTool = createOmniRouteSyncModelsTool({ resolved, cache: sharedCache, logger });
const bareProviderId = resolved.omnirouteProviderId;
// Config hook: keep existing catalog shim, and register slash command
// templates that ask the agent to call the force-sync tool (OpenCode has no
// Pi-style registerCommand API; tools + command templates are the native path).
const baseConfigHook = createOmniRouteConfigHook(resolved, {
cache: sharedCache,
logger,
diskSnapshotReader: defaultDiskSnapshotReader,
diskSnapshotWriter: defaultDiskSnapshotWriter,
});
const configWithSyncCommand = async (input: Config) => {
await baseConfigHook(input);
const cfg = input as Config & {
command?: Record<
string,
{
template: string;
description?: string;
agent?: string;
model?: string;
subtask?: boolean;
}
>;
};
if (!cfg.command) cfg.command = {};
if (!cfg.command["omni-sync"]) {
cfg.command["omni-sync"] = {
description: "Force-refresh OmniRoute model catalog (like Pi /omni sync)",
template:
`Force-refresh the OmniRoute model catalog now using the omniroute_sync_models tool ` +
`(provider ${bareProviderId}). After the tool returns, briefly report model count and whether the sync succeeded.`,
};
}
if (!cfg.command["omni-autosync"]) {
cfg.command["omni-autosync"] = {
description: "Show OmniRoute auto-sync / cache status",
template:
`Report OmniRoute discovery status for provider ${bareProviderId}: ` +
`autoSyncIntervalMs=${resolved.autoSyncIntervalMs}, modelCacheTtl=${resolved.modelCacheTtl}. ` +
`If the user asked to refresh now, call omniroute_sync_models.`,
};
}
};
return {
auth: createOmniRouteAuthHook(resolved),
provider: createOmniRouteProviderHook(resolved, { cache: sharedCache, logger }),
config: configWithSyncCommand,
tool: {
omniroute_sync_models: syncTool,
},
};
};
/**
* v1 plugin shape per OC plugin loader (`packages/opencode/src/plugin/shared.ts:readV1Plugin`).
* OC checks the default export for an object with `{id, server}` shape FIRST.
* If that fails it falls back to legacy `getLegacyPlugins` which walks every
* named export and rejects any non-function value — our package has
* constants (OMNIROUTE_PROVIDER_KEY, DEFAULT_MODEL_CACHE_TTL_MS) + types +
* schemas as named exports, so the legacy path always fails for us.
*
* Using v1 shape skips the legacy walk entirely. The `id` field is the
* plugin MODULE identifier (one per published package); per-instance
* `providerId` still flows through `options.providerId` as before.
*/
const OmniRouteV1Plugin = {
id: "@omniroute/opencode-plugin",
server: OmniRoutePlugin,
};
export default OmniRouteV1Plugin;
// ────────────────────────────────────────────────────────────────────────────
// Provider hook (T-03) — /v1/models pass-through with TTL cache
// ────────────────────────────────────────────────────────────────────────────
/**
* Raw shape of a `/v1/models` entry from OmniRoute. Captured verbatim from
* the prod gateway response (sample at /tmp/prod-v1-models.json: 455 entries).
* STRICT source-of-truth (OQ-3): every field that lands in ModelV2 traces
* back to this shape — no client-side variant synthesis.
*/
export interface OmniRouteRawModelEntry {
id: string;
object?: string;
owned_by?: string;
root?: string | null;
parent?: string | null;
context_length?: number;
max_input_tokens?: number;
max_output_tokens?: number;
input_modalities?: string[];
output_modalities?: string[];
capabilities?: {
tool_calling?: boolean;
reasoning?: boolean;
vision?: boolean;
thinking?: boolean;
attachment?: boolean;
structured_output?: boolean;
temperature?: boolean;
/** Runtime-learned or synced reasoning tiers (server-gated, blind-mapped). */
effort_tiers?: string[];
};
release_date?: string;
last_updated?: string;
api_format?: string;
}
/**
* Fetcher contract: returns the raw `/v1/models` entry list from a running
* OmniRoute instance. Surfaced as a dependency so unit tests can inject a
* stub without monkey-patching global `fetch`.
*
* Why we inline this instead of using `@omniroute/opencode-provider`'s
* `fetchLiveModels`: the sibling helper returns a stripped `{id, name,
* contextLength?}` shape (see opencode-provider/src/index.ts:480-569) that
* drops the `capabilities` / `*_modalities` / `max_*_tokens` blocks T-03
* needs for ModelV2 pass-through. Adopting the sibling here would force a
* client-side re-fetch or re-introduce the synthesis we explicitly rejected
* in OQ-3. A 30-line raw fetcher is cheaper than mutating the sibling's
* stable v0.1.0 contract.
*/
export type OmniRouteModelsFetcher = (
baseURL: string,
apiKey: string,
timeoutMs?: number
) => Promise<OmniRouteRawModelEntry[]>;
/**
* Default fetcher: `GET <baseURL>/v1/models` with bearer auth + AbortController
* timeout. Accepts both the `{object:"list", data:[…]}` envelope OmniRoute
* emits today and a bare-array envelope (defensive — keeps the plugin
* working if a future OmniRoute build trims the wrapper). Anything that
* isn't an object with a string `id` is filtered out silently.
*/
export const defaultOmniRouteModelsFetcher: OmniRouteModelsFetcher = async (
baseURL,
apiKey,
timeoutMs = 30_000
) => {
if (!apiKey) throw new Error("@omniroute/opencode-plugin: apiKey required to fetch /v1/models");
if (!baseURL) throw new Error("@omniroute/opencode-plugin: baseURL required to fetch /v1/models");
const trimmed = trimTrailingSlashes(baseURL);
// Tolerate both `https://host` and `https://host/v1` forms — the gateway
// exposes /v1/models either way; we just don't want a double `/v1/v1`.
const url = /\/v\d+$/.test(trimmed) ? `${trimmed}/models` : `${trimmed}/v1/models`;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetch(url, {
method: "GET",
headers: {
Authorization: `Bearer ${apiKey}`,
Accept: "application/json",
},
signal: controller.signal,
});
if (!res.ok) {
const err = new Error(
`@omniroute/opencode-plugin: GET ${url} failed: ${res.status} ${res.statusText}`
) as Error & { statusCode: number; status: number };
err.statusCode = res.status;
err.status = res.status;
throw err;
}
const body = (await res.json()) as unknown;
const rawList: unknown[] = Array.isArray(body)
? body
: body && typeof body === "object" && Array.isArray((body as { data?: unknown }).data)
? ((body as { data: unknown[] }).data as unknown[])
: [];
const out: OmniRouteRawModelEntry[] = [];
for (const r of rawList) {
if (r && typeof r === "object" && typeof (r as { id?: unknown }).id === "string") {
out.push(r as OmniRouteRawModelEntry);
}
}
return out;
} finally {
clearTimeout(timer);
}
};
/**
* Map a raw `/v1/models` entry → `ModelV2` (the type @opencode-ai/sdk/v2
* exports as `Model`, re-exported by @opencode-ai/plugin as `ModelV2`).
*
* ModelV2 (as of @opencode-ai/sdk@v2 — see node_modules path
* `@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts:964-1043`) requires a much
* richer shape than the T-03 spec's mapping table assumed. Concretely it
* expects:
* - flat `id`, `name`, `providerID`, `api: {id,url,npm}`
* - nested `capabilities: { temperature, reasoning, attachment, toolcall,
* input:{text,audio,image,video,pdf}, output:{…}, interleaved }`
* - `cost: { input, output, cache:{read,write} }` (NOT optional)
* - `limit: { context, input?, output }`
* - `status: "alpha"|"beta"|"deprecated"|"active"`, `options:{}`, `headers:{}`
* - `release_date: string`
*
* Deviations from the T-03 spec (documented per ticket §2 "CRITICAL: Check
* the actual ModelV2 type and adapt if field names differ"):
* 1. Spec's flat `tool_call` / `reasoning` / `attachment` / `modalities`
* top-level fields don't exist in ModelV2 — folded into
* `capabilities.{toolcall, reasoning, attachment, input.*, output.*}`.
* 2. `cost: undefined` is illegal (cost is required). OmniRoute doesn't
* surface pricing on /v1/models, so we emit a zeroed cost block.
* Downstream OC reads this for display only — the live pricing is
* OmniRoute's responsibility at routing time.
* 3. `tool_call` (spec) → `toolcall` (ModelV2 field name; one word).
* 4. `attachment` (spec) maps from `capabilities.vision` per OmniRoute
* convention: vision = ability to receive image attachments. If the
* raw entry happens to expose an explicit `capabilities.attachment`
* (some combo entries do), that wins.
* 5. `thinking` from OmniRoute has no 1:1 ModelV2 slot. We OR it into
* `reasoning` so thinking-only models still surface a non-false
* reasoning flag.
* 6. `last_updated` from OmniRoute has no ModelV2 slot — dropped (the
* spec also flagged this as "may not exist", and the prod sample
* confirms it's optional). `release_date` lands in ModelV2.release_date
* with `""` fallback (the field is required as `string`).
* 7. `temperature: true` per OmniRoute convention (OpenAI-compat mode
* always supports the temperature knob). If a raw entry sets
* `capabilities.temperature` explicitly, that wins.
* 8. Input/output modality arrays: each known modality flips its boolean.
* Unknown strings (future OmniRoute additions) are ignored — when the
* server adds new modalities we can map them here without breaking
* existing entries.
* 9. `status: "active"` — OmniRoute doesn't tier models alpha/beta on
* /v1/models, and OC needs a non-deprecated status to expose the
* model in the picker. If a future entry surfaces an explicit
* lifecycle hint we can map it then.
* 10. `options: {}` and `headers: {}` left empty — they're escape hatches
* for OC users to attach per-model overrides; the provider plugin
* must not preempt them.
* 11. `limit.input` is OPTIONAL on ModelV2 (the `?` modifier). We only
* emit it when OmniRoute supplies `max_input_tokens` — keeps the
* shape clean for combo entries that only carry context_length.
*/
export function mapRawModelToModelV2(
raw: OmniRouteRawModelEntry,
ctx: { providerId: string; baseURL: string; apiFormat?: { anthropicPrefixes?: string[] } }
): ModelV2 {
const caps = raw.capabilities ?? {};
// effort_tiers loop: server-declared tiers become ModelV2 variants so the
// UI offers exactly the tiers OmniRoute vouches for (instead of opencode's
// invented [low, medium, high] fallback). Blind: filtering/exclusion rules
// live server-side. Absent/empty/malformed => key omitted ENTIRELY (an
// empty variants object would suppress opencode's fallback for this model).
const declaredTiers = Array.isArray(caps.effort_tiers)
? caps.effort_tiers.filter((t): t is string => typeof t === "string" && t.length > 0)
: [];
const variants =
declaredTiers.length > 0
? Object.fromEntries(declaredTiers.map((tier) => [tier, { reasoningEffort: tier }]))
: undefined;
const inMods = new Set(raw.input_modalities ?? ["text"]);
const outMods = new Set(raw.output_modalities ?? ["text"]);
return {
// OC's static-catalog reader parses the key on `/` to recover
// `(providerID, modelID)`. If the raw id is already provider-prefixed
// (e.g. `cc/claude-opus-4-7` from the `cc` Claude Code alias, or
// `nvidia/llama-3-70b` from a provider that ships prefixed ids), leave
// it as-is — double-prefixing breaks OC's lookup. Bare **combo** ids
// (`owned_by: "combo"`, e.g. `gpt-5.6-sol`) must also stay unprefixed:
// OpenCode looks up `-m <plugin>/<combo>` as model id `<combo>` under
// the plugin provider (#10345). Other bare ids still prefix with
// `providerId` so credentials resolve as `(omniroute, model)`.
id: raw.id.includes("/") || raw.owned_by === "combo" ? raw.id : `${ctx.providerId}/${raw.id}`,
/**
* Display name. Falls back to raw.id when no enrichment is available;
* the caller (`createOmniRouteProviderHook`) overlays
* `/api/pricing/models` data via `applyEnrichment` when
* `features.enrichment` is true.
*/
name: _normaliseFreeLabel(raw.id),
capabilities: {
temperature: caps.temperature ?? true,
reasoning: Boolean(caps.reasoning || caps.thinking),
attachment: Boolean(caps.attachment ?? caps.vision ?? false),
toolcall: Boolean(caps.tool_calling ?? false),
input: {
text: inMods.has("text"),
audio: inMods.has("audio"),
image: inMods.has("image"),
video: inMods.has("video"),
pdf: inMods.has("pdf"),
},
output: {
text: outMods.has("text"),
audio: outMods.has("audio"),
image: outMods.has("image"),
video: outMods.has("video"),
pdf: outMods.has("pdf"),
},
interleaved: Boolean(caps.thinking),
},
cost: {
input: 0,
output: 0,
cache: { read: 0, write: 0 },
},
limit: {
context: typeof raw.context_length === "number" ? raw.context_length : 0,
...(typeof raw.max_input_tokens === "number" ? { input: raw.max_input_tokens } : {}),
output: typeof raw.max_output_tokens === "number" ? raw.max_output_tokens : 0,
},
...(variants ? { variants } : {}),
status: "active",
options: {},
headers: {},
release_date: raw.release_date ?? "",
providerID: ctx.providerId,
api: resolveApiBlock(raw.id, ctx.baseURL, ctx.apiFormat),
};
}
// ────────────────────────────────────────────────────────────────────────────
// Combo discovery (T-05) — /api/combos pass-through with LCD capability roll-up
// ────────────────────────────────────────────────────────────────────────────
/**
* Raw shape of a single combo entry as returned by OmniRoute's `/api/combos`.
*
* Schema established via a live probe against
* an OmniRoute `/api/combos` endpoint with a management-scoped key
* (response saved at /tmp/t05-combos.json) cross-referenced against the
* source-of-truth in this repo:
*
* - `src/app/api/combos/route.ts` GET handler — emits `{combos: [...]}`
* envelope after `getCombos()`.
* - `src/lib/db/combos.ts` `getCombos()` — returns rows persisted via
* `createCombo` / `updateCombo`, each shaped by `normalizeStoredCombo`.
* - `src/lib/combos/steps.ts` `ComboModelStep` + `ComboRefStep` — define
* the `models[]` array entry shape (a step references a member model
* by its full provider-prefixed id, e.g. `"claude-opus-4-5-thinking"`).
*
* Note: the preprod gateway returned `{combos: []}` at probe time (no combos
* provisioned). The defensive parser accepts both `{combos:[...]}` and a
* bare array envelope so the plugin keeps working if a future OmniRoute
* build trims the wrapper (mirrors the same pattern in the sibling
* `@omniroute/opencode-provider#listCombos`).
*
* STRICT source-of-truth (OQ-3, per T-03): every ModelV2 field a combo
* surfaces traces back to either (a) this raw combo entry or (b) the LCD
* roll-up across its raw member models. No client-side variant synthesis.
*/
export interface OmniRouteRawComboMemberRef {
/** Step kind: "model" references a raw model id; "combo-ref" nests another combo. */
kind?: "model" | "combo-ref";
/** Full model id referenced by this step (when kind === "model"). */
model?: string;
/** Nested combo name (when kind === "combo-ref"). */
comboName?: string;
/** Routing weight inside the combo (0–100, advisory at LCD time). */
weight?: number;
/** Step-local label, distinct from the parent combo's display name. */
label?: string;
}
export interface OmniRouteRawCombo {
id: string;
name?: string;
/** Routing strategy. Surfaced for forward-compat but not consumed by LCD. */
strategy?: string;
/** Member step list. Only `kind: "model"` steps participate in LCD. */
models?: OmniRouteRawComboMemberRef[];
/** Hidden combos are excluded from the OC model picker. */
isHidden?: boolean;
/** When OmniRoute attaches a lifecycle hint we forward it; today it doesn't. */
release_date?: string;
/**
* Server-computed context window for this combo (aggregated from member
* models using the same logic as /v1/models). When present, the client
* uses this value directly instead of re-aggregating from member models.
*
* Added in 3.9.x — old servers do not send it.
*/
computed_context_length?: number;
}
/**
* Fetcher contract for `/api/combos`. Same DI shape as
* `OmniRouteModelsFetcher` so unit tests can inject a stub instead of
* monkey-patching global `fetch`.
*/
export type OmniRouteCombosFetcher = (
baseURL: string,
apiKey: string,
timeoutMs?: number
) => Promise<OmniRouteRawCombo[]>;
/**
* Default fetcher: `GET <baseURL>/api/combos` with bearer auth +
* AbortController timeout. Accepts both the `{combos: [...]}` envelope the
* gateway emits today and a bare-array envelope (defensive — keeps the
* plugin working if a future OmniRoute build trims the wrapper).
*
* Differences from `defaultOmniRouteModelsFetcher`:
* - URL is `/api/combos`, NOT `/v1/combos`. The `/v1/...` namespace is the
* OpenAI-compatible surface (chat completions, models); combo discovery
* lives on the management plane under `/api/...`. We tolerate both
* `https://host` and `https://host/v1` baseURL forms by stripping the
* trailing `/v1` segment before appending `/api/combos`.
* - Combos endpoint requires a management-scoped API key when
* `REQUIRE_API_KEY` is enabled. We don't enforce that here; the
* gateway returns 401/403 with an actionable error which we propagate.
*
* Anything that isn't an object with a string `id` is filtered out silently.
*/
export const defaultOmniRouteCombosFetcher: OmniRouteCombosFetcher = async (
baseURL,
apiKey,
timeoutMs = 10_000
) => {
if (!apiKey) throw new Error("@omniroute/opencode-plugin: apiKey required to fetch /api/combos");
if (!baseURL)
throw new Error("@omniroute/opencode-plugin: baseURL required to fetch /api/combos");
// Strip trailing slashes, then strip a trailing `/v1` so we land on the
// management plane. Models live under `/v1/models`; combos live under
// `/api/combos` from the same gateway root.
const trimmed = trimTrailingSlashes(baseURL);
const root = trimmed.replace(/\/v\d+$/, "");
const url = `${root}/api/combos`;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetch(url, {
method: "GET",
headers: {
Authorization: `Bearer ${apiKey}`,
Accept: "application/json",
},
signal: controller.signal,
});
if (!res.ok) {
throw new Error(
`@omniroute/opencode-plugin: GET ${url} failed: ${res.status} ${res.statusText}`
);
}
const body = (await res.json()) as unknown;
const rawList: unknown[] = Array.isArray(body)
? body
: body && typeof body === "object" && Array.isArray((body as { combos?: unknown }).combos)
? ((body as { combos: unknown[] }).combos as unknown[])
: [];
const out: OmniRouteRawCombo[] = [];
for (const r of rawList) {
if (r && typeof r === "object" && typeof (r as { id?: unknown }).id === "string") {
out.push(r as OmniRouteRawCombo);
}
}
return out;
} finally {
clearTimeout(timer);
}
};
/**
* Map a raw combo entry → `ModelV2` by computing the lowest-common-denominator
* (LCD) of its underlying member models. The LCD policy is the only way to
* surface a single capability vector to OpenCode without lying: if any member
* lacks a capability, the combo as a whole cannot guarantee it.
*
* LCD rules:
* - `limit.context` = `min(...members.context_length)`.
* - `limit.output` = `min(...members.max_output_tokens)`.
* - `limit.input` = `min(...members.max_input_tokens)` ONLY when every
* member declares one (ModelV2.limit.input is optional — better to
* omit than to fabricate a min over partial data).
* - `capabilities.toolcall` / `reasoning` / `attachment` / `temperature`:
* `every(member ⇒ supports?)`. The `reasoning` axis ORs across
* `reasoning` and `thinking` per member before AND-ing across the
* combo (mirrors `mapRawModelToModelV2`). The `attachment` axis ORs
* across `attachment` and `vision` per member. The `temperature` axis
* uses default-true semantics: a member supports temperature unless
* it explicitly declares `temperature: false`.
* - `capabilities.input.*` / `output.*`: flattened AND across members'
* modality flags. Missing arrays default to `["text"]` (same default
* as `mapRawModelToModelV2`).
*
* Defensive: empty members array → ALL capabilities `false`, limits zero.
* That's an intentional safety posture (you can't route through an empty
* combo, so OC should grey it out in the picker).
*
* Spec mapping (T-05 §Scope.3): `cost` zeroed; `status = "active"`;
* `release_date = combo.release_date ?? ""`; `api.id = "openai-compatible"`;
* `name = combo.name ?? combo.id`.
*
* @param combo Raw `/api/combos` entry.
* @param members Raw `/v1/models` entries for THIS combo's member ids.
* Caller resolves `combo.models[].model` ids; unknown ids
* are silently dropped before this call.
* @param providerId OpenCode provider id (multi-instance aware).
* @param baseURL Resolved gateway base URL for ModelV2.api.url.
*/
export function mapComboToModelV2(
combo: OmniRouteRawCombo,
members: OmniRouteRawModelEntry[],
providerId: string,
baseURL: string,
apiFormat?: { anthropicPrefixes?: string[] }
): ModelV2 {
// `every` over an empty array returns true (would lie about an empty
// combo's capabilities) — short-circuit to all-false when no members.
const hasMembers = members.length > 0;
const memberInMods = members.map((m) => new Set(m.input_modalities ?? ["text"]));
const memberOutMods = members.map((m) => new Set(m.output_modalities ?? ["text"]));
const modalityAllHave = (sets: Array<Set<string>>, key: string): boolean =>
hasMembers && sets.every((s) => s.has(key));
const contextValues = members
.map((m) => m.context_length)
.filter((v): v is number => typeof v === "number" && v > 0);
const outputValues = members
.map((m) => m.max_output_tokens)
.filter((v): v is number => typeof v === "number" && v > 0);
const inputValues = members
.map((m) => m.max_input_tokens)
.filter((v): v is number => typeof v === "number" && v > 0);
const everyDeclaresInput = hasMembers && inputValues.length === members.length;
const capabilities: ModelV2["capabilities"] = {
temperature:
hasMembers && members.every((m) => (m.capabilities?.temperature ?? true) !== false),
reasoning:
hasMembers &&
members.every((m) => Boolean(m.capabilities?.reasoning || m.capabilities?.thinking)),
attachment:
hasMembers &&
members.every((m) => Boolean(m.capabilities?.attachment ?? m.capabilities?.vision ?? false)),
toolcall: hasMembers && members.every((m) => Boolean(m.capabilities?.tool_calling ?? false)),
input: {
text: modalityAllHave(memberInMods, "text"),
audio: modalityAllHave(memberInMods, "audio"),
image: modalityAllHave(memberInMods, "image"),
video: modalityAllHave(memberInMods, "video"),
pdf: modalityAllHave(memberInMods, "pdf"),
},
output: {
text: modalityAllHave(memberOutMods, "text"),
audio: modalityAllHave(memberOutMods, "audio"),
image: modalityAllHave(memberOutMods, "image"),
video: modalityAllHave(memberOutMods, "video"),
pdf: modalityAllHave(memberOutMods, "pdf"),
},
interleaved: hasMembers && members.every((m) => Boolean(m.capabilities?.thinking)),
};
// Combos span multiple providers. Use Anthropic format only when ALL
// members resolve to Anthropic — otherwise fall back to OpenAI-compat
// (lowest common denominator that every upstream understands).
const comboApiBlock = (() => {
if (!hasMembers) return resolveApiBlock("", baseURL, apiFormat);
const allAnthropic = members.every(
(m) => resolveApiBlock(m.id, baseURL, apiFormat).id === "anthropic"
);
return allAnthropic
? resolveApiBlock(members[0].id, baseURL, apiFormat)
: {
id: "openai-compatible",
url: ensureV1Suffix(baseURL),
npm: "@ai-sdk/openai-compatible",
};
})();
return {
id: combo.id,
providerID: providerId,
api: comboApiBlock,
name: combo.name && combo.name.trim().length > 0 ? combo.name : combo.id,
capabilities,
cost: {
input: 0,
output: 0,
cache: { read: 0, write: 0 },
},
limit: {
context:
typeof combo.computed_context_length === "number" && combo.computed_context_length > 0
? combo.computed_context_length
: contextValues.length > 0
? Math.min(...contextValues)
: 0,
...(everyDeclaresInput ? { input: Math.min(...inputValues) } : {}),
output: outputValues.length > 0 ? Math.min(...outputValues) : 0,
},
status: "active",
options: {},
headers: {},
release_date: combo.release_date ?? "",
};
}
// ─────────────────────────────────────────────────────────────────────────
// ENRICHMENT — pull display names + pricing from /api/pricing/models so
// the UI doesn't have to render raw model ids. Gated by features.enrichment.
// ─────────────────────────────────────────────────────────────────────────
/**
* Per-model enrichment overlay derived from OmniRoute's
* `/api/pricing/models` endpoint. The endpoint returns a per-provider
* catalog with curated `name` strings (e.g. `Claude 4.7 Opus`,
* `GPT 5.5 Pro`, `Gemini 3.1 Pro`) and per-million-token pricing
* (`pricing.input`, `pricing.output`, `pricing.cacheRead`,
* `pricing.cacheWrite`). These overlay the ModelV2 entries produced by
* `mapRawModelToModelV2`.
*/
export interface OmniRouteEnrichmentEntry {
/** Human-readable display name. Replaces ModelV2.name when present. */
name?: string;
/** Per-million-token cost overlay onto ModelV2.cost. */
pricing?: {
input?: number;
output?: number;
cacheRead?: number;
cacheWrite?: number;
};
/**
* Provider alias prefix seen in `/v1/models` ids (e.g. `cc`, `gemini`).
* Populated by `defaultOmniRouteEnrichmentFetcher` from
* `/api/pricing/models` keys. Drives the `usableOnly` alias↔canonical
* resolution.
*/
providerAlias?: string;
/**
* Canonical provider id used by `/api/providers` connections (e.g.
* `claude`, `gemini`, `kiro`). Populated from the per-provider
* `entry.id` field inside `/api/pricing/models`.
*/
providerCanonical?: string;
/**
* Human-readable upstream provider label (e.g. `Claude`, `Kiro`,
* `Windsurf`, `GitHub Models`). Populated from the per-provider
* `entry.name` field inside `/api/pricing/models`. Used by the
* `providerTag` feature to suffix `ModelV2.name` with the routing
* destination so the OC TUI picker can differentiate the same
* model id sold through different upstream connections.
*/
providerDisplayName?: string;
/** Free-model budget type (from freeModelCatalog). */
freeType?: FreeModelFreeType;
/** Monthly token budget for recurring free models. */
monthlyTokens?: number;
/** Credit token budget for credit-based free models. */
creditTokens?: number;
}
/** Map keyed by full model id (possibly namespaced, e.g. `cc/claude-sonnet-4-6`). */
export type OmniRouteEnrichmentMap = Map<string, OmniRouteEnrichmentEntry>;
export type OmniRouteEnrichmentFetcher = (
baseURL: string,
apiKey: string,
timeoutMs?: number
) => Promise<OmniRouteEnrichmentMap>;
/**
* Default enrichment fetcher — pulls nice display names from
* `GET /api/pricing/models` and merges per-million-token pricing from
* `GET /api/pricing` (the actual pricing source — `/api/pricing/models` is
* a catalog endpoint whose entries are `{id, name, custom}` only).
*
* `/api/pricing/models` shape (catalog):
* - `{ [providerAlias]: { id, alias, name, models: [{ id, name, custom }] } }`
*
* `/api/pricing` shape (pricing only):
* - `{ [providerAlias]: { [modelId]: { input, output, cached, reasoning, cache_creation } } }`
* where values are USD per million tokens.
*
* The two responses are joined on `(providerAlias, modelId)` and the merged
* entries are stored under both `${providerAlias}/${modelId}` and bare
* `${modelId}` keys so downstream lookups against either form succeed.
*
* Soft-fails (returns whatever was collected) on non-2xx or parse errors;
* the two fetches are independent so one missing source still surfaces the
* other.
*/
export const defaultOmniRouteEnrichmentFetcher: OmniRouteEnrichmentFetcher = async (
baseURL,
apiKey,
timeoutMs = 10_000
) => {
const out: OmniRouteEnrichmentMap = new Map();
if (!baseURL || !apiKey) return out;
const root = baseURL.replace(/\/v1\/?$/, "").replace(/\/$/, "");
const headers = {
Authorization: `Bearer ${apiKey}`,
Accept: "application/json",
};
// ── 1. Catalog with nice display names ────────────────────────────────
const catalogAc = new AbortController();
const catalogTimer = setTimeout(() => catalogAc.abort(), timeoutMs);
try {
const res = await fetch(`${root}/api/pricing/models`, {
method: "GET",
headers,
signal: catalogAc.signal,
});
if (res.ok) {
const body = (await res.json()) as unknown;
const providers =
(body as { providers?: Record<string, { models?: unknown[] }> })?.providers ??
(body as Record<string, { models?: unknown[] }>);
if (providers && typeof providers === "object") {
for (const [providerAlias, slot] of Object.entries(providers)) {
if (!slot || typeof slot !== "object") continue;
const models = (slot as { models?: unknown[] }).models;
if (!Array.isArray(models)) continue;
// Canonical id sits at the per-provider top level (e.g.
// `pricing-models.cc.id === 'claude'`). Falls back to the alias
// itself when missing — common case alias===canonical.
const canonicalRaw = (slot as { id?: unknown }).id;
const providerCanonical =
typeof canonicalRaw === "string" && canonicalRaw.length > 0
? canonicalRaw
: providerAlias;
// Upstream provider human label (e.g. `Claude`, `Kiro`,
// `GitHub Models`). Optional — falls back to undefined when
// OmniRoute hasn't curated a label for this slot.
const slotNameRaw = (slot as { name?: unknown }).name;
const providerDisplayName =
typeof slotNameRaw === "string" && slotNameRaw.trim().length > 0
? slotNameRaw.trim()
: undefined;
for (const m of models) {
if (!m || typeof m !== "object") continue;
const id = (m as { id?: unknown }).id;
if (typeof id !== "string" || id.length === 0) continue;
const name = (m as { name?: unknown }).name;
const entry: OmniRouteEnrichmentEntry = {
providerAlias,
providerCanonical,
};
if (providerDisplayName) entry.providerDisplayName = providerDisplayName;
if (typeof name === "string" && name.trim().length > 0) entry.name = name;
const namespaced = `${providerAlias}/${id}`;
if (!out.has(namespaced)) out.set(namespaced, entry);
if (!out.has(id)) out.set(id, entry);
}
}
}
}
} catch {
// Soft-fail; keep going to pricing fetch.
} finally {
clearTimeout(catalogTimer);
}
// ── 2. Pricing values from /api/pricing ───────────────────────────────
const priceAc = new AbortController();
const priceTimer = setTimeout(() => priceAc.abort(), timeoutMs);
try {
const res = await fetch(`${root}/api/pricing`, {
method: "GET",
headers,
signal: priceAc.signal,
});
if (res.ok) {
const body = (await res.json()) as unknown;
if (body && typeof body === "object" && !Array.isArray(body)) {
for (const [providerAlias, slot] of Object.entries(body as Record<string, unknown>)) {
if (!slot || typeof slot !== "object" || Array.isArray(slot)) continue;
for (const [modelId, raw] of Object.entries(slot as Record<string, unknown>)) {
if (!raw || typeof raw !== "object") continue;
const p = raw as Record<string, unknown>;
const parsed: NonNullable<OmniRouteEnrichmentEntry["pricing"]> = {};
// OmniRoute `/api/pricing` keys:
// input → cost.input
// output → cost.output
// cached → cost.cache.read (alias: cacheRead)
// cache_creation → cost.cache.write (alias: cacheWrite)
// Tolerate alternative spellings for forward-compat.
if (typeof p.input === "number") parsed.input = p.input;
if (typeof p.output === "number") parsed.output = p.output;
const cacheRead =
typeof p.cached === "number"
? p.cached
: typeof p.cacheRead === "number"
? p.cacheRead
: undefined;
if (typeof cacheRead === "number") parsed.cacheRead = cacheRead;
const cacheWrite =
typeof p.cache_creation === "number"
? p.cache_creation
: typeof p.cacheWrite === "number"
? p.cacheWrite
: undefined;
if (typeof cacheWrite === "number") parsed.cacheWrite = cacheWrite;
if (Object.keys(parsed).length === 0) continue;
const namespaced = `${providerAlias}/${modelId}`;
const existingNs = out.get(namespaced);
if (existingNs)
existingNs.pricing = {
...(existingNs.pricing ?? {}),
...parsed,
};
else out.set(namespaced, { pricing: parsed });
const existingBare = out.get(modelId);
if (existingBare)
existingBare.pricing = {
...(existingBare.pricing ?? {}),
...parsed,
};
else out.set(modelId, { pricing: parsed });
}
}
}
}
} catch {
// Soft-fail; return whatever names we collected.
} finally {
clearTimeout(priceTimer);
}
// ── 3. Free model budgets from /api/free-tier/summary ──────────────────
// Best-effort fetch: populates freeType/monthlyTokens/creditTokens on
// enrichment entries that match. 404 = endpoint doesn't exist — skip.
// Uses the EXISTING /api/free-tier/summary endpoint (no new server code).
const freeAc = new AbortController();
const freeTimer = setTimeout(() => freeAc.abort(), timeoutMs);
try {
const res = await fetch(`${root}/api/free-tier/summary`, {
method: "GET",
headers,
signal: freeAc.signal,
});
if (res.ok) {
const body = (await res.json()) as unknown;
// Response shape: { perModel: FreeModelBudget[], ... }
const perModel: unknown[] =
body && typeof body === "object" && Array.isArray((body as { perModel?: unknown }).perModel)
? ((body as { perModel: unknown[] }).perModel as unknown[])
: Array.isArray(body)
? (body as unknown[])
: [];
let matched = 0;
for (const fm of perModel) {
if (!fm || typeof fm !== "object") continue;
const fmObj = fm as Record<string, unknown>;
const provider = typeof fmObj.provider === "string" ? fmObj.provider : "";
const modelId = typeof fmObj.modelId === "string" ? fmObj.modelId : "";
const freeType = typeof fmObj.freeType === "string" ? fmObj.freeType : "";
if (!modelId || !freeType) continue;
const monthlyTokens =
typeof fmObj.monthlyTokens === "number" ? fmObj.monthlyTokens : undefined;
const creditTokens =
typeof fmObj.creditTokens === "number" ? fmObj.creditTokens : undefined;
// Match against enrichment entries: namespaced, bare, and displayName
const displayName = typeof fmObj.displayName === "string" ? fmObj.displayName : "";
const candidates = [
`${provider}/${modelId}`,
modelId,
...(displayName ? [displayName] : []),
];
for (const key of candidates) {
const entry = out.get(key);
if (entry) {
entry.freeType = freeType as FreeModelFreeType;
if (monthlyTokens !== undefined) entry.monthlyTokens = monthlyTokens;
if (creditTokens !== undefined) entry.creditTokens = creditTokens;
matched++;
break;
}
}
}
_logger.debug(
`free-tier/summary: ${perModel.length} models returned, ${matched} matched enrichment entries`
);
}
} catch {
// Soft-fail; free metadata is optional.
} finally {
clearTimeout(freeTimer);
}
return out;
};
// ── Startup diagnostics writer (file-based) ──────────────────────────────
// OC doesn't capture plugin console.warn in its log file. Write diagnostics
// to a file so they're readable after session starts. Capped at 64KB.
async function writeStartupDiagnostics(params: {
providerId: string;
baseURL: string;
modelCount: number;
comboCount: number;
enrichmentSize: number;
enrichment: OmniRouteEnrichmentMap;
features?: OmniRoutePluginOptions["features"];
}): Promise<void> {
const { providerId, baseURL, modelCount, comboCount, enrichmentSize, enrichment, features } =
params;
const enriched = [...enrichment.entries()];
const withName = enriched.filter(([, e]) => e.name);
const withPricing = enriched.filter(([, e]) => e.pricing);
const withFree = enriched.filter(([, e]) => e.freeType);
const lines: string[] = [];
lines.push(`=== startupDebug ${new Date().toISOString()} ===`);
lines.push(`providerId=${providerId} baseURL=${baseURL}`);
lines.push(`models=${modelCount} combos=${comboCount} enrichment=${enrichmentSize}`);
// #7624: surface the EFFECTIVE feature flags so an operator who omitted the
// `features` block can see combos/enrichment are on (the counts
// above can read 0 for reasons unrelated to the flags — e.g. missing auth).
// `features.autoCombos` is accepted but ignored, so it is hidden here.
const effectiveFlags = resolveEffectiveFeatureFlags(features);
lines.push(
`features(effective): ` +
(Object.keys(effectiveFlags) as OmniRouteFeatureFlag[])
.filter((k) => k !== "autoCombos")
.map((k) => `${k}=${effectiveFlags[k] ? "on" : "off"}`)
.join(" ")
);
lines.push(
`enrichment: ${withName.length} with name, ${withPricing.length} with pricing, ${withFree.length} free`
);
if (withFree.length > 0) {
lines.push(`free models (${withFree.length}):`);
for (const [k, e] of withFree.slice(0, 10)) {
lines.push(
` ${k} → name=${e.name ?? "(none)"}, freeType=${e.freeType}, monthly=${e.monthlyTokens ?? 0}, credits=${e.creditTokens ?? 0}`
);
}
} else {
lines.push(
`NO free models detected. ` +
(enrichmentSize === 0
? "Enrichment map is EMPTY."
: `Enrichment has ${enrichmentSize} entries but none have freeType.`)
);
}
const sampleNames = enriched
.filter(([, e]) => e.name)
.slice(0, 5)
.map(([k, e]) => ` ${k} → "${e.name}"`);
if (sampleNames.length > 0) {
lines.push(`sample enriched names:`);
lines.push(sampleNames.join("\n"));
}
lines.push(`=== end startupDebug ===\n`);
const diagnostics = lines.join("\n");
_logger.debug(diagnostics);
try {
const diagDir =
process.env.OPENCODE_DATA_DIR ?? path.join(os.homedir(), ".local/share/opencode");
const diagPath = path.join(diagDir, "plugins", "omniroute-startup-diagnostics.log");
let existing = "";
try {
existing = await readFile(diagPath, "utf8");
} catch {
/* first write */
}
const KEEP = 65_536;
const combined = existing + diagnostics;
const trimmed = combined.length > KEEP ? combined.slice(combined.length - KEEP) : combined;
await writeFile(diagPath, trimmed, "utf8");
} catch {
/* best effort */
}
}
/**
* Separator used by `applyProviderTag` between the upstream provider
* label (prefix) and the enriched model name. ASCII hyphen with
* surrounding spaces — terminal-safe everywhere, never collides with
* a model id (those use slashes / dots / underscores).
*
* Layout: `<short-label> - <model name>` (label leads so column scans
* group by provider — e.g. `Claude - Claude Opus 4.7`,
* `Kiro - Claude Opus 4.7`).
*/
export const PROVIDER_TAG_SEPARATOR = _PROVIDER_TAG_SEPARATOR;
// Re-export from naming.ts — thin wrapper preserving OmniRouteEnrichmentEntry signature
export function shortProviderLabel(
enrichment: OmniRouteEnrichmentEntry | undefined
): string | undefined {
return _shortProviderLabel(enrichment);
}
/**
* Prepend the upstream provider label to `model.name` so the OC TUI
* picker can differentiate the same model id sold through different
* upstream connections (e.g. `cc/claude-opus-4-7` via Anthropic
* vs `kr/claude-opus-4-7` via Kiro). Result shape:
*
* `<label>${PROVIDER_TAG_SEPARATOR}<enriched name>`
* → `Claude - Claude Opus 4.7`
* → `Kiro - Claude Opus 4.7`
* → `AssemblyAI - Universal 2 (Transcription)` (slot.name fits, used verbatim)
* → `GHM - GPT 5` (slot.name "GitHub Models" > 12 chars → UPPER(alias))
*
* Mutates the model in place and is idempotent — running twice never
* double-prefixes. No-op when:
*
* - `enrichment` is undefined,
* - {@link shortProviderLabel} returns `undefined`
* (no `providerDisplayName` AND no `providerAlias`),
* - the current `model.name` already starts with the prefix.
*
* Combos are intentionally skipped by callers (they're multi-upstream
* by definition; the `Combo: ` prefix conveys that). Raw models call
* this after `applyEnrichment` so the tag layers on top of the
* friendly name.
*/
export function applyProviderTag(
model: ModelV2,
enrichment: OmniRouteEnrichmentEntry | undefined
): ModelV2 {
const label = shortProviderLabel(enrichment);
if (!label) return model;
const prefix = `${label}${PROVIDER_TAG_SEPARATOR}`;
if (model.name.startsWith(prefix)) return model;
// When enrichment already prepended [Free], move it before the provider
// tag: "[Free] GPT-4.1" → "[Free] GHM - GPT-4.1" not "GHM - [Free] GPT-4.1"
if (model.name.startsWith("[Free] ")) {
model.name = `[Free] ${prefix}${model.name.slice(7)}`;
} else {
model.name = `${prefix}${model.name}`;
}
return model;
}
/**
* Reverse-index the enrichment map from `providerCanonical → providerAlias`.
*
* OmniRoute's `/api/pricing/models` is keyed by short ALIAS (`cc`, `cx`,
* `pol`). But `/v1/models` exposes some models a SECOND time under their
* CANONICAL name (`claude/claude-opus-4-7`, `codex/gpt-5.5`,
* `pollinations/midjourney`). Without a reverse map, those canonical
* rows miss enrichment entirely and surface as raw ids in the picker.
*
* Built once per refresh from the enrichment entries themselves — no
* hardcoded registry. Only records `canonical → alias` mappings when
* both are present AND distinct (skips slots where alias === canonical
* like `kiro`).
*/
export function buildCanonicalToAliasMap(
enrichment: OmniRouteEnrichmentMap | undefined
): Map<string, string> {
const out = new Map<string, string>();
if (!enrichment) return out;
for (const entry of enrichment.values()) {
const alias = typeof entry.providerAlias === "string" ? entry.providerAlias.trim() : "";
const canonical =
typeof entry.providerCanonical === "string" ? entry.providerCanonical.trim() : "";
if (alias.length === 0 || canonical.length === 0) continue;
if (alias === canonical) continue;
if (!out.has(canonical)) out.set(canonical, alias);
}
return out;
}
/**
* Enrichment lookup with alias-fallback chain.
*
* Resolution order (first hit wins):
*
* 1. `enrichment.get(rawId)` — direct hit on `<prefix>/<modelId>` or
* bare id (the fetcher writes under both forms).
* 2. If `rawId` is `<canonical>/<modelId>` and `canonicalToAlias` has
* a mapping for `canonical`, try `<alias>/<modelId>`. This rescues
* duplicate rows like `claude/claude-opus-4-7` (canonical) when
* enrichment only indexed under `cc/claude-opus-4-7` (alias).
* 3. Bare `<modelId>` as a last resort. A bare key matches by model name only,
* but its entry describes one provider (label, free budget, pricing). It is
* returned whole only when that provider owns the row (`ownedBy` or the id
* prefix); otherwise only its model name is kept, so a generic-adapter row
* such as `ih/kimi-k3` is not labelled with an unrelated provider (#14966).
*
* Returns `undefined` when no lookup hits.
*/
export function lookupEnrichment(
rawId: string,
enrichment: OmniRouteEnrichmentMap | undefined,
canonicalToAlias: Map<string, string>,
ownedBy?: string
): OmniRouteEnrichmentEntry | undefined {
if (!enrichment) return undefined;
const direct = enrichment.get(rawId);
if (direct) return direct;
const slash = rawId.indexOf("/");
if (slash > 0) {
const prefix = rawId.slice(0, slash);
const modelId = rawId.slice(slash + 1);
const alias = canonicalToAlias.get(prefix);
if (alias && alias !== prefix) {
const viaAlias = enrichment.get(`${alias}/${modelId}`);
if (viaAlias) return viaAlias;
}
const bare = enrichment.get(modelId);
if (bare) return bareFallbackEntry(bare, prefix, ownedBy);
}
return undefined;
}
/** A bare-key hit keeps its provider metadata only when that provider owns the row. */
function bareFallbackEntry(
entry: OmniRouteEnrichmentEntry,
prefix: string,
ownedBy: string | undefined
): OmniRouteEnrichmentEntry {
const owners = new Set([prefix, ownedBy].filter((v): v is string => Boolean(v)));
const entryProviders = [entry.providerAlias, entry.providerCanonical].filter(
(v): v is string => typeof v === "string" && v.trim().length > 0
);
if (entryProviders.length === 0 || entryProviders.some((p) => owners.has(p.trim()))) {
return entry;
}
return entry.name ? { name: entry.name } : {};
}
/**
* Pre-pass: detect raw rows that are the CANONICAL twin of an ALIAS row
* already in the catalog. Returns the set of canonical-keyed ids to skip
* during the raw-model loop so each model surfaces exactly once under
* its enriched alias key.
*
* Example: `/v1/models` returns BOTH `cc/claude-opus-4-7` and
* `claude/claude-opus-4-7`. The former is enriched (alias `cc` exists
* in `/api/pricing/models`); the latter is raw. We keep `cc/...` and
* drop `claude/...`.
*
* Built once per refresh. Cheap — O(M) where M = raw model count.
*/
export function canonicalDedupSet(
rawModels: ReadonlyArray<OmniRouteRawModelEntry>,
canonicalToAlias: Map<string, string>
): Set<string> {
const drop = new Set<string>();
if (canonicalToAlias.size === 0) return drop;
// Index every alias key present in the raw catalog.
const aliasKeys = new Set<string>();
for (const m of rawModels) {
if (typeof m.id === "string" && m.id.length > 0) aliasKeys.add(m.id);
}
for (const m of rawModels) {
if (typeof m.id !== "string" || m.id.length === 0) continue;
const slash = m.id.indexOf("/");
if (slash <= 0) continue;
const prefix = m.id.slice(0, slash);
const modelId = m.id.slice(slash + 1);
const alias = canonicalToAlias.get(prefix);
if (!alias || alias === prefix) continue;
// Canonical row only gets suppressed if the alias row actually
// exists — otherwise we'd hide the model entirely.
if (aliasKeys.has(`${alias}/${modelId}`)) drop.add(m.id);
}
return drop;
}
/**
* Build a per-alias index of enrichment metadata so we can render the
* provider prefix even for raw models that don't have their own
* curated `/api/pricing/models` entry.
*
* Real example: OmniRoute's `pricing['cohere']` slot lists 10 curated
* models but `/v1/models` also returns `cohere/rerank-multilingual-v3.0`
* and `cohere/rerank-v4.0-fast` (not in the curated 10). Without this
* index, those rows surface in the picker as `cohere/...` with no
* `Cohere - ` prefix because the per-model enrichment lookup misses.
*
* This index records the first non-empty `providerDisplayName` seen
* for each alias, plus the alias itself. Callers use it to synthesize
* a minimal `OmniRouteEnrichmentEntry` whenever the direct lookup
* misses but the raw id's prefix matches a known alias.
*
* Built once per refresh; first-wins on duplicate alias (matches
* `buildCanonicalToAliasMap` semantics).
*/
export function buildAliasIndex(
enrichment: OmniRouteEnrichmentMap | undefined
): Map<string, OmniRouteEnrichmentEntry> {
const out = new Map<string, OmniRouteEnrichmentEntry>();
if (!enrichment) return out;
for (const entry of enrichment.values()) {
const alias = typeof entry.providerAlias === "string" ? entry.providerAlias.trim() : "";
if (alias.length === 0) continue;
if (out.has(alias)) {
// First-wins, but upgrade to the first entry that carries a
// non-empty providerDisplayName so the prefix renders nicely.
const existing = out.get(alias);
if (
existing &&
(!existing.providerDisplayName || existing.providerDisplayName.trim().length === 0) &&
typeof entry.providerDisplayName === "string" &&
entry.providerDisplayName.trim().length > 0
) {
out.set(alias, entry);
}
continue;
}
out.set(alias, entry);
}
return out;
}
/**
* Resolve a synthesised enrichment entry for `applyProviderTag` /
* `shortProviderLabel` consumption, combining two sources:
*
* 1. The direct per-model enrichment match (if present).
* 2. A per-alias fallback derived from `buildAliasIndex` — covers raw
* ids whose prefix matches a known alias but the specific model
* id wasn't curated in `/api/pricing/models`. Example:
* `cohere/rerank-multilingual-v3.0` falls back to the cohere slot's
* `providerDisplayName='Cohere'` even though that specific id
* isn't in the curated 10-model list.
*
* Returns `undefined` when neither source surfaces an alias.
*
* NOTE: this function is read-only over its inputs; it never mutates
* the underlying `direct` entry. When it falls back to the alias
* index, it constructs a fresh minimal entry exposing only the
* provider-prefix fields (`providerAlias`, `providerCanonical`,
* `providerDisplayName`). Other fields (name, pricing) are explicitly
* left undefined so `applyEnrichment` won't accidentally overwrite a
* model name with the alias-slot label.
*/
export function resolveProviderTagEntry(
rawId: string,
direct: OmniRouteEnrichmentEntry | undefined,
aliasIndex: Map<string, OmniRouteEnrichmentEntry>,
canonicalToAlias?: Map<string, string>
): OmniRouteEnrichmentEntry | undefined {
if (direct) {
const alias = typeof direct.providerAlias === "string" ? direct.providerAlias.trim() : "";
const display =
typeof direct.providerDisplayName === "string" ? direct.providerDisplayName.trim() : "";
if (alias.length > 0 || display.length > 0) return direct;
}
const slash = rawId.indexOf("/");
if (slash <= 0) return direct;
const prefix = rawId.slice(0, slash);
// 1. Direct alias lookup (`cohere/...` → cohere slot keyed by alias=cohere).
let fromAlias = aliasIndex.get(prefix);
// 2. Canonical fallback (`pollinations/...` → look up via alias `pol`).
if (!fromAlias && canonicalToAlias) {
const alias = canonicalToAlias.get(prefix);
if (alias) fromAlias = aliasIndex.get(alias);
}
if (!fromAlias) return direct;
// Synthesize: borrow only the provider-prefix metadata.
return {
providerAlias: fromAlias.providerAlias,
providerCanonical: fromAlias.providerCanonical,
providerDisplayName: fromAlias.providerDisplayName,
};
}
/**
* Apply enrichment overlay onto a ModelV2 entry. Mutates and returns the
* passed entry for convenience.
*/
/**
* Normalise a model display name so free-tier models always carry a
* consistent `[Free] ` prefix instead of a trailing `(Free)` suffix or an
* ad-hoc `free` word anywhere in the name.
*
* Examples:
* "GPT-4.1 (Free)" → "[Free] GPT-4.1"
* "DeepSeek V4 Flash Free" → "[Free] DeepSeek V4 Flash"
* "Claude Opus 4.7" → "Claude Opus 4.7" (unchanged)
*/
export { _normaliseFreeLabel as normaliseFreeLabel };
export function applyEnrichment(
model: ModelV2,
enrichment: OmniRouteEnrichmentEntry | undefined
): ModelV2 {
if (!enrichment) return model;
if (enrichment.name && enrichment.name.trim().length > 0) {
model.name = _normaliseFreeLabel(enrichment.name);
}
if (enrichment.pricing) {
if (typeof enrichment.pricing.input === "number") {
model.cost.input = enrichment.pricing.input;
}
if (typeof enrichment.pricing.output === "number") {
model.cost.output = enrichment.pricing.output;
}
if (typeof enrichment.pricing.cacheRead === "number") {
model.cost.cache.read = enrichment.pricing.cacheRead;
}
if (typeof enrichment.pricing.cacheWrite === "number") {
model.cost.cache.write = enrichment.pricing.cacheWrite;
}
}
return model;
}
// ─────────────────────────────────────────────────────────────────────────
// COMPRESSION METADATA — pull /api/context/combos so combo entries can be
// tagged with their compression pipeline. Gated by
// features.compressionMetadata (off by default).
// ─────────────────────────────────────────────────────────────────────────
/** Single step in a compression combo's pipeline. */
export interface OmniRouteCompressionStep {
engine: string; // "rtk" | "caveman" | "aggressive" | ...
intensity?: string; // "minimal" | "lite" | "standard" | "full" | "ultra" | "aggressive"
}
/** Compression combo as returned by /api/context/combos. */
export interface OmniRouteCompressionCombo {
id: string;
name?: string;
description?: string;
pipeline: OmniRouteCompressionStep[];
isDefault?: boolean;
}
export type OmniRouteCompressionMetaFetcher = (
baseURL: string,
apiKey: string,
timeoutMs?: number
) => Promise<OmniRouteCompressionCombo[]>;
/**
* Default compression-metadata fetcher — calls `GET /api/context/combos`.
* Tolerates envelope shapes `{ combos: [...] }`, `[...]`, or
* `{ data: [...] }`. Soft-fails (returns []) on non-2xx or parse errors.
*/
export const defaultOmniRouteCompressionMetaFetcher: OmniRouteCompressionMetaFetcher = async (
baseURL,
apiKey,
timeoutMs = 10_000
) => {
const empty: OmniRouteCompressionCombo[] = [];
if (!baseURL || !apiKey) return empty;
const root = baseURL.replace(/\/v1\/?$/, "").replace(/\/$/, "");
const url = `${root}/api/context/combos`;
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), timeoutMs);
try {
const res = await fetch(url, {
method: "GET",
headers: {
Authorization: `Bearer ${apiKey}`,
Accept: "application/json",
},
signal: ac.signal,
});
if (!res.ok) return empty;
const body = (await res.json()) as unknown;
const list = Array.isArray(body)
? body
: Array.isArray((body as { combos?: unknown[] })?.combos)
? (body as { combos: unknown[] }).combos
: Array.isArray((body as { data?: unknown[] })?.data)
? (body as { data: unknown[] }).data
: [];
const out: OmniRouteCompressionCombo[] = [];
for (const raw of list) {
if (!raw || typeof raw !== "object") continue;
const id = (raw as { id?: unknown }).id;
const pipeline = (raw as { pipeline?: unknown }).pipeline;
if (typeof id !== "string" || id.length === 0) continue;
if (!Array.isArray(pipeline)) continue;
const steps: OmniRouteCompressionStep[] = [];
for (const step of pipeline) {
if (!step || typeof step !== "object") continue;
const engine = (step as { engine?: unknown }).engine;
if (typeof engine !== "string" || engine.length === 0) continue;
const intensity = (step as { intensity?: unknown }).intensity;
const entry: OmniRouteCompressionStep = { engine };
if (typeof intensity === "string" && intensity.length > 0) {
entry.intensity = intensity;
}
steps.push(entry);
}
const combo: OmniRouteCompressionCombo = { id, pipeline: steps };
const name = (raw as { name?: unknown }).name;
if (typeof name === "string" && name.length > 0) combo.name = name;
const description = (raw as { description?: unknown }).description;
if (typeof description === "string") combo.description = description;
const isDefault = (raw as { isDefault?: unknown }).isDefault;
if (typeof isDefault === "boolean") combo.isDefault = isDefault;
out.push(combo);
}
return out;
} catch {
return empty;
} finally {
clearTimeout(timer);
}
};
/**
* Map of well-known compression-intensity tokens to a single emoji
* conveying "how much" compression is applied. Traffic-light palette:
*
* 🟢 minimal / lite — almost no loss
* 🟡 standard — balanced
* 🟠 aggressive / full — heavy
* 🔴 ultra — extreme
*
* Lookup is case-insensitive. Unknown intensities fall through to the
* raw text form (`engine:<intensity>`) so we never hide a value that
* OmniRoute knows but the plugin doesn't.
*
* Exported for callers (and tests) that want to assemble their own
* pipeline strings.
*/
export const COMPRESSION_INTENSITY_EMOJI: Record<string, string> = {
minimal: "🟢",
lite: "🟢",
standard: "🟡",
aggressive: "🟠",
full: "🟠",
ultra: "🔴",
};
/**
* Format a compression pipeline as a short human-readable string for
* combo `name` decoration. Intensity tokens render as a traffic-light
* emoji so a column scan reveals "how compressed" the combo is at a
* glance:
*
* `[rtk🟡 → caveman🟠]` (rtk:standard → caveman:full)
* `[rtk🔴]` (rtk:ultra, single-step)
* `[caveman]` (engine without intensity, no emoji)
* `[rtk:custom-thing]` (unknown intensity, raw-text fallback)
*/
export function formatCompressionPipeline(pipeline: OmniRouteCompressionStep[]): string {
if (!pipeline || pipeline.length === 0) return "";
return (
"[" +
pipeline
.map((s) => {
if (!s.intensity) return s.engine;
const emoji = COMPRESSION_INTENSITY_EMOJI[s.intensity.toLowerCase()];
return emoji ? `${s.engine}${emoji}` : `${s.engine}:${s.intensity}`;
})
.join(" → ") +
"]"
);
}
// ─────────────────────────────────────────────────────────────────────────
// /api/providers (provider-connection status) — optional read used by the
// `features.usableOnly` filter. Returns the operator's installed OmniRoute
// provider connections, each with `provider` (canonical id), `isActive`,
// `testStatus`. We treat a provider as USABLE when at least one of its
// connections is `isActive: true && testStatus: 'active'`. Aliases (e.g.
// `cc → claude`) are resolved through the enrichment map.
// ─────────────────────────────────────────────────────────────────────────
/** Subset of `/api/providers/connections[]` we read. Other fields are kept as a permissive index signature. */
export interface OmniRouteProviderConnection {
/** Connection UUID. */
id: string;
/** Canonical provider id, e.g. `claude`, `gemini`, `kiro`. Matches `entry.id` in `/api/pricing/models`. */
provider: string;
/** Connection auth flavor, e.g. `apikey`, `oauth`, `cookie`. */
authType?: string;
/** Operator-visible label. */
name?: string;
/** Operator toggle — when false, the connection is provisioned but disabled. */
isActive?: boolean;
/** Health-check verdict — `active` means routable; `expired`/`error`/`unavailable` mean not. */
testStatus?: string;
/** Permissive bag — additional fields (priority, backoffLevel, etc.) pass through untouched. */
[k: string]: unknown;
}
export type OmniRouteProvidersFetcher = (
baseURL: string,
apiKey: string,
timeoutMs?: number
) => Promise<OmniRouteProviderConnection[]>;
/**
* Default providers fetcher — calls `GET /api/providers`. Tolerates envelope
* shapes `{ connections: [...] }`, `[...]`, or `{ data: [...] }`. Soft-fails
* (returns []) on non-2xx or parse errors so the `usableOnly` filter
* gracefully degrades to "no filter" instead of hiding the whole catalog.
*/
export const defaultOmniRouteProvidersFetcher: OmniRouteProvidersFetcher = async (
baseURL,
apiKey,
timeoutMs = 10_000
) => {
const empty: OmniRouteProviderConnection[] = [];
if (!baseURL || !apiKey) return empty;
const root = baseURL.replace(/\/v1\/?$/, "").replace(/\/$/, "");
const url = `${root}/api/providers`;
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), timeoutMs);
try {
const res = await fetch(url, {
method: "GET",
headers: {
Authorization: `Bearer ${apiKey}`,
Accept: "application/json",
},
signal: ac.signal,
});
if (!res.ok) return empty;
const body = (await res.json()) as unknown;
const list = Array.isArray(body)
? body
: Array.isArray((body as { connections?: unknown[] })?.connections)
? (body as { connections: unknown[] }).connections
: Array.isArray((body as { data?: unknown[] })?.data)
? (body as { data: unknown[] }).data
: [];
const out: OmniRouteProviderConnection[] = [];
for (const raw of list) {
if (!raw || typeof raw !== "object") continue;
const provider = (raw as { provider?: unknown }).provider;
if (typeof provider !== "string" || provider.length === 0) continue;
const id = (raw as { id?: unknown }).id;
const idStr = typeof id === "string" && id.length > 0 ? id : provider;
out.push({ ...(raw as Record<string, unknown>), id: idStr, provider });
}
return out;
} catch {
return empty;
} finally {
clearTimeout(timer);
}
};
/**
* Compute the set of provider aliases that have at least one healthy,
* active connection. Resolves alias → canonical id through the enrichment
* map (which is keyed under both `${alias}/${id}` and bare `${id}` — we
* walk only the namespaced keys to derive the alias↔canonical mapping).
*
* Returns:
* - `aliases`: set of alias prefixes safe to keep (e.g. `cc`, `gemini`).
* - `canonicals`: set of canonical provider ids (e.g. `claude`, `kiro`).
*
* Callers should treat membership in EITHER set as "usable" — raw model
* ids may be `<alias>/<model>` (`cc/claude-opus-4-7`) OR `<canonical>/<model>`
* (`claude/sonnet-4`) depending on the OmniRoute deployment's `/v1/models`
* surface shape.
*
* Subtract-filter semantics: callers MUST also keep models whose prefix is
* unknown to BOTH `/api/pricing/models` and `/api/providers` (e.g.
* agentrouter-style synthetic prefixes). The right boolean is "if I see this
* prefix in EITHER catalog table AND it's not usable, drop; otherwise keep".
*/
export function usableProviderAliasSet(
connections: OmniRouteProviderConnection[],
enrichment: OmniRouteEnrichmentMap | undefined
): {
aliases: Set<string>;
canonicals: Set<string>;
knownAliases: Set<string>;
} {
const usableCanonicals = new Set<string>();
for (const c of connections) {
if (!c || c.isActive !== true) continue;
if (typeof c.testStatus === "string" && c.testStatus !== "active") continue;
if (typeof c.provider === "string" && c.provider.length > 0) {
usableCanonicals.add(c.provider);
}
}
const aliases = new Set<string>();
const knownAliases = new Set<string>();
if (enrichment) {
// Walk enrichment entries to map alias → canonical via the metadata
// populated by `defaultOmniRouteEnrichmentFetcher`. Every entry carries
// its providerAlias + providerCanonical so the namespaced/bare key
// duplication is harmless. Collect EVERY alias we encounter (regardless
// of usability) into `knownAliases` so the downstream filter can decide
// "this prefix was in /api/pricing/models" in O(1) instead of O(E).
for (const entry of enrichment.values()) {
const alias = entry.providerAlias;
const canonical = entry.providerCanonical;
if (typeof alias !== "string" || alias.length === 0) continue;
knownAliases.add(alias);
if (typeof canonical !== "string" || canonical.length === 0) continue;
if (usableCanonicals.has(canonical)) aliases.add(alias);
}
}
// Always include every usable canonical as an alias too — handles the
// common case where `/v1/models` ids use the canonical id directly
// (e.g. `gemini/gemini-1.5-pro`).
for (const canonical of usableCanonicals) aliases.add(canonical);
return { aliases, canonicals: usableCanonicals, knownAliases };
}
/**
* Decide whether a raw `/v1/models` id passes the `usableOnly` filter.
*
* Rules (subtract-filter — bias toward keep):
* - id has no `/` → keep (combos/synthetic entries handled separately).
* - prefix matches a known usable alias OR canonical → keep.
* - prefix is unknown to BOTH the connection table AND the enrichment
* map → keep (we can't prove it's NOT usable; could be agentrouter).
* - prefix is known to the enrichment map BUT not in usable set → drop.
*
* Pure function — exported so static + dynamic hooks share the same
* verdict logic without divergence.
*/
export function isUsableRawModelId(
id: string,
usable: {
aliases: Set<string>;
canonicals: Set<string>;
knownAliases: Set<string>;
},
enrichment: OmniRouteEnrichmentMap | undefined
): boolean {
const slash = id.indexOf("/");
if (slash <= 0) return true;
const prefix = id.slice(0, slash);
if (usable.aliases.has(prefix) || usable.canonicals.has(prefix)) return true;
// O(1) "known prefix" check via pre-calculated knownAliases set.
// If prefix was in /api/pricing/models but is NOT in usable set,
// drop the model. Unknown prefixes (e.g. agentrouter-style synthetic)
// pass through (subtract-filter semantics).
if (usable.knownAliases.has(prefix)) return false;
return true;
}
/**
* Decide whether a combo passes the `usableOnly` filter. A combo keeps
* when AT LEAST ONE of its members maps to a usable canonical provider.
* Combos with zero resolvable members pass through (already degraded to
* all-false LCD posture and surfaced as cosmetic-only entries).
*/
export function isUsableCombo(
combo: OmniRouteRawCombo,
usable: {
aliases: Set<string>;
canonicals: Set<string>;
knownAliases: Set<string>;
}
): boolean {
const steps = Array.isArray(combo.models) ? combo.models : [];
if (steps.length === 0) return true;
// The provider id is folded INTO the full model string by OmniRoute's
// `normalizeComboRecord` (e.g. "cc/claude-opus-4-7") — combo member refs do
// NOT carry a separate `providerId` field. Derive the prefix from `step.model`
// and apply the same subtract-filter verdict as `isUsableRawModelId`.
let sawResolvableMember = false;
for (const step of steps) {
// Nested combo refs carry no model id we can resolve to a provider here.
if (step?.kind === "combo-ref") continue;
const modelId = typeof step?.model === "string" ? step.model : "";
const slash = modelId.indexOf("/");
if (slash <= 0) continue; // no provider prefix to evaluate
sawResolvableMember = true;
const prefix = modelId.slice(0, slash);
if (usable.aliases.has(prefix) || usable.canonicals.has(prefix)) return true;
// Unknown prefix (not in the known-alias universe) → can't prove
// unroutable; keep. Known-but-not-usable prefixes keep scanning.
if (!usable.knownAliases.has(prefix)) return true;
}
// No member resolved to a provider prefix → can't prove unroutable; keep.
if (!sawResolvableMember) return true;
// Every resolvable member used a known-but-non-usable prefix → drop.
return false;
}
// ─────────────────────────────────────────────────────────────────────────
// #9473 — Model allowlist / blocklist filter helpers
// ─────────────────────────────────────────────────────────────────────────
/**
* Pre-compiled filter structure for the model allowlist/blocklist.
*
* "exact" holds full raw IDs (e.g. "cc/claude-opus-4-7") for O(1) match.
* "suffixes" holds bare model IDs (e.g. "claude-opus-4-7") that match any
* "{prefix}/claude-opus-4-7" — so operators can curate by model name without
* knowing the provider prefix.
*/
export interface ModelListFilter {
exact: Set<string>;
suffixes: Set<string>;
}
/**
* Compile a string[] of model IDs into a pre-computed filter structure.
* Returns undefined when the list is empty or undefined — the "no filter"
* state that callers use as a passthrough.
*
* IDs containing a "/" are stored in "exact"; bare IDs (no slash) go into
* "suffixes" and match any "{prefix}/<suffix>" at check time.
*/
export function compileModelListFilter(list?: string[]): ModelListFilter | undefined {
if (!list || list.length === 0) return undefined;
const exact = new Set<string>();
const suffixes = new Set<string>();
for (const id of list) {
if (id.includes("/")) {
exact.add(id);
} else {
suffixes.add(id);
}
}
if (exact.size === 0 && suffixes.size === 0) return undefined;
return { exact, suffixes };
}
/**
* Decide whether a raw model ID passes the allowlist/blocklist filter.
*
* Rules (all filters AND together with usableOnly):
* - No visible filter and no hidden filter → keep (passthrough).
* - Visible filter set: id must match either the exact set or the suffix
* set (bare suffix "claude-opus-4-7" matches any "{prefix}/claude-opus-4-7").
* - Hidden filter set: id must NOT match either the exact or suffix set.
* - If id is in BOTH visible and hidden → DROP (deny wins — safer).
* - No-slash ids (e.g. combo names like "claude-primary") are checked
* against the exact set directly, and against the suffix set as a bare
* match.
*
* Pure function — exported so static + dynamic hooks share the same
* verdict logic without divergence.
*/
export function passesModelAllowlist(
id: string,
visible?: ModelListFilter,
hidden?: ModelListFilter
): boolean {
// Hidden filter takes precedence (deny wins over allow).
if (hidden) {
if (hidden.exact.has(id) || matchesSuffix(id, hidden.suffixes)) return false;
}
// Visible filter: if set, id must match.
if (visible) {
if (!visible.exact.has(id) && !matchesSuffix(id, visible.suffixes)) return false;
}
return true;
}
/**
* Decide whether a combo passes the allowlist filter. A combo keeps when
* AT LEAST ONE of its members matches the visible filter. When no visible
* filter is set, all combos pass. Combos with zero resolvable members pass
* (mirrors `isUsableCombo` semantics).
*/
export function passesComboAllowlist(combo: OmniRouteRawCombo, visible?: ModelListFilter): boolean {
if (!visible) return true;
const steps = Array.isArray(combo.models) ? combo.models : [];
if (steps.length === 0) return true;
let sawResolvableMember = false;
for (const step of steps) {
if (step?.kind === "combo-ref") continue;
const modelId = typeof step?.model === "string" ? step.model : "";
if (modelId.length === 0) continue;
sawResolvableMember = true;
if (visible.exact.has(modelId) || matchesSuffix(modelId, visible.suffixes)) return true;
}
// No resolvable member → can't prove it should be hidden; keep.
if (!sawResolvableMember) return true;
// Every resolvable member failed the allowlist → drop.
return false;
}
/**
* Check whether a raw model ID matches any suffix in the set.
* For an id like `cc/claude-opus-4-7`, the suffix after the first `/`
* is checked against the suffixes set. For a bare id like `claude-primary`,
* the id itself is checked against the suffixes set.
*/
function matchesSuffix(id: string, suffixes: Set<string>): boolean {
if (suffixes.size === 0) return false;
const slash = id.indexOf("/");
const suffix = slash > 0 ? id.slice(slash + 1) : id;
return suffixes.has(suffix);
}
/**
* Slugify a combo display name into a copy/paste-friendly URL-safe segment.
* Lowercases, replaces any run of non-alphanumeric chars with a single dash,
* trims leading/trailing dashes. Empty input or all-special input returns
* the empty string (caller must fall back to the combo's UUID id).
*
* Example: `Claude Tier` → `claude-tier`, `GPT 5.5 / Pro` → `gpt-5-5-pro`.
*/
export function slugifyComboName(name: string): string {
if (typeof name !== "string") return "";
return trimLeadingDashes(trimTrailingDashes(name.toLowerCase().replace(/[^a-z0-9]+/g, "-")));
}
/**
* Build a combo's static-block key, provider-prefixed as `<providerId>/<slug>`
* (e.g. `omniroute/MASTER`, `omniroute/MASTER-LIGHT`), guaranteeing uniqueness
* across an entire static catalog. If `<providerId>/<slug>` is already present in
* `used`, suffixes a short UUID-prefix disambiguator from `combo.id` so the second
* combo doesn't silently overwrite the first. Mutates `used` in place by recording
* the chosen key. Returns the final `<providerId>/<slug>` key.
*
* NOTE: the key MUST carry the OWNING provider prefix (`omniroute/…`), never a
* `combo/` namespace — OpenCode parses model IDs on `/` to extract the provider,
* so `combo/MASTER` would resolve provider=`combo` (no credentials) and fail with
* "Unable to determine provider", whereas `omniroute/MASTER` resolves provider=
* `omniroute` and the openai-compatible adapter strips the prefix and sends the
* bare slug upstream, which the server resolves via getComboByName. See PR #4184.
*
* Falls back to `<providerId>/<id>` when the friendly name slugifies to the empty
* string (e.g. a combo named just punctuation).
*/
export function buildComboKey(
combo: OmniRouteRawCombo,
used: Set<string>,
providerId: string
): string {
const friendlyName = combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
let slug = slugifyComboName(friendlyName);
if (slug.length === 0) slug = combo.id;
let key = `${providerId}/${slug}`;
if (used.has(key)) {
const tail = combo.id.split("-")[0] ?? combo.id;
key = `${providerId}/${slug}-${tail}`;
// Defensive: in the (impossible) event the disambiguated key also
// collides, append the full id.
if (used.has(key)) key = `${providerId}/${slug}-${combo.id}`;
}
used.add(key);
return key;
}
/**
* Internal cache key: `${baseURL}::sha256(credentialId)`. The credential id
* combines the inference key and effective management-read token so catalog
* results fetched under different permissions never share an entry. We hash
* it so the cache key is safe to inspect without leaking either secret.
* Different credential tuples MUST keep independent cache entries: a single
* OC user may register prod + preprod OmniRoute side-by-side with distinct
* keys, and serving one's catalog from the other's cache would be a
* correctness bug, not just a privacy one.
*/
// codeql[js/insufficient-password-hash]: the input here is an API-key
// identifier we use solely to derive an in-memory cache lookup key — it is
// never stored, transmitted, compared against a hash, or used as a password.
// SHA-256 is intentional: cheap + deterministic, prevents the raw secret
// from sitting in memory dumps alongside the cache map. Slow KDFs (bcrypt/
// argon2) would defeat the purpose (sub-ms lookups on every request).
function modelsCacheKey(baseURL: string, credentialId: string): string {
const h = createHash("sha256").update(credentialId).digest("hex");
return `${baseURL}::${h}`;
}
/**
* Shared fetch-result cache entry. Holds the RAW `/v1/models` + `/api/combos`
* responses (NOT a pre-derived ModelV2 / static-entry shape) so the provider
* hook (T-03/T-05) and the config-shim hook (T-07) can derive their own
* output shapes from the same source without re-fetching.
*
* Why raw instead of derived:
* - provider hook emits ModelV2 (rich nested capabilities + cost + limits).
* - config hook emits the stripped sibling shape
* (`{name, attachment, reasoning, tool_call, temperature, limit?}`).
* - These overlap but neither is a superset of the other (ModelV2 has no
* `tool_call` field — it's `toolcall`; the stripped shape has no
* `cost`/`status`/`headers`). Caching the raw responses is the only
* lossless option.
* - On OC ≥1.14.49 cold start BOTH hooks fire within the same
* OmniRoutePlugin instance — sharing the cache means /v1/models +
* /api/combos each hit the gateway exactly ONCE per TTL refresh, not
* twice.
*/
export interface OmniRouteFetchCacheEntry {
rawModels: OmniRouteRawModelEntry[];
rawCombos: OmniRouteRawCombo[];
/** Display-name + pricing overlay from /api/pricing/models. Empty Map when feature is disabled or fetch failed. */
rawEnrichment: OmniRouteEnrichmentMap;
/** Compression combos from /api/context/combos. Empty array when feature is disabled or fetch failed. */
rawCompressionCombos: OmniRouteCompressionCombo[];
/** Provider connections from /api/providers. Empty array when feature is disabled or fetch failed. */
rawConnections: OmniRouteProviderConnection[];
expiresAt: number;
}
export type OmniRouteFetchCache = Map<string, OmniRouteFetchCacheEntry>;
/**
* Build the ProviderHook portion of the plugin for a given options bag.
* Exported standalone so the contract is unit-testable without faking the
* full PluginInput / Hooks surface, and so multi-instance setups can each
* own their own cache (a fresh hook closure per plugin tuple).
*
* Behavioural contract:
* - `id` binds to the resolved `providerId` (multi-instance: each plugin
* tuple's hook lists models under its own provider id).
* - `models(provider, ctx)` extracts the api key from `ctx.auth` (rejecting
* non-`api` flavors with `{}` — same posture as the auth loader); calls
* both `/v1/models` and `/api/combos` fetchers; maps raw `/v1/models`
* entries through `mapRawModelToModelV2`; maps each `/api/combos` entry
* through `mapComboToModelV2` (LCD across its member models); merges
* combos into the same map under their combo id; caches the unified
* result by `(baseURL, sha256(apiKey))` for `modelCacheTtl`.
* - **Combo / model ID collisions: combos win.** OmniRoute treats combos
* as the curated routing surface; if a combo and a raw model share an
* id the operator's intent is clearly the combo. We emit a
* `console.warn` exactly once per `(baseURL, apiKey, comboId)`
* collision so the operator can spot the unusual naming choice
* without log spam on every cache refresh.
* - **Combos fetch failure does NOT break the catalog**: soft-fail with
* a `console.warn` and fall back to a models-only catalog. Rationale:
* `/api/combos` requires a management-scoped key and OmniRoute may
* not have any combos provisioned (preprod returned `{combos: []}`
* at probe time). Hard-failing the entire catalog when combos are
* optional would silently hide the whole provider from OC's model
* picker.
* - **`/v1/models` fetch failure DOES propagate.** Without models
* there's no catalog at all, so an empty `{}` would just mask the
* error.
* - Cache is in-memory per hook instance, shared between models and
* combos (one fetch pair per (baseURL, apiKey) per TTL refresh).
*
* @param opts Plugin options (providerId, baseURL, modelCacheTtl, …).
* @param deps Dependency injection. `fetcher` defaults to the live
* `/v1/models` HTTP fetcher; `combosFetcher` defaults to the
* live `/api/combos` HTTP fetcher (override for tests / to
* disable combos by injecting one that returns `[]`). `now`
* defaults to `Date.now` (overridable for TTL tests). `cache`
* lets the caller share state across reconstructions (unused
* outside tests today).
*/
export function createOmniRouteProviderHook(
opts?: OmniRoutePluginOptions,
deps: {
fetcher?: OmniRouteModelsFetcher;
combosFetcher?: OmniRouteCombosFetcher;
enrichmentFetcher?: OmniRouteEnrichmentFetcher;
compressionMetaFetcher?: OmniRouteCompressionMetaFetcher;
providersFetcher?: OmniRouteProvidersFetcher;
now?: () => number;
cache?: OmniRouteFetchCache;
logger?: _Logger;
} = {}
): ProviderHook {
const resolved = resolveOmniRoutePluginOptions(opts);
const logger =
deps.logger ??
createLogger(
resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")
);
const fetcher = deps.fetcher ?? defaultOmniRouteModelsFetcher;
// T-05: combo discovery merges `/api/combos` entries into the same map as
// `/v1/models`. Default fetcher is declared further down the file; the
// reference resolves at hook-invocation time, not at hook-construction
// time, so source-order beyond hoisting rules has no semantic effect.
const combosFetcher = deps.combosFetcher ?? defaultOmniRouteCombosFetcher;
const enrichmentFetcher = deps.enrichmentFetcher ?? defaultOmniRouteEnrichmentFetcher;
const compressionMetaFetcher =
deps.compressionMetaFetcher ?? defaultOmniRouteCompressionMetaFetcher;
const providersFetcher = deps.providersFetcher ?? defaultOmniRouteProvidersFetcher;
// Features defaults (mirror v0.1.0 behavior when unset).
const features = resolved.features ?? {};
const wantCombos = features.combos !== false;
const wantEnrichment = features.enrichment !== false;
const wantCompressionMeta = features.compressionMetadata === true;
const wantUsableOnly = features.usableOnly === true;
const wantProviderTag = features.providerTag !== false;
// #9473: model allowlist/blocklist — compile once per hook instance.
const visibleFilter = compileModelListFilter(features.visibleModels);
const hiddenFilter = compileModelListFilter(features.hiddenModels);
const now = deps.now ?? Date.now;
// T-07: cache holds RAW fetch results (not pre-derived ModelV2) so that
// the config-shim hook can share the same cache and derive its stripped
// sibling shape from the same source without a second round-trip.
const cache: OmniRouteFetchCache = deps.cache ?? new Map();
// T-05: collision-warning deduper. Emit warn once per (cacheKey, comboId)
// tuple per hook instance so the operator sees the unusual naming choice
// once per session, not once per cache refresh.
const collisionWarned = new Set<string>();
return {
id: resolved.providerId,
async models(_provider, ctx) {
// Auth narrowing — same posture as the auth loader (T-02). Non-api
// flavors and empty keys → empty catalog. OC then exposes the
// /connect flow rather than spamming /v1/models with bad creds.
const auth = ctx?.auth;
if (
!auth ||
typeof auth !== "object" ||
(auth as { type?: unknown }).type !== "api" ||
typeof (auth as { key?: unknown }).key !== "string" ||
(auth as { key: string }).key.length === 0
) {
return {};
}
const apiKey = (auth as { key: string }).key;
// Management-plane catalog reads may use a narrower read-only token.
// Backward compatibility: when unset, retain the historical apiKey use.
const managementReadToken = resolved.managementReadToken ?? apiKey;
// baseURL resolution: plugin opts first, then credential-attached
// baseURL (auth backends sometimes stash it next to the key), then the
// provider config itself — a baseURL set via opencode.json provider
// options (or a config hook) lands on `provider.options` and is not
// visible through either of the first two links. No silent default to
// localhost: a misconfigured plugin should surface a clear warning,
// not phantom /v1/models calls. Cast through unknown because the Auth
// union (OAuth | ApiAuth | WellKnownAuth) doesn't declare baseURL on
// any branch — we duck-type it as a defensive extension point.
const authBaseURL = (auth as unknown as { baseURL?: unknown }).baseURL;
const providerBaseURL = (_provider as { options?: { baseURL?: unknown } } | undefined)
?.options?.baseURL;
const baseURL =
resolved.baseURL ??
(typeof authBaseURL === "string" && authBaseURL.length > 0 ? authBaseURL : undefined) ??
(typeof providerBaseURL === "string" && providerBaseURL.length > 0
? providerBaseURL
: undefined) ??
"";
if (!baseURL) {
logger.error(
`provider.models(${resolved.providerId}): ` +
`no baseURL resolvable — checked plugin opts, auth.json, and provider config. ` +
`Set baseURL in opencode.json plugin options or run \`opencode connect ${resolved.providerId}\` with a baseURL.`
);
return {};
}
const cacheKey = modelsCacheKey(baseURL, `${apiKey}\0${managementReadToken}`);
const t = now();
const cached = cache.get(cacheKey);
let rawModels: OmniRouteRawModelEntry[];
let rawCombos: OmniRouteRawCombo[];
let rawEnrichment: OmniRouteEnrichmentMap;
let rawCompressionCombos: OmniRouteCompressionCombo[];
let rawConnections: OmniRouteProviderConnection[];
if (cached && cached.expiresAt > t) {
rawModels = cached.rawModels;
rawCombos = cached.rawCombos;
rawEnrichment = cached.rawEnrichment;
rawCompressionCombos = cached.rawCompressionCombos;
rawConnections = cached.rawConnections;
} else {
// Models fetch is required (no catalog otherwise → silent provider
// disappearance). We do NOT wrap this in a try; let the error
// propagate to OC's UI.
rawModels = await fetcher(baseURL, apiKey, 10_000);
// T-05: combos fetch is best-effort, gated by features.combos.
// Soft-fail on any error: emit a warn-level diagnostic and fall back
// to a models-only catalog. Rationale: /api/combos requires a
// management-scoped key and OmniRoute may not have any combos
// provisioned. Hard-failing when combos are optional would
// silently hide the whole provider from OC's picker.
rawCombos = [];
if (wantCombos) {
try {
rawCombos = await combosFetcher(baseURL, managementReadToken, 10_000);
} catch (err) {
logger.warn("combos fetch failed, falling back to models-only catalog", err);
}
}
// Enrichment fetch (nice names + pricing). Best-effort, gated by
// features.enrichment. Soft-fails to empty map.
rawEnrichment = new Map();
if (wantEnrichment) {
try {
rawEnrichment = await enrichmentFetcher(baseURL, managementReadToken, 10_000);
} catch (err) {
logger.warn("enrichment fetch failed, falling back to raw ids", err);
}
}
// Compression metadata fetch. Off by default, gated by
// features.compressionMetadata. Soft-fails to empty array.
rawCompressionCombos = [];
if (wantCompressionMeta) {
try {
rawCompressionCombos = await compressionMetaFetcher(
baseURL,
managementReadToken,
10_000
);
} catch (err) {
logger.warn("compression-metadata fetch failed", err);
}
}
// Provider-connections fetch. Off by default, gated by
// features.usableOnly. Soft-fails to empty array — when the
// connection table is unreadable we skip the filter entirely
// (subtract-filter semantics: don't drop everything we couldn't
// verify).
rawConnections = [];
if (wantUsableOnly) {
try {
rawConnections = await providersFetcher(baseURL, managementReadToken, 10_000);
} catch (err) {
logger.warn(
"/api/providers fetch failed; usableOnly filter disabled for this refresh",
err
);
}
}
cache.set(cacheKey, {
rawModels,
rawCombos,
rawEnrichment,
rawCompressionCombos,
rawConnections,
expiresAt: t + resolved.modelCacheTtl,
});
// Debug breadcrumb: surface fetch result so operators can confirm
// the dynamic pipeline fired and how much catalog OmniRoute returned.
// Emitted once per cache miss (TTL refresh) — quiet on cache hits.
// Info-level: hidden at the default `warn` level (see #8982).
logger.info(
`catalog refreshed for providerId=${resolved.providerId} baseURL=${baseURL}: ` +
`${rawModels.length} models + ${rawCombos.length} combos + ` +
`${rawEnrichment.size} enrichment entries + ` +
`${rawCompressionCombos.length} compression combos + ` +
`${rawConnections.length} connections ` +
`(TTL=${resolved.modelCacheTtl}ms)`
);
// ── Startup debug: deep-dive into enrichment ────────────────────
if (resolved.features?.startupDebug === true) {
await writeStartupDiagnostics({
providerId: resolved.providerId,
baseURL,
modelCount: rawModels.length,
comboCount: rawCombos.length,
enrichmentSize: rawEnrichment.size,
enrichment: rawEnrichment,
features: resolved.features,
});
}
}
// Lookup index for LCD member resolution: O(1) per member lookup.
// Indexed by raw model `id` — combo steps reference this exact
// string per ComboModelStep in src/lib/combos/steps.ts.
const rawModelById = new Map<string, OmniRouteRawModelEntry>();
for (const entry of rawModels) {
if (entry.id) rawModelById.set(entry.id, entry);
}
// usableOnly filter — compute the set of usable alias prefixes once
// per refresh. Empty when feature is off OR connection fetch failed
// OR no connections returned, in which case we keep everything
// (subtract-filter semantics: only drop when we can prove a prefix
// is NOT usable; never hide the catalog on a soft-fail).
const usable =
wantUsableOnly && rawConnections.length > 0
? usableProviderAliasSet(rawConnections, rawEnrichment)
: undefined;
// Build the canonical→alias reverse map AND the canonical-dedup
// set once per refresh. Together they fix the dual-keyed
// `/v1/models` problem where the same model surfaces under BOTH
// `<alias>/<id>` (enriched) AND `<canonical>/<id>` (raw): we keep
// the alias key and skip the canonical twin entirely.
const canonicalToAlias = buildCanonicalToAliasMap(rawEnrichment);
const canonicalDedup = canonicalDedupSet(rawModels, canonicalToAlias);
const aliasIndex = buildAliasIndex(rawEnrichment);
// Map raw models → ModelV2 keyed by id. When enrichment data is
// present (features.enrichment, default on), overlay the nicer
// display name + pricing from /api/pricing/models via the
// alias-fallback lookup chain (covers canonical rows lacking
// direct pricing entries).
const models: Record<string, ModelV2> = {};
for (const entry of rawModels) {
if (!entry.id) continue;
if (canonicalDedup.has(entry.id)) continue;
if (usable && !isUsableRawModelId(entry.id, usable, rawEnrichment)) continue;
// #9473: allowlist/blocklist filter (AND with usableOnly).
if (!passesModelAllowlist(entry.id, visibleFilter, hiddenFilter)) continue;
const model = mapRawModelToModelV2(entry, {
// #6859: server-facing id — NOT the OC-gate-prefixed `resolved.providerId`.
providerId: resolved.omnirouteProviderId,
baseURL,
apiFormat: resolved.features?.apiFormat,
});
const enrichEntry = lookupEnrichment(
entry.id,
rawEnrichment,
canonicalToAlias,
entry.owned_by
);
applyEnrichment(model, enrichEntry);
// Prepend upstream provider label (e.g. `Claude - Claude Opus 4.7`)
// so the picker groups same-model rows by upstream connection.
// Idempotent + gated by `features.providerTag` (default-on).
// Combos skip this on purpose. The alias-index fallback rescues
// raw rows like `cohere/rerank-multilingual-v3.0` whose specific
// model id isn't in `/api/pricing/models` but whose slot is.
if (wantProviderTag) {
const tagEntry = resolveProviderTagEntry(
entry.id,
enrichEntry,
aliasIndex,
canonicalToAlias
);
applyProviderTag(model, tagEntry);
}
// OC's static-catalog reader parses the key on `/` to recover
// (providerID, modelID). `mapRawModelToModelV2` already stamps the
// prefixed id on `model.id` (e.g. `omniroute/claude-primary`), so we
// must key by `model.id` — not by the raw `entry.id` which would be
// a bare slug and parse as `providerID=slug, modelID=""`.
models[model.id] = model;
}
// Default compression combo (used to decorate ALL combo names when
// compression metadata is present). OmniRoute returns at most one
// entry with `isDefault: true` per /api/context/combos.
const defaultCompression = wantCompressionMeta
? rawCompressionCombos.find((c) => c.isDefault === true)
: undefined;
// T-05: map raw combos → ModelV2. Skip hidden combos (operator
// preference — provisioned but intentionally not surfaced).
// Resolve each combo's member step list into the matching raw
// model entries; unknown member ids are silently dropped before
// mapComboToModelV2 sees them, which then degrades to the
// all-false LCD posture if zero members remain.
//
// Combos are keyed under the `combo/<slug>` namespace so the TUI
// picker separates them from provider/model pairs and the UUID
// never surfaces. This mirrors `buildStaticProviderEntry` so the
// static + dynamic catalogs publish identical keys.
const comboNames = new Set<string>();
for (const combo of rawCombos) {
if (!combo || combo.isHidden === true) continue;
const n = combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
if (typeof n === "string" && n.length > 0) comboNames.add(n);
}
for (const key of Object.keys(models)) {
if (comboNames.has(key)) delete models[key];
}
// ── Combo LCD across nested combo-refs (T-NN) ───────────────────────
// Combos can nest other combos via `kind: "combo-ref"` members
// (e.g. MASTER-LIGHT contains LEGACY, KIRO, Opecode Zen FREE). The
// nested combo's own `limit.context` is computed below in this same
// loop, so we need a fixpoint iteration: if a combo-ref points at a
// combo not yet processed, defer this combo and try again after the
// sibling combos catch up. We bound the retries so a circular combo
// graph can't deadlock the picker.
const MAX_COMBO_PASSES = 8;
const usedComboKeys = new Set<string>();
// Combos in `rawCombos` that still need (re)processing this round.
// Shrinks as combos resolve.
let pending = rawCombos.filter((combo) => {
if (!combo.id) return false;
if (combo.isHidden === true) return false;
if (usable && !isUsableCombo(combo, usable)) return false;
// #9473: combo allowlist — drop when no member matches visible filter.
if (visibleFilter && !passesComboAllowlist(combo, visibleFilter)) return false;
return true;
});
// Resolved nested combos keyed by their friendly name, so parent
// combos that reference them via combo-ref can lift the full
// capability vector (not just the context window) into their own
// LCD pass.
const resolvedComboModelsByName = new Map<string, ModelV2>();
for (let pass = 0; pass < MAX_COMBO_PASSES && pending.length > 0; pass++) {
const stillPending: typeof pending = [];
for (const combo of pending) {
const memberSteps = Array.isArray(combo.models) ? combo.models : [];
const memberEntries: OmniRouteRawModelEntry[] = [];
let deferredThisPass = false;
for (const step of memberSteps) {
// Unknown-bridge: ComboMemberRef's DTS type only declares
// `model?: string`, so verify the runtime shape before reading
// either `model` (raw member) or `comboName` (nested combo).
const stepKind = (step as unknown as { kind?: unknown }).kind;
if (stepKind === "combo-ref") {
const comboName = (step as unknown as { comboName?: unknown }).comboName;
if (typeof comboName !== "string" || comboName.length === 0) {
continue;
}
const nestedModel = resolvedComboModelsByName.get(comboName);
if (!nestedModel) {
// Nested combo hasn't been processed yet. Defer this
// combo to the next pass.
deferredThisPass = true;
break;
}
// Synthesize a member entry that contributes only the
// nested combo's pre-computed context_length + max_output.
// Other capability axes default conservatively (no tool
// calls, no vision) — a nested combo's modalities are an
// OR, but if we let raw-model defaults leak in we'd
// over-claim. The combo's own LCD (computed by
// mapComboToModelV2 from the synthesized entries) will only
// further restrict capabilities, so this is safe.
// Synthesize a member entry carrying the nested combo's
// pre-computed context + capabilities + modalities so the
// parent combo's LCD is accurate across the whole graph
// (not just its direct raw-model members).
const inputModalities: string[] = [];
if (nestedModel.capabilities.input.text) inputModalities.push("text");
if (nestedModel.capabilities.input.audio) inputModalities.push("audio");
if (nestedModel.capabilities.input.image) inputModalities.push("image");
if (nestedModel.capabilities.input.video) inputModalities.push("video");
if (nestedModel.capabilities.input.pdf) inputModalities.push("pdf");
const outputModalities: string[] = [];
if (nestedModel.capabilities.output.text) outputModalities.push("text");
if (nestedModel.capabilities.output.audio) outputModalities.push("audio");
if (nestedModel.capabilities.output.image) outputModalities.push("image");
if (nestedModel.capabilities.output.video) outputModalities.push("video");
if (nestedModel.capabilities.output.pdf) outputModalities.push("pdf");
memberEntries.push({
id: `combo-ref:${comboName}`,
context_length: nestedModel.limit.context,
max_output_tokens: nestedModel.limit.output,
max_input_tokens: nestedModel.limit.input ?? 0,
owned_by: "combo",
input_modalities: inputModalities,
output_modalities: outputModalities,
capabilities: {
temperature: nestedModel.capabilities.temperature,
reasoning: nestedModel.capabilities.reasoning,
thinking: nestedModel.capabilities.interleaved,
attachment: nestedModel.capabilities.attachment,
tool_calling: nestedModel.capabilities.toolcall,
},
} as unknown as OmniRouteRawModelEntry);
continue;
}
const modelId = (step as unknown as { model?: unknown }).model;
if (typeof modelId !== "string" || modelId.length === 0) continue;
const member = rawModelById.get(modelId);
if (member) memberEntries.push(member);
}
if (deferredThisPass) {
stillPending.push(combo);
continue;
}
const mapped = mapComboToModelV2(
combo,
memberEntries,
// #6859: server-facing id — NOT the OC-gate-prefixed `resolved.providerId`.
resolved.omnirouteProviderId,
baseURL,
features.apiFormat
);
const hasMembers = memberEntries.length > 0;
// Apply enrichment overlay to combos too (OmniRoute's
// /api/pricing/models surfaces combos alongside provider-scoped
// models with curated names).
applyEnrichment(mapped, rawEnrichment.get(combo.id));
// unroutable combo would mislead the picker.
if (hasMembers && defaultCompression && defaultCompression.pipeline.length > 0) {
const tag = formatCompressionPipeline(defaultCompression.pipeline);
if (tag.length > 0 && !mapped.name.includes(tag)) {
mapped.name = `${mapped.name} ${tag}`;
}
}
// #6859: server-facing key — NOT the OC-gate-prefixed `resolved.providerId`.
const comboKey = buildComboKey(combo, usedComboKeys, resolved.omnirouteProviderId);
// Collision policy: combos win. Warn ONCE per (cacheKey, comboKey)
// when overwriting a same-key raw model so the operator can spot
// the unusual naming choice without log spam. Suppress the warning
// when the collision is the intentional dedup pattern (combo.name
// exactly matches an existing raw model's id) — /v1/models
// pre-mirrors combos as raw entries and the operator's intent is
// always "combo wins" in that case.
if (Object.prototype.hasOwnProperty.call(models, comboKey)) {
const existing = models[comboKey];
// Intentional dedup: `/v1/models` pre-mirrors combos as raw
// entries, so the bare combo name appears as the model id in
// `rawModels`. After our prefixing the existing entry's id is
// `${providerId}/${raw.id}` — the combo name is a substring of
// that prefixed id (or, for already-prefixed raw models, the
// exact id). Use `endsWith` to avoid matching substrings of
// unrelated prefixed ids.
const isIntentionalDedup =
existing &&
combo.name &&
combo.name.trim().length > 0 &&
(existing.id === combo.name.trim() || existing.id.endsWith(`/${combo.name.trim()}`));
if (!isIntentionalDedup) {
const dedupeKey = `${cacheKey}::${comboKey}`;
if (!collisionWarned.has(dedupeKey)) {
collisionWarned.add(dedupeKey);
logger.warn(`combo key "${comboKey}" collides with a model id; combo wins.`);
}
}
}
models[comboKey] = mapped;
// Make this combo's resolved model available to parent combos
// that reference it via combo-ref. Use the friendly name
// (combo.name) since that's the lookup key on the parent side.
const lookupName =
combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
resolvedComboModelsByName.set(lookupName, mapped);
}
if (stillPending.length === pending.length) break;
pending = stillPending;
}
if (pending.length > 0) {
logger.warn(
`${pending.length} combo(s) could not resolve all nested combo-refs after ${MAX_COMBO_PASSES} passes; they will advertise context=0 to avoid over-claiming.`
);
}
return models;
},
};
}
// ────────────────────────────────────────────────────────────────────────────
// Fetch interceptor (T-04) — Bearer + Content-Type injection on intended
// same-origin OmniRoute inference requests only
// ────────────────────────────────────────────────────────────────────────────
/**
* Build a `fetch`-compatible interceptor that injects `Authorization: Bearer`
* (and a default `Content-Type`) only onto same-origin requests targeting
* `<base>/chat/completions` or `<base>/models`, where `<base>` is the
* configured baseURL path normalized to end in `/v1`. Management, MCP, and
* unrelated inference paths pass through untouched. The apiKey is treated as
* a secret bound to both the configured OmniRoute origin and these intended
* inference endpoints, and MUST NOT leak elsewhere.
*
* Ported from Alph4d0g's `[email protected]` `createFetchInterceptor`
* (their `dist/src/plugin.js:477-516`) with these intentional deviations:
*
* - **`baseURL` is required** here (no `localhost:20128/v1` fallback). T-04
* callers always have an authoritative baseURL (from plugin opts or
* auth.json); a silent local default would be a footgun.
* - **Content-Type defaulting is gated on `init.body` presence**. Their
* version unconditionally sets `application/json` even on `GET /v1/models`,
* which is harmless but noisy; we only set it when there's a body to
* describe.
* - **Gemini schema sanitisation is NOT applied here** — that's T-06's
* responsibility and will land as a body-transform step inside this
* same function (or as a thin wrapper around it).
* - **Header merge strategy mirrors theirs**: Request-attached headers
* first, then `init.headers` overlay, then our injected
* Authorization/Content-Type — so the apiKey we own ALWAYS wins over
* any caller-supplied Bearer for the same OmniRoute provider.
*
* @see https://opencode.ai/docs/plugins for the AuthLoaderResult.fetch contract
* (the returned function is invoked by the AI-SDK in lieu of global fetch).
*/
export function createOmniRouteFetchInterceptor(config: {
apiKey: string;
baseURL: string;
}): typeof fetch {
let baseOrigin: string | undefined;
const inferencePaths = new Set<string>();
try {
const baseUrl = new URL(config.baseURL);
baseOrigin = baseUrl.origin;
const basePath = ensureV1Suffix(baseUrl.pathname);
inferencePaths.add(`${basePath}/chat/completions`);
inferencePaths.add(`${basePath}/responses`);
inferencePaths.add(`${basePath}/messages`);
inferencePaths.add(`${basePath}/models`);
} catch {
// Credential-attached base URLs are not schema-validated. A malformed
// value must disable injection rather than broaden the credential scope.
}
return async (input, init = {}) => {
const url =
typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
let requestUrl: URL | undefined;
try {
requestUrl = new URL(url);
} catch {
// Native fetch will report malformed/relative URLs as usual. We only
// decline to attach credentials before forwarding the original input.
}
const normalizedPath = requestUrl ? trimTrailingSlashes(requestUrl.pathname) || "/" : undefined;
const targetsInference =
requestUrl?.origin === baseOrigin &&
normalizedPath !== undefined &&
inferencePaths.has(normalizedPath);
if (!targetsInference) {
return fetch(input, init);
}
// Merge order: Request-attached headers (when input is a Request) →
// init.headers overlay → our injected headers last (so we win).
const headers = new Headers(input instanceof Request ? input.headers : undefined);
if (init.headers) {
const initHeaders = new Headers(init.headers);
initHeaders.forEach((value, key) => {
headers.set(key, value);
});
}
headers.set("Authorization", `Bearer ${config.apiKey}`);
// Only default Content-Type when the caller actually has a body AND
// hasn't already declared the media type themselves.
const hasBody = init.body != null || input instanceof Request;
if (!headers.has("Content-Type") && hasBody) {
headers.set("Content-Type", "application/json");
}
return applyOmniRouteInferenceTelemetry(await fetch(input, { ...init, headers }));
};
}
// ────────────────────────────────────────────────────────────────────────────
// Gemini tool-schema sanitisation (T-06) — strip JSON-schema keywords that
// the Gemini API rejects from outbound chat-completion / responses bodies
// when the target model is a Gemini variant.
// ────────────────────────────────────────────────────────────────────────────
/**
* JSON-Schema keywords that the Gemini API rejects when present anywhere in
* a function-calling tool definition. Standard OpenAI / Anthropic clients
* happily emit these (they're valid Draft-07 schema) but Gemini's tool
* validator throws on them, breaking OmniRoute → Gemini chains transparently.
*
* Source: behavioural reverse-engineering from Alph4d0g's
* [email protected] (dist/src/plugin.js:517).
*/
const GEMINI_SCHEMA_KEYS_TO_REMOVE = new Set(["$schema", "$ref", "ref", "additionalProperties"]);
function isRecord(v: unknown): v is Record<string, unknown> {
return typeof v === "object" && v !== null && !Array.isArray(v);
}
/**
* Recursively strip `GEMINI_SCHEMA_KEYS_TO_REMOVE` from an arbitrary
* JSON-Schema-shaped record. Walks both the record's own properties and
* any nested objects / arrays so deeply nested `properties.x.properties.y`
* trees are reached without a separate traversal pass. Mutates in place
* and reports whether any key was deleted so callers can skip a
* `JSON.stringify` round-trip when nothing changed.
*/
function stripSchemaKeys(schema: Record<string, unknown>): boolean {
let changed = false;
for (const key of Object.keys(schema)) {
if (GEMINI_SCHEMA_KEYS_TO_REMOVE.has(key)) {
delete schema[key];
changed = true;
continue;
}
const value = schema[key];
if (Array.isArray(value)) {
for (const item of value) {
if (isRecord(item)) {
changed = stripSchemaKeys(item) || changed;
}
}
continue;
}
if (isRecord(value)) {
changed = stripSchemaKeys(value) || changed;
}
}
return changed;
}
/**
* Walk every tool definition in the payload and strip Gemini-incompatible
* schema keywords. Handles both chat-completion shape
* (`tools[].function.parameters`) and Responses-API shape
* (`tools[].input_schema`), plus the Gemini-native `function_declaration`
* variant some adapters use.
*
* Also strips top-level schema keywords from the payload itself — clients
* occasionally attach a top-level `$schema` declaration when re-serialising
* tool bundles, and Gemini rejects those too.
*/
function sanitizeToolSchemaContainer(payload: Record<string, unknown>): boolean {
let changed = false;
// Top-level keyword strip — covers payload-level `$schema` etc.
for (const key of Object.keys(payload)) {
if (GEMINI_SCHEMA_KEYS_TO_REMOVE.has(key)) {
delete payload[key];
changed = true;
}
}
const tools = (payload as { tools?: unknown }).tools;
if (!Array.isArray(tools)) {
return changed;
}
for (const tool of tools) {
if (!isRecord(tool)) continue;
const fn = (tool as { function?: unknown }).function;
if (isRecord(fn) && isRecord((fn as { parameters?: unknown }).parameters)) {
changed = stripSchemaKeys(fn.parameters as Record<string, unknown>) || changed;
}
const fnDecl = (tool as { function_declaration?: unknown }).function_declaration;
if (isRecord(fnDecl) && isRecord((fnDecl as { parameters?: unknown }).parameters)) {
changed = stripSchemaKeys(fnDecl.parameters as Record<string, unknown>) || changed;
}
const inputSchema = (tool as { input_schema?: unknown }).input_schema;
if (isRecord(inputSchema)) {
changed = stripSchemaKeys(inputSchema) || changed;
}
}
return changed;
}
/**
* Pure function — recursively strip Gemini-incompatible JSON-Schema
* keywords (`$schema`, `$ref`, `ref`, `additionalProperties`) from the
* tool definitions on a chat-completions / responses payload.
*
* Walks:
* - `payload.tools[].function.parameters` (OpenAI chat-completions shape)
* - `payload.tools[].function_declaration.parameters` (Gemini-native shape
* some adapters round-trip)
* - `payload.tools[].input_schema` (Responses-API shape)
* - all `properties.<x>` (and `properties.<x>.properties.<y>`…) inside
* each container, recursing through nested objects and arrays.
* - top-level payload keys (some clients attach a payload-level `$schema`).
*
* Returns the cleaned payload. Does NOT mutate input — clones first via
* `structuredClone` so callers can keep a reference to the original. If
* the payload is not a record, or carries no tools and no top-level
* stripped keys, returns a (still cloned) equivalent.
*
* Exported so the body-transform layer is unit-testable independent of the
* fetch wrapper.
*/
export function sanitizeGeminiToolSchemas(payload: unknown): unknown {
if (!isRecord(payload)) {
// Non-record payloads (string, array, number, null) can't carry tool
// schemas. Pass back the same value — there's nothing to clone-and-strip
// and propagating the original keeps caller semantics simple.
return payload;
}
// structuredClone is available in Node 18+; the package's engines field
// already requires Node >=22.22.3 so we can rely on it without a
// JSON round-trip fallback.
const cloned = structuredClone(payload) as Record<string, unknown>;
sanitizeToolSchemaContainer(cloned);
return cloned;
}
/**
* Detect whether a payload is bound for a Gemini model. Returns true if
* `payload.model` is a string AND matches any known Gemini routing pattern:
*
* - case-insensitive substring `gemini` (covers bare `gemini-1.5-pro`,
* `gemini-2.5-flash`, etc.)
* - `models/gemini-…` (Google Generative AI canonical id form)
* - `google-vertex/gemini-…` (OpenCode + AI-SDK Vertex routing prefix)
*
* Liberal by design: a false positive (cleaning a payload that didn't
* need cleaning) costs only a structuredClone + one walk; a false negative
* breaks the whole chain by forwarding $schema/additionalProperties to
* Gemini which throws 400 INVALID_ARGUMENT. The first three checks
* collapse into the case-insensitive substring check, but they're
* documented separately so future maintainers see the intent.
*
* Exported so callers and tests can probe detection independent of the
* fetch wrapper.
*/
export function shouldSanitizeForGemini(payload: unknown): boolean {
if (!isRecord(payload)) return false;
const model = (payload as { model?: unknown }).model;
if (typeof model !== "string") return false;
return /gemini/i.test(model);
}
/**
* Module-level latch so the streaming-body warning fires AT MOST once per
* Node process. ReadableStream bodies can't be safely cloned + JSON-parsed
* without consuming the stream (and re-creating a stream that survives both
* read paths is non-trivial), so the sanitiser skips them — but we want
* the operator to see one heads-up that schema stripping won't run on
* those requests.
*/
let geminiStreamingWarningEmitted = false;
/**
* Wrapper over an inner `fetch` that applies Gemini schema sanitisation to
* outbound chat-completion / responses request bodies.
*
* Behaviour:
* - URL gate: only inspects requests whose URL path contains
* `/chat/completions` or `/responses` (lenient about prefix — works for
* `/v1/chat/completions`, `/openai/v1/chat/completions`, …).
* - Body extraction handles `string`, `Buffer` / `Uint8Array`,
* `URLSearchParams` (calls `.toString()`), `Blob` (`await .text()`),
* AND `Request` input where the body lives on the Request not init.
* `ReadableStream` bodies are skipped (see below).
* - Body must JSON.parse to a record; otherwise pass-through.
* - `shouldSanitizeForGemini` gates the actual transform — non-Gemini
* payloads pass through unchanged regardless of endpoint.
* - Fail-open: ANY error during extraction / parse / sanitise falls back
* to forwarding the original `(input, init)` to the inner fetch.
* Sanitisation is a best-effort guard, never a hard failure mode.
* - `ReadableStream` bodies → skipped with a ONE-TIME `console.warn`.
* The Gemini-quirk only manifests with tool calls in the body, and
* OC streams plain text deltas; the operator should still know.
*
* @param inner The next fetch in the chain (typically the Bearer-injecting
* interceptor from `createOmniRouteFetchInterceptor`).
*/
export function createGeminiSanitizingFetch(inner: typeof fetch): typeof fetch {
return async (input, init) => {
try {
const url =
typeof input === "string"
? input
: input instanceof URL
? input.toString()
: input instanceof Request
? input.url
: "";
// URL gate — match the path substring with prefix tolerance.
const targetsCompletions = url.includes("/chat/completions") || url.includes("/responses");
if (!targetsCompletions) {
return inner(input, init);
}
// Body extraction. Cover the body shapes the AI-SDK + adapter layer
// actually emit; bail to pass-through on anything we can't read
// synchronously without consuming a stream.
let rawBody: string | undefined;
const initBody = init?.body as unknown;
if (typeof initBody === "string") {
rawBody = initBody;
} else if (initBody instanceof URLSearchParams) {
// Form-encoded bodies are never chat-completion JSON; pass-through.
return inner(input, init);
} else if (typeof Buffer !== "undefined" && initBody instanceof Buffer) {
rawBody = initBody.toString("utf8");
} else if (initBody instanceof Uint8Array) {
rawBody = new TextDecoder().decode(initBody);
} else if (initBody instanceof ReadableStream) {
// Streaming body — skip with one-shot warning.
if (!geminiStreamingWarningEmitted) {
geminiStreamingWarningEmitted = true;
console.warn(
"[omniroute-plugin] sanitizeGemini: streaming Request body, skipping schema strip (Gemini may reject)"
);
}
return inner(input, init);
} else if (
initBody !== null &&
initBody !== undefined &&
typeof (initBody as { text?: unknown }).text === "function"
) {
// Blob-like (has .text(): Promise<string>). Streaming was already
// matched above — anything left with a `.text` method we can buffer.
try {
rawBody = await (initBody as { text(): Promise<string> }).text();
} catch {
return inner(input, init);
}
} else if (initBody === undefined && input instanceof Request) {
// Body lives on the Request object itself, not init. Clone before
// reading — consuming the original Request body would make it
// unreadable downstream.
try {
rawBody = await (input as Request).clone().text();
} catch {
return inner(input, init);
}
}
if (rawBody === undefined || rawBody.length === 0) {
return inner(input, init);
}
let payload: unknown;
try {
payload = JSON.parse(rawBody);
} catch {
// Non-JSON body → pass-through, never throw.
return inner(input, init);
}
if (!shouldSanitizeForGemini(payload)) {
return inner(input, init);
}
const cleaned = sanitizeGeminiToolSchemas(payload);
const newBody = JSON.stringify(cleaned);
// Cloning init: we need to replace `body` without mutating the caller's
// init bag. If init was undefined (Request-input path), construct one.
const newInit: RequestInit = { ...(init ?? {}), body: newBody };
return inner(input, newInit);
} catch {
// Total fail-open — never let a sanitiser bug break the request path.
return inner(input, init);
}
};
}
/**
* Test-only hook: reset the module-level streaming-warning latch so each
* test can independently assert the one-shot semantics. Not part of the
* public stability contract — prefixed with `__` per convention to signal
* "do not depend on this from production code".
*/
export function __resetGeminiStreamingWarning(): void {
geminiStreamingWarningEmitted = false;
}
// ────────────────────────────────────────────────────────────────────────────
// Config hook (T-07) — backward-compat shim for OC ≤1.14.48
//
// OC ≤1.14.48 does NOT call `provider.models()` at startup; it reads the
// catalog from the static `provider.<id>` config block instead. OC ≥1.14.49
// calls `provider.models()` dynamically AND merges the dynamic catalog over
// any static block (dynamic wins on collision). To support both, the plugin
// publishes a static block via `config` AND a dynamic one via `provider.models`
// — OC's resolution order picks the right one per OC version. This module
// implements the static-publish half.
//
// Sibling shape source-of-truth: see
// `@omniroute/opencode-provider/src/index.ts` (`createOmniRouteProvider`,
// `OpenCodeProviderEntry`, `OpenCodeModelEntry`). We replicate that shape
// here rather than depending on the sibling package — the plugin must stay
// self-contained (npm-installable on its own, no peer dep on the provider
// builder).
// ────────────────────────────────────────────────────────────────────────────
/**
* Per-model entry shape under `provider.<id>.models[modelId]`. Mirrors
* `OpenCodeModelEntry` exported by `@omniroute/opencode-provider`. Stripped
* down to the fields OC's static catalog reader actually consumes — NOT a
* full ModelV2 (that's the dynamic-hook shape). Optional fields are omitted
* when OmniRoute didn't surface a value, NOT emitted as `undefined` — the
* resulting JSON must be diffable across OmniRoute deployments without
* `undefined` noise.
*/
/** Modalities accepted by OC's static catalog reader (see `@opencode-ai/sdk`). */
export type OmniRouteModalityKind = "text" | "audio" | "image" | "video" | "pdf";
const STATIC_MODALITY_VALUES: ReadonlySet<OmniRouteModalityKind> = new Set([
"text",
"audio",
"image",
"video",
"pdf",
]);
/** Normalise + filter raw modality list to the values OC accepts. Deduped. */
function normaliseModalities(raw: unknown): OmniRouteModalityKind[] {
if (!Array.isArray(raw)) return [];
const out: OmniRouteModalityKind[] = [];
const seen = new Set<string>();
for (const v of raw) {
if (typeof v !== "string") continue;
const lower = v.toLowerCase() as OmniRouteModalityKind;
if (!STATIC_MODALITY_VALUES.has(lower)) continue;
if (seen.has(lower)) continue;
seen.add(lower);
out.push(lower);
}
return out;
}
export interface OmniRouteStaticModelEntry {
/** Owning provider id. SHOULD match the parent `provider.<id>` key so OC's
* static-catalog reader resolves credentials via `providerID` instead of
* parsing the model key on `/`. Optional: OC's schema validator may
* reject the entire provider block when this field is present but the
* model KEY already carries the provider prefix (e.g. `omniroute/MASTER`),
* since the prefix makes the field redundant and the field is not part of
* OC's expected schema. We omit it from entries and rely on the prefix
* on the KEY alone. See PR #4184. */
providerID?: string;
/** Display label rendered in OC's model picker. Defaults to the model id. */
name: string;
/** ISO date the model was released. Surfaces in OC's model card when present. */
release_date?: string;
/** Model accepts image / file attachments. */
attachment?: boolean;
/** Model exposes a reasoning / extended-thinking surface. */
reasoning?: boolean;
/** Model honours the `temperature` parameter. */
temperature?: boolean;
/** Model supports function / tool calling. */
tool_call?: boolean;
/**
* Per-million-token cost. Maps from OmniRoute `/api/pricing` shape:
* `input`/`output` pass through; `cached` → `cache_read`;
* `cache_creation` → `cache_write`. Omitted when no pricing slot resolves.
*/
cost?: {
input: number;
output: number;
cache_read?: number;
cache_write?: number;
};
/**
* Context-window limits. OC's static reader requires both `context` AND
* `output` when `limit` is present, so the field is only emitted when
* BOTH are known.
*/
limit?: {
context: number;
output: number;
};
/**
* Modality lists the model accepts (input) and emits (output). Maps from
* OmniRoute's `input_modalities` / `output_modalities` on `/v1/models`.
* Emitted only when at least one modality is known — without this field
* OC's runtime catalog defaults `input.image: false` even when the model
* card has `attachment: true`, which blocks clipboard image paste in the
* TUI for vision-capable models.
*/
modalities?: {
input: OmniRouteModalityKind[];
output: OmniRouteModalityKind[];
};
}
/**
* Static `provider.<id>` block written to `input.provider` by the config hook.
* Mirrors `OpenCodeProviderEntry` from `@omniroute/opencode-provider`.
*
* - `npm` is always `"@ai-sdk/openai-compatible"` — OmniRoute exposes an
* OpenAI-compatible surface and that's the AI-SDK adapter that speaks it.
* - `options.baseURL` MUST be the fully-qualified `/v1` URL (the AI-SDK
* appends paths like `/chat/completions` directly under it).
* - `options.apiKey` is the bearer token; the fetch interceptor (T-04)
* also injects it on the dynamic path, but the static block needs it
* embedded too so OC ≤1.14.48 can construct the SDK client without
* going through the auth hook.
*/
export interface OmniRouteStaticProviderEntry {
npm: "@ai-sdk/openai-compatible";
name: string;
options: {
baseURL: string;
apiKey: string;
};
models: Record<string, OmniRouteStaticModelEntry>;
}
/**
* Build the static `provider.<id>` block from raw `/v1/models` + `/api/combos`
* responses. Pure function — no I/O, no side effects, no dependency on the
* sibling provider package. Exported so callers and tests can construct the
* block independently of the auth.json + fetch pipeline.
*
* Mapping rules (per the sibling `createOmniRouteProvider` output spec):
*
* - One entry per raw model AND one entry per non-hidden combo.
* - `name` = model id (no separate display name on `/v1/models`).
* - `attachment` = `caps.attachment ?? caps.vision ?? false` — same
* convention as `mapRawModelToModelV2` (T-03).
* - `reasoning` = `caps.reasoning || caps.thinking`. Booleans only — we
* do NOT emit the field when both source flags are absent (keeps the
* stripped shape minimal).
* - `temperature` = `caps.temperature ?? true` — OpenAI-compat surface
* supports temperature by default; only an explicit `false` suppresses.
* - `tool_call` = `caps.tool_calling ?? false`.
* - `limit.context` = raw `context_length` when > 0; omitted otherwise.
* - `limit.input` = raw `max_input_tokens` when present.
* - `limit.output` = raw `max_output_tokens` when present.
*
* For combos: LCD across member raw models (matches `mapComboToModelV2`):
*
* - `attachment`, `reasoning`, `tool_call`, `temperature`: `every` member.
* - `limit.context` = min(member context_lengths).
* - `limit.input` = min(member max_input_tokens) ONLY when every member
* declares one.
* - `limit.output` = min(member max_output_tokens).
* - Empty members → all-false / limits omitted.
*
* Collision: combos win (matches the dynamic provider hook).
*
* @param rawModels Raw `/v1/models` entries (may be empty).
* @param rawCombos Raw `/api/combos` entries (may be empty).
* @param opts Resolved plugin options (we read `displayName` + `providerId`).
* @param baseURL Fully-qualified `/v1` base URL — written verbatim to
* `options.baseURL`. Caller is responsible for `/v1`
* normalisation; we do NOT touch it here.
* @param apiKey Bearer token — written verbatim to `options.apiKey`.
*/
export function buildStaticProviderEntry(
rawModels: OmniRouteRawModelEntry[],
rawCombos: OmniRouteRawCombo[],
opts: ReturnType<typeof resolveOmniRoutePluginOptions>,
baseURL: string,
apiKey: string,
enrichment?: OmniRouteEnrichmentMap,
compressionCombos?: OmniRouteCompressionCombo[],
connections?: OmniRouteProviderConnection[],
logger?: OmniRouteLoggerSink
): OmniRouteStaticProviderEntry {
const log = logger ?? _logger;
const models: Record<string, OmniRouteStaticModelEntry> = {};
// usableOnly filter — compute once when feature enabled AND we have
// connection data to filter against. Soft-fail (empty connections list)
// disables the filter rather than hiding the catalog.
const wantUsableOnly = opts.features?.usableOnly === true;
const usable =
wantUsableOnly && connections && connections.length > 0
? usableProviderAliasSet(connections, enrichment)
: undefined;
// #9473: model allowlist/blocklist — compile once per static-block build.
const visibleFilter = compileModelListFilter(opts.features?.visibleModels);
const hiddenFilter = compileModelListFilter(opts.features?.hiddenModels);
// Provider-tag suffix — default-on, opt-out via `features.providerTag: false`.
// Prepends e.g. `Claude - ` to enriched raw-model names so the picker
// can tell `cc/claude-opus-4-7` (Anthropic) apart from `kr/claude-opus-4-7`
// (Kiro). Combos skip this by design.
const wantProviderTag = opts.features?.providerTag !== false;
// Build a name-set of every non-hidden combo from `/api/combos`. OmniRoute
// pre-mirrors combos into `/v1/models` with the friendly name as the raw
// id (e.g. `claude-primary`, `gemini-pro`), so without dedup the static
// catalog ends up with both `claude-primary` (raw, opaque) AND the same
// combo under `combo/claude-primary` (rich LCD). We suppress the raw twin
// so each combo surfaces exactly once, under the `combo/` namespace.
const comboNames = new Set<string>();
for (const combo of rawCombos) {
if (!combo || combo.isHidden === true) continue;
const name = combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
if (typeof name === "string" && name.length > 0) comboNames.add(name);
}
// Build the canonical→alias reverse map AND the canonical-dedup set
// once per static-block construction. Same shape as the dynamic hook
// so both catalogs publish identical keys (no `claude/X` raw twin
// shadowing the enriched `cc/X` row).
const canonicalToAlias = buildCanonicalToAliasMap(enrichment);
const canonicalDedup = canonicalDedupSet(rawModels, canonicalToAlias);
const aliasIndex = buildAliasIndex(enrichment);
// Raw model entries → stripped per-model shape.
for (const raw of rawModels) {
if (!raw.id) continue;
// Skip the 20 named no-slash entries that shadow combos under the
// `combo/<name>` namespace. We keep `codex-auto-review` and any other
// future no-slash raw entry that doesn't have a matching combo.
if (comboNames.has(raw.id)) continue;
// Skip canonical-named twins when the alias-keyed enriched row exists.
if (canonicalDedup.has(raw.id)) continue;
if (usable && !isUsableRawModelId(raw.id, usable, enrichment)) continue;
// #9473: allowlist/blocklist filter (AND with usableOnly).
if (!passesModelAllowlist(raw.id, visibleFilter, hiddenFilter)) continue;
const caps = raw.capabilities ?? {};
// Enrichment overlay: `/api/pricing/models` carries human display names
// (e.g. "Claude Opus 4.7" for raw id "cc/claude-opus-4-7"). The OC TUI
// model picker reads this `name` straight from the static block on
// OC ≤1.15.5 where the dynamic provider hook never fires. Falls back
// to the raw id when no enrichment entry is found. The alias-fallback
// lookup rescues `<canonical>/<id>` rows whose enrichment indexed only
// under `<alias>/<id>`.
const enrichmentEntry = lookupEnrichment(raw.id, enrichment, canonicalToAlias, raw.owned_by);
const enrichmentName = enrichmentEntry?.name;
let displayName = enrichmentName && enrichmentName.length > 0 ? enrichmentName : raw.id;
// Provider-tag PREFIX — `<label> - <name>` so the picker groups by
// upstream provider when scanning a column of model names. Mirrors
// `applyProviderTag` used in the dynamic hook. Idempotent: skip
// when the name already starts with the prefix. The alias-index
// fallback rescues raw rows like `cohere/rerank-multilingual-v3.0`
// whose specific model id isn't in `/api/pricing/models` but whose
// slot is.
if (wantProviderTag) {
const tagEntry = resolveProviderTagEntry(
raw.id,
enrichmentEntry,
aliasIndex,
canonicalToAlias
);
const label = shortProviderLabel(tagEntry);
if (label) {
const prefix = `${label}${PROVIDER_TAG_SEPARATOR}`;
if (!displayName.startsWith(prefix)) displayName = `${prefix}${displayName}`;
}
}
// OC's static-catalog schema doesn't expect a `providerID` field on
// individual entries — the parent block ID is the provider. Adding
// unknown fields here can cause OC's schema validator to reject the
// entire provider block, hiding ALL models. The provider prefix on the
// model KEY (e.g. `omniroute/claude-opus-4`) is what OC uses to recover
// (providerID, modelID) when the user selects a model.
const entry: OmniRouteStaticModelEntry = { name: displayName };
const attachment = caps.attachment ?? caps.vision;
if (typeof attachment === "boolean") entry.attachment = attachment;
if (typeof caps.reasoning === "boolean" || typeof caps.thinking === "boolean") {
entry.reasoning = Boolean(caps.reasoning || caps.thinking);
}
if (typeof caps.temperature === "boolean") {
entry.temperature = caps.temperature;
}
if (typeof caps.tool_calling === "boolean") {
entry.tool_call = caps.tool_calling;
}
// OC's SDK schema requires BOTH `context` and `output` when `limit` is
// present. We previously emitted `limit.input` too, but the SDK reader
// doesn't accept it — drop it. Only emit `limit` when both required
// values are known.
if (
typeof raw.context_length === "number" &&
raw.context_length > 0 &&
typeof raw.max_output_tokens === "number" &&
raw.max_output_tokens > 0
) {
entry.limit = {
context: raw.context_length,
output: raw.max_output_tokens,
};
}
// Modalities — emit when OmniRoute surfaced any. Without this field
// OC's runtime model defaults `input.image: false` even for vision-
// capable models, blocking clipboard image paste in the TUI.
const inModalities = normaliseModalities(raw.input_modalities);
const outModalities = normaliseModalities(raw.output_modalities);
if (inModalities.length > 0 || outModalities.length > 0) {
entry.modalities = {
input: inModalities.length > 0 ? inModalities : ["text"],
output: outModalities.length > 0 ? outModalities : ["text"],
};
}
// Cost from enrichment pricing (sourced from `/api/pricing`). Map
// OmniRoute field names to OC's static-schema field names.
const pricing = enrichmentEntry?.pricing;
if (pricing && (typeof pricing.input === "number" || typeof pricing.output === "number")) {
const cost: NonNullable<OmniRouteStaticModelEntry["cost"]> = {
input: typeof pricing.input === "number" ? pricing.input : 0,
output: typeof pricing.output === "number" ? pricing.output : 0,
};
if (typeof pricing.cacheRead === "number") cost.cache_read = pricing.cacheRead;
if (typeof pricing.cacheWrite === "number") cost.cache_write = pricing.cacheWrite;
entry.cost = cost;
}
// release_date from /v1/models — surfaces in OC's model card when present.
if (typeof raw.release_date === "string" && raw.release_date.length > 0) {
entry.release_date = raw.release_date;
}
// #9175: OC's `getModel` looks the model up by BARE id — the part after
// the first `/` in the user's request — so a dict key with an embedded
// provider prefix (`<providerId>/<raw-id>`) is unreachable. Keys are the
// raw id verbatim; ids that already contain `/` (e.g. `cc/claude-opus-4-7`)
// keep it because the slash is part of the upstream model id itself.
const key = raw.id;
models[key] = entry;
}
// Combo entries → stripped LCD shape. Each combo is keyed as
// `combo/<friendly-name>` so the OC TUI model picker shows them under a
// distinct namespace (e.g. `combo/claude-primary`) instead of the opaque
// upstream UUID id (e.g. `b4a0211e-e3e1-472d-b252-fb9bf6d1c935`).
const rawModelById = new Map<string, OmniRouteRawModelEntry>();
for (const m of rawModels) {
if (m.id) rawModelById.set(m.id, m);
}
// Resolve the default compression pipeline once — its short signature
// (e.g. `[rtk:standard → caveman:full]`) is appended to every routable
// combo `name` so operators can see what compression a combo applies
// at a glance. Provider hook does the same decoration when feature is
// on. Suffix is suppressed for combos with no resolvable members —
// claiming compression on an unroutable combo would mislead the
// picker.
let compressionSuffix = "";
if (compressionCombos && compressionCombos.length > 0) {
const def = compressionCombos.find((c) => c.isDefault === true);
if (def) {
const sig = formatCompressionPipeline(def.pipeline);
if (sig.length > 0) compressionSuffix = ` ${sig}`;
}
}
// Track combo keys to detect slug collisions across the catalog.
const usedComboKeys = new Set<string>();
// ── Combo LCD across nested combo-refs (T-NN mirror) ─────────────────
// Mirror of the dynamic-catalog fixpoint iteration: combos can nest
// other combos via `kind: "combo-ref"` members (e.g. MASTER-LIGHT
// contains LEGACY, KIRO, Opecode Zen FREE). The nested combo's own
// capabilities and limits are computed in this same loop, so we need
// a fixpoint pass: if a combo-ref points at a combo not yet processed,
// defer this combo and try again after the sibling combos catch up.
// We bound the retries so a circular combo graph can't deadlock the
// picker, and we break early when a pass makes no progress.
const MAX_STATIC_COMBO_PASSES = 8;
const resolvedStaticCombosByName = new Map<string, OmniRouteStaticModelEntry>();
let pendingStatic = rawCombos.filter((combo) => {
if (!combo.id) return false;
if (combo.isHidden === true) return false;
if (usable && !isUsableCombo(combo, usable)) return false;
// #9473: combo allowlist — drop when no member matches visible filter.
if (visibleFilter && !passesComboAllowlist(combo, visibleFilter)) return false;
return true;
});
for (let pass = 0; pass < MAX_STATIC_COMBO_PASSES && pendingStatic.length > 0; pass++) {
const stillPendingStatic: typeof pendingStatic = [];
for (const combo of pendingStatic) {
const memberSteps = Array.isArray(combo.models) ? combo.models : [];
const memberEntries: OmniRouteRawModelEntry[] = [];
let deferredThisPass = false;
for (const step of memberSteps) {
const stepKind = (step as unknown as { kind?: unknown }).kind;
if (stepKind === "combo-ref") {
const comboName = (step as unknown as { comboName?: unknown }).comboName;
if (typeof comboName !== "string" || comboName.length === 0) {
continue;
}
const nestedEntry = resolvedStaticCombosByName.get(comboName);
if (!nestedEntry) {
deferredThisPass = true;
break;
}
// Synthesize a raw-model-shaped member entry carrying the
// nested combo's pre-computed context + capabilities +
// modalities. Mirrors the dynamic path so the static catalog
// stays in lockstep with the dynamic one.
const inputModalities = (nestedEntry.modalities?.input ?? ["text"]) as string[];
const outputModalities = (nestedEntry.modalities?.output ?? ["text"]) as string[];
memberEntries.push({
id: `combo-ref:${comboName}`,
context_length: nestedEntry.limit?.context ?? 0,
max_output_tokens: nestedEntry.limit?.output ?? 0,
max_input_tokens: 0,
owned_by: "combo",
input_modalities: inputModalities,
output_modalities: outputModalities,
capabilities: {
temperature: nestedEntry.temperature,
reasoning: nestedEntry.reasoning,
thinking: nestedEntry.reasoning,
attachment: nestedEntry.attachment,
tool_calling: nestedEntry.tool_call,
},
} as unknown as OmniRouteRawModelEntry);
continue;
}
const modelId = (step as unknown as { model?: unknown }).model;
if (typeof modelId !== "string" || modelId.length === 0) continue;
const member = rawModelById.get(modelId);
if (member) memberEntries.push(member);
}
if (deferredThisPass) {
stillPendingStatic.push(combo);
continue;
}
const hasMembers = memberEntries.length > 0;
const friendlyName =
combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
const displayName =
hasMembers && compressionSuffix ? `${friendlyName} ${compressionSuffix}` : friendlyName;
// See the raw-model entry comment above — `providerID` on entries is
// not part of OC's static-catalog schema; the parent block ID is the
// provider and the KEY prefix (`omniroute/<slug>`) is what OC parses.
const entry: OmniRouteStaticModelEntry = { name: displayName };
if (hasMembers) {
// LCD across capabilities — every member must support for the combo
// to support. Mirrors mapComboToModelV2.
entry.attachment = memberEntries.every((m) =>
Boolean(m.capabilities?.attachment ?? m.capabilities?.vision ?? false)
);
entry.reasoning = memberEntries.every((m) =>
Boolean(m.capabilities?.reasoning || m.capabilities?.thinking)
);
entry.temperature = memberEntries.every(
(m) => (m.capabilities?.temperature ?? true) !== false
);
entry.tool_call = memberEntries.every((m) =>
Boolean(m.capabilities?.tool_calling ?? false)
);
// LCD across limits — min over declared values. OC's SDK static schema
// accepts only `context` + `output` on `limit`, so we drop the legacy
// `input` emission. Emit only when BOTH context AND output are known
// across at least one member (mirrors the required-field constraint).
const contextValues = memberEntries
.map((m) => m.context_length)
.filter((v): v is number => typeof v === "number" && v > 0);
const outputValues = memberEntries
.map((m) => m.max_output_tokens)
.filter((v): v is number => typeof v === "number" && v > 0);
// Prefer the server-computed aggregate (accounts for explicit
// context_length overrides and members outside memberEntries, e.g.
// not yet resolved in /v1/models) over the raw Math.min(member)
// lower bound. Mirrors mapComboToModelV2's limit.context logic
// (#13000) so the static catalog and the dynamic hook agree.
const preferredContext =
typeof combo.computed_context_length === "number" && combo.computed_context_length > 0
? combo.computed_context_length
: contextValues.length > 0
? Math.min(...contextValues)
: undefined;
if (preferredContext !== undefined && outputValues.length > 0) {
entry.limit = {
context: preferredContext,
output: Math.min(...outputValues),
};
}
// LCD across modalities — combo accepts modality M iff every member
// accepts M. Same intersection rule as runtime capabilities.
const inSets = memberEntries.map((m) => new Set(normaliseModalities(m.input_modalities)));
const outSets = memberEntries.map((m) => new Set(normaliseModalities(m.output_modalities)));
const intersect = (sets: Set<OmniRouteModalityKind>[]): OmniRouteModalityKind[] => {
if (sets.length === 0) return [];
const [first, ...rest] = sets;
const out: OmniRouteModalityKind[] = [];
for (const v of first) {
if (rest.every((s) => s.has(v))) out.push(v);
}
return out;
};
const inModalities = intersect(inSets);
const outModalities = intersect(outSets);
if (inModalities.length > 0 || outModalities.length > 0) {
entry.modalities = {
input: inModalities.length > 0 ? inModalities : ["text"],
output: outModalities.length > 0 ? outModalities : ["text"],
};
}
} else {
// Empty members → safety posture: all caps false. Caller's OC picker
// will grey out an unroutable combo rather than promise capabilities
// we can't honour.
entry.attachment = false;
entry.reasoning = false;
entry.temperature = false;
entry.tool_call = false;
}
// Key under bare slug (e.g. `claude-primary`) — no `combo/` prefix
// because OpenCode parses model IDs on `/` and would treat
// `combo/MASTER` as provider=`combo`. Slug collisions across
// combos are disambiguated with a short UUID-prefix suffix; see
// `buildComboKey` for the policy.
// #6859: server-facing key — NOT the OC-gate-prefixed `opts.providerId`.
// OC dispatches the static-catalog `models` map key VERBATIM as the
// `model` field of the outbound `@ai-sdk/openai-compatible` request
// (only the top-level `provider["<id>"]` segment is stripped for
// routing) — so a bare-slug combo key prefixed with the OC-gated
// `opts.providerId` reaches OmniRoute's server doubled
// (`opencode-omniroute/opencode-omniroute/<slug>`), and `parseModel()`
// resolves credentials for the nonexistent provider `opencode-omniroute`
// instead of `omniroute`. See #7976.
const key = buildComboKey(combo, usedComboKeys, opts.omnirouteProviderId).split("/").pop()!;
models[key] = entry;
// Make this combo's resolved entry available to parent combos
// that reference it via combo-ref. Use the friendly name since
// that's the lookup key on the parent side.
resolvedStaticCombosByName.set(friendlyName, entry);
}
if (stillPendingStatic.length === pendingStatic.length) {
// No progress in this pass — remaining combos have unresolvable
// refs (missing nested combo, circular graph, or nested combo
// with no members). Break early to avoid wasting the pass budget.
break;
}
pendingStatic = stillPendingStatic;
}
if (pendingStatic.length > 0) {
log.warn(
`${pendingStatic.length} combo(s) in the static catalog could not resolve all nested combo-refs after ${MAX_STATIC_COMBO_PASSES} passes; they will be omitted.`
);
}
return {
npm: "@ai-sdk/openai-compatible",
name: opts.displayName,
options: { baseURL, apiKey },
models,
};
}
/**
* Shape we expect inside `auth.json`. The file is keyed by providerId, with
* each entry being a flavor-tagged credential. Today only the `api` flavor
* is consumed by this plugin (OAuth + WellKnown flavors are passed through
* but never decoded into a static block).
*/
interface AuthJsonApiEntry {
type: "api";
key: string;
baseURL?: string;
}
type AuthJsonShape = Record<string, AuthJsonApiEntry | { type?: string; [k: string]: unknown }>;
/**
* Read & parse `auth.json` from OC's data dir. The path resolution mirrors
* OC core's:
*
* `${OPENCODE_DATA_DIR ?? path.join(os.homedir(), ".local/share/opencode")}/auth.json`
*
* Returns `undefined` when the file is missing (most-common case on a fresh
* install — silent no-op). Returns `null` when the file exists but doesn't
* parse as JSON (logs ONE warn so the operator sees the corruption).
*
* Exported as a dependency-injectable function on `createOmniRouteConfigHook`
* so tests can stub it without monkey-patching `node:fs/promises`.
*/
// ─────────────────────────────────────────────────────────────────────────
// Disk-cache fallback. Persists the last successful raw-fetch snapshot to
// `${OPENCODE_DATA_DIR ?? ~/.local/share/opencode}/plugins/omniroute-<providerId>.json`.
// When `/v1/models` is unreachable (e.g. IP whitelist drop, offline laptop)
// AND the in-memory cache is cold, the config hook reads from disk so the
// last-known catalog still surfaces in OC's model picker. Feature-flagged:
// `features.diskCache !== false` (default-on).
// ─────────────────────────────────────────────────────────────────────────
/** Disk snapshot envelope. Versioned for forward-compat. */
interface OmniRouteDiskSnapshot {
v: 2;
/** Opaque identity for normalized baseURL + both effective credentials. */
identityFingerprint: string;
rawModels: OmniRouteRawModelEntry[];
rawCombos: OmniRouteRawCombo[];
/** Serialised as array-of-pairs (Map is not JSON-friendly). */
rawEnrichment: Array<[string, OmniRouteEnrichmentEntry]>;
rawCompressionCombos: OmniRouteCompressionCombo[];
rawConnections: OmniRouteProviderConnection[];
/** When the snapshot was written (epoch ms). */
writtenAt: number;
}
/** Resolve the disk-snapshot path for a given providerId. */
export function diskSnapshotPath(providerId: string): string {
const dir = process.env.OPENCODE_DATA_DIR ?? path.join(os.homedir(), ".local/share/opencode");
return path.join(dir, "plugins", `omniroute-${providerId}.json`);
}
/** Best-effort delete of the disk snapshot for a provider (force-sync). */
export async function clearDiskSnapshot(providerId: string): Promise<boolean> {
const file = diskSnapshotPath(providerId);
try {
await unlink(file);
return true;
} catch (err) {
const code = (err as NodeJS.ErrnoException | undefined)?.code;
if (code === "ENOENT") return false;
return false;
}
}
export type OmniRouteDiskSnapshotWriter = (
providerId: string,
entry: Omit<OmniRouteFetchCacheEntry, "expiresAt">,
identityFingerprint: string
) => Promise<void>;
export type OmniRouteDiskSnapshotReader = (
providerId: string,
identityFingerprint: string
) => Promise<(Omit<OmniRouteFetchCacheEntry, "expiresAt"> & { writtenAt?: number }) | undefined>;
/**
* Bind a snapshot to the endpoint and effective credential tuple without
* persisting any raw token. This opaque value is only stored and compared;
* it is never logged or included in generated provider configuration.
*/
function diskSnapshotIdentityFingerprint(
baseURL: string,
apiKey: string,
managementReadToken: string
): string {
let normalizedBaseURL: string;
try {
const parsed = new URL(baseURL);
parsed.hash = "";
parsed.pathname = trimTrailingSlashes(parsed.pathname) || "/";
normalizedBaseURL = parsed.toString();
} catch {
normalizedBaseURL = trimTrailingSlashes(baseURL);
}
return createHash("sha256")
.update(JSON.stringify([normalizedBaseURL, apiKey, managementReadToken]))
.digest("hex");
}
/** Best-effort disk write. Soft-fails on any I/O error (no exception thrown). */
export const defaultDiskSnapshotWriter: OmniRouteDiskSnapshotWriter = async (
providerId,
entry,
identityFingerprint
) => {
try {
const file = diskSnapshotPath(providerId);
// Restrict perms to the owner: the snapshot lives alongside auth.json
// (0o600) and embeds provider topology + masked connection records.
await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
const snapshot: OmniRouteDiskSnapshot = {
v: 2,
identityFingerprint,
rawModels: entry.rawModels,
rawCombos: entry.rawCombos,
rawEnrichment: Array.from(entry.rawEnrichment.entries()),
rawCompressionCombos: entry.rawCompressionCombos,
rawConnections: entry.rawConnections,
writtenAt: Date.now(),
};
await writeFile(file, JSON.stringify(snapshot), {
encoding: "utf8",
mode: 0o600,
});
} catch {
// Soft-fail; caller already has the in-memory cache.
}
};
/** Best-effort disk read. Returns `undefined` when missing/corrupt/unreadable. */
export const defaultDiskSnapshotReader: OmniRouteDiskSnapshotReader = async (
providerId,
identityFingerprint
) => {
try {
const file = diskSnapshotPath(providerId);
const body = await readFile(file, "utf8");
const parsed = JSON.parse(body) as Partial<OmniRouteDiskSnapshot>;
if (
!parsed ||
parsed.v !== 2 ||
typeof parsed.identityFingerprint !== "string" ||
parsed.identityFingerprint !== identityFingerprint
) {
return undefined;
}
return {
rawModels: Array.isArray(parsed.rawModels) ? parsed.rawModels : [],
rawCombos: Array.isArray(parsed.rawCombos) ? parsed.rawCombos : [],
rawEnrichment: new Map(Array.isArray(parsed.rawEnrichment) ? parsed.rawEnrichment : []),
rawCompressionCombos: Array.isArray(parsed.rawCompressionCombos)
? parsed.rawCompressionCombos
: [],
rawConnections: Array.isArray(parsed.rawConnections) ? parsed.rawConnections : [],
writtenAt: typeof parsed.writtenAt === "number" ? parsed.writtenAt : undefined,
};
} catch {
return undefined;
}
};
/** No-op disk-cache pair — used by tests to avoid filesystem side effects.
* Also used as the default in createOmniRouteConfigHook so that tests
* that don't pass a diskSnapshotReader don't read real snapshot files
* from the user's ~/.local/share/opencode/plugins/ directory.
* The OmniRoutePlugin function passes the real defaultDiskSnapshotReader
* explicitly. */
export const noopDiskSnapshotReader: OmniRouteDiskSnapshotReader = async () => undefined;
export const noopDiskSnapshotWriter: OmniRouteDiskSnapshotWriter = async () => {};
/**
* In-flight refresh guard: prevents concurrent refreshes for the same
* cacheKey. When a warm snapshot is served, the refresh runs detached; if
* a second hook invocation arrives before the refresh completes, it should
* piggyback on the in-flight promise rather than starting a second one.
* Cleared on settle so it doesn't leak.
*/
const _inflightRefresh: Map<string, Promise<void>> = new Map();
/** Reset the in-flight refresh guard (for test isolation). */
export function _resetInflightRefresh(): void {
_inflightRefresh.clear();
}
// ────────────────────────────────────────────────────────────────────────────
// Debug logging (features.debugLog)
// ────────────────────────────────────────────────────────────────────────────
/**
* One captured request/response pair written to the debug JSONL log.
* Schema documented in the schema-aware `DebugLogEntry` interface below.
*/
export interface DebugLogEntry {
reqId: string;
providerId: string;
ts: number;
url: string;
method: string;
reqHeaders: Record<string, string>;
reqBody: unknown;
resStatus: number | null;
resHeaders: Record<string, string>;
resBody: unknown;
durationMs: number | null;
error?: string;
}
function debugLogDir(): string {
return join(
process.env.OPENCODE_DATA_DIR ?? join(homedir(), ".local", "share", "opencode"),
"plugins"
);
}
function debugLogPath(providerId: string): string {
return join(debugLogDir(), `omniroute-debug-${providerId}.jsonl`);
}
function debugStatePath(providerId: string): string {
return join(debugLogDir(), `omniroute-debug-${providerId}.state.json`);
}
export function debugLogEnabled(providerId: string): boolean {
try {
const p = debugStatePath(providerId);
if (!existsSync(p)) return false;
const s = JSON.parse(readFileSync(p, "utf8")) as { enabled?: boolean };
return s.enabled === true;
} catch {
return false;
}
}
export function debugLogSetEnabled(providerId: string, enabled: boolean): void {
try {
const dir = debugLogDir();
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
writeFileSync(debugStatePath(providerId), JSON.stringify({ enabled, ts: Date.now() }, null, 2));
} catch (err) {
// best-effort; never break the auth flow
console.warn(`[omniroute-plugin] debugLogSetEnabled failed: ${(err as Error).message}`);
}
}
/**
* Header names whose values must never be written to the debug JSONL on disk.
*
* Audit #15159 O-05: `createDebugLoggingFetch` copies every request and response
* header into the captured entry, and the entry was serialized to disk verbatim —
* so enabling `features.debugLog` persisted live bearer tokens (and session
* cookies) in plaintext, contradicting the AES-256-GCM-at-rest guarantee. The
* feature defaults to off, which limits exposure but does not remove it.
*
* Matched list: the explicit credential headers plus anything whose name looks
* like a credential (`token` / `secret` / `key`). The broad tail is deliberate —
* a debug log is the wrong place to be clever about which credential slipped
* through, and a false positive only costs one redacted header in a log whose
* purpose is troubleshooting. Non-credential headers (`content-type`, `accept`,
* …) are preserved so the log stays useful.
*
* Case-insensitive: `fetch` lowercases header names, but `debugLogAppend` is
* exported and entries can also be appended directly with original casing.
*/
const DEBUG_LOG_REDACTED = "[REDACTED]";
const DEBUG_LOG_SENSITIVE_HEADER =
/^(?:authorization|proxy-authorization|cookie|set-cookie|x-api-key)$|token|secret|key/i;
/**
* Credential shapes scrubbed out of free-form text before it is persisted —
* the `error` field, which carries an untrusted upstream message that routinely
* echoes the rejected credential back ("invalid Authorization: Bearer sk-…").
*
* Covers the three shapes that actually occur: an auth-scheme value, a labeled
* assignment, and credentials embedded in a URL's userinfo. Deliberately NOT a
* blanket "any long random string" rule: the debug log's purpose is reading
* error text, and an over-broad matcher would redact the message away while
* still missing secret shapes it did not anticipate.
*/
const DEBUG_LOG_AUTH_SCHEME = /\b(bearer|basic)\s+[^\s"',;}]+/gi;
const DEBUG_LOG_LABELED_SECRET =
/\b((?:x-)?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|auth[_-]?token|secret|password|passwd|token|key))(\s*[:=]\s*)("?)[^\s"',;}]+\3/gi;
const DEBUG_LOG_URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/)[^/\s:@]+:[^/\s@]+@/gi;
/** Scrub credential-shaped substrings out of a free-form string (e.g. an error). */
function redactDebugText(value: string): string {
return value
.replace(DEBUG_LOG_URL_USERINFO, `$1${DEBUG_LOG_REDACTED}@`)
.replace(DEBUG_LOG_AUTH_SCHEME, `$1 ${DEBUG_LOG_REDACTED}`)
.replace(DEBUG_LOG_LABELED_SECRET, `$1$2${DEBUG_LOG_REDACTED}`);
}
/**
* Copy a header map with every sensitive value replaced by `[REDACTED]`.
* Defensive about a missing map: this runs on the logging path, where throwing
* would silently drop the entry instead of writing it.
*/
function redactDebugHeaders(headers: Record<string, string> | undefined): Record<string, string> {
const out: Record<string, string> = {};
for (const [name, value] of Object.entries(headers ?? {})) {
out[name] = DEBUG_LOG_SENSITIVE_HEADER.test(name) ? DEBUG_LOG_REDACTED : value;
}
return out;
}
export function debugLogAppend(entry: DebugLogEntry): void {
try {
const dir = debugLogDir();
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
// Redact here rather than at the call sites: this is the only choke point
// every captured entry passes through, so no future caller can reintroduce
// the leak by forgetting to sanitize its own headers.
const safe: DebugLogEntry = {
...entry,
reqHeaders: redactDebugHeaders(entry.reqHeaders),
resHeaders: redactDebugHeaders(entry.resHeaders),
...(typeof entry.error === "string" ? { error: redactDebugText(entry.error) } : {}),
};
appendFileSync(debugLogPath(entry.providerId), JSON.stringify(safe) + "\n", "utf8");
} catch (err) {
console.warn(`[omniroute-plugin] debugLogAppend failed: ${(err as Error).message}`);
}
}
export function debugLogRead(providerId: string, limit = 20): DebugLogEntry[] {
try {
const p = debugLogPath(providerId);
if (!existsSync(p)) return [];
const lines = readFileSync(p, "utf8").trim().split("\n").filter(Boolean);
return lines
.slice(-limit)
.map((line) => {
try {
return JSON.parse(line) as DebugLogEntry;
} catch {
return null;
}
})
.filter((e): e is DebugLogEntry => e !== null);
} catch {
return [];
}
}
export function debugLogGetById(providerId: string, reqId: string): DebugLogEntry | null {
try {
const p = debugLogPath(providerId);
if (!existsSync(p)) return null;
const lines = readFileSync(p, "utf8").trim().split("\n").filter(Boolean);
for (let i = lines.length - 1; i >= 0; i--) {
try {
const e = JSON.parse(lines[i]) as DebugLogEntry;
if (e.reqId === reqId) return e;
} catch {
// skip malformed
}
}
return null;
} catch {
return null;
}
}
export function debugLogClear(providerId: string): void {
try {
const p = debugLogPath(providerId);
if (existsSync(p)) writeFileSync(p, "", "utf8");
} catch (err) {
console.warn(`[omniroute-plugin] debugLogClear failed: ${(err as Error).message}`);
}
}
/**
* Wrap a fetch function to capture request/response pairs into the debug
* JSONL log. Honours the `featureDefault` opt-in flag and the on-disk
* runtime toggle (`debugLogEnabled`).
*/
export function createDebugLoggingFetch(
inner: typeof fetch,
providerId: string,
featureDefault: boolean
): typeof fetch {
return async (input, init) => {
const active = featureDefault || debugLogEnabled(providerId);
if (!active) return inner(input, init);
const reqId = randomUUID();
const url =
typeof input === "string"
? input
: input instanceof URL
? input.toString()
: input instanceof Request
? input.url
: String(input);
const method = (
init?.method ?? (typeof input === "string" ? "GET" : ((input as Request).method ?? "GET"))
).toUpperCase();
const reqHeaders: Record<string, string> = {};
if (input instanceof Request) {
input.headers.forEach((v, k) => (reqHeaders[k] = v));
}
if (init?.headers) {
const h = init.headers;
if (h instanceof Headers) h.forEach((v, k) => (reqHeaders[k] = v));
else if (Array.isArray(h)) for (const [k, v] of h) reqHeaders[k] = v;
else Object.assign(reqHeaders, h);
}
let reqBody: unknown = undefined;
if (init?.body) {
if (typeof init.body === "string") {
try {
reqBody = JSON.parse(init.body);
} catch {
reqBody = init.body.slice(0, 4096);
}
} else {
reqBody = "[non-string body]";
}
} else if (input instanceof Request) {
try {
const clonedReq = input.clone();
const text = await clonedReq.text();
try {
reqBody = JSON.parse(text);
} catch {
reqBody = text.slice(0, 4096);
}
} catch {
reqBody = "[body unreadable]";
}
}
const t0 = Date.now();
try {
const res = await inner(input, init);
const durationMs = Date.now() - t0;
const resHeaders: Record<string, string> = {};
res.headers.forEach((v, k) => (resHeaders[k] = v));
let resBody: unknown = undefined;
try {
const clone = res.clone();
const ct = clone.headers.get("content-type") ?? "";
if (ct.includes("application/json")) {
resBody = await clone.json();
} else if (ct.includes("text/event-stream")) {
resBody = "[stream]";
} else if (ct.includes("text/")) {
const txt = await clone.text();
resBody = txt.length > 4096 ? txt.slice(0, 4096) + "...[truncated]" : txt;
} else {
resBody = `[${ct || "unknown"} body, status ${res.status}]`;
}
} catch {
resBody = "[body unparseable]";
}
debugLogAppend({
reqId,
providerId,
ts: t0,
url,
method,
reqHeaders,
reqBody,
resStatus: res.status,
resHeaders,
resBody,
durationMs,
});
return res;
} catch (err) {
const durationMs = Date.now() - t0;
debugLogAppend({
reqId,
providerId,
ts: t0,
url,
method,
reqHeaders,
reqBody,
resStatus: null,
resHeaders: {},
resBody: undefined,
durationMs,
error: (err as Error).message,
});
throw err;
}
};
}
export type OmniRouteReadAuthJson = () => Promise<AuthJsonShape | undefined | null>;
export const defaultReadAuthJson: OmniRouteReadAuthJson = async () => {
const dir = process.env.OPENCODE_DATA_DIR ?? path.join(os.homedir(), ".local/share/opencode");
const file = path.join(dir, "auth.json");
let body: string;
try {
body = await readFile(file, "utf8");
} catch {
// File missing or unreadable — silent no-op. This is the expected path
// on a fresh install BEFORE `/connect` has been run.
return undefined;
}
try {
const parsed = JSON.parse(body) as unknown;
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
return parsed as AuthJsonShape;
}
return null;
} catch {
return null;
}
};
/**
* Build the config-hook portion of the plugin for a given options bag.
* Exported standalone so the contract is unit-testable without faking the
* full PluginInput / Hooks surface, and so multi-instance setups can each
* own their own (auth.json reader, fetch cache, fetcher) trio.
*
* Behavioural contract:
* - Runs BEFORE `auth.loader` in the OC startup sequence (per the
* @opencode-ai/plugin contract). `getAuth()` is NOT available here,
* so we read `auth.json` directly via the injected reader.
* - No-op when:
* (a) `auth.json` is missing / unreadable (fresh install before
* `/connect`),
* (b) `auth.json[providerId]` is missing or not type-api,
* (c) `apiKey` is empty after extraction,
* (d) `baseURL` is unresolvable (neither opts.baseURL nor
* `auth.json[providerId].baseURL`),
* (e) `input.provider[providerId]` is ALREADY set (operator override
* wins — we never clobber manually-curated catalogs).
* Each no-op path emits ONE debug-level breadcrumb through the leveled logger
* so the operator can diagnose without log spam. Malformed `auth.json`
* warns once and continues as if the file were missing.
* - Fail-open on fetcher errors: a `/v1/models` failure → still publish
* a stub `{models: {}}` provider block (so OC has a complete-shape
* entry to render). A `/api/combos` failure → publish models-only.
* Both paths emit ONE error-level logger message.
* - When the provider hook (T-03/T-05) has ALREADY populated the shared
* cache for this (baseURL, apiKey) tuple, we reuse the raw payloads
* directly — no second fetch. (And vice-versa: the config hook fires
* first on OC ≥1.14.49 cold start, populating the cache for the
* provider hook moments later.)
* - DUAL-PUBLISH SAFE: on OC ≥1.14.49 BOTH this static block and the
* dynamic `provider.models()` result will land in OC's catalog
* reducer. The dynamic block wins by OC's own merge rule — see
* OpenCode core's provider resolution order — so emitting both is a
* correctness-positive: ≤1.14.48 reads static, ≥1.14.49 prefers
* dynamic but the static one keeps things responsive during the
* ~50ms window before the dynamic fetch resolves.
*
* @param opts Plugin options (validated, resolved with defaults).
* @param deps Dependency injection.
* - `readAuthJson` — replaces `defaultReadAuthJson` (test stub).
* - `fetcher` — replaces `defaultOmniRouteModelsFetcher`.
* - `combosFetcher` — replaces `defaultOmniRouteCombosFetcher`.
* - `now` — clock for cache TTL (default `Date.now`).
* - `cache` — shared fetch-result cache (see
* `OmniRouteFetchCache`). Pass the same Map the
* provider hook owns to dedupe round-trips.
* - `logger` — injected sink for breadcrumb capture in tests.
* Defaults to the plugin's leveled logger.
*/
export function createOmniRouteConfigHook(
opts?: OmniRoutePluginOptions,
deps: {
readAuthJson?: OmniRouteReadAuthJson;
fetcher?: OmniRouteModelsFetcher;
combosFetcher?: OmniRouteCombosFetcher;
enrichmentFetcher?: OmniRouteEnrichmentFetcher;
compressionMetaFetcher?: OmniRouteCompressionMetaFetcher;
providersFetcher?: OmniRouteProvidersFetcher;
diskSnapshotReader?: OmniRouteDiskSnapshotReader;
diskSnapshotWriter?: OmniRouteDiskSnapshotWriter;
now?: () => number;
cache?: OmniRouteFetchCache;
logger?: {
error?: (message: string, ...args: unknown[]) => void;
warn: (message: string, ...args: unknown[]) => void;
debug?: (message: string, ...args: unknown[]) => void;
};
} = {}
): (input: Config) => Promise<void> {
const resolved = resolveOmniRoutePluginOptions(opts);
const readAuthJson = deps.readAuthJson ?? defaultReadAuthJson;
const fetcher = deps.fetcher ?? defaultOmniRouteModelsFetcher;
const combosFetcher = deps.combosFetcher ?? defaultOmniRouteCombosFetcher;
const enrichmentFetcher = deps.enrichmentFetcher ?? defaultOmniRouteEnrichmentFetcher;
const compressionMetaFetcher =
deps.compressionMetaFetcher ?? defaultOmniRouteCompressionMetaFetcher;
const providersFetcher = deps.providersFetcher ?? defaultOmniRouteProvidersFetcher;
const diskSnapshotReader = deps.diskSnapshotReader ?? noopDiskSnapshotReader;
const diskSnapshotWriter = deps.diskSnapshotWriter ?? noopDiskSnapshotWriter;
const now = deps.now ?? Date.now;
const cache: OmniRouteFetchCache = deps.cache ?? new Map();
const logger = deps.logger ?? _logger;
const logAt = (level: "error" | "warn" | "debug", message: string): void => {
const sink = logger[level] ?? logger.warn;
sink.call(logger, message);
};
const features = resolved.features ?? {};
const wantCombos = features.combos !== false;
const wantEnrichment = features.enrichment !== false;
const wantCompressionMeta = features.compressionMetadata === true;
const wantUsableOnly = features.usableOnly === true;
const wantDiskCache = features.diskCache !== false;
const wantProviderTag = features.providerTag !== false;
return async (input: Config) => {
// (e) operator override — `input.provider[providerId]` already set →
// leave it alone. Manually curated catalogs ALWAYS win over the plugin's
// generated block. Detect-and-respect before any I/O.
const existingProviders = (input as { provider?: Record<string, unknown> }).provider;
if (existingProviders && existingProviders[resolved.providerId] !== undefined) {
logAt("debug", `config shim skipped: provider.${resolved.providerId} already set by user`);
return;
}
// Read auth.json. `undefined` = missing file (silent path), `null` =
// malformed JSON (warn once and treat as missing).
let authJson: AuthJsonShape | undefined | null;
try {
authJson = await readAuthJson();
} catch {
// Reader threw — be conservative and treat like a missing file.
authJson = undefined;
}
if (authJson === null) {
logAt("warn", "config shim: auth.json failed to parse; treating as missing");
authJson = undefined;
}
// Try both prefixed (e.g. opencode-omniroute) and unprefixed (e.g. omniroute)
// keys so a user who ran `/connect omniroute` before the auto-prefix fix
// does not need to re-auth. Also handles dual-key for auth.json entries
// written by a newer OC dispatcher with the prefixed key.
const bareKey = resolved.providerId.startsWith("opencode-")
? resolved.providerId.slice("opencode-".length)
: resolved.providerId;
const lookupKeys = [resolved.providerId];
if (bareKey !== resolved.providerId) lookupKeys.push(bareKey);
let entry;
for (const k of lookupKeys) {
const e = authJson?.[k];
if (e?.type === "api" && typeof e.key === "string" && e.key.length > 0) {
entry = e;
break;
}
}
const apiKey = entry?.type === "api" && typeof entry.key === "string" ? entry.key : "";
if (!apiKey) {
// (c) no apiKey — silent no-op (with debug breadcrumb). The operator
// hasn't run `/connect <providerId>` yet, OR the stored credential
// isn't api-flavored. OC will handle the `/connect` flow at runtime.
logAt("debug", `config shim skipped: no apiKey for providerId=${resolved.providerId}`);
return;
}
// Management-plane catalog reads may use a narrower read-only token.
// Backward compatibility: when unset, retain the historical apiKey use.
const managementReadToken = resolved.managementReadToken ?? apiKey;
// baseURL resolution: opts.baseURL wins, then auth.json's stored baseURL.
// No silent localhost default — a misconfigured plugin should surface a
// breadcrumb and skip, not phantom requests.
const storedBaseURL = entry && typeof entry.baseURL === "string" ? entry.baseURL : undefined;
const baseURL = resolved.baseURL ?? storedBaseURL ?? "";
if (!baseURL) {
logAt("debug", `config shim skipped: no baseURL for providerId=${resolved.providerId}`);
return;
}
// Try the shared cache first. On OC ≥1.14.49 the provider hook may have
// populated it moments earlier; on OC ≤1.14.48 only this hook runs but
// the cache still works (single producer + consumer through one Map).
const cacheKey = modelsCacheKey(baseURL, `${apiKey}\0${managementReadToken}`);
const snapshotFingerprint = diskSnapshotIdentityFingerprint(
baseURL,
apiKey,
managementReadToken
);
const t = now();
const cached = cache.get(cacheKey);
let rawModels: OmniRouteRawModelEntry[] = [];
let rawCombos: OmniRouteRawCombo[] = [];
let rawEnrichment: OmniRouteEnrichmentMap = new Map();
let rawCompressionCombos: OmniRouteCompressionCombo[] = [];
let rawConnections: OmniRouteProviderConnection[] = [];
if (cached && cached.expiresAt > t) {
rawModels = cached.rawModels;
rawCombos = cached.rawCombos;
rawEnrichment = cached.rawEnrichment;
rawCompressionCombos = cached.rawCompressionCombos;
rawConnections = cached.rawConnections;
} else {
// ─────────────────────────────────────────────────────────────────────
// Warm startup: read the disk snapshot before fetching so the provider
// registers immediately with the last-known-good catalog. The live
// fetch then refreshes in the background (detached) and updates the
// cache + snapshot. Gated by features.diskCache (default-on).
// ─────────────────────────────────────────────────────────────────────
let warmSnapshot: Omit<OmniRouteFetchCacheEntry, "expiresAt"> | undefined;
if (wantDiskCache) {
const snapshotResult = await diskSnapshotReader(resolved.providerId, snapshotFingerprint);
if (snapshotResult && snapshotResult.rawModels.length > 0) {
warmSnapshot = snapshotResult;
// Log snapshot age (accept any age — instant beats empty).
const age = (snapshotResult as { writtenAt?: number }).writtenAt;
const ageLabel =
typeof age === "number" ? `${Math.round((Date.now() - age) / 3_600_000)}h` : "unknown";
logAt(
"warn",
`config shim: warm startup from disk snapshot (${snapshotResult.rawModels.length} models, age ${ageLabel})`
);
}
}
// ─────────────────────────────────────────────────────────────────────
// Parallel refresh: all five fetchers run concurrently via
// Promise.allSettled. Each wrapper never rejects (catches internally)
// so partial failure is tolerated — same soft-fail semantics as the
// old sequential chain, but ~5x faster.
// ─────────────────────────────────────────────────────────────────────
const doRefresh = async (): Promise<void> => {
let modelsFetchThrew = false;
let localRawModels: OmniRouteRawModelEntry[] = [];
let localRawCombos: OmniRouteRawCombo[] = [];
let localRawEnrichment: OmniRouteEnrichmentMap = new Map();
let localRawCompressionCombos: OmniRouteCompressionCombo[] = [];
let localRawConnections: OmniRouteProviderConnection[] = [];
// Each wrapper keeps the existing try/catch, default value, and
// exact warn message so per-endpoint fallbacks are preserved.
const doModels = async (): Promise<void> => {
try {
localRawModels = await fetcher(baseURL, apiKey, 30_000);
} catch (err) {
logAt(
"error",
`config shim: /v1/models fetch failed; publishing stub provider entry: ${err instanceof Error ? err.message : String(err)}`
);
localRawModels = [];
modelsFetchThrew = true;
}
};
const doCombos = async (): Promise<void> => {
if (!wantCombos) return;
try {
localRawCombos = await combosFetcher(baseURL, managementReadToken, 10_000);
} catch (err) {
logAt(
"error",
`config shim: /api/combos fetch failed; publishing models-only static catalog: ${err instanceof Error ? err.message : String(err)}`
);
}
};
const doEnrichment = async (): Promise<void> => {
if (!wantEnrichment) return;
try {
localRawEnrichment = await enrichmentFetcher(baseURL, managementReadToken, 10_000);
} catch (err) {
logAt(
"error",
`config shim: /api/pricing/models fetch failed; publishing raw-id static catalog: ${err instanceof Error ? err.message : String(err)}`
);
}
};
const doCompression = async (): Promise<void> => {
if (!wantCompressionMeta) return;
try {
localRawCompressionCombos = await compressionMetaFetcher(
baseURL,
managementReadToken,
10_000
);
} catch (err) {
logAt(
"error",
`config shim: /api/context/combos fetch failed; publishing combos without compression suffix: ${err instanceof Error ? err.message : String(err)}`
);
}
};
const doConnections = async (): Promise<void> => {
if (!wantUsableOnly) return;
try {
localRawConnections = await providersFetcher(baseURL, managementReadToken, 10_000);
} catch (err) {
logAt(
"error",
`config shim: /api/providers fetch failed; usableOnly filter disabled for this refresh: ${err instanceof Error ? err.message : String(err)}`
);
}
};
await Promise.allSettled([
doModels(),
doCombos(),
doEnrichment(),
doCompression(),
doConnections(),
]);
const modelsFetchOk = !modelsFetchThrew && localRawModels.length > 0;
// Snapshot backfill for computed_context_length: a live /api/combos
// response can come back without this field (server hasn't finished
// recomputing it yet, e.g. just after a restart) even though the
// combo's members and identity are otherwise unchanged. When that
// happens, prefer the last-known-good value from the warm disk
// snapshot over the Math.min(member) fallback in
// mapComboToModelV2() — never overwrite any other combo field
// (models/name/etc.) with stale data, only this one derived number.
if (warmSnapshot) {
const snapshotComboById = new Map(warmSnapshot.rawCombos.map((c) => [c.id, c]));
for (const combo of localRawCombos) {
const hasLive =
typeof combo.computed_context_length === "number" &&
combo.computed_context_length > 0;
if (hasLive) continue;
const stale = snapshotComboById.get(combo.id);
if (
stale &&
typeof stale.computed_context_length === "number" &&
stale.computed_context_length > 0
) {
combo.computed_context_length = stale.computed_context_length;
}
}
}
// Disk-cache fallback (cold first run, no warm snapshot): when the
// live fetch returned no models AND features.diskCache !== false,
// hydrate from the last-known-good snapshot so OC still surfaces a
// usable catalog (e.g. IP whitelist drop, offline laptop).
if (modelsFetchThrew && wantDiskCache && !warmSnapshot) {
const snapshot = await diskSnapshotReader(resolved.providerId, snapshotFingerprint);
if (snapshot && snapshot.rawModels.length > 0) {
// Report snapshot age like the warm-startup path already does:
// "stale" alone reads as a transient blip, so a week-old catalog
// is indistinguishable from a five-minute-old one.
const snapshotAge = snapshot.writtenAt;
const ageMs = typeof snapshotAge === "number" ? now() - snapshotAge : undefined;
const snapshotAgeLabel =
typeof ageMs === "number" ? `${Math.round(ageMs / 3_600_000)}h` : "unknown";
const maxAgeMs = features.diskCacheMaxAgeMs;
const pastMaxAge =
typeof maxAgeMs === "number" &&
maxAgeMs > 0 &&
typeof ageMs === "number" &&
ageMs > maxAgeMs;
logAt(
pastMaxAge ? "error" : "warn",
`config shim: /v1/models unreachable; using stale disk cache (${snapshot.rawModels.length} models, age ${snapshotAgeLabel}${
pastMaxAge ? `, past diskCacheMaxAgeMs=${maxAgeMs}` : ""
})`
);
localRawModels = snapshot.rawModels;
localRawCombos = snapshot.rawCombos;
localRawEnrichment = snapshot.rawEnrichment;
localRawCompressionCombos = snapshot.rawCompressionCombos;
localRawConnections = snapshot.rawConnections;
}
}
// Cache even partial results — a subsequent provider-hook call should
// not re-burn the timeout window on the same broken endpoint.
cache.set(cacheKey, {
rawModels: localRawModels,
rawCombos: localRawCombos,
rawEnrichment: localRawEnrichment,
rawCompressionCombos: localRawCompressionCombos,
rawConnections: localRawConnections,
expiresAt: now() + resolved.modelCacheTtl,
});
// Startup diagnostics (file-based) — fires at startup via config hook
if (resolved.features?.startupDebug === true) {
await writeStartupDiagnostics({
providerId: resolved.providerId,
baseURL,
modelCount: localRawModels.length,
comboCount: localRawCombos.length,
enrichmentSize: localRawEnrichment.size,
enrichment: localRawEnrichment,
features: resolved.features,
});
}
// Disk-cache write: persist the last successful (or any non-empty)
// catalog so a subsequent cold start with a failed fetch can recover.
// Best-effort; soft-fail keeps us moving when the data dir isn't
// writable (e.g. read-only container). A failed refresh never
// overwrites the snapshot (modelsFetchOk gate).
if (modelsFetchOk && wantDiskCache) {
await diskSnapshotWriter(
resolved.providerId,
{
rawModels: localRawModels,
rawCombos: localRawCombos,
rawEnrichment: localRawEnrichment,
rawCompressionCombos: localRawCompressionCombos,
rawConnections: localRawConnections,
},
snapshotFingerprint
);
}
// Re-publish a fresh block via the shared cache so OC >=1.14.49's
// dynamic provider hook picks it up from the cache. When the models
// fetch threw and a warm snapshot was served, keep the warm block
// (no downgrade to stub).
if (modelsFetchOk || !warmSnapshot) {
const freshBlock = buildStaticProviderEntry(
localRawModels,
localRawCombos,
resolved,
baseURL,
apiKey,
localRawEnrichment,
localRawCompressionCombos,
localRawConnections,
logger
);
const inputWithProvider2 = input as { provider?: Record<string, unknown> };
if (inputWithProvider2.provider) {
inputWithProvider2.provider[resolved.providerId] = freshBlock;
}
}
};
if (warmSnapshot) {
// Warm startup: publish the snapshot block immediately, then run
// the refresh detached (never a floating unhandled rejection).
rawModels = warmSnapshot.rawModels;
rawCombos = warmSnapshot.rawCombos;
rawEnrichment = warmSnapshot.rawEnrichment;
rawCompressionCombos = warmSnapshot.rawCompressionCombos;
rawConnections = warmSnapshot.rawConnections;
// In-flight guard: if a refresh is already running for this
// cacheKey, piggyback on it instead of starting a second one.
const existing = _inflightRefresh.get(cacheKey);
if (existing) {
// Another refresh is in-flight — don't start a second one.
// The existing refresh will update the cache when it completes.
} else {
const refreshP = doRefresh()
.catch((err: unknown) => {
logAt(
"error",
`config shim: background refresh failed: ${err instanceof Error ? err.message : String(err)}`
);
})
.finally(() => {
_inflightRefresh.delete(cacheKey);
});
_inflightRefresh.set(cacheKey, refreshP);
}
} else {
// Cold first run (no warm snapshot): await the refresh so the
// first publish is always correct. In-flight guard still applies.
const existing = _inflightRefresh.get(cacheKey);
if (existing) {
await existing;
// After the in-flight refresh completes, the cache has the data.
const fresh = cache.get(cacheKey);
if (fresh) {
rawModels = fresh.rawModels;
rawCombos = fresh.rawCombos;
rawEnrichment = fresh.rawEnrichment;
rawCompressionCombos = fresh.rawCompressionCombos;
rawConnections = fresh.rawConnections;
}
} else {
const refreshP = doRefresh()
.catch((err: unknown) => {
logAt(
"error",
`config shim: refresh failed: ${err instanceof Error ? err.message : String(err)}`
);
})
.finally(() => {
_inflightRefresh.delete(cacheKey);
});
_inflightRefresh.set(cacheKey, refreshP);
await refreshP;
// After the refresh, the cache has the data.
const fresh = cache.get(cacheKey);
if (fresh) {
rawModels = fresh.rawModels;
rawCombos = fresh.rawCombos;
rawEnrichment = fresh.rawEnrichment;
rawCompressionCombos = fresh.rawCompressionCombos;
rawConnections = fresh.rawConnections;
}
}
}
}
const block = buildStaticProviderEntry(
rawModels,
rawCombos,
resolved,
baseURL,
apiKey,
rawEnrichment,
rawCompressionCombos,
rawConnections,
logger
);
// Mutate the input.provider map. The Config type declares
// `provider?: {[key: string]: ProviderConfig}` — we initialise the
// bag when absent so users who never set `provider` in opencode.json
// still get the static block.
const inputWithProvider = input as { provider?: Record<string, unknown> };
if (!inputWithProvider.provider) {
inputWithProvider.provider = {};
}
inputWithProvider.provider[resolved.providerId] = block;
// ─────────────────────────────────────────────────────────────────────
// MCP auto-emit — opt-in via features.mcpAutoEmit. When enabled, writes
// an `input.mcp[<providerId>]` remote entry pointing at
// `<baseURL>/api/mcp/stream` with the resolved Bearer token. Token
// resolution: features.mcpToken wins if set; otherwise falls back to
// the same apiKey used for chat. Operator overrides win (same posture
// as provider-block emit): if input.mcp[providerId] is already set,
// we leave it alone.
// ─────────────────────────────────────────────────────────────────────
if (features.mcpAutoEmit === true) {
const mcpKey = features.mcpToken ?? apiKey;
if (!mcpKey) {
logAt(
"debug",
`mcp auto-emit skipped: no Bearer token for providerId=${resolved.providerId}`
);
} else {
const inputWithMcp = input as { mcp?: Record<string, unknown> };
if (!inputWithMcp.mcp) {
inputWithMcp.mcp = {};
}
if (inputWithMcp.mcp[resolved.providerId] !== undefined) {
logAt("debug", `mcp auto-emit skipped: mcp.${resolved.providerId} already set by user`);
} else {
// Strip a trailing `/v1` from baseURL when present so we land on
// the MCP transport at /api/mcp/stream, not /v1/api/mcp/stream.
const mcpRoot = baseURL.replace(/\/v1\/?$/, "").replace(/\/$/, "");
inputWithMcp.mcp[resolved.providerId] = {
type: "remote",
url: `${mcpRoot}/api/mcp/stream`,
enabled: true,
headers: {
Authorization: `Bearer ${mcpKey}`,
},
};
}
}
}
};
}