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
/**
* Public projection helpers for GET /v1/combos (issue #2300).
*
* Strip internal routing details (connectionId, weights, labels, etc.) before
* returning combo metadata to API-key callers. Kept in a separate module so
* the projection can be unit-tested without spinning up the Next.js route.
*
* #10968: the projection also reports `accountPinned` per model step — a boolean
* derived from the stripped `connectionId`, so callers can distinguish a combo
* that fails over between two accounts of one provider from a duplicated step.
*
* #3979: client-facing combo catalogs (the `/v1/combos`, VS Code and LobeHub /
* OpenCode import surfaces) can opt into advertising the combo's resolved
* capabilities (multimodal / reasoning / caching) so importing clients enable
* those features instead of requiring manual config after import.
*/
import {
createModelCapabilityResolutionSnapshot,
getResolvedModelCapabilities,
} from "@/lib/modelCapabilities";
import { resolveNestedComboTargets } from "@omniroute/open-sse/services/combo/comboStructure.ts";
// The shapes live in the combo type module; comboStructure.ts only re-uses them
// internally, so importing them from there is a TS2459/TS2724 at build time.
import type {
ComboCollectionLike,
ComboLike,
ResolvedComboTarget,
} from "@omniroute/open-sse/services/combo/types.ts";
export interface PublicComboStep {
kind: "model" | "combo-ref";
model?: string;
comboName?: string;
providerId?: string;
/**
* #10968: whether this step pins one specific account of its provider.
*
* Two steps that pin different accounts of the same provider project to
* identical `{kind, model, providerId}` objects, so a client cannot tell a
* two-account failover from the same step listed twice. This says which it
* is without exposing the `connectionId` the flag is derived from — not even
* a prefix, per the issue.
*
* Set on every `model` step. Absent on `combo-ref`, which routes through
* another combo and has no account of its own.
*/
accountPinned?: boolean;
/**
* #14587: whether the resolved capability sources prove this member accepts
* images (`null` = no source knows). Only set on `model` steps when the
* projection includes capabilities. A combo's `multimodal` is true exactly
* when every member reports `true`, so a `false`/`null` here identifies the
* member blocking it.
*/
supportsVision?: boolean | null;
}
/**
* #3979: capabilities a combo can be safely imported with. A combo advertises
* a capability only when EVERY concrete model step proves it (the routing
* strategy may dispatch to any member, so the weakest member is the ceiling).
*/
export interface PublicComboCapabilities {
multimodal: boolean;
reasoning: boolean;
caching: boolean;
}
export interface PublicCombo {
name: string;
strategy: string;
description?: string;
models: PublicComboStep[];
capabilities?: PublicComboCapabilities;
}
/** Capability subset projectCombo needs; injectable so tests stay DB-free + deterministic. */
export type ComboCapabilityResolver = (model: string) => {
supportsVision: boolean | null;
reasoning: boolean;
};
export interface ProjectComboOptions {
/** When true, attach the resolved `capabilities` block to the projection (#3979). */
includeCapabilities?: boolean;
/** Override the capability resolver (defaults to the model registry). */
resolveCapabilities?: ComboCapabilityResolver;
/**
* #14232: the full combo collection. When supplied, combo-ref steps are
* expanded through the same resolver the routing runtime uses, so nested
* leaves count toward capabilities exactly as they would count at dispatch
* time — matching how /v1/models evaluates the same combo. Without it the
* legacy behavior applies: any combo-ref forces the conservative false.
*/
allCombos?: ComboCollectionLike;
}
const defaultCapabilityResolver: ComboCapabilityResolver = (model) => {
const caps = getResolvedModelCapabilities(model);
return { supportsVision: caps.supportsVision, reasoning: caps.reasoning };
};
export function projectComboStep(step: Record<string, unknown>): PublicComboStep | null {
const kind = step.kind;
if (kind === "combo-ref" && typeof step.comboName === "string") {
return { kind: "combo-ref", comboName: step.comboName };
}
if (kind === "model" && typeof step.model === "string") {
const out: PublicComboStep = { kind: "model", model: step.model };
if (typeof step.providerId === "string" && step.providerId.length > 0) {
out.providerId = step.providerId;
}
// Same shape test as providerId above. `cleanupComboConnectionRefs` drops the
// key when the connection is deleted, so a step whose pinned account is gone
// reports false rather than pointing at nothing.
out.accountPinned = typeof step.connectionId === "string" && step.connectionId.length > 0;
return out;
}
return null;
}
/**
* #3979: derive the capabilities a combo can be imported with.
* - `multimodal` / `reasoning`: true only when there is at least one concrete
* model step, there are no unresolvable nested combo-refs, and EVERY model
* step proves the capability via the registry. #14232: with `allCombos`
* supplied, resolvable combo-refs are expanded through
* `resolveNestedComboTargets` — the same target pool the routing runtime
* dispatches against and /v1/models evaluates — so nested leaves count
* toward the verdict instead of every nested combo being capped at false.
* - `caching`: reflects the operator's explicit per-combo Context-Cache-Protection
* choice (no registry caching flag exists), so caching is never advertised
* unless the operator opted in — avoiding surprise prompt-cache cost.
*/
export function computeComboCapabilities(
combo: Record<string, unknown>,
resolve: ComboCapabilityResolver = defaultCapabilityResolver,
allCombos?: ComboCollectionLike
): PublicComboCapabilities {
const rawModels = Array.isArray(combo.models) ? combo.models : [];
let hasComboRef = false;
const directModelIds: string[] = [];
for (const m of rawModels) {
if (!m || typeof m !== "object") continue;
const step = m as Record<string, unknown>;
if (step.kind === "combo-ref") {
hasComboRef = true;
} else if (step.kind === "model" && typeof step.model === "string") {
directModelIds.push(step.model);
}
}
// #14232: with the collection in hand, combo-ref steps expand through the
// same resolver the runtime dispatch uses, so the projection evaluates the
// exact target pool a request would hit. Unresolvable refs (dangling names,
// cycles at the depth cap) contribute no targets and force the conservative
// false below, matching the doc contract.
const modelIds: string[] = [...directModelIds];
if (hasComboRef && allCombos) {
const resolved = resolveNestedComboTargets(combo as unknown as ComboLike, allCombos);
for (const target of resolved as ResolvedComboTarget[]) {
if (target.kind === "model" && typeof target.modelStr === "string") {
modelIds.push(target.modelStr);
}
}
}
let multimodal = modelIds.length > 0 && (!hasComboRef || Boolean(allCombos));
let reasoning = modelIds.length > 0 && (!hasComboRef || Boolean(allCombos));
if (multimodal || reasoning) {
for (const id of modelIds) {
const caps = resolve(id);
if (caps.supportsVision !== true) multimodal = false;
if (caps.reasoning !== true) reasoning = false;
}
}
const caching = combo.context_cache_protection === true;
return { multimodal, reasoning, caching };
}
/** #14587: attach the per-member vision verdict to each direct model step. */
function annotateMemberVision(
steps: PublicComboStep[],
resolve: ComboCapabilityResolver = defaultCapabilityResolver
): void {
for (const step of steps) {
if (step.kind !== "model" || typeof step.model !== "string") continue;
step.supportsVision = resolve(step.model).supportsVision;
}
}
export function projectCombo(
combo: Record<string, unknown>,
options?: ProjectComboOptions
): PublicCombo | null {
const name = typeof combo.name === "string" ? combo.name.trim() : "";
if (!name) return null;
const strategy = typeof combo.strategy === "string" ? combo.strategy : "priority";
const out: PublicCombo = { name, strategy, models: [] };
if (typeof combo.description === "string" && combo.description.length > 0) {
out.description = combo.description;
}
const rawModels = Array.isArray(combo.models) ? combo.models : [];
for (const m of rawModels) {
if (m && typeof m === "object") {
const step = projectComboStep(m as Record<string, unknown>);
if (step) out.models.push(step);
}
}
if (options?.includeCapabilities) {
annotateMemberVision(out.models, options.resolveCapabilities);
out.capabilities = computeComboCapabilities(
combo,
options.resolveCapabilities,
options.allCombos
);
}
return out;
}
/** Project one request's combo collection with a single bulk capability snapshot. */
export function projectComboCollectionWithCapabilities(combos: readonly unknown[]): PublicCombo[] {
const allCombos = combos.filter(
(combo): combo is Record<string, unknown> => Boolean(combo) && typeof combo === "object"
);
const snapshot = createModelCapabilityResolutionSnapshot();
const resolveCapabilities: ComboCapabilityResolver = (model) => {
const caps = getResolvedModelCapabilities(model, undefined, snapshot);
return { supportsVision: caps.supportsVision, reasoning: caps.reasoning };
};
return allCombos
.map((combo) =>
projectCombo(combo, {
includeCapabilities: true,
resolveCapabilities,
allCombos,
})
)
.filter((combo): combo is PublicCombo => combo !== null);
}