@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
690 lines (665 loc) • 32.4 kB
text/typescript
import { normalizeJevQuotaTiers, type ResolvedJevQuotaTiers } from "./jev-quota-config";
import {
JEV_SESSION_PIN_TTL_MAX_MS,
JEV_SESSION_PIN_TTL_MIN_MS,
normalizeJevSessionPin,
type JevSessionPinConfig,
} from "./jev-session-pin-config";
import { isCodexReasoningEffort, isDeclaredReasoningEffort } from "../reasoning-effort";
import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
import type { OcxComboCapabilityPolicy, OcxComboConfig, OcxComboCooldownWaitPolicy, OcxComboDefaultEffort, OcxComboDefaultEffortMode, OcxComboJevEffortMode, OcxComboOnUnservable, OcxComboReasoningEffortMode, OcxComboStrategy, OcxComboTarget, OcxProviderConfig } from "../types";
import { COMBO_NAMESPACE, isValidComboId, resolveComboId, targetKey } from "./identifiers";
import {
CANONICAL_JEV_DECISION_PROVIDER,
JEV_DECISION_TIMEOUT_MAX_MS,
JEV_DECISION_TIMEOUT_MIN_MS,
isSystemOneEndpoint,
} from "./jev-decision-contract";
export const COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS = 0;
export const COMBO_DEFAULT_COOLDOWN_REPROBE_INTERVAL_MS = 300_000;
export const JEV_MAX_CANDIDATE_FIELD_CHARS = 512;
export {
JEV_DECISION_TIMEOUT_DEFAULT_MS,
JEV_DECISION_TIMEOUT_MAX_MS,
JEV_DECISION_TIMEOUT_MIN_MS,
isSystemOneEndpoint,
} from "./jev-decision-contract";
export { COMBO_NAMESPACE, preservesPhysicalComboProvider, isNativeAliasCombo, targetKey, parseComboModelId, comboModelId, comboPublicModelId, comboDisabledModelId, comboDisabledModelSelectors, resolveComboId, isValidComboId } from "./identifiers";
/**
* Public alias shape: one optional "/" segment, each segment id-shaped. Bare aliases
* (no "/") are the masquerade case — the combo answers to a mandated model id with no
* `combo/` prefix. Codex-facing slugs tolerate at most one "/", so deeper paths reject.
*/
const COMBO_ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?:\/[A-Za-z0-9][A-Za-z0-9._-]{0,63})?$/;
/** Bare aliases in this family require the explicit `nativeAlias` opt-in below. */
const NATIVE_OPENAI_FAMILY_PATTERN = /^(?:gpt-|o1-|o3-|o4-|codex-)/;
export interface ComboValidationIssue {
path: Array<string | number>;
message: string;
}
export interface NormalizedComboTarget {
provider: string;
model: string;
weight: number;
/** Emergency-only target, deferred under `cooldownWaitPolicy` (#5691). */
lastResort: boolean;
/** Pay-per-use target; requires key consent or loopback-only operator consent. */
metered: boolean;
reasoningEfforts?: OcxComboDefaultEffort[];
/** Optional JEV decision description. */
modelProfile?: string;
}
export interface NormalizedComboConfig {
/** Operator consent, effective only on a loopback-only proxy. */
allowMeteredTargets?: boolean;
strategy: OcxComboStrategy;
stickyLimit: number;
cooldownMs?: number;
waitForCooldownMs: number;
cooldownReprobe?: { enabled: true; intervalMs: number };
/** `before-last-resort` defers lastResort targets while a normal one can be waited out (#5691). */
cooldownWaitPolicy: OcxComboCooldownWaitPolicy | null;
defaultEffort: OcxComboDefaultEffort | null;
/** Client-precedence policy; `fallback` preserves legacy behavior. */
defaultEffortMode: OcxComboDefaultEffortMode;
/** Picker-ladder derivation policy; `strict` preserves the legacy intersection rule. */
reasoningEffortMode: OcxComboReasoningEffortMode;
/**
* Who owns the wire effort on a JEV combo.
*
* `decide` (default) applies the decision's effort and lets it override the caller.
* `client` keeps the decision's target choice but leaves effort to the caller and the
* target ladder, so a provider that must hold one tier to keep its prompt cache warm
* (for example one whose effort swaps the upstream model id) is never re-tiered.
*/
jevEffortMode: OcxComboJevEffortMode;
/** Catalog derivation and per-request member filtering; absent means `intersection`, the legacy rule. */
capabilityPolicy?: Extract<OcxComboCapabilityPolicy, "union">;
/** `union` only: what to do when no member can serve the request; absent means `degrade`. */
onUnservable?: Extract<OcxComboOnUnservable, "reject">;
/** Disable image input; `auto` preserves the intersection derived from all targets. */
imageInput: "auto" | "disabled";
/** Trimmed public alias, or null when the combo keeps the default `combo/<id>` slug. */
alias: string | null;
/** Explicit native-family alias opt-in. */
nativeAlias: boolean;
/** Display-only label for the catalog row, or null when unset. */
displayName: string | null;
/** Display-only catalog row description; absent keeps the generated text (#7229). */
description?: string;
/** JEV decision service provider id; absent means the canonical `jev` service. */
decisionProvider?: string;
/** Ordinary inference route used for JEV decisions. */
decisionModel?: string;
/** JEV decision deadline override; absent keeps the default four-second deadline. */
decisionTimeoutMs?: number;
decisionQuotaSignals?: boolean;
decisionQuotaTiers?: ResolvedJevQuotaTiers;
/** JEV only, opt-in: keep a session on the target JEV chose for it (#7525). */
sessionPin?: JevSessionPinConfig;
targets: NormalizedComboTarget[];
}
/**
* Cross-combo alias checks that need the full combos map (uniqueness). Kept separate
* from `comboConfigIssues` so config-file validation and the management API share it.
*/
export function comboAliasIssues(
id: string,
alias: string,
combos: Record<string, OcxComboConfig> | undefined,
options: { excludeComboId?: string; allowNativeAlias?: boolean } = {},
): ComboValidationIssue[] {
const issues: ComboValidationIssue[] = [];
if (!COMBO_ALIAS_PATTERN.test(alias)) {
issues.push({
path: ["alias"],
message: "alias must use letters, numbers, dot, underscore, or hyphen, with at most one \"/\" segment",
});
return issues;
}
if (alias === COMBO_NAMESPACE || alias.startsWith(`${COMBO_NAMESPACE}/`)) {
issues.push({
path: ["alias"],
message: `alias must not use the reserved "${COMBO_NAMESPACE}/" namespace`,
});
}
if (!alias.includes("/")
&& NATIVE_OPENAI_FAMILY_PATTERN.test(alias)
&& options.allowNativeAlias !== true) {
issues.push({
path: ["alias"],
message: "bare aliases in the OpenAI native family require nativeAlias=true",
});
}
for (const [otherId, other] of Object.entries(combos ?? {})) {
if (otherId === id || otherId === options.excludeComboId) continue;
const otherAlias = typeof other?.alias === "string" ? other.alias.trim() : "";
if (otherAlias && otherAlias === alias) {
issues.push({
path: ["alias"],
message: `alias "${alias}" is already used by combo "${otherId}"`,
});
}
}
return issues;
}
export interface ComboValidationOptions {
requireEnabledTarget?: boolean;
/**
* Save-time only: also reject a `decisionProvider` row the runtime would skip (disabled, or no
* model). Config-file load stays lenient so disabling a referenced row never breaks startup.
*/
requireUsableDecisionService?: boolean;
/** Full combos map for alias uniqueness checks; omitted during early config load. */
combos?: Record<string, OcxComboConfig>;
/** Ingress selector grammar, injected so combo validation never imports server routing. */
normalizeDecisionModel?: (model: string) => string;
/** Combo being renamed — its stored alias is excluded from uniqueness checks. */
excludeComboId?: string;
}
/** Validate a raw combo definition against the configured providers and return every issue found, without mutating the input. */
export function comboConfigIssues(
id: string,
raw: unknown,
providers: Record<string, OcxProviderConfig>,
options: ComboValidationOptions = {},
): ComboValidationIssue[] {
const issues: ComboValidationIssue[] = [];
if (!isValidComboId(id)) {
issues.push({
path: [],
message: "combo id must start with a letter/number and use letters, numbers, dot, underscore, or hyphen (max 64)",
});
}
if (Object.hasOwn(providers, COMBO_NAMESPACE)) {
issues.push({
path: [],
message: 'provider name "combo" collides with the reserved "combo/" namespace while combos are configured',
});
}
if (Object.hasOwn(providers, id)) {
issues.push({
path: [],
message: `combo id "${id}" collides with configured provider name "${id}"`,
});
}
if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
issues.push({ path: [], message: "combo must be an object" });
return issues;
}
const body = raw as Record<string, unknown>;
if (body.allowMeteredTargets !== undefined && typeof body.allowMeteredTargets !== "boolean") {
issues.push({ path: ["allowMeteredTargets"], message: "allowMeteredTargets must be a boolean" });
}
if (typeof body.alias === "string") {
const alias = body.alias.toLowerCase();
for (const [providerName, provider] of Object.entries(providers)) {
if (provider.alias?.toLowerCase() === alias) {
issues.push({ path: ["alias"], message: `alias "${body.alias}" is already used by provider "${providerName}"` });
}
const model = Object.entries(provider.modelAliases ?? {}).find(([, value]) => value.toLowerCase() === alias);
if (model) issues.push({ path: ["alias"], message: `alias "${body.alias}" is already used by model "${providerName}/${model[0]}"` });
}
}
if (body.strategy !== undefined
&& body.strategy !== "failover"
&& body.strategy !== "round-robin"
&& body.strategy !== "random"
&& body.strategy !== "least-used"
&& body.strategy !== "reset-window"
&& body.strategy !== "jev") {
issues.push({ path: ["strategy"], message: 'strategy must be "failover", "round-robin", "random", "least-used", "reset-window", or "jev"' });
}
if (body.stickyLimit !== undefined
&& (typeof body.stickyLimit !== "number" || !Number.isInteger(body.stickyLimit)
|| body.stickyLimit < 1
|| body.stickyLimit > 100)) {
issues.push({ path: ["stickyLimit"], message: "stickyLimit must be an integer from 1 to 100" });
}
if (body.cooldownMs !== undefined
&& (typeof body.cooldownMs !== "number" || !Number.isInteger(body.cooldownMs)
|| body.cooldownMs < 1
|| body.cooldownMs > 600_000)) {
issues.push({ path: ["cooldownMs"], message: "cooldownMs must be an integer from 1 to 600000" });
}
if (body.waitForCooldownMs !== undefined
&& (typeof body.waitForCooldownMs !== "number" || !Number.isInteger(body.waitForCooldownMs)
|| body.waitForCooldownMs < 0
|| body.waitForCooldownMs > 600_000)) {
issues.push({ path: ["waitForCooldownMs"], message: "waitForCooldownMs must be an integer from 0 to 600000" });
}
if (body.cooldownReprobe !== undefined) {
const value = body.cooldownReprobe;
if (!value || typeof value !== "object" || Array.isArray(value)) {
issues.push({ path: ["cooldownReprobe"], message: "cooldownReprobe must be an object" });
} else {
const reprobe = value as Record<string, unknown>;
if (typeof reprobe.enabled !== "boolean") {
issues.push({ path: ["cooldownReprobe", "enabled"], message: "cooldownReprobe.enabled must be a boolean" });
}
if (reprobe.intervalMs !== undefined && (typeof reprobe.intervalMs !== "number"
|| !Number.isSafeInteger(reprobe.intervalMs) || reprobe.intervalMs < 1000 || reprobe.intervalMs > 86_400_000)) {
issues.push({ path: ["cooldownReprobe", "intervalMs"], message: "cooldownReprobe.intervalMs must be an integer from 1000 to 86400000" });
}
if (Object.keys(reprobe).some(key => key !== "enabled" && key !== "intervalMs")) {
issues.push({ path: ["cooldownReprobe"], message: "cooldownReprobe supports only enabled and intervalMs" });
}
}
}
if (body.cooldownWaitPolicy !== undefined && body.cooldownWaitPolicy !== null
&& body.cooldownWaitPolicy !== "before-last-resort") {
issues.push({
path: ["cooldownWaitPolicy"],
message: 'cooldownWaitPolicy must be "before-last-resort" when set',
});
}
if (body.defaultEffort !== undefined
&& body.defaultEffort !== null
&& (typeof body.defaultEffort !== "string" || !isCodexReasoningEffort(body.defaultEffort))) {
issues.push({
path: ["defaultEffort"],
message: "defaultEffort must be one of: low, medium, high, xhigh, max, ultra",
});
}
if (body.defaultEffortMode !== undefined
&& body.defaultEffortMode !== "fallback"
&& body.defaultEffortMode !== "force") {
issues.push({
path: ["defaultEffortMode"],
message: 'defaultEffortMode must be "fallback" or "force"',
});
}
if (body.defaultEffortMode === "force"
&& (typeof body.defaultEffort !== "string" || !isCodexReasoningEffort(body.defaultEffort))) {
issues.push({
path: ["defaultEffort"],
message: "defaultEffort is required when defaultEffortMode is force",
});
}
if (body.jevEffortMode !== undefined
&& body.jevEffortMode !== "decide"
&& body.jevEffortMode !== "client") {
issues.push({
path: ["jevEffortMode"],
message: 'jevEffortMode must be "decide" or "client"',
});
} else if (body.jevEffortMode === "client" && body.strategy !== "jev") {
issues.push({ path: ["jevEffortMode"], message: 'jevEffortMode "client" is only valid with strategy "jev"' });
}
if (body.imageInput !== undefined && body.imageInput !== "auto" && body.imageInput !== "disabled") {
issues.push({ path: ["imageInput"], message: 'imageInput must be "auto" or "disabled"' });
}
if (body.reasoningEffortMode !== undefined
&& body.reasoningEffortMode !== "strict"
&& body.reasoningEffortMode !== "adaptive") {
issues.push({
path: ["reasoningEffortMode"],
message: 'reasoningEffortMode must be "strict" or "adaptive"',
});
}
if (body.capabilityPolicy !== undefined && body.capabilityPolicy !== "intersection" && body.capabilityPolicy !== "union") {
issues.push({ path: ["capabilityPolicy"], message: 'capabilityPolicy must be "intersection" or "union"' });
}
if (body.onUnservable !== undefined && body.onUnservable !== "degrade" && body.onUnservable !== "reject") {
issues.push({ path: ["onUnservable"], message: 'onUnservable must be "degrade" or "reject"' });
}
if (body.alias !== undefined) {
if (typeof body.alias !== "string") {
issues.push({ path: ["alias"], message: "alias must be a string" });
} else {
const alias = body.alias.trim();
if (alias) {
issues.push(...comboAliasIssues(id, alias, options.combos, {
...options,
allowNativeAlias: body.nativeAlias === true,
}));
}
}
}
if (body.nativeAlias !== undefined && typeof body.nativeAlias !== "boolean") {
issues.push({ path: ["nativeAlias"], message: "nativeAlias must be a boolean" });
}
if (body.displayName !== undefined) {
if (typeof body.displayName !== "string") {
issues.push({ path: ["displayName"], message: "displayName must be a string" });
} else if (body.displayName.trim().length > 128 || /[\u0000-\u001f\u007f]/.test(body.displayName)) {
issues.push({
path: ["displayName"],
message: "displayName must be at most 128 characters and contain no control characters",
});
}
}
if (body.description !== undefined) {
if (typeof body.description !== "string") {
issues.push({ path: ["description"], message: "description must be a string" });
} else if (body.description.trim().length > 128 || /\p{Cc}/u.test(body.description)) {
issues.push({
path: ["description"],
message: "description must be at most 128 characters and contain no control characters",
});
}
}
const alias = typeof body.alias === "string" ? body.alias.trim() : "";
const nativeAlias = body.nativeAlias === true;
if (nativeAlias && !SUPPORTED_NATIVE_OPENAI_SLUGS.has(alias)) {
issues.push({
path: ["nativeAlias"],
message: "nativeAlias requires a currently supported bare OpenAI-native model alias",
});
}
if (nativeAlias && (typeof body.displayName !== "string" || body.displayName.trim().length === 0)) {
issues.push({ path: ["displayName"], message: "displayName is required for native aliases" });
}
for (const field of ["decisionQuotaSignals", "decisionQuotaTiers"] as const) {
if (body[field] === undefined || body[field] === null) continue;
if (body.strategy !== "jev") issues.push({ path: [field], message: `${field} is only valid with strategy "jev"` });
if (field === "decisionQuotaSignals" ? typeof body[field] !== "boolean" : !normalizeJevQuotaTiers(body[field]))
issues.push({ path: [field], message: field === "decisionQuotaSignals" ? "decisionQuotaSignals must be a boolean" : "decisionQuotaTiers must contain finite 0..100 strictly ascending thresholds" });
}
if (body.sessionPin !== undefined && body.sessionPin !== null) {
if (body.strategy !== "jev") {
issues.push({ path: ["sessionPin"], message: 'sessionPin is only valid with strategy "jev"' });
} else if (!normalizeJevSessionPin(body.sessionPin)) {
issues.push({
path: ["sessionPin"],
message: `sessionPin must be { "ttlMs": <integer from ${JEV_SESSION_PIN_TTL_MIN_MS} to ${JEV_SESSION_PIN_TTL_MAX_MS}> }`,
});
}
}
if (body.decisionProvider !== undefined && body.decisionProvider !== null) {
const decisionProvider = typeof body.decisionProvider === "string" ? body.decisionProvider.trim() : "";
if (!decisionProvider) {
issues.push({ path: ["decisionProvider"], message: "decisionProvider must be a non-empty provider name" });
} else if (body.strategy !== "jev") {
issues.push({ path: ["decisionProvider"], message: 'decisionProvider is only valid with strategy "jev"' });
} else if (decisionProvider === CANONICAL_JEV_DECISION_PROVIDER) {
// Explicit "jev" means exactly what omission means: the canonical TypeSafe service.
} else if (!Object.hasOwn(providers, decisionProvider)) {
issues.push({
path: ["decisionProvider"],
message: `decisionProvider "${decisionProvider}" is not configured`,
});
} else if (providers[decisionProvider]?.adapter !== "jev-decision") {
issues.push({
path: ["decisionProvider"],
message: `decisionProvider "${decisionProvider}" is not a decision service (adapter must be "jev-decision")`,
});
} else if (!isSystemOneEndpoint(String(providers[decisionProvider]?.baseUrl ?? ""))) {
issues.push({
path: ["decisionProvider"],
message: `decisionProvider "${decisionProvider}" baseUrl must be a full HTTPS decision endpoint or an HTTP /systemone endpoint`,
});
} else if (options.requireUsableDecisionService && providers[decisionProvider]?.disabled === true) {
issues.push({
path: ["decisionProvider"],
message: `decisionProvider "${decisionProvider}" is disabled`,
});
} else if (options.requireUsableDecisionService
&& !providers[decisionProvider]?.defaultModel?.trim()
&& !providers[decisionProvider]?.models?.[0]?.trim()) {
issues.push({
path: ["decisionProvider"],
message: `decisionProvider "${decisionProvider}" has no model (set defaultModel or models)`,
});
}
}
if (body.decisionModel !== undefined && body.decisionModel !== null) {
const model = typeof body.decisionModel === "string" ? body.decisionModel.trim() : "";
if (!model || model.length > JEV_MAX_CANDIDATE_FIELD_CHARS) {
issues.push({ path: ["decisionModel"], message: `decisionModel must be a non-empty string of at most ${JEV_MAX_CANDIDATE_FIELD_CHARS} characters` });
} else {
if (body.strategy !== "jev") {
issues.push({ path: ["decisionModel"], message: 'decisionModel is only valid with strategy "jev"' });
}
if (body.decisionProvider !== undefined && body.decisionProvider !== null) {
issues.push({ path: ["decisionModel"], message: "decisionModel cannot coexist with decisionProvider" });
}
const comboId = resolveComboId({ combos: options.combos }, options.normalizeDecisionModel?.(model) ?? model);
if (comboId === id || (comboId && options.combos?.[comboId]?.strategy === "jev")) {
issues.push({ path: ["decisionModel"], message: `decisionModel must not reference ${comboId === id ? "itself" : "a JEV combo"} (combo "${comboId}")` });
}
}
}
if (body.decisionTimeoutMs !== undefined && body.decisionTimeoutMs !== null) {
if (typeof body.decisionTimeoutMs !== "number" || !Number.isInteger(body.decisionTimeoutMs)
|| body.decisionTimeoutMs < JEV_DECISION_TIMEOUT_MIN_MS
|| body.decisionTimeoutMs > JEV_DECISION_TIMEOUT_MAX_MS) {
issues.push({
path: ["decisionTimeoutMs"],
message: `decisionTimeoutMs must be an integer from ${JEV_DECISION_TIMEOUT_MIN_MS} to ${JEV_DECISION_TIMEOUT_MAX_MS}`,
});
} else if (body.strategy !== "jev") {
issues.push({ path: ["decisionTimeoutMs"], message: 'decisionTimeoutMs is only valid with strategy "jev"' });
}
}
if (!Array.isArray(body.targets) || body.targets.length === 0) {
issues.push({ path: ["targets"], message: "targets must be a non-empty array" });
return issues;
}
const seen = new Set<string>();
let configuredProviderCount = 0;
let enabledProviderCount = 0;
for (let i = 0; i < body.targets.length; i++) {
const rawTarget = body.targets[i];
if (!rawTarget || typeof rawTarget !== "object" || Array.isArray(rawTarget)) {
issues.push({ path: ["targets", i], message: `targets[${i}] must be an object` });
continue;
}
const target = rawTarget as Record<string, unknown>;
const provider = typeof target.provider === "string" ? target.provider.trim() : "";
const model = typeof target.model === "string" ? target.model.trim() : "";
if (!provider) {
issues.push({ path: ["targets", i, "provider"], message: `targets[${i}].provider is required` });
} else if (!Object.hasOwn(providers, provider)) {
issues.push({
path: ["targets", i, "provider"],
message: `targets[${i}].provider "${provider}" is not configured`,
});
} else if (providers[provider]?.adapter === "jev-decision") {
issues.push({
path: ["targets", i, "provider"],
message: `targets[${i}].provider "${provider}" is a decision service and cannot be a model target`,
});
} else {
configuredProviderCount += 1;
if (providers[provider]?.disabled !== true) enabledProviderCount += 1;
}
if (!model) {
issues.push({ path: ["targets", i, "model"], message: `targets[${i}].model is required` });
}
if (target.weight !== undefined
&& (typeof target.weight !== "number" || !Number.isInteger(target.weight)
|| target.weight < 1
|| target.weight > 10_000)) {
issues.push({
path: ["targets", i, "weight"],
message: `targets[${i}].weight must be an integer from 1 to 10000`,
});
}
if (target.reasoningEfforts !== undefined) {
if (!Array.isArray(target.reasoningEfforts) || target.reasoningEfforts.length === 0) {
issues.push({
path: ["targets", i, "reasoningEfforts"],
message: `targets[${i}].reasoningEfforts must be a non-empty array`,
});
} else {
const seenEfforts = new Set<OcxComboDefaultEffort>();
for (let effortIndex = 0; effortIndex < target.reasoningEfforts.length; effortIndex++) {
const effort = target.reasoningEfforts[effortIndex];
if (typeof effort !== "string" || !isCodexReasoningEffort(effort)) {
issues.push({
path: ["targets", i, "reasoningEfforts", effortIndex],
message: `targets[${i}].reasoningEfforts[${effortIndex}] must be one of: low, medium, high, xhigh, max, ultra`,
});
} else if (seenEfforts.has(effort as OcxComboDefaultEffort)) {
issues.push({
path: ["targets", i, "reasoningEfforts", effortIndex],
message: `targets[${i}].reasoningEfforts must not contain duplicates`,
});
} else {
seenEfforts.add(effort as OcxComboDefaultEffort);
}
}
}
}
if (target.lastResort !== undefined && typeof target.lastResort !== "boolean") {
issues.push({
path: ["targets", i, "lastResort"],
message: `targets[${i}].lastResort must be a boolean`,
});
}
if (target.metered !== undefined && typeof target.metered !== "boolean") {
issues.push({
path: ["targets", i, "metered"],
message: `targets[${i}].metered must be a boolean`,
});
}
if (target.modelProfile !== undefined
&& (typeof target.modelProfile !== "string"
|| target.modelProfile.trim().length === 0
|| target.modelProfile.length > JEV_MAX_CANDIDATE_FIELD_CHARS
|| /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(target.modelProfile))) {
issues.push({
path: ["targets", i, "modelProfile"],
message: `targets[${i}].modelProfile must be a non-empty string of at most ${JEV_MAX_CANDIDATE_FIELD_CHARS} characters; only tab, line feed and carriage return are allowed among control characters`,
});
}
if (provider && model) {
const key = targetKey({ provider, model });
if (seen.has(key)) {
issues.push({ path: ["targets", i], message: `duplicate combo target "${key}"` });
} else {
seen.add(key);
}
}
}
if (options.requireEnabledTarget
&& configuredProviderCount === body.targets.length
&& enabledProviderCount === 0) {
issues.push({
path: ["targets"],
message: "targets must include at least one enabled provider",
});
}
return issues;
}
export function comboConfigError(
id: string,
raw: unknown,
providers: Record<string, OcxProviderConfig>,
options: ComboValidationOptions = {},
): string | null {
return comboConfigIssues(id, raw, providers, options)[0]?.message ?? null;
}
/** Normalize a validated combo definition into its canonical form: trimmed strings, defaults and the opt-in quota signal fields. */
export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig {
const alias = typeof raw.alias === "string" ? raw.alias.trim() : "";
const displayName = typeof raw.displayName === "string" ? raw.displayName.trim() : "";
const description = typeof raw.description === "string" ? raw.description.trim() : "";
const decisionProvider = typeof raw.decisionProvider === "string" ? raw.decisionProvider.trim() : "";
const decisionModel = typeof raw.decisionModel === "string" ? raw.decisionModel.trim() : "";
const defaultEffort = typeof raw.defaultEffort === "string" && isCodexReasoningEffort(raw.defaultEffort)
? raw.defaultEffort
: null;
return {
strategy: raw.strategy ?? "failover",
...(raw.allowMeteredTargets === true ? { allowMeteredTargets: true } : {}),
stickyLimit: raw.stickyLimit ?? 1,
cooldownMs: raw.cooldownMs,
...(raw.cooldownReprobe?.enabled === true ? { cooldownReprobe: {
enabled: true as const,
intervalMs: raw.cooldownReprobe.intervalMs ?? COMBO_DEFAULT_COOLDOWN_REPROBE_INTERVAL_MS,
} } : {}),
waitForCooldownMs: raw.waitForCooldownMs ?? COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS,
cooldownWaitPolicy: raw.cooldownWaitPolicy === "before-last-resort" ? "before-last-resort" : null,
defaultEffort,
defaultEffortMode: raw.defaultEffortMode === "force" && defaultEffort !== null ? "force" : "fallback",
reasoningEffortMode: raw.reasoningEffortMode === "adaptive" ? "adaptive" : "strict",
jevEffortMode: raw.jevEffortMode === "client" ? "client" : "decide",
// Sparse like `allowMeteredTargets`: the default shape stays exactly what it was before the policy existed.
...(raw.capabilityPolicy === "union" ? { capabilityPolicy: "union" as const } : {}),
...(raw.onUnservable === "reject" ? { onUnservable: "reject" as const } : {}),
imageInput: raw.imageInput === "disabled" ? "disabled" : "auto",
alias: alias || null,
nativeAlias: raw.nativeAlias === true,
displayName: displayName || null,
...(description ? { description } : {}),
// Explicit "jev" is the default and stays sparse.
...(decisionProvider && decisionProvider !== CANONICAL_JEV_DECISION_PROVIDER ? { decisionProvider } : {}),
...(decisionModel ? { decisionModel } : {}),
...(typeof raw.decisionTimeoutMs === "number" ? { decisionTimeoutMs: raw.decisionTimeoutMs } : {}),
...(raw.strategy === "jev" && raw.decisionQuotaSignals === true ? { decisionQuotaSignals: true } : {}),
...(raw.strategy === "jev" && normalizeJevQuotaTiers(raw.decisionQuotaTiers) ? { decisionQuotaTiers: normalizeJevQuotaTiers(raw.decisionQuotaTiers)! } : {}),
...(raw.strategy === "jev" && normalizeJevSessionPin(raw.sessionPin) ? { sessionPin: normalizeJevSessionPin(raw.sessionPin)! } : {}),
targets: raw.targets.map(target => ({
provider: target.provider.trim(),
model: target.model.trim(),
weight: target.weight ?? 1,
...(target.reasoningEfforts !== undefined
? { reasoningEfforts: [...target.reasoningEfforts] }
: {}),
...(typeof target.modelProfile === "string" && target.modelProfile.trim()
? { modelProfile: target.modelProfile.trim() }
: {}),
lastResort: target.lastResort === true,
metered: target.metered === true,
})),
};
}
/**
* Load-time stand-in for the ingress synthetic-row grammar: strip a `--fast` suffix, and a
* `--<effort>` suffix when Cursor effort rows are on. It reads only the string, so schema
* validation needs no server module, model inventory, or Cursor install detection. The
* management save path still resolves the exact grammar against the live inventory.
*/
export function lexicalDecisionModelBase(model: string, cursorEffortRows: boolean): string {
if (model.endsWith("--fast")) return model.slice(0, -"--fast".length);
if (!cursorEffortRows) return model;
const separator = model.lastIndexOf("--");
if (separator <= 0) return model;
const effort = model.slice(separator + 2);
return effort !== "none" && isDeclaredReasoningEffort(effort) ? model.slice(0, separator) : model;
}
/**
* Whether removing `provider` would leave this stored combo invalid: a target uses it, or the
* combo names it as its JEV decision service. The canonical `jev` id stays valid without a row.
*/
export function comboDependsOnProvider(combo: OcxComboConfig, provider: string): boolean {
if (combo.targets.some(target => target.provider === provider)) return true;
if (typeof combo.decisionModel === "string" && combo.decisionModel.trim().startsWith(`${provider}/`)) return true;
const decisionProvider = typeof combo.decisionProvider === "string" ? combo.decisionProvider.trim() : "";
return decisionProvider === provider && provider !== CANONICAL_JEV_DECISION_PROVIDER;
}
export function comboDefaultEffort(
config: { combos?: Record<string, OcxComboConfig> },
id: string,
): OcxComboDefaultEffort | null {
const combos = config.combos;
if (!combos || !Object.hasOwn(combos, id)) return null;
const value: unknown = combos[id]!.defaultEffort ?? null;
return typeof value === "string" && isCodexReasoningEffort(value)
? value as OcxComboDefaultEffort
: null;
}
export function listComboIds(config: { combos?: Record<string, OcxComboConfig> }): string[] {
return Object.keys(config.combos ?? {}).sort((a, b) => a.localeCompare(b));
}
export function listLiveComboTargetKeys(
config: { combos?: Record<string, OcxComboConfig> },
): ReadonlySet<string> {
const keys = new Set<string>();
for (const id of listComboIds(config)) {
const combo = getCombo(config, id);
if (!combo) continue;
for (const target of combo.targets) keys.add(`${id}::${targetKey(target)}`);
}
return keys;
}
export function getCombo(
config: { combos?: Record<string, OcxComboConfig> },
id: string,
): NormalizedComboConfig | undefined {
const combos = config.combos;
if (!combos || !Object.hasOwn(combos, id)) return undefined;
return normalizeComboConfig(combos[id]!);
}