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
/** db/models/compat.ts — model-compat overrides (normalizeToolCallId, per-protocol flags, upstream headers). */
import { getDbInstance } from "../core";
import {
MODEL_COMPAT_PROTOCOL_KEYS,
type ModelCompatProtocolKey,
} from "@/shared/constants/modelCompat";
import { isForbiddenUpstreamHeaderName } from "@/shared/constants/upstreamHeaders";
import { isHiddenForModality } from "@/shared/utils/modelVisibility";
import { getKeyValue } from "./shared";
import { finishModelCatalogWriteWithBackup } from "./modelCatalogWriteSignals";
/** Built-in / alias models: tool-call + developer-role flags without a full custom row */
const MODEL_COMPAT_NAMESPACE = "modelCompatOverrides";
export { MODEL_COMPAT_PROTOCOL_KEYS, type ModelCompatProtocolKey };
export type ModelCompatPerProtocol = {
normalizeToolCallId?: boolean;
preserveOpenAIDeveloperRole?: boolean;
preserveVideoUrl?: boolean;
/** Merged into upstream HTTP requests for this model (after default auth headers). */
upstreamHeaders?: Record<string, string>;
};
export type CompatByProtocolMap = Partial<Record<ModelCompatProtocolKey, ModelCompatPerProtocol>>;
export function isCompatProtocolKey(p: string): p is ModelCompatProtocolKey {
return (MODEL_COMPAT_PROTOCOL_KEYS as readonly string[]).includes(p);
}
const UPSTREAM_HEADERS_MAX = 16;
const UPSTREAM_HEADER_NAME_MAX = 128;
const UPSTREAM_HEADER_VALUE_MAX = 4096;
function isValidUpstreamHeaderName(k: string): boolean {
if (!k || k.length > UPSTREAM_HEADER_NAME_MAX) return false;
if (isForbiddenUpstreamHeaderName(k)) return false;
if (/[\r\n\0]/.test(k)) return false;
if (/\s/.test(k)) return false;
if (k.includes(":")) return false;
return true;
}
/** Sanitize user-provided upstream header map (used when persisting and when reading for requests). */
export function sanitizeUpstreamHeadersMap(
raw: Record<string, unknown> | null | undefined
): Record<string, string> {
const out: Record<string, string> = {};
if (!raw || typeof raw !== "object") return out;
for (const [k0, v0] of Object.entries(raw)) {
const k = String(k0).trim();
if (!k || !isValidUpstreamHeaderName(k)) {
continue;
}
const v =
typeof v0 === "string"
? v0.trim().slice(0, UPSTREAM_HEADER_VALUE_MAX)
: String(v0 ?? "")
.trim()
.slice(0, UPSTREAM_HEADER_VALUE_MAX);
if (v.includes("\r") || v.includes("\n")) continue;
out[k] = v;
if (Object.keys(out).length >= UPSTREAM_HEADERS_MAX) break;
}
return out;
}
export function deepMergeCompatByProtocol(
prev: CompatByProtocolMap | undefined,
patch: Partial<Record<ModelCompatProtocolKey, Partial<ModelCompatPerProtocol>>>
): CompatByProtocolMap {
const out: CompatByProtocolMap = { ...(prev || {}) };
for (const key of Object.keys(patch) as ModelCompatProtocolKey[]) {
if (!isCompatProtocolKey(key)) continue;
const deltas = patch[key];
if (!deltas || typeof deltas !== "object") continue;
const hasDelta =
Object.prototype.hasOwnProperty.call(deltas, "normalizeToolCallId") ||
Object.prototype.hasOwnProperty.call(deltas, "preserveOpenAIDeveloperRole") ||
Object.prototype.hasOwnProperty.call(deltas, "preserveVideoUrl") ||
Object.prototype.hasOwnProperty.call(deltas, "upstreamHeaders");
if (!hasDelta) continue;
const cur: ModelCompatPerProtocol = { ...(out[key] || {}) };
if ("normalizeToolCallId" in deltas) {
cur.normalizeToolCallId = Boolean(deltas.normalizeToolCallId);
}
if ("preserveOpenAIDeveloperRole" in deltas) {
cur.preserveOpenAIDeveloperRole = Boolean(deltas.preserveOpenAIDeveloperRole);
}
if ("preserveVideoUrl" in deltas) {
cur.preserveVideoUrl = Boolean(deltas.preserveVideoUrl);
}
if ("upstreamHeaders" in deltas) {
const uh = deltas.upstreamHeaders;
if (uh === undefined) {
/* skip */
} else {
const s = sanitizeUpstreamHeadersMap(uh as Record<string, unknown>);
if (Object.keys(s).length === 0) delete cur.upstreamHeaders;
else cur.upstreamHeaders = s;
}
}
if (Object.keys(cur).length === 0) delete out[key];
else out[key] = cur;
}
return out;
}
export type ModelCompatOverride = {
id: string;
normalizeToolCallId?: boolean;
preserveOpenAIDeveloperRole?: boolean;
preserveVideoUrl?: boolean;
compatByProtocol?: CompatByProtocolMap;
upstreamHeaders?: Record<string, string>;
isHidden?: boolean;
/**
* #12172: per-modality visibility override, keyed by endpoint/modality id
* (e.g. "chat", "images", "embeddings", ...). A key present here always wins
* over the legacy top-level `isHidden` for that specific modality — this is
* what lets an operator hide a model from Chat without also suppressing an
* identically-ID'd model in the Image (or any other) registry. A modality
* with no entry here falls back to `isHidden` (the pre-#12172 "hide
* everywhere" behavior), so existing rows keep working unchanged.
*/
hiddenModalities?: Record<string, boolean>;
apiFormat?: string;
targetFormat?: string;
supportsVision?: boolean;
};
/** Nested provider → model map of explicit model-compat vision overrides. */
export type ModelCompatVisionOverrideMap = ReadonlyMap<string, ReadonlyMap<string, boolean>>;
/**
* Resolve whether an override hides its model for a given modality.
* Precedence: an explicit `hiddenModalities[modality]` entry always wins;
* otherwise fall back to the legacy all-modalities `isHidden` flag.
* Delegates to the shared rule (`src/shared/utils/modelVisibility.ts`) so the dashboard
* UI and the server agree — the duplicated copy is what let the dashboard drift (#12172).
*/
export function isOverrideHiddenForModality(
override: Pick<ModelCompatOverride, "isHidden" | "hiddenModalities"> | null | undefined,
modality: string
): boolean {
return isHiddenForModality(override, modality);
}
export function readCompatList(providerId: string): ModelCompatOverride[] {
const db = getDbInstance();
const row = db
.prepare("SELECT value FROM key_value WHERE namespace = ? AND key = ?")
.get(MODEL_COMPAT_NAMESPACE, providerId);
const value = getKeyValue(row).value;
if (!value) return [];
try {
const parsed: unknown = JSON.parse(value);
if (!Array.isArray(parsed)) return [];
return parsed.flatMap((raw): ModelCompatOverride[] => {
if (!raw || typeof raw !== "object") return [];
// Old releases persisted an `isDeleted` tombstone alongside `isHidden`.
// Ignore that retired state while preserving the visibility choice.
const entry = { ...(raw as Record<string, unknown>) };
delete entry.isDeleted;
return typeof entry.id === "string" ? [entry as ModelCompatOverride] : [];
});
} catch {
return [];
}
}
export function writeCompatList(providerId: string, list: ModelCompatOverride[]) {
const db = getDbInstance();
if (list.length === 0) {
db.prepare("DELETE FROM key_value WHERE namespace = ? AND key = ?").run(
MODEL_COMPAT_NAMESPACE,
providerId
);
} else {
db.prepare("INSERT OR REPLACE INTO key_value (namespace, key, value) VALUES (?, ?, ?)").run(
MODEL_COMPAT_NAMESPACE,
providerId,
JSON.stringify(list)
);
}
finishModelCatalogWriteWithBackup();
}
export function getModelCompatOverrides(providerId: string): ModelCompatOverride[] {
return readCompatList(providerId);
}
/**
* Resolve one exact provider/model `supportsVision` compat override.
* A supplied bulk map performs no SQLite work.
*/
export function getModelCompatVisionOverride(
providerId: string,
modelIds: readonly string[],
bulk?: ModelCompatVisionOverrideMap | null
): boolean | null {
if (!providerId || modelIds.length === 0) return null;
const candidates = new Set(modelIds.filter(Boolean));
if (candidates.size === 0) return null;
try {
const overrides = bulk
? bulk.get(providerId)
: new Map(
readCompatList(providerId).flatMap((entry) =>
typeof entry.supportsVision === "boolean"
? [[entry.id, entry.supportsVision] as const]
: []
)
);
if (!overrides) return null;
for (const modelId of candidates) {
const value = overrides.get(modelId);
if (typeof value === "boolean") return value;
}
} catch {
// Capability resolution must remain available when the override store is unavailable.
}
return null;
}
function parseCompatVisionOverrides(value: string): Map<string, boolean> {
try {
const parsed = JSON.parse(value) as unknown;
if (!Array.isArray(parsed)) return new Map<string, boolean>();
return new Map(
parsed.flatMap((candidate) => {
if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return [];
const { id, supportsVision } = candidate as {
id?: unknown;
supportsVision?: unknown;
};
return typeof id === "string" && typeof supportsVision === "boolean"
? [[id, supportsVision] as const]
: [];
})
);
} catch {
return new Map<string, boolean>();
}
}
/** Bulk-load all explicit model-compat vision overrides with one SQLite query. */
export function listModelCompatVisionOverrides(): ModelCompatVisionOverrideMap {
try {
const rows = getDbInstance()
.prepare("SELECT key, value FROM key_value WHERE namespace = 'modelCompatOverrides'")
.all();
const result = new Map<string, Map<string, boolean>>();
for (const row of rows) {
const { key, value } = getKeyValue(row);
if (!key || !value) continue;
const byModel = parseCompatVisionOverrides(value);
if (byModel.size > 0) result.set(key, byModel);
}
return result;
} catch {
return new Map<string, Map<string, boolean>>();
}
}
export type ModelCompatPatch = {
normalizeToolCallId?: boolean;
preserveOpenAIDeveloperRole?: boolean | null;
preserveVideoUrl?: boolean | null;
compatByProtocol?: CompatByProtocolMap;
/** Replace top-level extra headers for override-only rows; omit to leave unchanged. */
upstreamHeaders?: Record<string, string> | null;
isHidden?: boolean | null;
/**
* #12172: when set alongside `isHidden`, scopes the write to that one
* modality (see {@link ModelCompatOverride.hiddenModalities}) instead of
* the legacy all-modalities flag. `isHidden: null` with a `modality` clears
* just that modality's override (reverting it to inherit the legacy flag).
*/
modality?: string | null;
apiFormat?: string | null;
targetFormat?: string | null;
supportsVision?: boolean | null;
};
export function compatByProtocolHasEntries(map: CompatByProtocolMap | undefined): boolean {
if (!map || typeof map !== "object") return false;
return Object.keys(map).some((k) => {
const v = map[k as ModelCompatProtocolKey];
return v && typeof v === "object" && Object.keys(v).length > 0;
});
}
export function mergeModelCompatOverride(
providerId: string,
modelId: string,
patch: ModelCompatPatch
) {
const list = readCompatList(providerId);
const idx = list.findIndex((e) => e.id === modelId);
const prev = idx >= 0 ? { ...list[idx] } : { id: modelId };
const next: ModelCompatOverride = { ...prev, id: modelId };
if ("normalizeToolCallId" in patch) {
if (patch.normalizeToolCallId) next.normalizeToolCallId = true;
else delete next.normalizeToolCallId;
}
if ("preserveOpenAIDeveloperRole" in patch) {
if (patch.preserveOpenAIDeveloperRole === null) {
delete next.preserveOpenAIDeveloperRole; // unset: revert to default (undefined at read time)
} else {
next.preserveOpenAIDeveloperRole = Boolean(patch.preserveOpenAIDeveloperRole);
}
}
if ("preserveVideoUrl" in patch) {
if (patch.preserveVideoUrl === null) {
delete next.preserveVideoUrl;
} else {
next.preserveVideoUrl = Boolean(patch.preserveVideoUrl);
}
}
if (patch.compatByProtocol && Object.keys(patch.compatByProtocol).length > 0) {
const merged = deepMergeCompatByProtocol(next.compatByProtocol, patch.compatByProtocol);
if (compatByProtocolHasEntries(merged)) next.compatByProtocol = merged;
else delete next.compatByProtocol;
}
if ("upstreamHeaders" in patch) {
if (patch.upstreamHeaders === null) {
delete next.upstreamHeaders;
} else if (patch.upstreamHeaders && typeof patch.upstreamHeaders === "object") {
const s = sanitizeUpstreamHeadersMap(patch.upstreamHeaders as Record<string, unknown>);
if (Object.keys(s).length === 0) delete next.upstreamHeaders;
else next.upstreamHeaders = s;
}
}
const filtered = list.filter((e) => e.id !== modelId);
const hasPreserveFlag = Object.prototype.hasOwnProperty.call(next, "preserveOpenAIDeveloperRole");
const hasVideoUrlFlag = Object.prototype.hasOwnProperty.call(next, "preserveVideoUrl");
const hasTopUpstream = next.upstreamHeaders && Object.keys(next.upstreamHeaders).length > 0;
if ("isHidden" in patch) {
const modality = typeof patch.modality === "string" && patch.modality ? patch.modality : null;
if (modality) {
const hiddenModalities = { ...(next.hiddenModalities || {}) };
if (patch.isHidden === null) {
delete hiddenModalities[modality];
} else {
hiddenModalities[modality] = Boolean(patch.isHidden);
}
if (Object.keys(hiddenModalities).length > 0) next.hiddenModalities = hiddenModalities;
else delete next.hiddenModalities;
} else if (patch.isHidden === null) {
delete next.isHidden;
} else {
next.isHidden = Boolean(patch.isHidden);
}
}
if ("apiFormat" in patch) {
if (!patch.apiFormat) {
delete next.apiFormat;
} else {
next.apiFormat = patch.apiFormat;
}
}
if ("targetFormat" in patch) {
if (!patch.targetFormat) {
delete next.targetFormat;
} else {
next.targetFormat = patch.targetFormat;
}
}
if ("supportsVision" in patch) {
if (patch.supportsVision === null) {
delete next.supportsVision;
} else {
next.supportsVision = Boolean(patch.supportsVision);
}
}
const hasHiddenFlag =
Object.prototype.hasOwnProperty.call(next, "isHidden") ||
(!!next.hiddenModalities && Object.keys(next.hiddenModalities).length > 0);
const hasApiFormat = Object.prototype.hasOwnProperty.call(next, "apiFormat");
const hasTargetFormat = Object.prototype.hasOwnProperty.call(next, "targetFormat");
const hasVisionFlag = Object.prototype.hasOwnProperty.call(next, "supportsVision");
if (
next.normalizeToolCallId ||
hasPreserveFlag ||
hasVideoUrlFlag ||
hasHiddenFlag ||
hasApiFormat ||
hasTargetFormat ||
hasVisionFlag ||
compatByProtocolHasEntries(next.compatByProtocol) ||
hasTopUpstream
) {
filtered.push(next);
}
writeCompatList(providerId, filtered);
}
export function removeModelCompatOverride(providerId: string, modelId: string) {
const list = readCompatList(providerId);
const filtered = list.filter((e) => e.id !== modelId);
if (filtered.length === list.length) return;
writeCompatList(providerId, filtered);
}