UNPKG

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