@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
479 lines (459 loc) • 24.5 kB
text/typescript
import { clientFacingModelLabel } from "../../lib/error-destination";
/**
* Native Chat and Messages candidates inside the combo loop.
*
* Each opted-in ingress hands the combo its `ComboProtocolSource`; without one nothing here
* runs. Messages supports canonical strict failover children without effort rewriting.
* For the candidate the
* combo is about to dispatch, the concrete route is settled the way the Chat ingress settles a
* single route, and the native Chat lane's own eligibility rule decides whether the child goes
* native. A native child runs `runNativeChatAttempt` (through the source) on the attempt the combo
* already opened, with the combo's per-target budget, the client's abort signal and the turn
* lease, built from a fresh copy of the source body; every other candidate keeps the bridge.
* Under `unrepresentable: "reject"` a candidate whose path would drop a requested feature is never
* picked, and a combo whose every enabled candidate is skipped answers the ingress refusal.
*
* No `./` sibling import on purpose: `core-options.ts` names this module's types, so an edge back
* into the owner graph would close a cycle.
*/
import type { OcxConfig } from "../../types";
import type { RouteResult } from "../../router";
import type { AdmissionModelScope } from "../admission-model-scope";
import type { AdmissionLease } from "../../lib/admission";
import type { RequestExecutionBudget, SingleUseDispatchPermit } from "../../lib/request-execution-budget";
import type { TransientSendBudget } from "../../lib/upstream-retry";
import type { ResponsesTerminalStatus } from "../../bridge";
import type { NativeChatFinishLog } from "../chat-native";
import type { InferenceAttempt } from "../inference/attempt";
import type { ProtocolEnvelope } from "../../protocols/envelope";
import type { ProtocolFeature } from "../../protocols/features";
import type { PersistedUsageAttempt } from "../../usage/log";
import {
finishRequestAttempt,
sealRequestAttemptIdentity,
type RequestLogContext,
} from "../request-log";
import { captureRouteStaticPolicy, routeConcreteModel } from "../../router";
import { comboDefaultEffort, concreteComboRequestBody, getCombo, type JevDecision } from "../../combos";
import { comboAdvertisesEffortUnion } from "../../combos/capability-policy";
import { comboStripsReasoningControls, stripUnsupportedReasoningControls } from "../../combos/request";
import { clampComboCallerEffort } from "../../combos/request-capability";
import { supportedLadderFor } from "../effort-policy";
import { applyDroidReasoningDefault } from "../droid-reasoning-default";
import { resolveWireProtocolOverride } from "../adapter-resolve";
import { resolveOpenCodeGoTransport } from "../../providers/opencode-go-transport";
import { getOrAllocateRequestSessionLane } from "../request-log-conversation";
import { assertRouteAllowedByScope } from "../admission-model-scope";
import { isNativeChatRouteEligible } from "../chat-native-eligibility";
import { nativeMessagesDeclineReason, type NativeMessagesSelector } from "../messages-native-eligibility";
import type { NativeMessagesFinishLog } from "../messages-native";
import { credentialDomainFor } from "../../protocols/opaque-state";
import { chatCompletionsErrorResponse } from "../../chat/outbound";
import { OUTPUT_CONFIG_EFFORTS } from "../../chat/inbound";
import { anthropicErrorResponse } from "../../claude/outbound";
import { hasAnthropicOnlyServerTool, hasNativeOnlyTool } from "../../claude/inbound-content-options";
import { nativeMessagesInlineToolNames } from "../messages-native-tool-guard";
const isRecord = (value: unknown): value is Record<string, unknown> =>
value !== null && typeof value === "object" && !Array.isArray(value);
/**
* An inline definition without a usable name cannot be withdrawn by a tool_reference, so it stays in
* force; nativeMessagesInlineToolNames tracks only named, callable tools and skips it.
*/
/** The bridge drops inline removals too, so withdrawing a top-level tool would re-enable it there. */
function withdrawsTopLevelTool(body: Record<string, unknown>): boolean {
const declared = new Set(Array.isArray(body.tools)
? body.tools.flatMap(tool => isRecord(tool) && typeof tool.name === "string" ? [tool.name] : []) : []);
return declared.size > 0 && Array.isArray(body.messages) && body.messages.some(message => isRecord(message)
&& message.role === "system" && Array.isArray(message.content) && message.content.some(block => isRecord(block)
&& block.type === "tool_removal" && isRecord(block.tool) && block.tool.type === "tool_reference"
&& typeof block.tool.name === "string" && declared.has(block.tool.name)));
}
function hasUnnamedInlineToolDefinition(body: Record<string, unknown>): boolean {
return Array.isArray(body.messages) && body.messages.some(message => isRecord(message) && message.role === "system"
&& Array.isArray(message.content) && message.content.some(block => isRecord(block) && block.type === "tool_addition"
&& isRecord(block.tool) && block.tool.type === "tool_definition"
&& !(isRecord(block.tool.definition) && typeof block.tool.definition.name === "string" && block.tool.definition.name.length > 0)));
}
import { isRequestExecutionBudget } from "../../lib/request-execution-budget";
import { markResponseNonReplayable } from "../../lib/upstream-retry";
import { redactSecretString } from "../../lib/redact";
import { upstreamWireForAdapter } from "../../protocols/contract";
import { checkRepresentable, unrepresentableMessage } from "../../protocols/guard";
import { deliveryModeForLane, requestPathForLane } from "../../protocols/path";
import { resolveProtocolSettings } from "../../protocols/settings";
import { addProtocolEntryReason, markAttemptProtocolPath, markProtocolBlocked } from "../../protocols/trace";
import { markClientWire } from "../inference/client-wire";
type Rec = Record<string, unknown>;
type ComboTarget = { provider: string; model: string };
/** What the source needs to run one native child on the combo's open attempt. */
export interface NativeComboChildRun {
route: RouteResult;
/** A fresh copy of the source body, never another candidate's rewritten one. */
body: Rec;
childLog: RequestLogContext;
attemptHandle: InferenceAttempt;
sendBudget: RequestExecutionBudget;
comboDispatchPermit?: SingleUseDispatchPermit;
turnAdmissionLease?: AdmissionLease;
onFirstOutput: () => void;
/** Reports to the combo's child callbacks; it never writes the parent's final row itself. */
finishLog: NativeChatFinishLog;
}
/** Supplied by the Chat ingress for a combo route when `nativeChatCombos` is on. */
interface NativeChatComboSource {
readonly inbound: "chat";
readonly envelope: ProtocolEnvelope;
/** Runs `runNativeChatAttempt`; the response it returns is in the Chat wire. */
dispatchNativeChild(input: NativeComboChildRun): Promise<Response>;
}
interface NativeMessagesComboSource {
readonly inbound: "messages";
readonly envelope: ProtocolEnvelope;
readonly selector?: NativeMessagesSelector;
dispatchNativeChild(input: Omit<NativeComboChildRun, "finishLog"> & { finishLog: NativeMessagesFinishLog }): Promise<Response>;
}
export type ComboProtocolSource = NativeChatComboSource | NativeMessagesComboSource;
/** The native plan for one dispatch: the settled route and its own fresh body. */
export interface NativeComboChildPlan {
route: RouteResult;
body: Rec;
sendBudget: RequestExecutionBudget;
}
export interface ComboProtocolLanes {
/** Pick predicate. False for a candidate the `reject` policy skips or a translated child of a native-only tool. */
pickable(target: ComboTarget): boolean;
/** The ingress refusal when every enabled candidate was skipped; otherwise undefined. */
refusal(): Response | undefined;
/**
* The native plan for the candidate about to dispatch, or undefined to keep the bridge.
* `decisionOwnsEffort` is the caller's pre-decision reading of `jevEffortMode`: re-reading a
* combo the management API can replace mid-decision would split this lane from its log label.
*/
nativeChild(
target: ComboTarget,
targetRoute: RouteResult,
targetSendBudget: TransientSendBudget | undefined,
initialDecision: Pick<JevDecision, "effort"> | undefined,
decisionOwnsEffort: boolean,
): NativeComboChildPlan | undefined;
}
interface CandidateVerdict {
skip?: ProtocolFeature[];
/** A translated child would silently drop the request's native-only tool. */
nativeOnly?: true;
}
/** Build opt-in native eligibility and child plans; only the initial plan applies a JEV choice. */
export function createComboProtocolLanes(input: {
source: ComboProtocolSource | undefined;
req: Request;
config: OcxConfig;
logCtx: RequestLogContext;
/** The request's resolved model-scope snapshot; internal callers carry the caller's scope. */
admissionScope: AdmissionModelScope | undefined;
droidDefaultEffort?: string;
comboId: string;
targets: readonly ComboTarget[];
}): ComboProtocolLanes | undefined {
const { source, req, config, logCtx, admissionScope, droidDefaultEffort, comboId, targets } = input;
if (!source) return undefined;
const envelope = source.envelope;
const inbound = source.inbound;
const inboundWire = inbound === "messages" ? "anthropic" : "chat";
const reject = resolveProtocolSettings(config).unrepresentable === "reject";
const selector = (target: ComboTarget): string => `${target.provider}/${target.model}`;
// The Chat ingress's own settlement of a single route, applied to the concrete target: the
// key's model scope, the static policy captured for a Chat inbound, the wire override and the
// OpenCode Go transport. A refusal here keeps the bridge, which reports it in its own shape.
const settle = (target: ComboTarget, targetRoute: RouteResult): RouteResult | undefined => {
try {
const route: RouteResult = { ...targetRoute };
assertRouteAllowedByScope(admissionScope, clientFacingModelLabel(undefined), route);
const routedProvider = route.provider;
route.staticPolicy = captureRouteStaticPolicy(
route.providerName, route.modelId, routedProvider, route.staticPolicy.effectiveAlias, inboundWire,
);
const wireProvider = resolveWireProtocolOverride(route.providerName, route.modelId, routedProvider, inboundWire, route.staticPolicy);
route.provider = resolveOpenCodeGoTransport(wireProvider, getOrAllocateRequestSessionLane(req), routedProvider);
return route;
} catch {
return undefined;
}
};
// Eligibility only reads the body, so it reads the source in place: judging a candidate charges
// no copy and can never refuse the turn on the translator budget. Only a dispatch takes a copy.
const nativeEligible = (target: ComboTarget, route: RouteResult | undefined): route is RouteResult => {
if (!route || route.provider.adapter !== (inbound === "messages" ? "anthropic" : "openai-chat")) return false;
if (inbound === "messages") {
const combo = getCombo(config, comboId);
// ponytail: exact replay supports no combo effort rewrite; the existing bridge owns those policies.
const domain = credentialDomainFor(route.provider);
if (!combo || combo.strategy !== "failover" || comboDefaultEffort(config, comboId)
|| combo.reasoningEffortMode !== "strict" || !domain
|| (route.provider.authMode === "oauth" && !domain.firstPartyAnthropic)
|| supportedLadderFor({ provider: route.provider, modelId: route.modelId })?.length === 0) return false;
}
// The concrete selector, as the bridge child's body carries it; the wire model comes from
// the route either way, and the pinned-effort lookup reads this.
const body = { ...envelope.readBody(), model: selector(target) };
return inbound === "messages"
? nativeMessagesDeclineReason(route, body, config, { ...(source.inbound === "messages" ? source.selector : undefined), routeSelector: selector(target) }) === undefined
: isNativeChatRouteEligible(route, body, config);
};
const verdicts = new Map<string, CandidateVerdict>();
let skipRecorded = false;
let nativeOnlyTool: boolean | undefined;
let anthropicOnlyTool: boolean | undefined;
// The bridge keeps only text from system messages, so an active inline tool_addition definition
// has no translated equivalent either; fail closed like a top-level native-only tool.
const declaresNativeOnlyTool = (body: Record<string, unknown>) =>
hasNativeOnlyTool(body) || nativeMessagesInlineToolNames(body).size > 0 || hasUnnamedInlineToolDefinition(body)
|| withdrawsTopLevelTool(body);
const judge = (target: ComboTarget): CandidateVerdict => {
const key = selector(target);
const cached = verdicts.get(key);
if (cached) return cached;
let verdict: CandidateVerdict = {};
let targetRoute: RouteResult | undefined;
try {
targetRoute = routeConcreteModel(config, key);
} catch {
// Not evidence about the path; dispatch keeps the existing routing failure surface.
targetRoute = undefined;
}
if (targetRoute) {
const settled = settle(target, targetRoute);
const native = nativeEligible(target, settled);
const upstream = native ? inbound : upstreamWireForAdapter((settled ?? targetRoute).provider.adapter);
const checked = checkRepresentable({
inbound,
requestPath: requestPathForLane(inbound, native ? "native" : "bridge", upstream),
features: envelope.features(),
policy: "reject",
});
if (!checked.ok) {
verdict = { skip: checked.features };
if (!skipRecorded) {
skipRecorded = true;
addProtocolEntryReason(logCtx, "feature-unrepresentable");
}
}
// Under any policy: the source chose a native-only tool, so a translated child never runs it.
// web_fetch and a restricted web_search only travel out of body, to a first-party Anthropic child.
if (!native && inbound === "messages") {
const provider = (settled ?? targetRoute).provider;
if ((nativeOnlyTool ??= declaresNativeOnlyTool(envelope.readBody()))
|| ((anthropicOnlyTool ??= hasAnthropicOnlyServerTool(envelope.readBody()))
&& !(provider.adapter === "anthropic" && credentialDomainFor(provider)?.firstPartyAnthropic))) {
verdict.nativeOnly = true;
}
}
}
verdicts.set(key, verdict);
return verdict;
};
return {
pickable: target => {
const verdict = judge(target);
return verdict.nativeOnly !== true && (!reject || verdict.skip === undefined);
},
refusal: () => {
if (!reject) return undefined;
const enabled = targets.filter(target => {
const provider = config.providers[target.provider];
return provider !== undefined && provider.disabled !== true;
});
if (enabled.length === 0) return undefined;
const skipped = enabled.map(judge);
if (skipped.some(verdict => verdict.skip === undefined)) return undefined;
const features = [...new Set(skipped.flatMap(verdict => verdict.skip ?? []))];
// The same refusal the ingress gives a single route: 400 in the Chat shape, feature keys
// only, a blocked trace, and no upstream send.
markProtocolBlocked(logCtx, { inbound, reasonCodes: ["feature-unrepresentable"], features });
logCtx.errorCode = "unsupported_feature";
return markClientWire((inbound === "messages" ? anthropicErrorResponse : chatCompletionsErrorResponse)(
400, unrepresentableMessage(features), "invalid_request_error", "unsupported_feature",
), inbound);
},
nativeChild: (target, targetRoute, targetSendBudget, initialDecision, decisionOwnsEffort) => {
// Without the request's execution budget a native child could not share its sends, so it
// keeps the bridge rather than opening a tracker of its own.
if (!isRequestExecutionBudget(targetSendBudget)) return undefined;
const route = settle(target, targetRoute);
if (!nativeEligible(target, route)) return undefined;
const body = envelope.freshBody();
body.model = selector(target);
if (inbound === "messages") return initialDecision ? undefined : { route, body, sendBudget: targetSendBudget };
applyDroidReasoningDefault(body, droidDefaultEffort, {
provider: targetRoute.provider,
modelId: targetRoute.modelId,
});
// `client` keeps the decision's target but not its tier, so the ordinary combo effort
// policy applies instead of the decision's effort.
if (initialDecision && decisionOwnsEffort) {
// A validated JEV choice owns only this first dispatch, including explicit no-effort.
// Do not run ordinary force defaults for null: they require a non-null default.
delete body.service_tier;
delete body.thinking_budget;
delete body.thinking;
const reasoning = body.reasoning;
if (reasoning && typeof reasoning === "object" && !Array.isArray(reasoning)) {
const preserved = { ...reasoning as Rec };
delete preserved.effort;
if (Object.keys(preserved).length > 0) body.reasoning = preserved;
else delete body.reasoning;
}
if (initialDecision.effort === null) delete body.reasoning_effort;
else body.reasoning_effort = initialDecision.effort;
} else applyComboEffort(body, config, comboId, target, targetRoute);
return { route, body, sendBudget: targetSendBudget };
},
};
}
/**
* The combo's reasoning-effort policy, applied to the Chat spelling of the same field.
*
* The bridge child gets it from `concreteComboRequestBody` on the Responses body; a native child
* must not lose a forced or default effort just because it skipped that body. The same function
* decides, through a one-field Responses view, so the two lanes cannot disagree.
*/
function applyComboEffort(
body: Rec,
config: OcxConfig,
comboId: string,
target: ComboTarget,
targetRoute: RouteResult,
): void {
const combo = getCombo(config, comboId);
if (!combo) return;
const ladder = supportedLadderFor({ provider: targetRoute.provider, modelId: targetRoute.modelId });
if (comboStripsReasoningControls(ladder, combo.reasoningEffortMode)) {
stripUnsupportedReasoningControls(body);
return;
}
// Same precedence as the Chat inbound parser (`resolveReasoningEffort`): a string
// `reasoning_effort` first, a string nested `reasoning.effort` second. A non-string top-level
// value (an explicit null) is no caller effort, so the nested one still decides.
const nested = body.reasoning && typeof body.reasoning === "object" && !Array.isArray(body.reasoning)
? (body.reasoning as Rec).effort
: undefined;
const hadEffort = Object.hasOwn(body, "reasoning_effort");
// With no string anywhere, a present top-level value (an explicit null) is passed on as before.
const callerEffort = typeof body.reasoning_effort === "string" ? body.reasoning_effort
// The parser reads a nested effort only when it is a level it knows; anything else is no effort.
: typeof nested === "string" && OUTPUT_CONFIG_EFFORTS.has(nested) ? nested
: hadEffort ? body.reasoning_effort : undefined;
const shaped = concreteComboRequestBody(
callerEffort !== undefined || hadEffort ? { reasoning: { effort: callerEffort } } : {},
target,
comboDefaultEffort(config, comboId),
ladder,
combo.reasoningEffortMode,
combo.defaultEffortMode,
);
const reasoning = shaped.reasoning;
if (reasoning === undefined) {
if (hadEffort) delete body.reasoning_effort;
return;
}
const effort = (reasoning as { effort?: unknown }).effort;
if (typeof effort === "string") body.reasoning_effort = effort;
if (comboAdvertisesEffortUnion(combo.capabilityPolicy, combo.reasoningEffortMode)) {
clampComboCallerEffort(body, ladder, target);
}
}
/** The combo's child callbacks, gated so a discarded attempt never reaches the parent. */
export interface ComboChildCallbacks {
onTerminal(status: ResponsesTerminalStatus): void;
onCancel(): void;
onResponseComplete(model: string): void;
}
/**
* Run one native child on the attempt the combo opened, and mark its client wire.
*
* The child's outcomes map onto the combo's existing child callbacks: a terminal or cancellation
* after the response was handed over publishes through the gate (and so reaches the parent's
* final-row owner only once the combo commits), while a failure answered before that is left to
* the combo's ordinary failure path. A non-OK answer produced after output was observed is marked
* non-replayable, so the combo stops instead of re-running a turn that already ran upstream.
*/
export async function dispatchNativeComboChild(input: {
source: ComboProtocolSource;
plan: NativeComboChildPlan;
comboDispatchPermit?: SingleUseDispatchPermit;
logCtx: RequestLogContext;
childLog: RequestLogContext;
attempt: PersistedUsageAttempt;
startedAt: number;
turnAdmissionLease?: AdmissionLease;
onFirstOutput: () => void;
callbacks: ComboChildCallbacks;
}): Promise<Response> {
const { plan, logCtx, childLog, attempt, startedAt, callbacks } = input;
const inbound = input.source.inbound;
childLog.providerAdapter = plan.route.provider.adapter;
markAttemptProtocolPath(attempt, {
mode: deliveryModeForLane(inbound, "native", inbound),
requestPath: requestPathForLane(inbound, "native", inbound),
});
let outputSeen = false;
const finishLog: NativeChatFinishLog = (status, message, closeReason = "non_stream") => {
if (message) childLog.upstreamError = redactSecretString(message).slice(0, 500);
if (closeReason !== "non_stream") {
// A streamed body ends after the combo merged this child into the parent row, so what the
// stream learned last is carried across here before the parent's row is written.
if (childLog.usage !== undefined) logCtx.usage = childLog.usage;
if (closeReason === "client_cancel") return callbacks.onCancel();
}
if (status < 400) {
callbacks.onTerminal("completed");
callbacks.onResponseComplete(plan.route.modelId);
return;
}
if (closeReason === "terminal") {
childLog.terminalHttpStatus = status;
callbacks.onTerminal("failed");
}
};
const attemptHandle: InferenceAttempt = {
attempt,
startedAt,
seal: label => sealRequestAttemptIdentity(attempt, childLog.provider, childLog.providerAdapter ?? attempt.adapter, label),
// A rotation inside the child seals the earlier account and moves the segment start forward.
finish: (status, usage) => finishRequestAttempt(attempt, status, Date.now() - (childLog.activeAttemptStartedAt ?? startedAt), usage),
};
const child = {
route: plan.route,
body: plan.body,
childLog,
attemptHandle,
sendBudget: plan.sendBudget,
comboDispatchPermit: input.comboDispatchPermit,
...(input.turnAdmissionLease ? { turnAdmissionLease: input.turnAdmissionLease } : {}),
onFirstOutput: () => {
outputSeen = true;
input.onFirstOutput();
},
};
let response: Response | undefined;
try {
response = await (input.source.inbound === "messages"
? input.source.dispatchNativeChild({ ...child, finishLog: (status, message, meta) => {
if (meta?.terminalStatus === "incomplete") {
childLog.terminalHttpStatus = status;
if (childLog.usage !== undefined) logCtx.usage = childLog.usage;
callbacks.onTerminal("incomplete");
return;
}
// A 200 stream whose terminal was an upstream error event did not complete.
if (childLog.streamErrorStatus !== undefined && status < 400) return finishLog(childLog.streamErrorStatus, message, "terminal");
finishLog(status, message, meta?.closeReason === "client_cancel" ? "client_cancel"
: meta?.closeReason && meta.closeReason !== "non_stream" ? "terminal" : "non_stream");
} })
: input.source.dispatchNativeChild({ ...child, finishLog }));
} finally {
// A failed child's copy is spent; the next target takes its own, so this charge must not outlive it.
if (!response?.ok) input.source.envelope.releaseBody(plan.body);
}
if (!response.ok && outputSeen) markResponseNonReplayable(response);
return markClientWire(response, inbound);
}