@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
text/typescript
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>;
}