@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
214 lines (203 loc) • 11.8 kB
text/typescript
import type { NativeResponseControl } from "./native-response-control";
import type { AdapterEvent, OcxUsage, OcxProviderContinuationState, OcxConfig } 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 { 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 { TranslatorBudget } from "../../lib/translator-budget";
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";
export interface ConsumedComboFailure {
response: Response;
classificationText: string;
/** Structured upstream `error.code` when present in the failure body. */
upstreamCode?: 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;
}
/**
* 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;
}
export interface HandleResponsesOptions {
/** 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 used setter, including booking settlement. */
onCompactionRecoverySendsReported?: (count: number) => void;
/** Private holder for the Kiro serving-account lease. */
accountLoad?: { lease: AccountLease | null };
/** 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;
/** Original live policy owner; separate from caller-specific routing/sidecar snapshots. */
codexAuthPolicy?: CodexAuthPolicyConfig;
turnAdmissionLease?: AdmissionLease;
/**
* 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;
/** 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;
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;
/** PF-07: the Chat source a combo child may send natively; set only by the Chat ingress. */
protocolSource?: import("./core-combo-native").ComboProtocolSource;
/** Internal transport identity for route-scoped upstream compatibility policy. */
inboundTransport?: "websocket";
/**
* 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;
/** 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 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;
/**
* 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;
}
/** 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>;
}