@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
344 lines (330 loc) • 17.5 kB
text/typescript
/**
* Managed native Messages request builder (PF-08, PF-10).
*
* The request a proxy-managed Anthropic credential sends when the client already spoke Messages:
* the caller's own body, cut to a fixed field allowlist, with the wire model and the provider's
* credential. URL, `anthropic-version`, client identity and credential placement come from the
* same helpers the Anthropic adapter uses, so the two lanes cannot drift apart.
*
* Authority: only the provider's own credential is ever placed on the request — a configured
* key, or (PF-10) the access token of the OAuth account the lane resolved, which is sent only to
* `api.anthropic.com`. Caller betas are reduced to `beta-allowlist.ts`; a bounded opaque
* CLI identity handle carries only observed compatibility headers for first-party destinations. The
* caller-forward passthrough in `src/server/claude-messages.ts` is the only place a caller's
* Anthropic credential may travel, and it does not come through here.
*
* Opaque state: thinking signatures and `redacted_thinking` blocks reach only first-party
* Anthropic (`src/protocols/opaque-state.ts`). The source body is never mutated, so every build
* for every destination decides from the full source again.
*/
import { mergeAnthropicBetaHeader } from "../../providers/anthropic-fast";
import { applyClaudeToolPrefix, CLAUDE_CODE_SYSTEM_INSTRUCTION } from "../../oauth/anthropic";
import { credentialDomainFor, opaqueStateForDestination } from "../../protocols/opaque-state";
import type { OcxConfig, OcxProviderConfig } from "../../types";
import {
anthropicBaseRequestHeaders,
applyAnthropicKeyAuth,
applyAnthropicOAuthAuth,
resolveAnthropicMessagesUrl,
} from "../anthropic";
import { applyAnthropicClientIdentity, hasObservedAnthropicClientIdentity, type AnthropicClientIdentity } from "./client-identity";
import { bindAnthropicAccountMetadata, extractAnthropicCallerSessionId } from "./account-metadata";
import { shouldPreserveNativeClientPreamble } from "./native-client-preamble";
import { allowlistAnthropicBetas } from "./beta-allowlist";
import { pairAnthropicBetaBody } from "./beta-body-pairs";
import { applyAnthropicNativeCacheTtlDefault, resolveAnthropicCacheRetention } from "./cache-retention";
export { contextManagementForWire } from "./beta-body-pairs";
/**
* Top-level Messages fields the native lane forwards. Everything else is dropped: an unknown or
* beta-gated field would otherwise reach the provider unchecked. None of the dropped fields has
* a name in the protocol feature vocabulary, so no feature effect is recorded for them.
* Beta-gated top-level and nested fields are reconciled with the final header through
* `beta-body-pairs.ts`, which also restores admitted top-level schemas.
*/
export const ANTHROPIC_MESSAGES_PASSTHROUGH_FIELDS = [
"model",
"messages",
"system",
"max_tokens",
"metadata",
"stop_sequences",
"stream",
"temperature",
"top_p",
"top_k",
"tools",
"tool_choice",
"thinking",
"output_config",
"service_tier",
] as const;
const PASSTHROUGH_FIELD_SET: ReadonlySet<string> = new Set(ANTHROPIC_MESSAGES_PASSTHROUGH_FIELDS);
export interface AnthropicMessagesPassthroughRequest {
url: string;
headers: Record<string, string>;
/** The serialized wire body. */
body: string;
/** The same body before serialization, for callers that count or inspect what is sent. */
wireBody: Record<string, unknown>;
/** Caller `anthropic-beta` values were left out. The trace never records which ones. */
droppedBetas: boolean;
/** Log-safe names of the dropped values (known beta names only); see beta-allowlist.ts. */
droppedBetaNames: string[];
/** Dropped values that are not known beta names, counted only. */
droppedUnrecognizedBetas: number;
/** Thinking signatures or `redacted_thinking` blocks were removed for this destination. */
strippedOpaqueState: boolean;
/**
* OAuth only: wire tool name to the caller's name, for every tool the OAuth prefix renamed.
* The lane maps `tool_use` names in the answer back through it.
*/
oauthToolNames?: ReadonlyMap<string, string>;
}
export interface AnthropicMessagesPassthroughOptions {
/** The caller's `anthropic-beta` header, handed over by the ingress. */
callerAnthropicBeta?: string | null;
/** Provider UUID captured with the serving OAuth credential; never a local account slot id. */
providerAccountUuid?: string;
/** Internal request-local handle; never part of the serialized Messages body. */
clientIdentity?: AnthropicClientIdentity;
/** Optional conversation/session key for deterministic per-conversation X-Claude-Code-Session-Id. */
sessionKey?: string | null;
}
/** The allowlisted copy of `body` with `model` set to the wire model. Shallow: nothing is cloned. */
export function anthropicMessagesPassthroughBody(
body: Readonly<Record<string, unknown>>,
modelId: string,
): Record<string, unknown> {
const out: Record<string, unknown> = {};
for (const [key, value] of Object.entries(body)) {
if (PASSTHROUGH_FIELD_SET.has(key) && value !== undefined) out[key] = value;
}
out.model = modelId;
return out;
}
type Rec = Record<string, unknown>;
function isRec(value: unknown): value is Rec {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
/** A tool the caller executes (no `type`, or `custom`), as opposed to a typed server tool. */
function isClientTool(tool: unknown): tool is Rec & { name: string } {
return isRec(tool) && typeof tool.name === "string" && (tool.type === undefined || tool.type === "custom");
}
/** Only documented system-message tool blocks enable the caller's inline-tools beta. */
function hasInlineToolChanges(body: Rec): boolean {
return Array.isArray(body.messages) && body.messages.some(message => isRec(message)
&& message.role === "system" && Array.isArray(message.content) && message.content.some(block => {
if (!isRec(block) || !isRec(block.tool)) return false;
if (block.type !== "tool_addition" && block.type !== "tool_removal") return false;
const tool = block.tool;
return tool.type === "tool_reference" && typeof tool.name === "string"
|| block.type === "tool_addition" && tool.type === "tool_definition"
&& isRec(tool.definition) && typeof tool.definition.name === "string";
}));
}
/** Allocate only once the first changed item is encountered. */
function mapPreservingIdentity<T>(items: T[], mapItem: (item: T) => T): T[] {
let out: T[] | undefined;
for (let i = 0; i < items.length; i++) {
const item = items[i]!;
const mapped = mapItem(item);
if (mapped !== item && !out) out = items.slice(0, i);
if (out) out.push(mapped);
}
return out ?? items;
}
/** Collection and rewriting follow exactly the same typed content containers. */
function mapOAuthContentBlocks(blocks: unknown[], mapBlock: (block: Rec) => Rec): unknown[] {
return mapPreservingIdentity(blocks, block => {
if (!isRec(block)) return block;
if (block.type === "tool_result" && Array.isArray(block.content)) {
const content = mapOAuthContentBlocks(block.content, mapBlock);
if (content !== block.content) return mapBlock({ ...block, content });
}
return mapBlock(block);
});
}
/**
* The Claude OAuth request shape the adapter produces, applied to a Messages body: the Claude
* Code identity as the first system block, and declared client tool names under the OAuth
* prefix — in declarations, choices, uses and typed references, including tool-result content.
* An observed Claude Code client keeps its own tool names (no rename, an empty reverse map).
* Copy-on-write; arguments, schemas, unknown containers and cache markers stay opaque.
* Ambiguous original or wire names are refused before any history is rewritten.
*/
export function anthropicOAuthWireBody(body: Rec, clientIdentity?: AnthropicClientIdentity): { body: Rec; toolNames: Map<string, string> } {
const out: Rec = { ...body };
const toolNames = new Map<string, string>();
const owners = new Map<string, string>();
// An observed Claude Code client already sends the tool names its own OAuth login uses. The
// prefix would only hide them from first-party features keyed by tool name, such as auto
// mode's server-side review (`safeguards`), which then reviews none of the client's calls.
const keepClientToolNames = hasObservedAnthropicClientIdentity(clientIdentity);
const prefixed = (name: string): string => keepClientToolNames ? name : applyClaudeToolPrefix(name);
const wireName = (name: string): string => {
const wire = prefixed(name);
const owner = owners.get(wire);
if (owner !== undefined && owner !== name) throw new Error("tool names collide under the Claude OAuth tool prefix");
owners.set(wire, name);
if (wire !== name) toolNames.set(wire, name);
return wire;
};
const identity = { type: "text", text: CLAUDE_CODE_SYSTEM_INSTRUCTION };
if (shouldPreserveNativeClientPreamble(body.system, clientIdentity)) {
out.system = body.system;
} else if (typeof body.system === "string" && body.system.length > 0) {
out.system = [identity, { type: "text", text: body.system }];
} else if (Array.isArray(body.system)) {
const first = body.system[0];
const present = isRec(first) && first.type === "text" && first.text === CLAUDE_CODE_SYSTEM_INSTRUCTION;
out.system = present ? body.system : [identity, ...body.system];
} else {
out.system = [identity];
}
// Collect every declaration before mapping, including definitions after their references.
// Typed server/client builtins keep fixed names and reserve them against client collisions.
const declared = new Set<string>();
const typedNames = new Set<string>();
const inlineTypedNames = new Set<string>();
const collectDeclaration = (tool: unknown, inline = false): void => {
if (isClientTool(tool)) declared.add(tool.name);
else if (isRec(tool) && typeof tool.name === "string") {
typedNames.add(tool.name);
if (inline) inlineTypedNames.add(tool.name);
}
};
if (Array.isArray(body.tools)) body.tools.forEach(tool => collectDeclaration(tool));
if (Array.isArray(body.messages)) {
for (const message of body.messages) {
if (!isRec(message) || !Array.isArray(message.content)) continue;
mapOAuthContentBlocks(message.content, block => {
if (block.type === "tool_addition" && isRec(block.tool) && block.tool.type === "tool_definition") {
collectDeclaration(block.tool.definition, true);
}
return block;
});
}
}
for (const name of declared) {
if (typedNames.has(name)) throw new Error(inlineTypedNames.has(name)
? "inline typed and client tool names collide" : "typed and client tool names collide");
if (typedNames.has(prefixed(name))) throw new Error("typed and client wire tool names collide");
wireName(name);
}
const renames = (name: unknown): name is string => typeof name === "string" && declared.has(name) && prefixed(name) !== name;
const mapDeclaration = (tool: unknown): unknown => isClientTool(tool) && renames(tool.name)
? { ...tool, name: wireName(tool.name) } : tool;
if (Array.isArray(body.tools)) {
out.tools = mapPreservingIdentity(body.tools, mapDeclaration);
}
if (isRec(body.tool_choice) && body.tool_choice.type === "tool" && renames(body.tool_choice.name)) {
out.tool_choice = { ...body.tool_choice, name: wireName(body.tool_choice.name) };
}
const mapBlock = (block: Rec): Rec => {
if (block.type === "tool_use" && renames(block.name)) return { ...block, name: wireName(block.name) };
if (block.type === "tool_reference" && renames(block.tool_name)) return { ...block, tool_name: wireName(block.tool_name) };
if ((block.type === "tool_addition" || block.type === "tool_removal") && isRec(block.tool)) {
const tool = block.tool;
if (tool.type === "tool_reference" && renames(tool.name)) {
return { ...block, tool: { ...tool, name: wireName(tool.name) } };
}
if (block.type === "tool_addition" && tool.type === "tool_definition") {
const definition = mapDeclaration(tool.definition);
if (definition !== tool.definition) return { ...block, tool: { ...tool, definition } };
}
}
return block;
};
if (Array.isArray(body.messages)) {
out.messages = mapPreservingIdentity(body.messages, message => {
if (!isRec(message) || !Array.isArray(message.content)) return message;
const content = mapOAuthContentBlocks(message.content, mapBlock);
return content !== message.content ? { ...message, content } : message;
});
}
return { body: out, toolNames };
}
/**
* What the native lane sends for this provider, without a credential: the allowlisted body,
* opaque state kept only for first-party Anthropic, and the OAuth request shape for an OAuth
* provider. `count_tokens` counts this; the builder below sends it.
*/
export function anthropicMessagesNativeWireBody(
provider: Pick<OcxProviderConfig, "baseUrl" | "authMode">,
modelId: string,
body: Readonly<Record<string, unknown>>,
options: Pick<AnthropicMessagesPassthroughOptions, "clientIdentity"> = {},
): { wireBody: Rec; strippedOpaqueState: boolean; oauthToolNames?: Map<string, string> } {
const allowlisted = anthropicMessagesPassthroughBody(body, modelId);
const opaque = opaqueStateForDestination(allowlisted, credentialDomainFor(provider));
if (provider.authMode !== "oauth") return { wireBody: opaque.body, strippedOpaqueState: opaque.stripped };
const oauth = anthropicOAuthWireBody(opaque.body, credentialDomainFor(provider)?.firstPartyAnthropic ? options.clientIdentity : undefined);
return { wireBody: oauth.body, strippedOpaqueState: opaque.stripped, oauthToolNames: oauth.toolNames };
}
/**
* Build the upstream request. Throws the adapter's own errors for a missing credential or a
* malformed or unresolved base URL, and refuses an OAuth credential for any destination other
* than first-party Anthropic. `config.cacheRetention` decides the TTL of caller breakpoints
* that carry none (see applyAnthropicNativeCacheTtlDefault).
*/
export function buildAnthropicMessagesPassthroughRequest(
provider: OcxProviderConfig,
modelId: string,
body: Readonly<Record<string, unknown>>,
config?: OcxConfig,
options: AnthropicMessagesPassthroughOptions = {},
): AnthropicMessagesPassthroughRequest {
const oauth = provider.authMode === "oauth";
if (provider.authMode !== undefined && provider.authMode !== "key" && !oauth) {
throw new Error("managed native Messages requires a key-auth or OAuth anthropic provider");
}
const domain = credentialDomainFor(provider);
if (oauth && !domain?.firstPartyAnthropic) {
throw new Error("managed native Messages sends Anthropic OAuth credentials only to api.anthropic.com");
}
if (typeof provider.apiKey !== "string" || provider.apiKey.trim() === "") {
throw new Error(oauth
? "anthropic oauth token missing — run ocx login anthropic"
: "anthropic provider requires a non-empty apiKey (authMode: key)");
}
const url = resolveAnthropicMessagesUrl(provider);
const native = anthropicMessagesNativeWireBody(provider, modelId, body, options);
const { strippedOpaqueState, oauthToolNames } = native;
const ttlBody = applyAnthropicNativeCacheTtlDefault(
native.wireBody, resolveAnthropicCacheRetention(config?.cacheRetention, provider));
const wireBody = oauth ? bindAnthropicAccountMetadata(ttlBody, options.providerAccountUuid) : ttlBody;
const headers = anthropicBaseRequestHeaders(wireBody.stream === true);
const resolvedSessionKey = options.sessionKey?.trim() || extractAnthropicCallerSessionId(body);
if (oauth) applyAnthropicOAuthAuth(headers, provider.apiKey, resolvedSessionKey);
else applyAnthropicKeyAuth(headers, provider);
// Operator-configured provider headers apply exactly as the adapter applies them.
if (provider.headers) {
const configured = new Set(Object.keys(provider.headers).map(name => name.toLowerCase()));
for (const name of Object.keys(headers)) if (configured.has(name.toLowerCase())) delete headers[name];
Object.assign(headers, provider.headers);
}
if (oauth) {
const wireHeaders = new Headers(headers);
if (wireHeaders.get("authorization") !== `Bearer ${provider.apiKey}` || wireHeaders.has("x-api-key")) {
throw new Error("native OAuth serving credential was overridden by provider headers");
}
}
if (domain?.firstPartyAnthropic) applyAnthropicClientIdentity(headers, options.clientIdentity, provider.headers);
const betas = allowlistAnthropicBetas(options.callerAnthropicBeta, domain?.firstPartyAnthropic ? "first-party" : "compatible",
{ inlineTools: hasInlineToolChanges(wireBody), observedNativeClient: hasObservedAnthropicClientIdentity(options.clientIdentity) });
mergeAnthropicBetaHeader(headers, betas.betas);
// Header and body travel as a pair: the field goes out only when its beta does.
const sentBody = pairAnthropicBetaBody(wireBody, body, headers["anthropic-beta"],
domain?.firstPartyAnthropic === true, oauthToolNames);
return {
url,
headers,
body: JSON.stringify(sentBody),
wireBody: sentBody,
droppedBetas: betas.dropped,
droppedBetaNames: betas.droppedNames,
droppedUnrecognizedBetas: betas.droppedUnrecognized,
strippedOpaqueState,
...(oauthToolNames ? { oauthToolNames } : {}),
};
}