UNPKG

@bitkyc08/opencodex

Version:

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

646 lines (617 loc) • 30.7 kB
import type { KiroOAuthMetadata } from "../oauth/types"; import type { NativeReasoningOwner } from "../responses/reasoning-replay-cache"; import type { OcxTool, OcxToolChoice } from "./tools"; import type { TierDecision, TierObservationContext } from "./provider"; import type { TranslatorBudget } from "../lib/translator-budget"; /** 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. The request's own thread-id wins so a child agent * cannot write its route into the parent's record (#8632); otherwise this is the Codex * parent-thread id, and headerless Responses callers use a raw sanitized thread/Cursor/session * fallback, never the hashed request-log conversation id. */ readonly clientThreadId: string; current?: Readonly<OcxReasoningReplayIdentity>; } /** One replayed hosted search cell, rebuilt as the `web_search` call/result pair `callId`. */ export interface OcxReplayedWebSearchCell { /** The client-visible cell id; absent when the cell carried no usable id (no recorded result). */ cellId?: string; callId: string; failed: boolean; } 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; /** Trusted ingress provenance: preserve Chat's tool defaults only on the final Responses wire. */ _chatCompletionsInput?: boolean; /** Server-owned request provenance. All system text on this turn belongs at system priority. */ _proxyOwnedSystemPrompt?: true; /** Claude replay tags, retained only until each route binding verifies them. */ _nativeReasoningReplay?: ReadonlyMap<string, string>; _nativeReasoningBoundOwner?: NativeReasoningOwner; _nativeReasoningMint?: { owner?: NativeReasoningOwner }; /** * The Claude client's typed Anthropic web tools, as declared. Only the anthropic adapter reads * them, and only for api.anthropic.com; every other destination never sees them. */ _anthropicServerTools?: readonly Record<string, unknown>[]; /** * Routed Anthropic compaction summary: build tools and system exactly as the ordinary request * would (prompt-cache prefix), then send tool_choice none so no client or hosted tool runs. */ _summaryProhibitsToolCalls?: boolean; /** * Completed server-tool exchanges from the Claude client's history, keyed by the block that * followed them (`call:<tool_use id>` / `text:<text>`). Same audience as `_anthropicServerTools`. */ _anthropicServerReplay?: ReadonlyMap<string, readonly Record<string, unknown>[]>; /** * The caller's `instructions` prefix through its last cache-marked system block. The anthropic * adapter ends a system block there so the breakpoint stays off the per-turn tail. */ _anthropicSystemCachePrefix?: string; /** The request arrived on the Anthropic Messages surface (Claude Code, Claude Desktop). */ _anthropicInbound?: boolean; /** * 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; /** Trusted configuration snapshot; never read from the client's request body. */ _nativeReasoningRetention?: Readonly<{ modelSwitch: boolean; accountSwitch: boolean }>; /** * Set by bindRouteReasoningReplayScope after a proven serving-identity change, or by * prepareOpaqueBlobRecovery after an authoritative rejection; consumers strip replayed blobs. */ _stripReasoningEncryptedContent?: boolean; /** Native compaction remains nonportable even when reasoning-only retention is enabled. */ _stripNativeCompactionEncryptedContent?: boolean; /** Retention kept reasoning ciphertext across a model/account change; arms streamed rejection recovery. */ _nativeReasoningRetainedAcrossRoute?: 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; _plaintextV2Decision?: boolean; _plaintextV2EverPrepared?: 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">; /** Account-scoped Zed user identity paired with the long-lived access token. */ _zedAuthContext?: { userId: string }; _workbuddyAuthContext?: import("../oauth/types").WorkBuddyOAuthMetadata; /** 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; /** Serving owner of image history that was summarized within this request. */ _anthropicImageOwner?: OcxProviderContinuationOwner; /** Internal image recovery summary that must bypass native adaptive thinking defaults. */ _anthropicImageSummary?: true; /** * 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>; /** * Replayed hosted `web_search_call` cells the parser rebuilt as `web_search` call/result pairs * (src/responses/web-search-replay.ts). The web-search sidecar swaps in the result it recorded for * a cell, or removes the pairs when it does not run (src/web-search/sidecar-search-replay.ts). */ _replayedWebSearchCells?: OcxReplayedWebSearchCell[]; /** 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 for a Claude Messages `output_config.format` json_schema. Anthropic promises an answer * that conforms to that schema, whatever `strict` the Responses translation states for * OpenAI-compatible destinations, so an emulating adapter (Kiro) holds it to full conformance. * Process-local; never forwarded. */ _structuredOutputConformance?: 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; /** Request-owned encoding of readable routed v2 retention; never used for native ciphertext. */ _compactionRetention?: { encode(summary: string): string; commit(): void }; /** 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; /** * Codex's own per-turn metadata for this request says `history_initialization: "New"` (HTTP header, * or a WebSocket frame's own `client_metadata`). Read once in request preparation; the experimental * Anthropic `perMessageEffort` option takes it as the new-transcript receipt (#6895). */ _codexNewHistory?: boolean; /** This turn's per-message effort bookkeeping (src/adapters/anthropic/per-message-effort.ts). */ _perMessageEffort?: PerMessageEffortTurn; /** * Core-owned registration slot for the optional advisor subsystem (src/advisor). Set per request * by the sidecar planner, never at module load: the core Responses path only sees this * structural shape, so an advisor-disabled install imports no advisor module. When present, the * adapter delivery wraps the worker's event stream with it — the guard holds synthetic * `advisor` tool calls, consults the configured expert model, and re-dispatches the worker. */ _advisorGuard?: (options: { parsed: OcxParsedRequest; translatorBudget?: TranslatorBudget; firstEvents: AsyncIterable<AdapterEvent>; /** One bounded worker continuation re-dispatch (same machinery as the terminal guard). */ continuation: (parsed: OcxParsedRequest) => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>; }) => AsyncGenerator<AdapterEvent>; } export interface OcxContext { systemPrompt?: string[]; /** Proxy-authored suffixes in systemPrompt (including any joining separator). Keeping their * provenance lets adapters relocate caller text while preserving the original system layout. */ proxySystemPrompt?: { blockIndex: number; suffix: 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; } /** * Inline audio carried by Codex's Responses input. Chat Completions accepts this as an * `input_audio` content part only for WAV and MP3 payloads, so the normalized form keeps the * base64 bytes and a wire-safe format label rather than the original data URL. */ export interface OcxAudioContent { type: "audio"; /** Base64 payload with no `data:` prefix. */ data: string; /** Chat Completions input_audio supports WAV and MP3. */ format: "mp3" | "wav"; /** Text marker for wires that cannot carry the bytes. */ text: string; } /** A user/developer message content part: text, native media, or an attached document. */ export type OcxContentPart = OcxTextContent | OcxImageContent | OcxVideoContent | OcxDocumentContent | OcxAudioContent; 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; /** Root functions explicitly selected by the caller. An empty list permits no synthetic root function. */ explicitRootFunctionChoices?: readonly string[]; /** Caller-owned function and custom selectors before hosted tools are lowered for the provider. */ explicitClientToolChoices?: readonly { type: "function" | "custom"; name: string; namespace?: string }[]; parallelToolCalls?: boolean; reasoning?: string; /** * Independent reasoning toggle resolved at client-compatibility ingress. This is distinct from * the strength-like `reasoning` effort: toggle-only models consume this value as `thinking.type`. */ thinkingEnabled?: boolean; hideThinkingSummary?: boolean; /** Provider policy: suppress raw content-channel reasoning while summaries stay visible. */ hideRawReasoning?: boolean; /** Final-route Chat-to-Responses display compatibility, off unless explicitly enabled. */ rawReasoningAsSummary?: 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 * emulates it through a private structured-output tool (src/adapters/kiro/structured-output.ts). */ 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; } /** One Anthropic server-side call as the API returned it: `server_tool_use` + its `*_tool_result`. */ export interface AnthropicServerBlocks { use: Record<string, unknown>; result: Record<string, unknown> } export type AdapterEvent = | { type: "heartbeat"; replayUnsafe?: true; preflightReady?: true } | { type: "text_delta"; text: string; phase?: OcxMessagePhase; /** Complete documented Anthropic progress block: text remains signed thinking on replay. */ anthropicThinkingSignature?: string } | { 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. // afterOutput marks a turn-level attestation emitted after text/tools, not a new thinking block. | { type: "thinking_signature"; signature: string; afterOutput?: true } | { 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"; incomplete?: true } /** 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. // `itemId` lets the loop name the client-visible cell so it can record the result for replay. | { type: "web_search_call_begin"; id: string; itemId?: string } | { type: "web_search_call_end"; id: string; itemId?: string; queries: string[]; status?: "completed" | "failed"; sources?: OcxUrlCitation[]; /** Anthropic's server-side call (adapters/anthropic.ts): its `server_tool_use` and result block, verbatim. */ anthropic?: AnthropicServerBlocks; } | { 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; /** Proxy-internal permission to consider API-key recovery; never serialized. */ apiKeyRecovery?: true; retryable?: boolean; /** * Proxy-internal, never serialized: the upstream failed the turn before producing text or a * tool call, so the opt-in empty-completion guard may replay the identical request once. */ replaySafeBeforeOutput?: 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; } /** * One turn's per-message effort state (#6895). Spread copies of the parsed request share it, so a * rebuild of the same turn is seen as a second build. */ export interface PerMessageEffortTurn { /** The pending decision this turn owns, until it commits or is abandoned. */ token?: string; generation: string; builds: number; } /** * 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`. * - `cacheCreation1hInputTokens` is the 1-hour-TTL subset of `cacheCreationInputTokens` * (Anthropic `cache_creation.ephemeral_1h_input_tokens`), priced at the 1h write tier. * - `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; cacheCreation1hInputTokens?: number; reasoningOutputTokens?: number; estimated?: boolean; /** * The adapter read these counts off the upstream's own usage frame. Only an adapter whose * provider is estimated by default (usageForFinalLog) sets it, and a merge keeps it only when * every leg had it. A figure taken off a bridged wire or guessed never carries it, so the * provider default still marks those as estimated. */ upstreamReported?: true; /** * 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>; }