@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
215 lines (200 loc) • 11 kB
text/typescript
import { nativeContextLimits } from "../codex/catalog/metadata";
import { effectiveAdapterContract } from "../adapters/registry";
import { getModelMetadataCaseInsensitive, resolveMetadataProvider } from "../generated/model-metadata";
import { errorDestinationText, providerErrorDestinationLabel } from "../lib/error-destination";
import { isCodexReasoningEffort, modelRecordValue, resolveEffortAtOrBelow } from "../reasoning-effort";
import { parseRequest } from "../responses/parser";
import { checkComboTargetInputAdmission } from "../server/responses/input-admission";
import type { OcxComboTarget, OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
import { requiresVisionPreprocessing } from "../vision/plan";
import { customRowInputModalities } from "../vision/eligibility";
import { comboRequestHasAudioInput, comboRequestHasImageInput } from "./request";
import { targetKey, type NormalizedComboConfig } from "./types";
/**
* How one `union` combo member serves this request.
*
* `native` takes it as is. `degraded` takes it after a local rewrite the child request already
* owns (the vision sidecar describes the image). `unable` cannot take it at all and is skipped.
*/
export type ComboTargetService = "native" | "degraded" | "unable";
export interface ComboTargetRoute {
providerName: string;
provider: OcxProviderConfig;
modelId: string;
codexAccountId?: string;
}
/** Resolves a combo target to its concrete route; `undefined` when it does not resolve. */
export type ComboTargetRouter = (target: Pick<OcxComboTarget, "provider" | "model">) => ComboTargetRoute | undefined;
type ComboCapabilityConfig = Pick<OcxConfig, "providers" | "customModels" | "providerContextCaps" | "visionSidecar">;
type ComboVisionProbe = (route: ComboTargetRoute, parsed: OcxParsedRequest) => Promise<boolean>;
function comboTargetAcceptsAudio(config: ComboCapabilityConfig, route: ComboTargetRoute | undefined): boolean {
if (!route) return false;
const { provider, providerName, modelId } = route;
const wire = effectiveAdapterContract(provider.adapter).wire;
if (wire !== "openai-chat" && wire !== "openai-responses") return false;
const declared = Object.hasOwn(provider.modelCapabilities ?? {}, modelId)
? provider.modelCapabilities?.[modelId]?.inputModalities : undefined;
const modalities = declared ?? customRowInputModalities(config, providerName, modelId)
?? modelRecordValue(provider.modelInputModalities, modelId) ?? provider.inputModalities
?? getModelMetadataCaseInsensitive(resolveMetadataProvider(providerName) ?? providerName, modelId)?.input;
return modalities?.includes("audio") === true;
}
/** What the admitted members cannot serve. */
export type ComboUnservable = false | "audio" | "image" | "context";
export interface ComboCapabilityGate {
/** Selection filter: false only for a member that cannot serve this request. */
eligible: (target: Pick<OcxComboTarget, "provider" | "model">) => boolean;
/** No enabled member can serve the request as is; the caller applies `onUnservable`. */
unservable: ComboUnservable;
/** The child must still have a plan if it needs to describe images before sending. */
requiresVisionPlan: ComboCapabilityGate["eligible"];
/** Members that fit and can serve the turn once the combo permits omission. */
imageDegradationEligible: ComboCapabilityGate["eligible"];
}
const OPEN_GATE: ComboCapabilityGate = {
eligible: () => true, unservable: false, requiresVisionPlan: () => false,
imageDegradationEligible: () => false,
};
interface ContextFit {
fits: boolean;
/** Known context window, or null when the target publishes none (fail-open, like the child). */
window: number | null;
}
/**
* Context fit for one member: the estimated input must sit inside the member's input ceiling, and,
* when the caller declares an output allowance, the strict combo admission the child applies
* (`checkComboTargetInputAdmission`) must also pass. Without a declared allowance the child falls
* back to the loose 2.5x pathological-input gate, which would let a member far too small through,
* so the filter is the stricter of the two. The estimator overcounts on purpose, so the filter
* leaves a member slightly early rather than late. An unresolved route or unknown window fits,
* matching the child's fail-open.
*/
function comboTargetContextFit(
config: ComboCapabilityConfig,
parsed: OcxParsedRequest | undefined,
route: ComboTargetRoute | undefined,
): ContextFit {
if (!parsed || !route) return { fits: true, window: null };
const result = checkComboTargetInputAdmission(
{ ...parsed, modelId: route.modelId }, route.provider, route.providerName, route.modelId, nativeContextLimits(config),
);
if (result.ceiling === null) return { fits: true, window: null };
return { fits: result.admitted && result.estimatedTokens <= result.ceiling, window: result.contextWindow ?? result.ceiling };
}
/** The request as the child will parse it. */
function parseComboInput(body: unknown): OcxParsedRequest | undefined {
try {
return parseRequest(body);
} catch {
return undefined;
}
}
/**
* Request-side half of `capabilityPolicy: "union"`. The catalog advertises the union of member
* capabilities and the minimum member window. Dispatch can try the largest compatible member
* when context is unservable, so a request may need something only some members
* have. Audio requires a member that accepts it. Members that can degrade an image stay
* eligible (keeping the subscription order and the prompt cache); members that cannot take the
* image, or whose window cannot hold the input, are filtered.
*
* When no enabled, admitted member can serve, the gate reports why:
* - `"audio"`: no member declares audio input. The caller refuses without discarding audio.
* - `"context"`: no member can hold the input. Only the members with the largest known window stay
* eligible; the caller sends there with the loose direct-request admission (`onUnservable:
* "degrade"`) or refuses before any send (`"reject"`).
* - `"image"`: every member that can hold the input is unable to take the image. Those members stay
* eligible and the child strips the image, or the caller refuses.
*/
export async function comboCapabilityGate(
config: ComboCapabilityConfig,
combo: Pick<NormalizedComboConfig, "capabilityPolicy" | "targets">,
body: unknown,
route: ComboTargetRouter,
isAdmitted: (target: NormalizedComboConfig["targets"][number], route: ComboTargetRoute | undefined, parsed: OcxParsedRequest | undefined) => boolean = () => true,
canDescribe?: ComboVisionProbe,
): Promise<ComboCapabilityGate> {
if (combo.capabilityPolicy !== "union") return OPEN_GATE;
const hasImage = comboRequestHasImageInput(body);
const hasAudio = comboRequestHasAudioInput(body);
const parsed = parseComboInput(body);
const contextInput = parsed?._compactionRequest ? undefined : parsed;
if (!hasImage && !hasAudio && !contextInput) return OPEN_GATE;
let hasAdmittedTarget = false;
const visionChecks = new Map<string, ComboTargetRoute>();
const judged = new Map<string, { image: ComboTargetService; context: ContextFit }>();
for (const target of combo.targets) {
if (config.providers[target.provider]?.disabled === true) continue;
const key = targetKey(target);
const resolved = route(target);
if (!isAdmitted(target, resolved, parsed)) continue;
hasAdmittedTarget = true;
if (judged.has(key)) continue;
if (hasAudio && !comboTargetAcceptsAudio(config, resolved)) continue;
const context = comboTargetContextFit(config, contextInput, resolved);
const needsDescription = hasImage && context.fits && resolved
&& requiresVisionPreprocessing(config, resolved.provider, resolved.modelId, resolved.providerName);
judged.set(key, { image: needsDescription ? "unable" : "native", context });
if (needsDescription && parsed && config.visionSidecar?.enabled !== false) visionChecks.set(key, resolved);
}
// Finish evaluating admission metadata for all members before any asynchronous
// sidecar planning can observe or trigger a configuration change.
if (parsed && canDescribe) {
for (const [key, resolved] of visionChecks) {
if (await canDescribe(resolved, parsed)) judged.get(key)!.image = "degraded";
}
}
if (!hasAdmittedTarget) return OPEN_GATE;
const verdicts = [...judged.values()];
if (verdicts.length === 0) return { ...OPEN_GATE, eligible: () => false, unservable: "audio" };
const filter = (keep: (verdict: { image: ComboTargetService; context: ContextFit }) => boolean): ComboCapabilityGate["eligible"] =>
target => {
const verdict = judged.get(targetKey(target));
return verdict !== undefined && keep(verdict);
};
if (verdicts.some(v => v.context.fits && v.image !== "unable")) {
return {
eligible: filter(v => v.context.fits && v.image !== "unable"),
unservable: false,
requiresVisionPlan: filter(v => v.image === "degraded"),
imageDegradationEligible: filter(v => v.context.fits && v.image !== "native"),
};
}
if (verdicts.some(v => v.context.fits)) {
return { ...OPEN_GATE, eligible: filter(v => v.context.fits), unservable: "image" };
}
const largest = Math.max(...verdicts.map(v => v.context.window ?? 0));
return { ...OPEN_GATE, eligible: filter(v => (v.context.window ?? 0) === largest), unservable: "context" };
}
/**
* `union` + `adaptive` combos advertise the union of their members' effort ladders, so a caller
* can pick a rung this member lacks (xhigh against a low/medium/high lane). Snap it to the
* highest rung at or below, the rule the default effort already uses, instead of forwarding a
* value the member would reject or silently ignore. A rung below the whole ladder rises to its
* lowest rung, as `resolveEffortAtOrBelow` does for the default effort.
*/
export function clampComboCallerEffort(
body: Record<string, unknown>,
ladder: readonly string[] | undefined,
target: Pick<OcxComboTarget, "provider">,
): void {
if (!ladder || ladder.length === 0) return;
const clamp = (effort: unknown): string | undefined => {
if (typeof effort !== "string" || !isCodexReasoningEffort(effort) || ladder.includes(effort)) return undefined;
const clamped = resolveEffortAtOrBelow(effort, ladder);
if (clamped) {
console.debug("[opencodex] combo effort clamped to target ladder", {
provider: errorDestinationText(providerErrorDestinationLabel(target.provider)),
requestedEffort: effort,
effort: clamped,
});
}
return clamped;
};
const reasoning = body.reasoning;
if (reasoning && typeof reasoning === "object" && !Array.isArray(reasoning)) {
const clamped = clamp((reasoning as Record<string, unknown>).effort);
if (clamped) body.reasoning = { ...(reasoning as Record<string, unknown>), effort: clamped };
}
const flat = clamp(body.reasoning_effort);
if (flat) body.reasoning_effort = flat;
}