@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
528 lines (492 loc) • 25.6 kB
text/typescript
/**
* Claude Code inbound: Anthropic Messages API request -> internal /v1/responses body.
*
* Design (devlog/260711_claude_inbound/010, 003_evidence.md):
* - translate-and-replay: the produced body MUST pass the real responsesRequestSchema
* parse so routing/OAuth/pool/failover are inherited unchanged.
* - thinking/redacted_thinking replay is preserved in Responses reasoning items;
* signatures and redacted payloads travel in bounded ocxr1 envelopes.
* - thinking.budget_tokens is NEVER forwarded raw; it maps to an effort tier.
* - top_k is accepted and silently dropped (no Responses equivalent, CCR parity).
*/
import type { OcxClaudeCodeConfig } from "../types";
import { createHash } from "node:crypto";
export { AnthropicRequestError, DesktopModelMappingUnavailableError } from "./inbound-records";
export { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, extractOcxRouteDirective, extractOcxEffortDirective } from "./inbound-model-options";
import { AnthropicRequestError, isRec, type Rec } from "./inbound-records";
import { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, formatFromOutputConfig } from "./inbound-model-options";
import { systemToInstructions, toolsToResponses, toolChoiceToResponses } from "./inbound-content-options";
import { stabilizeClaudeInstructionsForPromptCache } from "./inbound-cache-stabilize";
import { decodeReasoningEnvelope, encodeReasoningEnvelope, OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
import { inlineDocumentMarker } from "../responses/inline-document";
import { createTranslatorBudget, type TranslatorBudget } from "../lib/translator-budget";
function imageBlockToInputImage(block: Rec): Rec | null {
const source = block.source;
if (!isRec(source)) return null;
if (source.type === "file") {
throw new AnthropicRequestError(
"File-backed images require native Anthropic passthrough; use base64 or URL images on translated routes.",
);
}
if (source.type === "base64" && typeof source.data === "string") {
const media = typeof source.media_type === "string" ? source.media_type : "image/png";
return { type: "input_image", image_url: `data:${media};base64,${source.data}` };
}
if (source.type === "url" && typeof source.url === "string") {
return { type: "input_image", image_url: source.url };
}
return null;
}
function documentTitle(block: Rec): string | undefined {
return typeof block.title === "string" && block.title.length > 0 ? block.title : undefined;
}
/** An Anthropic base64 document as the Responses `input_file` block that carries its bytes. */
function documentBlockToInputFile(block: Rec): Rec | null {
const source = block.source;
if (!isRec(source) || source.type !== "base64") return null;
const mediaType = typeof source.media_type === "string" && source.media_type.length > 0
? source.media_type
: "application/octet-stream";
if (typeof source.data !== "string" || source.data.length === 0) return null;
const title = documentTitle(block);
return {
type: "input_file",
file_data: `data:${mediaType};base64,${source.data}`,
...(title !== undefined ? { filename: title } : {}),
};
}
function toolResultOutput(block: Rec): string | Rec[] {
const isError = block.is_error === true;
const content = block.content;
if (typeof content === "string") return isError ? `[tool error] ${content}` : content;
if (Array.isArray(content)) {
const out: Rec[] = [];
for (const item of content) {
if (!isRec(item)) continue;
if (item.type === "text" && typeof item.text === "string") {
out.push({ type: "input_text", text: item.text });
} else if (item.type === "image") {
const img = imageBlockToInputImage(item);
if (img) out.push(img);
} else if (item.type === "document") {
// Tool output has no structured document carrier on this route — the Responses tool
// output vocabulary has no input_file block, and every adapter's tool-result path
// flattens to text — so this keeps the #939 marker. The user-message branch below is
// where bytes survive. Recorded as the remaining half of #5212.
out.push({ type: "input_text", text: inlineDocumentMarker(documentTitle(item)) });
}
}
if (isError) out.unshift({ type: "input_text", text: "[tool error]" });
if (out.length === 0) return isError ? "[tool error]" : "";
return out;
}
return isError ? "[tool error]" : "";
}
function pushUserMessage(input: Rec[], blocks: Rec[]): void {
if (blocks.length === 0) return;
input.push({ type: "message", role: "user", content: blocks });
}
/**
* Bundled-skill elision for routed models (devlog 060). Claude Code loads a skill
* by calling the `Skill` tool; the ~136k-token document bundle then rides the
* paired tool_result on EVERY subsequent turn. Third-party models are not trained
* on these Anthropic bundles, so for blocked skills we substitute the result body
* with a short stub — the function_call_output item itself stays (pairing intact).
* Native Anthropic passthrough never reaches this translation.
*/
export const DEFAULT_BLOCKED_SKILLS = ["claude-api"];
/** Shared effective policy for proxy elision and generated routed-agent guards. */
export function effectiveBlockedSkillNames(cc?: Pick<OcxClaudeCodeConfig, "blockedSkills">): string[] {
const names = cc?.blockedSkills ?? DEFAULT_BLOCKED_SKILLS;
return [...new Set(names
.filter((name): name is string => typeof name === "string")
.map(name => name.trim().toLowerCase())
.filter(name => name.length > 0))];
}
/** Injected-skill payloads below this size are never stubbed (not worth it). */
const SKILL_ELISION_MIN_CHARS = 10_000;
const SKILL_TEXT_MARKER = "Base directory for this skill: ";
const SKILL_TEXT_PATH_MAX_CHARS = 4_096;
interface SkillElisionContext {
/** Skill-tool call ids whose input names a blocked skill (result-body carrier). */
callIds: ReadonlySet<string>;
/** Lowercased blocked skill names (text-block carrier). */
names: readonly string[];
}
const NO_ELISION: SkillElisionContext = { callIds: new Set(), names: [] };
/**
* Claude Code 2.1.207 (live capture, devlog 060 follow-up): the Skill tool_result is
* a tiny "Launching skill: <name>" note; the actual ~570k-char document bundle rides
* as a SEPARATE text block in the same user message, whose first line is
* `Base directory for this skill: <dir>/<skill-name>`. Stub that block when the
* directory basename matches a blocked skill.
*/
function maybeElideSkillText(text: string, names: readonly string[]): string {
if (names.length === 0 || text.length < SKILL_ELISION_MIN_CHARS) return text;
if (!text.startsWith(SKILL_TEXT_MARKER)) return text;
const pathStart = SKILL_TEXT_MARKER.length;
const pathPrefix = text.slice(pathStart, pathStart + SKILL_TEXT_PATH_MAX_CHARS + 1);
const firstLineEnd = pathPrefix.indexOf("\n");
if (firstLineEnd === -1 && pathPrefix.length > SKILL_TEXT_PATH_MAX_CHARS) return text;
const dir = pathPrefix.slice(0, firstLineEnd === -1 ? pathPrefix.length : firstLineEnd).trim();
// Windows clients send `C:\Users\...\claude-api`; normalize separators before
// basenaming (repo precedent: src/codex/inject.ts isOpencodexCatalogPath).
const normalizedDir = dir.replace(/\\/g, "/").replace(/\/+$/, "");
const base = normalizedDir.slice(normalizedDir.lastIndexOf("/") + 1).toLowerCase();
if (!names.includes(base)) return text;
return `[opencodex] '${base}' skill document bundle (${text.length} chars) elided for routed models `
+ "(claudeCode.blockedSkills). The skill is loaded; answer from general knowledge instead of citing the bundle.";
}
function skillElisionStub(callId: string): string {
return "[opencodex] Skill document bundle elided for routed models (claudeCode.blockedSkills). "
+ `The skill loaded, but its reference documents were removed to save context (call ${callId}). `
+ "Answer from general knowledge instead of citing the bundle.";
}
/** Collect Skill-tool call ids whose input names a blocked skill. */
function blockedSkillCallIds(messages: readonly unknown[], blocked: readonly string[]): Set<string> {
const ids = new Set<string>();
if (blocked.length === 0) return ids;
const needles = blocked.map(name => name.toLowerCase()).filter(name => name.length > 0);
if (needles.length === 0) return ids;
for (const msg of messages) {
if (!isRec(msg) || msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
for (const block of msg.content) {
if (!isRec(block) || block.type !== "tool_use" || block.name !== "Skill") continue;
if (typeof block.id !== "string" || block.id.length === 0) continue;
const inputJson = JSON.stringify(block.input ?? {}).toLowerCase();
if (needles.some(name => inputJson.includes(name))) ids.add(block.id);
}
}
return ids;
}
/**
* Whether translating this Messages body would elide a blocked skill bundle: a user text block
* `maybeElideSkillText` would stub, or a tool_result answering a blocked Skill call. Pure; the
* managed native Messages lane asks it so a request whose bundle the operator blocked keeps the
* translated path that applies the block.
*/
export function anthropicBodyElidesBlockedSkill(body: unknown, cc?: Pick<OcxClaudeCodeConfig, "blockedSkills">): boolean {
if (!isRec(body) || !Array.isArray(body.messages)) return false;
const names = effectiveBlockedSkillNames(cc);
if (names.length === 0) return false;
const callIds = blockedSkillCallIds(body.messages, names);
for (const msg of body.messages) {
if (!isRec(msg) || msg.role !== "user" || !Array.isArray(msg.content)) continue;
for (const block of msg.content) {
if (!isRec(block)) continue;
if (block.type === "text" && typeof block.text === "string" && maybeElideSkillText(block.text, names) !== block.text) return true;
if (block.type === "tool_result" && typeof block.tool_use_id === "string" && callIds.has(block.tool_use_id)) return true;
}
}
return false;
}
/**
* Claude Code (observed 2026-07-11, real CLI smoke) sends `role:"system"` entries in
* `messages` despite the published API having no system role. They are emitted as
* chronological `role:"developer"` input items, which keeps the timeline intact and
* leaves `instructions` owned solely by the top-level Anthropic `system` field.
*
* The original mapping folded them into `instructions` because the native ChatGPT
* backend rejects `role:"system"` items in `input` ("System messages are not allowed",
* verified live). That constraint is real and still respected — but it only rules out
* `system`, not `developer`, which every Responses route accepts. Folding meant each
* mid-conversation reminder mutated the prompt head, invalidating the upstream KV
* prefix and rotating the Desktop `prompt_cache_key` fallback below on every turn
* (#4148).
*/
function systemMessageText(content: unknown): string {
if (typeof content === "string") return content;
if (!Array.isArray(content)) return "";
const parts: string[] = [];
for (const raw of content) {
if (isRec(raw) && raw.type === "text" && typeof raw.text === "string") parts.push(raw.text);
}
return parts.join("\n\n");
}
function userMessageToItems(content: unknown, input: Rec[], elide: SkillElisionContext = NO_ELISION): void {
if (typeof content === "string") {
if (content.length > 0) pushUserMessage(input, [{ type: "input_text", text: content }]);
return;
}
if (!Array.isArray(content)) return;
// Preserve block order: tool_result blocks become standalone function_call_output
// items; contiguous text/image runs become one user message.
let pending: Rec[] = [];
for (const raw of content) {
if (!isRec(raw)) continue;
switch (raw.type) {
case "text":
if (typeof raw.text === "string") pending.push({ type: "input_text", text: maybeElideSkillText(raw.text, elide.names) });
break;
case "image": {
const img = imageBlockToInputImage(raw);
if (img) pending.push(img);
break;
}
case "tool_result": {
pushUserMessage(input, pending);
pending = [];
if (typeof raw.tool_use_id !== "string" || raw.tool_use_id.length === 0) {
throw new AnthropicRequestError("tool_result requires tool_use_id");
}
input.push({
type: "function_call_output",
call_id: raw.tool_use_id,
// Blocked-skill bundles are stubbed out for routed models (devlog 060).
output: elide.callIds.has(raw.tool_use_id) ? skillElisionStub(raw.tool_use_id) : toolResultOutput(raw),
});
break;
}
case "document":
// A base64 document now rides the Responses input_file block, so a target with a
// counterpart receives the bytes instead of a sentence about them (#5212). Every other
// source is a reference this route cannot dereference, and keeps the marker #939
// introduced — which is also what a target with no document representation still sees.
pending.push(documentBlockToInputFile(raw)
?? { type: "input_text", text: inlineDocumentMarker(documentTitle(raw)) });
break;
default:
break; // thinking/redacted_thinking never appear in user messages; ignore unknowns
}
}
pushUserMessage(input, pending);
}
function assistantMessageToItems(content: unknown, input: Rec[], budget: TranslatorBudget): void {
if (typeof content === "string") {
if (content.length > 0) input.push({ type: "message", role: "assistant", content: [{ type: "output_text", text: content }] });
return;
}
if (!Array.isArray(content)) return;
let pendingText: Rec[] = [];
const flush = () => {
if (pendingText.length > 0) input.push({ type: "message", role: "assistant", content: pendingText });
pendingText = [];
};
for (const raw of content) {
if (!isRec(raw)) continue;
switch (raw.type) {
case "text":
if (typeof raw.text === "string") pendingText.push({ type: "output_text", text: raw.text });
break;
case "tool_use": {
flush();
if (typeof raw.id !== "string" || raw.id.length === 0 || typeof raw.name !== "string" || raw.name.length === 0) {
throw new AnthropicRequestError("tool_use requires id and name");
}
input.push({ type: "function_call", call_id: raw.id, name: raw.name, arguments: JSON.stringify(raw.input ?? {}) });
break;
}
case "thinking": {
flush();
const thinking = typeof raw.thinking === "string" ? raw.thinking : "";
const signature = typeof raw.signature === "string" ? raw.signature : "";
if (signature.startsWith(OCX_REASONING_PREFIX)) {
const owned = decodeReasoningEnvelope(signature, budget);
if (!owned) throw new AnthropicRequestError("malformed ocxr1 reasoning signature");
if (Object.hasOwn(owned, "sig")) throw new AnthropicRequestError("OpenCodex reasoning continuity cannot be replayed as an Anthropic signature");
}
const encrypted = signature.length === 0 ? undefined : signature.startsWith(OCX_REASONING_PREFIX) ? signature : encodeReasoningEnvelope({ sig: signature }, budget);
if (encrypted) budget.chargeRetained(2 * encrypted.length, { kind: "reasoning" });
if (thinking.length === 0 && !encrypted) break;
input.push({ type: "reasoning", id: `rs_${crypto.randomUUID().replace(/-/g, "")}`, summary: thinking.length > 0 ? [{ type: "summary_text", text: thinking }] : [], ...(encrypted ? { encrypted_content: encrypted } : {}) });
break;
}
case "redacted_thinking": {
flush();
const data = typeof raw.data === "string" ? raw.data : "";
if (data.length > 0) {
const encrypted = encodeReasoningEnvelope({ red: [data] }, budget);
budget.chargeRetained(2 * encrypted.length, { kind: "reasoning" });
input.push({ type: "reasoning", id: `rs_${crypto.randomUUID().replace(/-/g, "")}`, summary: [], encrypted_content: encrypted });
}
break;
}
default:
break;
}
}
flush();
}
/** Recursive canonical JSON (keys sorted at every depth) — stable cache-cohort input. */
function canonicalJson(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
if (value && typeof value === "object") {
const entries = Object.entries(value as Rec).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
}
return JSON.stringify(value) ?? "null";
}
/** Provenance of the generated prompt_cache_key (never serialized into the wire body). */
export type ClaudeCacheKeySource = "metadata" | "system" | null;
export interface ClaudeInboundTranslation {
body: Rec;
cacheKeySource: ClaudeCacheKeySource;
}
/**
* Translate an Anthropic Messages request body into a /v1/responses request body.
* Throws AnthropicRequestError (-> 400 invalid_request_error) on malformed input.
*/
export function anthropicToResponsesBody(
raw: unknown,
cc?: OcxClaudeCodeConfig,
): Rec {
return anthropicToResponsesTranslation(raw, cc).body;
}
/**
* Full translation result: the wire body plus the prompt-cache-key provenance as an
* OUT-OF-BODY tuple (audit 133 R3#1 — an in-body marker would leak upstream through
* the native Responses forward and 400).
*/
export function anthropicToResponsesTranslation(
raw: unknown,
cc?: OcxClaudeCodeConfig,
budget?: TranslatorBudget,
): ClaudeInboundTranslation {
const activeBudget = budget ?? createTranslatorBudget();
try {
return translateAnthropicRequest(raw, cc, activeBudget);
} finally {
if (!budget) activeBudget.dispose();
}
}
function translateAnthropicRequest(
raw: unknown,
cc: OcxClaudeCodeConfig | undefined,
budget: TranslatorBudget,
): ClaudeInboundTranslation {
if (!isRec(raw)) throw new AnthropicRequestError("request body must be a JSON object");
if (typeof raw.model !== "string" || raw.model.length === 0) {
throw new AnthropicRequestError("model is required");
}
if (!Array.isArray(raw.messages) || raw.messages.length === 0) {
throw new AnthropicRequestError("messages must be a non-empty array");
}
const input: Rec[] = [];
const systemParts: string[] = [];
const topLevelSystem = systemToInstructions(raw.system);
if (topLevelSystem !== undefined) systemParts.push(topLevelSystem);
const blockedNames = effectiveBlockedSkillNames(cc);
const elide: SkillElisionContext = {
callIds: blockedSkillCallIds(raw.messages, blockedNames),
names: blockedNames,
};
for (const msg of raw.messages) {
if (!isRec(msg)) throw new AnthropicRequestError("each message must be an object");
if (msg.role === "user") userMessageToItems(msg.content, input, elide);
else if (msg.role === "assistant") assistantMessageToItems(msg.content, input, budget);
else if (msg.role === "system") {
const text = systemMessageText(msg.content);
// Keep it where the client put it. `developer` is first-class in the Responses
// schema and survives parseRequest as a chronological message, where `system`
// would be re-hoisted back onto the system prompt and defeat the point.
if (text.length > 0) {
input.push({ type: "message", role: "developer", content: [{ type: "input_text", text }] });
}
}
else throw new AnthropicRequestError(`unsupported message role: ${String(msg.role)}`);
}
const body: Rec = {
model: resolveInboundModel(raw.model, cc),
input,
store: false,
stream: raw.stream === true,
};
const joinedSystem = systemParts.length > 0 ? systemParts.join("\n\n") : "";
const stabilizePromptCache = cc?.stabilizePromptCache === true;
// Desktop fallback hashes raw systemParts unless the caller opted into
// harness cleanup. Opt-in then hashes the same string as body.instructions.
let cacheSystem: string | string[] = systemParts;
if (joinedSystem) {
if (stabilizePromptCache) {
// Claude Code appends growing <total_tokens>N tokens left</total_tokens>
// footers (and occasional TaskCreate nudges) into system text. That churn
// breaks Muse/Go prefix cache on the Responses instructions prefix even
// when tools stay stable. Relocation is caller-opted, not inferred from
// a matching suffix or metadata.user_id.
const stabilized = stabilizeClaudeInstructionsForPromptCache(joinedSystem);
if (stabilized.instructions) body.instructions = stabilized.instructions;
if (stabilized.dynamicNotice) {
input.push({
type: "message",
role: "user",
content: [{ type: "input_text", text: stabilized.dynamicNotice }],
});
}
cacheSystem = stabilized.instructions;
} else {
body.instructions = joinedSystem;
}
}
const tools = toolsToResponses(raw.tools);
if (tools) body.tools = tools;
toolChoiceToResponses(raw.tool_choice, body);
if (typeof raw.max_tokens === "number") body.max_output_tokens = raw.max_tokens;
if (typeof raw.temperature === "number") body.temperature = raw.temperature;
if (typeof raw.top_p === "number") body.top_p = raw.top_p;
// top_k: accepted and dropped (no Responses equivalent).
if (Array.isArray(raw.stop_sequences) && raw.stop_sequences.length > 0) {
body.stop = raw.stop_sequences.filter((s): s is string => typeof s === "string");
}
const outputConfigFormat = formatFromOutputConfig(raw.output_config, body.model as string);
if (outputConfigFormat) body.text = { format: outputConfigFormat };
let cacheKeySource: ClaudeCacheKeySource = null;
if (isRec(raw.metadata) && typeof raw.metadata.user_id === "string") {
const userIdHash = createHash("sha256").update(raw.metadata.user_id).digest("hex");
// OpenAI and Azure reject `user` longer than 64 chars, and Claude Code's metadata.user_id
// is a JSON blob well past that; send its 64-char hash instead of the raw value.
body.user = raw.metadata.user_id.length <= 64 ? raw.metadata.user_id : userIdHash;
// OpenAI-side prompt caching is routed by prompt_cache_key (Codex clients send
// their session id; without it consecutive /v1/messages turns reported
// cached_tokens: 0 on the ChatGPT backend — devlog 090). Claude Code's
// metadata.user_id embeds the session uuid, so hashing it yields a stable
// per-session key with a bounded length/charset.
body.prompt_cache_key = userIdHash.slice(0, 32);
cacheKeySource = "metadata";
} else if (systemParts.length > 0) {
// Claude Desktop sends no metadata.user_id (H1, devlog 130): without any key the
// ChatGPT/OpenAI backends reported cached_tokens:0 on every turn. Fall back to a
// cache-cohort hash (devlog 260712 B4 + Pro review 012): fingerprint what the
// upstream actually receives — resolved model, post-translation system, and the
// FULL translated tool definitions in WIRE ORDER (sorting the hash while sending
// a different order would break the key↔prefix correspondence). canonical JSON
// (recursive key sort) + a version field so future normalization changes never
// mix cohorts. system-only keys herded different models/toolsets into one key
// and burned OpenAI's ~15 RPM per-key routing budget (audit R1#4/R2#5/R1#10).
// Exact-prefix matching still isolates content; the key only steers routing
// affinity. Callers must NOT synthesize a session_id header from this fallback
// (audit 133 R2#3).
// Outside opt-in, hash the raw systemParts array (pre-stabilize Desktop
// key). Opt-in hashes the same string used for body.instructions so the
// key tracks the cacheable prefix after peel.
body.prompt_cache_key = createHash("sha256")
.update(canonicalJson({
version: 2,
model: body.model,
system: cacheSystem,
tools: Array.isArray(body.tools) ? body.tools : [],
}))
.digest("hex").slice(0, 32);
cacheKeySource = "system";
}
const thinking = raw.thinking;
const outputConfigEffort = effortFromOutputConfig(raw.output_config);
const thinkingDisabled = isRec(thinking) && thinking.type === "disabled";
if (thinkingDisabled) {
// An explicit "disabled" is an instruction, not an absence. Dropping it made this
// indistinguishable from a request that never mentioned thinking — and for models that
// think by default, omission means thinking is ON, sharing the caller's max_tokens (#545).
// `none` is the effort disable sentinel. It is not a valid OpenAI summary
// value, so do not attach the similarly named internal catalog sentinel.
body.reasoning = { effort: "none" };
} else if (isRec(thinking) || outputConfigEffort !== undefined) {
const reasoning: Rec = { summary: isRec(thinking) && thinking.display === "omitted" ? "none" : "auto" };
if (outputConfigEffort !== undefined) {
// Adaptive wire: /effort arrives as output_config.effort (devlog 080).
reasoning.effort = outputConfigEffort;
} else if (isRec(thinking) && thinking.type === "enabled" && typeof thinking.budget_tokens === "number") {
reasoning.effort = effortForThinkingBudget(thinking.budget_tokens);
}
body.reasoning = reasoning;
}
return { body, cacheKeySource };
}