import type { CodexCompactionRequestContext, Context, Model, ProviderSessionState, RawSseEvent, ServiceTier, StreamFunction, StreamOptions, Tool, ToolChoice } from "../types.js"; import { type HeadersLike } from "../utils/retry-after.js"; import { type CodexLiteShapedBody, type CodexReasoningContext, type InputItem, type ReasoningConfig, type RequestBody } from "./openai-codex/request-transformer.js"; import { type CodexAcceptedSteer, type CodexSteerAck } from "./openai-codex/live-steering.js"; export { createOpenAICodexCompactionRequestContext } from "./openai-codex-compaction.js"; export { setCodexAttestationProvider } from "./openai-codex-attestation.js"; export type { CodexAttestationProvider } from "./openai-codex-attestation.js"; import { type OpenAIEffortControlState } from "./openai-configuration-update.js"; import type { ResponseInput } from "./openai-responses-wire.js"; export interface OpenAICodexResponsesOptions extends StreamOptions { reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; /** * Run with the least reasoning the model allows; takes precedence over * `reasoning`. Sends the `none` tier where the catalog's disable mode is * `none-effort`, else the model's lowest supported effort. */ disableReasoning?: boolean; reasoningSummary?: "auto" | "concise" | "detailed" | null; /** Explicit `reasoning.context` replay scope. Omitted by default so Codex applies its native request policy. */ reasoningContext?: CodexReasoningContext; textVerbosity?: "low" | "medium" | "high"; codexMode?: boolean; toolChoice?: ToolChoice; preferWebsockets?: boolean; serviceTier?: ServiceTier; /** * Responses Lite transport opt-in. Normal inference defaults to full * Responses; provider-native compaction explicitly follows the model's * `useResponsesLite` flag. */ responsesLite?: boolean; /** * Additional fields embedded in the canonical * `client_metadata["x-codex-turn-metadata"]` JSON blob. Reserved identity * keys are ignored; extras are never emitted as top-level metadata fields. */ clientMetadata?: Record; /** * Turn id of the initiating (parent) Codex turn for nested requests such as * subagent spawns (codex-rs `parent_turn_id`, #35835). Emitted both as the * flat `client_metadata.parent_turn_id` key and inside the * `x-codex-turn-metadata` JSON blob; blank values are ignored. The key is * reserved: `clientMetadata` extras cannot supply it. */ parentTurnId?: string; /** * Invoked when the server streams a `response.metadata` event carrying * ChatGPT moderation metadata (`metadata.openai_chatgpt_moderation_metadata`) * for first-party presentation parity. Diagnostic observer: failures are * swallowed and must not alter the stream. */ onModerationMetadata?: (metadata: unknown) => void; } /** Raw V2 compaction body accepted by the Codex transport selector. */ export interface OpenAICodexCompactionBody extends CodexLiteShapedBody { model: string; [key: string]: unknown; } /** Transport controls for a provider-native Codex V2 compaction stream. */ export interface OpenAICodexCompactionStreamOptions extends OpenAICodexResponsesOptions { apiKey: string; } /** Inputs for synthesizing Codex request identity outside the normal stream path. */ export interface OpenAICodexCompatibilityMetadataOptions { sessionId?: string; providerSessionState?: Map; requestKind: OpenAICodexRequestKind; compaction?: CodexCompactionRequestContext; startNewTurn?: boolean; turnStartedAtUnixMs?: number; clientMetadata?: Readonly>; /** Parent Codex turn id for nested requests; see {@link OpenAICodexResponsesOptions.parentTurnId}. */ parentTurnId?: string; /** Add the direct installation header required by `/responses/compact`. */ includeInstallationHeader?: boolean; } /** Canonical Codex body metadata and compatibility headers for one request. */ export interface OpenAICodexCompatibilityMetadata { clientMetadata: Record; headers: Record; } export type CodexTransport = "sse" | "websocket"; /** Shape of the Codex request sent on the latest provider turn. */ export interface OpenAICodexTurnRequestDiagnostics { transport: "sse" | "websocket"; previousResponseIdPresent: boolean; inputItemCount: number; inputItemTypes: string[]; firstInputItemType?: string; inputJsonBytes: number; promptCacheKey?: string; toolsHash?: string; optionsHash: string; canAppendBeforeRequest: boolean; } /** Raw provider usage plus the normalized buckets OMP displays for the latest Codex turn. */ export interface OpenAICodexTurnUsageDiagnostics { rawInputTokens: number; rawCachedTokens: number; rawUncachedTokens: number; rawOutputTokens: number; rawTotalTokens?: number; rawOrchestrationInputTokens?: number; rawOrchestrationCachedTokens?: number; rawOrchestrationOutputTokens?: number; displayedInputTokens: number; displayedOutputTokens: number; displayedCacheReadTokens: number; displayedCacheWriteTokens: number; displayedTotalTokens: number; displayedOrchestrationInputTokens: number; displayedOrchestrationCacheReadTokens: number; displayedOrchestrationOutputTokens: number; } /** Latest Codex turn request/usage diagnostics exposed to debug UIs and tests. */ export interface OpenAICodexTurnDiagnostics { request: OpenAICodexTurnRequestDiagnostics; usage?: OpenAICodexTurnUsageDiagnostics; } /** * Per-session request-shape counters and latest turn diagnostics. Despite the * name, these cover both transports. */ export interface OpenAICodexWebSocketDebugStats { fullContextRequests: number; deltaRequests: number; lastInputItems: number; lastDeltaInputItems?: number; lastPreviousResponseId?: string; lastTurn?: OpenAICodexTurnDiagnostics; } /** * Per-session transport state shared by both transports: WebSocket turn * chaining, models-etag headers, connection pooling, and debug stats. The name * is historical — SSE-only sessions use it too. */ export type CodexWebSocketSessionState = { sessionId: string; disableWebsocket: boolean; lastRequest?: RequestBody; /** Last completed response; an in-progress response cannot replace the retry baseline. */ lastResponseId?: string; lastResponseItems?: InputItem[]; canAppend: boolean; modelsEtag?: string; connection?: CodexWebSocketConnection; /** * Steering the server accepted on `connection` for `lastResponseId`. The * next request reads the server's automatic successor or sends only the * pending tool output; see {@link planSteeredRequest}. */ acceptedSteering?: { connection: CodexWebSocketConnection; steers: CodexAcceptedSteer[]; }; /** The server refused steering for this session (native turn lane); later responses are not steered. */ steeringUnsupported?: boolean; lastTransport?: CodexTransport; fallbackCount: number; lastFallbackAt?: number; prewarmed: boolean; stats: OpenAICodexWebSocketDebugStats; }; interface CodexTurnStateCell { value?: string; } export interface CodexProviderSessionState extends ProviderSessionState { webSocketSessions: Map; webSocketPublicToPrivate: Map; metadataSessions: Map; /** `configuration_update` effort baselines, keyed by model + session. */ effortControls: Map>; } /** Request classification encoded in Codex turn metadata. */ export type OpenAICodexRequestKind = "turn" | "prewarm" | "compaction"; interface CodexMetadataSessionState { sessionId: string; threadId: string; windowId: string; turnId?: string; turnStartedAtUnixMs?: number; compactionOperationId?: string; reuseTurnForNextRequest?: boolean; turnStates: Map; } /** * Synthesize Codex request identity for raw provider routes such as remote * compaction while reusing the live session's thread, window, and turn. */ export declare function createOpenAICodexCompatibilityMetadata(options: OpenAICodexCompatibilityMetadataOptions): OpenAICodexCompatibilityMetadata; /** @internal Exported for tests. */ export declare function normalizeCodexToolChoice(choice: ToolChoice | undefined, tools?: Tool[], model?: Model<"openai-codex-responses">): string | Record | undefined; /** Serialize normal Codex turns and V2 compaction with the same cacheable prefix. */ export declare function buildTransformedCodexRequestBody(model: Model<"openai-codex-responses">, context: Context, options: OpenAICodexResponsesOptions | undefined, promptCacheKey?: string | undefined, inputPrefix?: InputItem[]): Promise; /** * Open a provider-native V2 compaction stream through Codex's WebSocket-first * transport, replaying WebSocket transport failures over SSE. */ export declare function openCodexCompactionEventStream(model: Model<"openai-codex-responses">, body: OpenAICodexCompactionBody, options: OpenAICodexCompactionStreamOptions): Promise>>; export declare const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses">; export declare function prewarmOpenAICodexResponses(model: Model<"openai-codex-responses">, options?: Pick): Promise; interface CodexWebSocketRequestTimeouts { idleTimeoutMs?: number; firstEventTimeoutMs?: number; } /** What {@link CodexWebSocketConnection.streamRequest} puts on the wire before reading a response. */ type CodexWebSocketExchange = { send: Record; } /** Read the successor the server creates from accepted steering; nothing is sent. */ | { attachSteerIds: readonly string[]; }; interface CodexWebSocketConnectionOptions { onHandshakeHeaders?: (headers: Headers) => void; proxy?: string; } /** Codex steering and legacy error boundary around the shared physical channel. */ declare class CodexWebSocketConnection { #private; constructor(url: string, headers: Record, options: CodexWebSocketConnectionOptions); isOpen(): boolean; isConnecting(): boolean; /** True while a handshake is in flight or a request owns or has reserved this socket. */ isBusy(): boolean; hasActiveRequest(): boolean; /** True while a request stream owns this socket or a request has reserved it. */ isReserved(): boolean; /** * Reserve the socket for a request that selected it but has not started * streaming yet (e.g. while `onPayload` runs). The reservation only keeps * prewarm and routing-hint reconnects off the socket; concurrent turns still * race for it, and the first to start streaming wins (the other falls back to * SSE). Pass the returned release to {@link streamRequest}, which drops the * reservation once it owns the socket; callers that never iterate that stream * MUST call the release themselves, or the socket stays reserved until * {@link close}. */ reserveForRequest(): () => void; isHealthyForReuse(): boolean; matchesAuth(headers: Record): boolean; matchesRoutingHint(headers: Record): boolean; close(reason?: string): void; connect(signal?: AbortSignal): Promise; streamRequest(exchange: CodexWebSocketExchange, timeouts: CodexWebSocketRequestTimeouts, signal?: AbortSignal, onSseEvent?: (event: RawSseEvent) => void, onOwned?: () => void, releaseReservation?: () => void): AsyncGenerator>; /** Submit steering on the current socket, even between response readers. */ steer(previousResponseId: string, input: InputItem[]): Promise; hasFailedSteer(ids: readonly string[]): boolean; } /** Resolve a Codex Responses endpoint exactly as the chat and compaction transports do. */ export declare function resolveCodexResponsesUrl(baseUrl: string | undefined): string; declare function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput; /** @internal Exported for tests. */ export { convertMessages as convertCodexResponsesMessages }; type CodexToolPayload = { type: "computer"; name?: never; } | { type: "function"; name: string; description: string; parameters: Record; strict?: boolean; } | { type: "custom"; name: string; description: string; format: { type: "grammar"; syntax: "lark" | "regex"; definition: string; }; }; /** @internal Exported for tests. */ export declare function convertOpenAICodexResponsesTools(tools: Tool[], model: Model<"openai-codex-responses">): CodexToolPayload[]; export declare class CodexWebSocketTransportError extends Error { constructor(detail: string, options?: ErrorOptions); } declare class CodexProviderStreamError extends Error { readonly retryable: boolean; readonly code?: string; readonly headers?: HeadersLike; constructor(message: string, retryable: boolean, code?: string, headers?: HeadersLike); } export declare function isRetryableCodexFailureEvent(rawEvent: Record): boolean; export declare function createCodexProviderStreamError(rawEvent: Record): CodexProviderStreamError;