@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
225 lines (212 loc) • 11 kB
text/typescript
import type { AdapterEvent, OcxParsedRequest } from "../types";
import type { TranslatorBudget } from "../lib/translator-budget";
import type { RequestExecutionBudget } from "../lib/request-execution-budget";
import type { AttemptRecoveryKind, AttemptRecoveryWithheld } from "../usage/log";
import type { AdapterTierMetadata } from "../providers/fastwire";
import type { ProviderRequestSlot } from "../providers/request-pacing";
/** Metadata about the caller's incoming request, for auth-forwarding adapters. */
export interface IncomingMeta {
headers: Headers;
/** Canonical routed provider identity for provider-specific wire fields. */
providerName?: string;
translatorBudget: TranslatorBudget;
abortSignal?: AbortSignal;
/** Lease acquired before the response is committed; the physical send transfers it to its body. */
pacingSlot?: ProviderRequestSlot;
/** Combo children must surface a pre-output refusal so the selector can try the next target. */
comboAttempt?: boolean;
/**
* Provider-scoped fetch prepared by the Responses router. Stateful transports that emit more
* than one physical HTTP request per logical turn must reuse it so every request participates in
* the same pacing queue and custom provider fetch seam.
*/
providerFetch?: typeof globalThis.fetch;
/**
* Image-normalization ladder bias for upstream-413 tightened retries: every image
* starts one tier lower (devlog/260714_image_normalization_pipeline/030). Consumed by
* the anthropic and openai-chat adapters; others ignore it.
*/
imageTierBias?: number;
/**
* The enclosing request's send budget, for adapters that own their upstream transport.
*
* A `runTurn` adapter never receives an `AdapterFetchContext`, so the budget that bounds every
* other leg could not reach it: Cursor re-sends a whole turn up to three times inside one
* adapter call, and the request cap counted that as one send. Optional, and absent means
* unlimited, because adapter unit tests build a meta with neither a budget nor a request
* behind it (#4546).
*/
sendBudget?: RequestExecutionBudget;
/**
* Physical-send observations for runTurn adapters. Without the same callback carried by
* AdapterFetchContext, an adapter-owned replay spends the shared budget but remains absent
* from the request's sendCount.
*/
onPhysicalSend?: (send: { ordinal: number; recovery?: AttemptRecoveryKind }) => void;
/**
* Recovery refusals for runTurn adapters. A refused replay is not a send, so this separate
* channel explains why recovery stopped without inflating physical-send telemetry.
*/
onRecoveryWithheld?: (withheld: { reason: AttemptRecoveryWithheld }) => void;
}
export interface ProviderAdapter {
name: string;
/**
* This adapter reports every physical inference send through `IncomingMeta.onPhysicalSend`,
* including its first.
*
* The caller normally logs the first send before handing control over, which is correct for a
* transport whose sends it can see. An adapter that admits its own sends through the shared
* budget can have that first send refused, and a send logged before admission is a send the
* log claims and the wire never made. Setting this moves the first send's accounting to the
* boundary where it is actually dispatched.
*/
reportsPhysicalSends?: boolean;
/**
* Convert an already-read provider HTTP error into client-safe text. This hook must be pure and
* return fully redacted output: callers may pass untrusted provider headers and payload text.
*/
formatErrorBody?(status: number, headers: Headers, payloadText: string): string;
/**
* Build the upstream request. May be async: adapters that resolve a short-lived credential
* (e.g. Vertex AI ADC token) return a Promise. Sync adapters return the object directly; callers
* must `await` the result (awaiting a non-Promise is a no-op).
*/
buildRequest(parsed: OcxParsedRequest, incoming: IncomingMeta): AdapterRequest | Promise<AdapterRequest>;
/**
* Decide, BEFORE any request is built or sent, that this turn has nothing to ask upstream.
*
* Returning a reason short-circuits the turn to a locally constructed completed response: no
* `buildRequest`, no send, no token estimate, and no empty-completion retry. That last part is
* why this cannot be expressed as an outputless `done` from `parseStream`: the empty-completion
* guard treats a terminal with no content as a failed turn and re-invokes the identical request,
* so an adapter that "successfully returned nothing" would be retried into the very loop it was
* trying to end.
*
* Only for turns whose input already contains the answer — see the Kiro adapter, where replayed
* history ending in a delivered final answer has nothing left to complete.
*/
localTerminal?(parsed: OcxParsedRequest): AdapterLocalTerminal | undefined;
fetchResponse?(request: AdapterRequest, ctx?: AdapterFetchContext): Promise<Response>;
/**
* Parse one upstream response. `tierMetadata` is the same live observer returned on the
* corresponding AdapterRequest; adapters that receive a documented tier echo may update it.
*/
parseStream(
response: Response,
budget: TranslatorBudget,
tierMetadata?: AdapterTierMetadata,
): AsyncGenerator<AdapterEvent>;
parseResponse?(
response: Response,
budget: TranslatorBudget,
tierMetadata?: AdapterTierMetadata,
): Promise<AdapterEvent[]>;
runTurn?(
parsed: OcxParsedRequest,
incoming: IncomingMeta,
emit: (event: AdapterEvent) => void,
): Promise<void>;
/** Exact no-field observation for runTurn adapters, which expose no AdapterRequest object. */
tierLogForRunTurn?(parsed: OcxParsedRequest): AdapterTierMetadata | undefined;
}
export interface AdapterRequest {
url: string;
method: string;
headers: Record<string, string>;
body: string;
/** Final upstream wire names of custom tools lowered to functions while building this request. */
convertedRoutedCustomToolNames?: ReadonlySet<string>;
/** Native custom-tool wire names authorized for representation-only response repair. */
routedCustomToolRepairNames?: ReadonlySet<string>;
/** Client tool-search names actually lowered to upstream function calls for this request. */
convertedRoutedToolSearchNames?: ReadonlySet<string>;
/** Upstream-only aliases for namespace tools flattened in this request. */
convertedRoutedNamespaceToolAliases?: ReadonlyMap<string, { namespace: string; name: string; kind: "function" | "custom" }>;
/** Request-declared collaboration child names eligible for plaintext-v2 alias restoration. */
plaintextV2AgentMessageToolNames?: ReadonlySet<string>;
/** Collaboration message-tool names actually rewritten to fixed aliases in this request. */
plaintextV2AgentMessageAliasedToolNames?: ReadonlySet<string>;
/** Upstream-only <=64-char aliases for Meta Muse tool names rewritten in this request. */
convertedMuseToolNameAliases?: ReadonlyMap<string, string>;
/** Releases observation of a serialized request body after its final fetch attempt settles. */
releaseBodyObservation?: () => void;
/** Exact reasoning parameter emitted by the adapter, for request-log diagnostics only. */
reasoningLog?:
| {
effectiveEffort: string;
wireField: "reasoning.enabled";
wireValue: boolean;
}
| {
effectiveEffort: string;
wireField: "thinking_budget";
wireValue: number;
}
| {
effectiveEffort: string;
wireField: "reasoning_effort" | "reasoning.effort" | "thinking.type";
wireValue: string;
};
/**
* Exact tier outcome seeded after this adapter serialized the outbound request.
* This is a live shared observer: response-phase methods mutate `outcome`, so retain
* the reference rather than cloning or snapshotting it.
*/
tierLog?: AdapterTierMetadata;
usageLog?: {
inputTokens?: number;
estimated?: boolean;
};
}
export interface AdapterFetchContext {
/** Kiro may hand a pooled refusal to the outer account rotator before same-account retry. */
kiroPreferAccountFailover?: boolean;
/** Remains attached to the returned response body after the response headers arrive. */
abortSignal?: AbortSignal;
/** Deadline for receiving response headers on each attempt, not for consuming the response body. */
timeoutMs?: number;
/** Return final non-2xx responses untouched so the caller can own the error-body read. */
returnRawErrors?: boolean;
/** Whether the upstream response will be consumed as a stream; adapters may select low-latency transport settings. */
stream?: boolean;
/** Custom fetch executor to use for physical upstream network requests (defaults to globalThis.fetch). */
executor?: typeof globalThis.fetch;
/**
* The logical request's send budget (#4546). Optional and unlimited when absent, so an
* adapter unit test that calls a transport context-free keeps its own retry shape. An
* adapter that retries internally must admit EVERY physical send against it: counting one
* adapter entry as one send is how a nested 3x3 ladder stayed invisible to a request cap.
*/
sendBudget?: RequestExecutionBudget;
/**
* Observes every physical upstream send this adapter makes, including its own inner retries.
*
* `ordinal` counts from 1 within this fetch call, so a caller that already recorded the entry
* send records only ordinals above 1 and an adapter that never retries internally logs exactly
* what it logs today. Kiro and Cursor were unpinnable without this: they report one send per
* adapter call however many requests they actually made, so their inner ladders were invisible
* to `sendCount` and no regression could assert a count for them (#4546).
*/
onPhysicalSend?: (send: { ordinal: number; recovery?: AttemptRecoveryKind }) => void;
/**
* Observes a recovery this adapter was ready to make and did not, because the send budget
* refused the dispatch.
*
* Separate from `onPhysicalSend` because nothing was sent: folding it in would inflate
* `sendCount`, the one number that means "requests this proxy actually made". Without it a
* log with one send cannot distinguish "no recovery was eligible" from "one was and the
* budget withheld it", and those need opposite follow-ups (#5044).
*/
onRecoveryWithheld?: (withheld: { reason: AttemptRecoveryWithheld }) => void;
}
/**
* An adapter's decision that a turn needs no upstream inference at all.
*
* `reason` is diagnostic only. It is never sent to the client and never logged as request
* content: it names the code path for a maintainer reading a request log, so it must stay a
* fixed identifier rather than anything derived from the conversation.
*/
export interface AdapterLocalTerminal {
reason: string;
}