UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

485 lines (460 loc) • 21.5 kB
import type { KiroOAuthMetadata } from "../oauth/types"; import type { OcxTool, OcxToolChoice } from "./tools"; import type { TierDecision, TierObservationContext } from "./provider"; /** Exact provider/credential namespace for process-local reasoning replay. */ export interface OcxReasoningReplayIdentity { providerName: string; /** Opaque process-local digest of the exact upstream destination. */ providerDestinationIdentity: string; /** * The same destination, digested WITHOUT the process-local random key, so it can key a * durable store. Absent when no base URL was resolvable. */ providerDestinationDurableIdentity?: string; adapterName: string; modelId: string; /** Opaque process-local credential identity; never a raw token or API key. */ credentialIdentity: string; /** * Salted-HMAC credential identity that survives restarts, for the durable * thought-signature store (#1926). Absent when no durable identity could be * derived — the durable store then refuses to key the entry (fail closed). */ credentialDurableIdentity?: string; } /** * Stable holder shared by parsed-request copies and already-created bridges. * Credential/provider rotation replaces `current` atomically without replacing * the holder, so late tool-call cache writes see the active physical identity. */ export interface OcxReasoningReplayScopeRef { /** * Process-local caller principal from resolveContextPrincipal. Absent when the caller presented * no identity (keyless loopback); replay state keyed by it then fails closed. */ readonly clientPrincipalId?: string; /** * Conversation namespace for replay state. Historically this was always the Codex parent-thread * id; headerless Responses callers use a raw sanitized thread/Cursor/session fallback, never the * hashed request-log conversation id. */ readonly clientThreadId: string; current?: Readonly<OcxReasoningReplayIdentity>; } export interface OcxParsedRequest { modelId: string; /** Client-facing model selector retained for Anthropic routes after wire-model normalization. */ _responseModelId?: string; /** Selected OpenAI API virtual-model id retained after it rewrites the upstream wire model. */ _openAiVirtualSelectedModelId?: string; /** Serialized-only model id (xAI OAuth Fast lane); policy keeps reading `modelId`. */ _wireModelOverride?: string; previousResponseId?: string; context: OcxContext; stream: boolean; options: OcxRequestOptions; _rawBody?: unknown; /** * Boundary between replayed history and this turn's newly appended input. Usually the * items the proxy restored from local previous_response_id state; also set when the * CLIENT already carried that history verbatim and the proxy skipped the prepend. */ _replayPrefixLen?: number; /** Parsed-message index before the first conversational item in a continuation's current delta. */ _continuationConversationMessageIndex?: number; /** * True when the full history for a previous_response_id request is present in the input — * whether the proxy expanded it or the client already sent it. Consumers read this as * "this request is self-contained", never as "the proxy mutated it". */ _previousResponseInputExpanded?: boolean; /** Provider-private stable Cursor conversation id resolved from the Responses previous_response_id chain. */ _cursorConversationId?: string; /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */ _clientThreadId?: string; /** * This request's OWN Codex thread id (`thread-id`), as opposed to `_clientThreadId`, which * carries `x-codex-parent-thread-id` and is therefore shared by every parallel child of one * parent. Only a surface that must distinguish siblings should read it. */ _codexOwnThreadId?: string; /** True when promptCacheKey identifies a shared cache cohort rather than one conversation. */ _promptCacheKeyIsSharedCohort?: boolean; /** Cursor-only thread owner; may be an opaque process-local Desktop session/thread identity. */ _cursorClientThreadId?: string; /** Conversation/provider/account/model-bound namespace for reasoning replay state. */ _reasoningReplayScope?: OcxReasoningReplayScopeRef; /** * Set by bindRouteReasoningReplayScope after a proven serving-identity change, or by * prepareOpaqueBlobRecovery after an authoritative rejection; consumers strip replayed blobs. */ _stripReasoningEncryptedContent?: boolean; /** * Set when replayed reasoning item ids name items in a store this destination cannot read: by * prepareOpaqueBlobRecovery before the one recovery rebuild, and by bindRouteReasoningReplayScope * while the rejection memo is live or after a proven switch to a different destination or * credential. The Responses passthrough then removes the `id` of every replayed reasoning item, * whether or not it carries a blob. A stateful destination resolves a replayed id against its own * store, so keeping it turns the send into `Item with id 'rs_…' not found` (#5583). A model * change on the same destination and credential does not set this. */ _dropForeignReasoningItemIds?: boolean; /** Final-route opt-in: emit v2 collaboration message arguments as plaintext on ChatGPT. */ _plaintextV2AgentMessages?: boolean; /** * Optional authenticated tenant/operator namespace for Cursor thread→conversation derivation. * When absent (single-operator local proxy), derivation stays local-scoped. */ _cursorIdentityScope?: string; /** * True for helper/shadow/compaction turns that must not append into the main Cursor conversation * derived from the parent thread id. */ _cursorIsolateConversation?: boolean; /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */ _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion" | "authType">; /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */ _providerContinuation?: OcxProviderContinuationState; /** Persisted continuation considered only after the final physical route is known. */ _providerContinuationCandidate?: OcxProviderContinuationState; /** Exact process-local route owner attached to newly persisted provider state. */ _providerContinuationOwner?: OcxProviderContinuationOwner; /** * The hosted `{type:"web_search", ...}` tool config, stashed when Codex enables web search. Routed * (non-OpenAI) providers can't run it server-side, so the proxy re-exposes it as a function tool and * executes searches via the gpt-5.6-luna sidecar (see src/web-search). Absent when not requested. */ _webSearch?: Record<string, unknown>; /** Hosted image_generation tool config stashed for the image bridge sidecar (see src/images). */ _imageGeneration?: { toolNames: Set<string>; originalTool?: Record<string, unknown> }; /** * True when Codex requested structured output (`text.format` = json_schema/json_object). The * web-search tool_result is then rendered as compact JSON instead of markdown prose, so its * answer/"Sources:" text can't bleed into and corrupt the model's schema-constrained output. */ _structuredOutput?: boolean; /** * True when the input carried `{type:"compaction_trigger"}` — Codex remote compaction v2 asking * this turn to produce a `{type:"compaction"}` output item. Routed adapters can't natively; * the server runs the model as a summarizer and the bridge emits a synthetic compaction item * (see src/responses/compaction.ts). */ _compactionRequest?: boolean; /** Manual compaction moved to another provider: summarize portably even on a canonical ChatGPT target. */ _portableCompaction?: boolean; /** * Codex memory pipeline phase this turn belongs to, when `memoryModels` routes it * (src/server/responses/memory-models.ts). Read at the effort choke point, which runs after the * route is known. */ _memoryModelPhase?: "extract" | "consolidation"; /** * True when the current request newly introduced a stored compaction summary/marker. Historical * markers restored by previous_response_id expansion were already acknowledged and do not reset * provider-private continuation caches again on every later turn. */ _contextCompactionBoundary?: boolean; } export interface OcxContext { systemPrompt?: string[]; messages: OcxMessage[]; tools?: OcxTool[]; } export type OcxMessage = | OcxUserMessage | OcxAssistantMessage | OcxDeveloperMessage | OcxToolResultMessage; export interface OcxUserMessage { role: "user"; content: string | OcxContentPart[]; timestamp: number; } export interface OcxAssistantMessage { role: "assistant"; content: OcxAssistantContentPart[]; /** Responses message phase, preserved when replaying translated provider output. */ phase?: OcxMessagePhase; model?: string; timestamp: number; /** * Kiro's encrypted reasoning blob for THIS assistant turn — the opaque value from the turn's * `reasoningContentEvent` (`signature` for the GPT-5.6 family, `redactedContent` for the base64 * shape), tagged with the wire field it must be replayed on (see kiro/reasoning.ts). Kiro * replays it to preserve model reasoning across turns. Provider-specific and unrenderable, so it * rides the message rather than a content part: any other adapter simply ignores it. */ kiroRedactedReasoning?: string; } export interface OcxDeveloperMessage { role: "developer"; content: string | OcxContentPart[]; timestamp: number; } export interface OcxToolResultMessage { role: "toolResult"; toolCallId: string; toolName: string; /** MCP namespace from the originating tool call, if any. */ toolNamespace?: string; /** Text, or content parts when a tool (e.g. Codex view_image) returns an image in its output. */ content: string | OcxContentPart[]; /** True when the Responses result contained opaque encrypted output Kiro cannot translate. */ containsEncryptedContent?: boolean; isError: boolean; timestamp: number; } export interface OcxTextContent { type: "text"; text: string; } export interface OcxImageContent { type: "image"; /** A `data:` URL (base64) or a remote https URL — passed through from Codex verbatim, NEVER inlined as text. */ imageUrl: string; /** Fidelity hint from Codex: "low" | "high" | "auto". */ detail?: string; } export interface OcxVideoContent { type: "video"; /** * A base64 `data:` URL from an OpenAI-compatible `video_url` part, or a URI * the upstream can fetch itself (a YouTube watch URL, a Files API uri). */ videoUrl: string; /** * Gemini's agentic video mode, carried verbatim from the caller's * `video_url.processing` (#3271). Absent for every request that does not ask * for it, so no existing traffic gains a field. */ processing?: string; } /** * An attached document carried as bytes rather than as a description of itself. * * Both inbound parsers used to reduce an attachment to a title before any adapter ran, so no * adapter could forward one even to a target that has a representation for it, and the caller * could not tell "the model read the document" from "the model was told a document existed" * (#5212). * * `text` is that marker, derived once from what the part knows and kept on the part itself. * Every text-only consumer in the tree reaches a `.text` fallback for a part it does not * recognize, so carrying it here means a wire with no document representation still states the * attachment instead of emitting `undefined` or a mislabelled `[video]`. Only the wires that * have a counterpart read `data`. */ export interface OcxDocumentContent { type: "document"; /** `[document: name]` marker, for every wire with no document representation. */ text: string; /** IANA media type of the payload, for example `application/pdf`. */ mediaType: string; /** Base64 payload with no `data:` prefix. */ data: string; /** The document's own name: an Anthropic document title or a Chat file part's filename. */ filename?: string; } /** A user/developer message content part: text, native media, or an attached document. */ export type OcxContentPart = OcxTextContent | OcxImageContent | OcxVideoContent | OcxDocumentContent; export interface OcxThinkingContent { type: "thinking"; thinking: string; signature?: string; itemId?: string; /** Raw Anthropic redacted_thinking block payloads to replay verbatim (order preserved). */ redacted?: string[]; } export interface OcxToolCall { type: "toolCall"; id: string; name: string; arguments: Record<string, unknown>; customWireName?: string; thoughtSignature?: string; /** * Provider-issued opaque metadata that must survive the whole round trip unchanged * (issue #1735). A signed Gemini part is only valid when its signature comes back on the * SAME part it was issued for, so this travels with the individual tool call rather than * being matched by name/arguments after the fact. */ providerMetadata?: OcxProviderOpaqueToolCallMetadata; /** MCP namespace (e.g. "mcp__context7") when this call targets a namespaced tool. */ namespace?: string; } /** * Opaque, provider-scoped tool-call metadata. Values are never parsed, merged, re-encoded, or * synthesized — they are carried verbatim or not at all. */ export interface OcxProviderOpaqueToolCallMetadata { google?: { thoughtSignature?: string; }; } export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall; export interface OcxRequestOptions { maxOutputTokens?: number; temperature?: number; topP?: number; stopSequences?: string[]; toolChoice?: OcxToolChoice; parallelToolCalls?: boolean; reasoning?: string; hideThinkingSummary?: boolean; /** Provider policy: suppress raw content-channel reasoning while summaries stay visible. */ hideRawReasoning?: boolean; serviceTier?: string; /** Final outbound tier action, resolved after the provider/model wire is settled. */ tierDecision?: TierDecision; /** Internal B0 observation inputs; adapters combine these with the wire they actually serialize. */ tierObservation?: TierObservationContext; presencePenalty?: number; frequencyPenalty?: number; /** Responses prompt-cache affinity key. Passthrough preserves it via _rawBody; routed adapters do not consume it unless their upstream wire supports it. */ promptCacheKey?: string; /** * Responses `text.format` (json_schema / json_object), preserved for adapters whose * upstream wire has an equivalent. The openai-chat adapter re-nests it as chat * `response_format`, the exact inverse of responseFormatToText in src/chat/inbound.ts. * The native passthrough ignores it (it forwards `_rawBody.text` verbatim) and Kiro * keeps rejecting structured output via `_structuredOutput`. */ textFormat?: { type: "json_schema" | "json_object"; name?: string; description?: string; schema?: Record<string, unknown>; strict?: boolean; }; } export type OcxMessagePhase = "commentary" | "final_answer"; /** Non-secret, process-local owner fence for provider-private continuation state. */ export interface OcxProviderContinuationOwner { [field: string]: string | number; version: 1; providerName: string; providerDestinationIdentity: string; adapterName: string; modelId: string; credentialIdentity: string; } /** * Provider-private state that must follow a locally expanded `previous_response_id` chain. * Kept out of public Responses output and persisted only in the bounded local continuation cache. */ export interface OcxProviderContinuationState { /** Proxy-authored owner metadata; stripped before provider adapters receive the state. */ __ocxOwner?: OcxProviderContinuationOwner; cursor?: { [field: string]: unknown; conversationId?: string; checkpointUsable?: boolean; /** Opaque process-local Cursor ConversationStateStructure snapshot ref. Never raw protobuf. */ checkpointRef?: string; }; kiro?: { [field: string]: unknown; conversationId?: string; }; [provider: string]: Record<string, unknown> | undefined; } export type AdapterEvent = | { type: "heartbeat"; replayUnsafe?: true; preflightReady?: true } | { type: "text_delta"; text: string; phase?: OcxMessagePhase } | { type: "thinking_delta"; thinking: string } // Anthropic extended-thinking round-trip: signature_delta for the current thinking block, and // opaque redacted_thinking blocks. Both must be replayed verbatim or tool-use turns 400. | { type: "thinking_signature"; signature: string } | { type: "redacted_thinking"; data: string } // Kiro reasoning round-trip: the encrypted reasoning blob for the CURRENT assistant turn, tagged // with the wire field it arrived on. Never rendered — it only rides the reasoning item's envelope // so the next request can replay it verbatim. | { type: "kiro_redacted_reasoning"; data: string } | { type: "reasoning_raw_delta"; text: string } | { type: "tool_call_start"; id: string; name: string; providerMetadata?: OcxProviderOpaqueToolCallMetadata } | { type: "tool_call_delta"; arguments: string } | { type: "tool_call_end" } /** Internal boundary between a guarded first pass and its one-shot continuation. */ | { type: "assistant_boundary" } // Native web-search activity surfaced by the web-search sidecar so Codex renders a "Searched the // web" cell. Emitted as a lifecycle PAIR at real wall-clock moments by src/web-search/loop.ts // (routed adapters never emit these): `begin` right before the sidecar runs so Codex shows the // "Searching the web" spinner, then `end` once it resolves. The bridge maps begin → an // output_item.added(in_progress) and end → the matching output_item.done(completed|failed) under // the SAME output index, so the activity animates instead of flashing completed instantly. | { type: "web_search_call_begin"; id: string } | { type: "web_search_call_end"; id: string; queries: string[]; status?: "completed" | "failed"; sources?: OcxUrlCitation[] } | { type: "done"; usage?: OcxUsage; /** Native opaque compaction ciphertext returned by a Responses backend. */ compactionEncryptedContent?: string; stopReason?: string; endTurn?: boolean; providerState?: OcxProviderContinuationState; } | { type: "incomplete"; reason: string; message?: string; usage?: OcxUsage; retryable?: boolean; endTurn?: boolean; providerState?: OcxProviderContinuationState; } // `usage` carries best-effort partial consumption when a turn dies before a clean done // (e.g. cursor upstream 502 mid-stream), so failed requests can log real token counts. | { type: "error"; message: string; usage?: OcxUsage; /** Authoritative upstream/proxy status when known; avoids message-based classification. */ status?: number; /** Responses error type and code when the adapter has a structured provider failure. */ errorType?: string; code?: string; retryable?: boolean; }; /** * A web source backing a search answer. Surfaced on the search-end event and rendered by the bridge * as a `url_citation` annotation on the following assistant message (the desktop app's Sources chip * reads these; the TUI ignores annotations, so this is additive). */ export interface OcxUrlCitation { url: string; title?: string; } /** * Canonical usage convention (devlog/260711_claude_inbound/070): * - `inputTokens` is the TOTAL prompt size, INCLUDING cache reads and cache writes * (OpenAI Responses convention). Anthropic parse sites normalize into this shape. * - `cachedInputTokens` is cache READ tokens only (a subset of `inputTokens`). * - `cacheReadInputTokens`/`cacheCreationInputTokens` carry the read/write split when * the provider reports both; reads mirror `cachedInputTokens`. * - `totalTokens` = inputTokens + outputTokens. Never re-add cache detail on top. */ export interface OcxUsage { /** Provider-reported credit spend, independent of token estimates and USD pricing. */ providerCredits?: number; inputTokens: number; outputTokens: number; /** * Absolute active-context size after the response. Stateful providers can expose this separately * from their per-attempt usage. Responses serialization derives the input side from * `contextTotalTokens - outputTokens` so output is never added to an absolute checkpoint twice. */ contextTotalTokens?: number; totalTokens?: number; cachedInputTokens?: number; cacheReadInputTokens?: number; cacheCreationInputTokens?: number; reasoningOutputTokens?: number; estimated?: boolean; /** * The raw upstream usage object for Responses-shaped upstreams (openai/codex#41980 parity): * codex-rs preserves the complete `response.usage` object through its own pipeline, so fields * the proxy does not model (subscription metadata, future counters) must survive the bridged / * rebuilt `response.completed` too. Accounting paths read only the canonical fields above; the * wire rebuild merges this object's unknown keys back under the normalized values. */ rawUsage?: Record<string, unknown>; }