UNPKG

@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
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>; }