UNPKG

@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
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]!); }