@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
404 lines (390 loc) • 23.7 kB
text/typescript
import type { ClientFacingModelLabel } from "../../lib/error-destination";
import type { HostedAdvisorSelection } from "../../claude/inbound-content-options";
import type { CodexAccountModelRefusal } from "../../combos/failover";
import type { NativeResponseControl } from "./native-response-control";
import type { AdapterEvent, OcxUsage, OcxProviderContinuationState, OcxConfig, OcxProviderConfig, OcxVisionSidecarConfig } from "../../types";
import type { RouteResult } from "../../router";
import type { SingleUseDispatchPermit } from "../../lib/request-execution-budget";
import type { CodexAuthPolicyConfig, CodexAuthContext } from "../../codex/auth-context";
import type { AdmissionLease } from "../../lib/admission";
import type { DataPlaneAdmission } from "../auth-cors";
import type { AdmissionModelScope } from "../admission-model-scope";
import type { resolveCodexModelEntitlements } from "../../codex/model-entitlements";
import type { ResponsesTerminalStatus } from "../../bridge";
import type { ResponsesTerminalRepairScheduler } from "../responses-terminal-repair";
import type { BunRuntimeGateInput } from "./ws-upstream";
import type { NativeMainRefreshDependencies } from "../../codex/main-account";
import type { InboundWire } from "../../providers/registry";
import type { ExplicitOpenAiCallerAuth } from "../../providers/openai-sidecar";
import type { CallerDirectAuth } from "../../providers/caller-authorization";
import type { CompactionRoutingOverride } from "./compaction-routing";
import type { MainHardLockFallbackOverride } from "./main-hard-lock-routing";
import type { TranslatorBudget } from "../../lib/translator-budget";
import type { NativeReasoningOwner } from "../../responses/reasoning-replay-cache";
import type { TransientSendBudget } from "../../lib/upstream-retry";
import type { RequestLogContext } from "../request-log";
import type { UpstreamHostAdmissionLease } from "../../codex/upstream-host-health";
import type { AccountLease } from "../../oauth/kiro-account-load";
import type { PolicyRequestScope } from "./policy-request-scope";
import type { SpendAdmissionPolicy } from "../../lib/spend-reservation-ledger";
import type { OcxParsedRequest } from "../../types";
import type { PolicyRequestEvidence } from "../../routing/evaluator";
import type { ConnectionReplayScope } from "../../responses/state/connection-scope";
export interface HostedAdvisorSpendScope {
readonly ceilings: SpendAdmissionPolicy;
optionalWithheld: boolean;
}
export interface ConsumedComboFailure {
response: Response;
classificationText: string;
/** Complete bounded-envelope evidence captured before display truncation; never serialized. */
codexModelRefusal?: CodexAccountModelRefusal;
/** Complete bounded-envelope malformed response_format diagnostic verdict captured before display truncation. */
malformedResponseFormat?: boolean;
/** Complete bounded-envelope OpenRouter opaque-400 verdict captured before display truncation. */
openRouterOpaque400?: boolean;
/** Complete bounded-envelope unoffered-tool-call verdict captured before display truncation. */
unofferedToolCallRefusal?: boolean;
/** Complete bounded-envelope provider moderation verdict captured before display truncation. */
providerModerationRefusal?: boolean;
/** Complete bounded-envelope provider-413 intake verdict captured before display truncation. */
providerIntakeRefusal?: boolean;
/** Structured upstream `error.code` when present in the failure body. */
upstreamCode?: string;
/**
* The envelope root's own structured code when it differs from {@link upstreamCode}.
*
* `normalizeUpstreamErrorText` selects the nested record first, so a root verdict would
* otherwise never reach the combo decision. Both transports pass it, and the decision hops
* only when the root and the record each would.
*/
upstreamRootCode?: string;
/** Sanitized structured `error.message`; compared only against proxy-owned constants, never emitted. */
upstreamMessage?: string;
/** Complete structured provider type, retained for conservative recovery classification. */
upstreamType?: string;
/** Valid numeric/date value used only for cooldown calculation. */
retryAfter?: string;
/** Upstream Codex quota-window reset timestamps used for combo cooldowns. */
resetAt?: string[];
/** Reserved for 040 usage attribution without adding another body read. */
usage?: OcxUsage;
/**
* The failed attempt's response was marked non-replayable, such as the answer to a spent
* ambiguous-reset replacement. The re-wrapped {@link response} cannot carry that in-memory
* marker, so the combo loop reads it here and stops instead of sending the turn to a later target.
*/
nonReplayable?: boolean;
/** The failed attempt was an adapter-normalized plan refusal; only this grants its combo hop. */
verifiedPlanRefusal?: boolean;
}
/**
* Direct client encoding for a translated Chat or Messages turn (PF-09). `model` is the model
* string the client asked for, which every client frame carries; `inputTokenFloor` is the
* Messages prompt estimate `message_start` reports when no usage arrived first (#4857).
*/
export interface ClientEncoderOption {
protocol: "chat" | "messages";
stream: boolean;
model: string;
inputTokenFloor?: number;
/** Chat only: the client set `stream_options.include_usage`. */
includeUsage?: boolean;
/**
* `direct` when the request side also skipped the internal Responses body (the Antigravity
* direct lane), so the attempt's request path is traced as `[inbound, ir, upstream]`.
*/
requestLane?: "bridge" | "direct";
}
/**
* The Antigravity direct lane (`protocols.rollout.antigravityDirect`). The ingress sends the core
* a Responses body that carries only the request settings; the conversation is decoded straight
* from the client body. Request preparation applies `decode` at the parse seam, reads routing
* evidence from `evidence`, and calls `restoreBridgeConversation` if the final route is not the
* one the lane was decided for, so every `_rawBody` reader of another adapter sees the full
* bridge body.
*/
export interface DirectRequestOption {
protocol: "chat" | "messages";
/** The concrete route the ingress decided the lane for. */
providerName: string;
modelId: string;
/** Policy-routing evidence from the client body; the settings-only body has no `input`. */
evidence: PolicyRequestEvidence;
/** The settings-only parse with the directly decoded conversation in place of its empty one. */
decode(base: OcxParsedRequest): OcxParsedRequest;
/** The bridge projection's conversation fields (`input`, `instructions`, `tools`). */
bridgeConversation(): Record<string, unknown>;
}
export interface HandleResponsesOptions {
/** Original caller label, carried through synthetic children without route substitution. */
clientModelLabel?: ClientFacingModelLabel;
/** Original client envelope label when a combo was selected by a synthetic rewrite. */
clientResponseModelLabel?: ClientFacingModelLabel;
/** Immutable caller scope inherited by a capability-authenticated internal sidecar request. */
admissionScope?: AdmissionModelScope;
/** Captured synchronously at ingress, before parsing or child replay can suspend. */
advisorAdmissionPolicy?: import("../../types/admission-policy").CapturedAdmissionPolicy;
/** Internal request-owned policy authorization; never read from client headers or body. */
policyRequestScope?: PolicyRequestScope;
/** Internal concrete selector chosen from the original policy evaluation. */
policyFallbackCandidate?: { provider: string; model: string };
/** Internal routed-compaction recovery: one logical request, one emergency target. */
compactionRecoveryAttempted?: boolean;
compactionRecoveryPermit?: SingleUseDispatchPermit;
compactionRecoveryKind?: "compaction-v1" | "compaction-v2";
onCompactionRecoveryRoute?: (route: RouteResult) => void;
onCompactionRecoveryAdapterEvent?: (event: AdapterEvent) => void;
/** Physical-send reports already delivered to the shared ledger, including exact booking settlement. */
onCompactionRecoverySendsReported?: (count: number) => void;
/** Private holder for the Kiro serving-account lease. */
accountLoad?: { lease: AccountLease | null; cancelled: boolean };
/** Internal Claude replay identity; consumed only by the final canonical Go transport. */
claudeGoAffinity?: { sessionLane?: string };
/** Validated Claude metadata identity; projected only into final canonical attempt headers. */
claudeNativeSessionId?: string;
/** Private Claude bridge pool identity (validated, principal-scoped when derived); completes session-id/thread-id only on Codex account-selection headers. */
claudeBridgePoolSession?: string;
/** Original live policy owner; separate from caller-specific routing/sidecar snapshots. */
codexAuthPolicy?: CodexAuthPolicyConfig;
turnAdmissionLease?: AdmissionLease;
/**
* A JEV decision-model call issued by a combo. It never carries caller credentials, is never
* rewritten by memory or shadow-call routing, and may not dispatch into a JEV combo.
*/
internalDecisionCall?: boolean;
/**
* How the caller proved data-plane admission (#1686).
*
* A bearer-presented admission secret is one of OUR OWN secrets, so a Direct turn must
* SUBSTITUTE the stored main credential rather than forward it. Without this fact at the
* decision point, Direct cannot tell an admission bearer from the user own ChatGPT bearer,
* which is why it refused the whole env_key flow instead of serving it.
*/
admission?: DataPlaneAdmission;
/**
* Internal caller identity captured before Combo strips provisional credentials. An existing
* holder with no principal preserves keyless replay; never populate it from client data.
*/
replayPrincipal?: Readonly<{ clientPrincipalId: string | undefined }>;
/**
* Internal connection-owned replay scope minted by the /v1/responses WebSocket upgrade for an
* unidentified loopback caller (src/responses/state/connection-scope.ts). Memory-only, bound to
* that socket's handshake thread, never sent to the client. It backfills only the replay owner
* key when no caller principal resolved; it is not a credential, grants no data-plane, history
* or notes authority, and must never be populated from client data.
*/
replayScope?: ConnectionReplayScope;
/** Captured for the logical request and inherited by retries and combo children. */
readonly plaintextV2Decision?: boolean;
/** Called at most once after the complete client body is read and accepted for dispatch. */
onRequestBodyRead?: () => void;
/** Internal handoff for retry wrappers that must reuse the already-accounted request body. */
onRequestBodyParsed?: (body: unknown) => void;
forceEmptyResponseId?: boolean;
/** Internal, connection-owned control channel; never reconstructed from headers. */
nativeControl?: NativeResponseControl;
/** A Remote Link WebSocket turn: told the expanded input and the terminal (src/server/link-turn.ts). */
linkTurn?: import("../link-turn").LinkTurnObserver;
abortSignal?: AbortSignal;
/** One-shot TTFT callback: first non-empty model output observed (WP4). */
onFirstOutput?: () => void;
onCodexAuthContextResolved?: (context: CodexAuthContext | undefined) => void;
/** Internal deterministic seam for account-gated native fallback tests. */
resolveCodexModelEntitlements?: typeof resolveCodexModelEntitlements;
/** Internal: validated final client-visible model, after completed terminal success only. */
onResponseComplete?: (model: string) => void;
recordTerminalOutcomes?: boolean;
setTerminalOutcomeRecorder?: (recorder: ((status: ResponsesTerminalStatus, httpStatusOverride?: number) => void) | undefined) => void;
onNativePassthroughTerminal?: (status: ResponsesTerminalStatus) => void;
onNativePassthroughCancel?: () => void;
/** Internal deterministic clock/timer seam for provider terminal repair. */
responsesTerminalRepairScheduler?: ResponsesTerminalRepairScheduler;
/** Internal deterministic runtime-identity seam for Codex upstream WS selection tests. */
codexWsRuntimeIdentity?: BunRuntimeGateInput;
/** Test seam for native main refresh without live OAuth traffic. */
nativeMainRefreshDependencies?: NativeMainRefreshDependencies;
/**
* When true, body `prompt_cache_key` is a Claude Desktop shared cache cohort
* (system/tools hash), not a per-session id — do not use it for Anthropic pool affinity.
*/
promptCacheKeyIsSharedCohort?: boolean;
/**
* Wire protocol the ORIGINAL client spoke. The Chat and Anthropic surfaces translate
* their body into a Responses shape and replay through this function, so without an
* explicit value the replay would look like a native Responses request and an
* inbound-scoped registry wire default would fire for a client that never asked for
* it. Omitted means a genuine Responses inbound.
*/
inboundWire?: InboundWire;
/**
* Set by a translating ingress (Chat / Anthropic) when the client sent an explicit empty
* tool catalog. Those wires may defer tool delivery, so their translated body carries no
* readable catalog boundary; an explicit `[]` is still a deny-all declaration and the
* undeclared-tool guard enforces it. Absent catalogs and partial catalogs stay deferred.
*/
clientDeclaredEmptyToolCatalog?: boolean;
nativeReasoningReplay?: ReadonlyMap<string, string>;
nativeReasoningMint?: { owner?: NativeReasoningOwner };
/** The Claude client's typed `web_search_*` / `web_fetch_*` declarations; kept only for `inboundWire: "anthropic"`. */
anthropicServerTools?: readonly Record<string, unknown>[];
/** The original Messages choice names a typed hosted Advisor, possibly with a duplicate name. */
anthropicHostedAdvisorSelection?: HostedAdvisorSelection;
/** Hosted work shares this state across routing candidates and translated combo children. */
hostedAdvisorSpendScope?: HostedAdvisorSpendScope;
/** The Claude client's replayable server-tool exchanges (`replayedAnthropicServerBlocks`); same scope. */
anthropicServerReplay?: ReadonlyMap<string, readonly Record<string, unknown>[]>;
/** The caller's cached system prefix (`systemCachePrefix`); same scope. */
anthropicSystemCachePrefix?: string;
/** Metadata-qualified Messages discovery evidence, never caller JSON or a preselected destination. */
anthropicToolLoadingSource?: Readonly<Record<string, unknown>>;
/** Droid's per-request effort default; each concrete combo or policy target applies it only if its ladder allows it. */
droidDefaultEffort?: string;
/** The Chat or Messages source a combo child may send natively; set only by that ingress. */
protocolSource?: import("./core-combo-native").ComboProtocolSource;
/** Internal transport identity for route-scoped upstream compatibility policy. */
inboundTransport?: "websocket";
/** ACP refusal signal captured from the original HTTP request, before any bridge translation. */
agyAcpUnattendedHttpTurn?: boolean;
/**
* Set by the HTTP `/v1/responses` ingress only: a streaming combo turn whose target selection
* outlasts `COMBO_SELECTION_KEEPALIVE_THRESHOLD_MS` commits a 200 SSE head and sends keepalive
* comments (#8326). `clock` is a test seam; production uses the global timers.
*/
comboSelectionKeepalive?: {
clock?: { setTimeout(callback: () => void, ms: number): unknown; clearTimeout(handle: unknown): void };
};
/**
* Claude replay may add native-main auth so OpenAI sidecars remain available.
* Strip only that internal credential when the final route is a noncanonical
* forward/caller-auth destination; final routing can differ from Claude's preflight route.
*/
stripClaudeMainAuthForNoncanonicalForward?: boolean;
/** In-memory credential proven by Claude's native-main turn claim; never persist or log. */
trustedClaudeMainAuth?: { authorization: string; chatgptAccountId?: string };
/** Sidecar-only auth captured before route changes; null means no usable original pair. */
openAiSidecarAuth?: ExplicitOpenAiCallerAuth | null;
/** Internal Chat bridge permission to obtain claimed stored auth only for a final Direct sidecar. */
allowStoredOpenAiSidecarAuth?: boolean;
/** Original caller-owned native pair; separate from any claimed sidecar enrichment. */
nativeCallerAuth?: ExplicitOpenAiCallerAuth | null;
/** Caller Direct credential under Direct\'s own predicate; restored only for the canonical OpenAI final route. */
callerDirectAuth?: CallerDirectAuth | null;
/** Internal recursion guard; callers outside this module must not set it. */
comboAttempt?: boolean;
/** `union` combo with no member whose window fits: the child keeps the loose direct admission. */
comboContextDegraded?: boolean;
/** A union combo admitted this image-bearing child through a dispatchable vision plan. */
comboRequiresVisionPlan?: boolean;
/** The union combo exhausted its image-serving targets and selected omission. */
comboOmitImages?: boolean;
/**
* The request-start Vision Sidecar settings the combo admitted this request under. Vision
* planning reads `settings` instead of the live `visionSidecar`, so an edit made while the
* request is in flight applies to the next request. Credentials still resolve from live config.
*/
comboVisionSidecar?: { settings: OcxVisionSidecarConfig | undefined };
/**
* Set by the combo loop for each child. A child logs into its own context, which the combo
* copies once when the child commits, and the bridge reports usage after that, at the terminal
* frame. The transport calls this when it binds that usage on the child's context, so the combo
* can carry the binding to the context that writes the row.
*/
onBridgeUsageBound?: () => void;
/** A web-search deadline has been recorded on the child before its failure is emitted. */
onWebSearchLocalFailure?: () => void;
onHostedWebSearchStream?: () => void;
/** Child-owned prepaid initial send; capacity remains charged until dispatch or unsent release. */
comboInitialSend?: { permit: SingleUseDispatchPermit; producerOwned?: boolean };
/** Exact externally booked combo hop, used for its child's spend preflight and send reports. */
comboDispatchPermit?: SingleUseDispatchPermit;
/** Internal handoff: this combo was selected by shadow-call interception. */
shadowCallIntercepted?: boolean;
/** Internal handoff: the memory phase this turn belongs to, so combo children keep its routing. */
memoryModelPhase?: "extract" | "consolidation";
compactionRoutingOverride?: CompactionRoutingOverride | null;
/** Internal handoff: the hard-lock fallback rewrote this turn; the log shows `sourceModel`. */
mainHardLockFallbackOverride?: MainHardLockFallbackOverride | null;
/** Internal combo handoff for one parent-validated continuation snapshot. */
comboReplaySnapshot?: {
sourceBody: unknown;
previousResponseInputExpanded: boolean;
providerContinuation: OcxProviderContinuationState | undefined;
recoveredPlaintext: boolean;
};
/** Internal combo handoff: allow a later same-provider model after a reset-derived 429/402. */
deferCodexResetDerivedCooldown?: boolean;
/** 030-owned handoff when a child consumed the original failure under bounds. */
onConsumedComboFailure?: (failure: ConsumedComboFailure) => void;
/** A stored Pool credential was refreshed and its one allowed same-account replay was sent. */
onStoredPool401ReplayDispatched?: () => void;
/** Caller-owned for Chat/Claude replay; omitted only at genuine Responses ingress. */
translatorBudget?: TranslatorBudget;
/**
* Transient sends already spent by this logical request. Combo children inherit the parent's
* holder through the options spread, so a fan-out shares one allowance instead of taking a
* fresh one per target (#4546).
*/
sendBudget?: TransientSendBudget;
/**
* Terminal vision-describe marker (roadmap 180): true when the inbound
* request IS the vision sidecar's own loopback describe call. The plan site
* then STRIPS images instead of planning another describe — a depth cap of 1
* that holds under predicate drift and combo re-resolution. The Chat surface
* detects the raw `x-opencodex-vision-describe` header before its bridge
* rebuilds headers and carries the fact through this flag.
*/
visionDescribeTerminal?: boolean;
/**
* Terminal advisor marker: true when the inbound request IS the advisor sidecar's own loopback
* consultation. The advisor planner then never plans a consultation — a depth cap of 1 that
* keeps Worker → Advisor → Advisor recursion impossible (same structure as
* {@linkcode visionDescribeTerminal}). The Chat surface validates the capability and registered
* policy before its bridge rebuilds headers and carries the fact through this flag.
*/
advisorInternal?: boolean;
/** A local Chat helper authenticated through its registered process capability. */
internalSidecarCall?: boolean;
/**
* Set only by the Chat and Messages ingresses when `protocols.rollout.directEncoders` is on and
* the settled route is one non-Responses target. Adapter delivery then encodes the adapter
* events straight into the client's wire and returns a response marked with `markClientWire`.
* Passthrough, run-turn adapters, combo children and compaction turns ignore it and keep
* returning a Responses body, which the ingress converts as before.
*/
clientEncoder?: ClientEncoderOption;
/** Chat ingress raw-channel delivery preference; never an upstream generation option. */
chatRawReasoningVisible?: boolean;
/** Value-free fact retained before Chat instruction content is projected to text. */
chatInstructionImage?: boolean;
/** Original Responses instruction image, retained across preprocessing and combo replay. */
responsesInstructionImage?: boolean;
/** File-backed Responses image retained before parsing and replay. */
responsesFileImage?: boolean;
/** Set only by the Chat or Messages ingress on an eligible Antigravity route; see {@link DirectRequestOption}. */
directRequest?: DirectRequestOption;
}
/** The internal Responses handoff for /responses/compact keeps the endpoint's global budgets. */
export function responsesTimeoutProvider(options: HandleResponsesOptions, provider: OcxProviderConfig): OcxProviderConfig | undefined {
return options.compactionRecoveryKind === "compaction-v1" ? undefined : provider;
}
/** Values shared by the call, not a bag of mutable pipeline state. */
export interface ResponsesRequestContext {
req: Request;
config: OcxConfig;
logCtx: RequestLogContext;
options: HandleResponsesOptions & { translatorBudget: TranslatorBudget };
}
/** Admission leases remain owned by the outer finally until explicitly transferred. */
export interface ResponsesAdmissionState {
pendingHostAdmissionLease: UpstreamHostAdmissionLease | null;
authCtx: CodexAuthContext;
}
export interface PassthroughAdmissionState {
lease: UpstreamHostAdmissionLease | null;
}
/** Recursive combo children enter the same ingress without a runtime import cycle. */
export interface ResponsesDispatchers {
handleResponses(req: Request, config: OcxConfig, logCtx: RequestLogContext, options?: HandleResponsesOptions): Promise<Response>;
handleComboResponses(req: Request, body: unknown, comboId: string, config: OcxConfig, logCtx: RequestLogContext, options: HandleResponsesOptions & { translatorBudget: TranslatorBudget }): Promise<Response>;
}