UNPKG

@bitkyc08/opencodex

Version:

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

518 lines (498 loc) • 27.7 kB
import { isMistralChatTarget, isNativeOpenAIChatTarget, stripBracketedModelSuffix } from "./wire"; import { reasoningDetailSegmentForWire } from "./response-events"; import { translatedChatDeveloperWireRole } from "./developer-role"; import { singleLeadingSystemMessages } from "./single-system"; import { limitMistralChatImages } from "./mistral-image-limit"; import { isVolcengineArkPaygChatTarget } from "./tool-schema"; import { contentPartsToText } from "../image"; import { EMPTY_TOOL_OUTPUT_ANNOTATION, isWhitespaceOnlyTextPartArray } from "../empty-tool-output-annotation"; import { identifyRoutedModel } from "../identity"; import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalogNudge } from "../tool-catalog-nudge"; import { peekReasoningForCall } from "../../responses/reasoning-replay-cache"; import { chatReasoningReplayPolicy, isReflectionThinkingModel } from "./reasoning-replay"; import type { ClaudeThinkingProjection } from "../../lib/claude-request-projection"; import { inlineDocumentDataUrl } from "../../responses/inline-document"; import type { OcxAssistantMessage, OcxContentPart, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall } from "../../types"; import { modelInList, namespacedToolName } from "../../types"; /** * The translated Chat route has no video mapping: this adapter does not implement one, * and the marker records that fact so the payload is not dropped in silence. * * The wording is deliberately about opencodex's own translation, not the provider or * model. An earlier revision said "unsupported by this provider", which attributed an * opencodex mapping limit to upstream capability the proxy has not established. Native * Chat passthrough and Google inline video are unaffected by this route. */ const VIDEO_UNSUPPORTED_MARKER = "[video omitted: the translated Chat route has no video mapping]"; /** * Chat-completions image_url parts for images carried inside a tool result (issue #888). role:"tool" * content is text-only on every chat provider, so these ride in a follow-up user message instead of * being flattened to the "[image]" marker the model can't actually see. The same follow-up carries * inline audio as input_audio, which is also user-content-only on this wire. */ export function toolResultTextForWire(content: string | OcxContentPart[], annotateEmpty = false): string { // An empty content array is a present-but-empty result; `contentPartsToText` would // otherwise fall back to the "[image]" marker and hide the emptiness from the model. if (annotateEmpty && Array.isArray(content) && content.length === 0) return EMPTY_TOOL_OUTPUT_ANNOTATION; if (typeof content === "string") { if (annotateEmpty && content.trim() === "") return EMPTY_TOOL_OUTPUT_ANNOTATION; return content; } const text = content.filter((p) => p.type === "text").map((p) => (p as OcxTextContent).text).join(""); // A whitespace-only text-part array is the array twin of a blank string; the // shared emptiness contract (same module as the Responses adapter) annotates it // instead of forwarding whitespace the model silently accepts. Image parts and // any other non-text part keep the array non-empty. if (annotateEmpty && isWhitespaceOnlyTextPartArray(content)) { return EMPTY_TOOL_OUTPUT_ANNOTATION; } if (text) { const untransportableImages = content.filter((p) => p.type === "image" && !p.imageUrl).length; return `${text}${"[image]".repeat(untransportableImages)}`; } return contentPartsToText(content); } export function toolResultImageChatParts(content: string | OcxContentPart[]): unknown[] { if (typeof content === "string") return []; const parts: unknown[] = []; for (const p of content) { if (p.type !== "image" || !p.imageUrl) continue; parts.push({ type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }); } return parts; } /** Chat input_audio parts for audio carried inside a tool result. */ export function toolResultAudioChatParts(content: string | OcxContentPart[]): unknown[] { if (typeof content === "string") return []; return content .filter((p): p is Extract<OcxContentPart, { type: "audio" }> => p.type === "audio") .map(p => ({ type: "input_audio", input_audio: { data: p.data, format: p.format } })); } /** * Whether this wire serializes a replayed thinking block for the given model. * * The single source of truth for that question on the Chat wire: the assistant branch below uses * it to decide replayed reasoning fields/chunks, and the Messages ingress uses it to decide how much of a * prompt is worth counting. Two copies of this rule would drift, and the count would then * describe a body this adapter does not send. */ export function openAIChatSerializesThinking( provider: OcxProviderConfig, modelId: string, ): ClaudeThinkingProjection { return { text: (isMistralChatTarget(provider) && provider.preserveReasoningContentModels === undefined) || chatReasoningReplayPolicy(provider, modelId).preserve, // The wire has no `signature` field — base64 replay tokens are Anthropic-wire-only. signature: false, // A `redacted_thinking` block is opaque provider data with no Chat representation: the // assistant branch below reads only `type: "thinking"` parts, so the encrypted form is // dropped whatever the preserve list says. redacted: false, }; } export function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] { const out: unknown[] = []; const { context, options } = parsed; const replayCacheScope = parsed._reasoningReplayScope; // One question, one answer for the whole conversion: does this wire carry replayed thinking // back for this model? Asked once so a long history cannot pay for it per message. const wireSerializesThinking = openAIChatSerializesThinking(provider, parsed.modelId).text; const mistralThinking = isMistralChatTarget(provider); interface PendingToolCall { id: string; name: string } let pendingToolCalls: PendingToolCall[] = []; let deferredBarrierMessages: unknown[] = []; let pendingToolResultImageParts: unknown[] = []; let pendingToolResultAudioParts: unknown[] = []; let mintedIdSeq = 0; const seenWireCallIds = new Set<string>(); // One call id can arrive with more than one result: Codex code mode records the yield marker // for a running cell, then each late `notify()`/wait output as a further result for the same // call. OpenAI-compatible chat providers reject the second `role:"tool"` reply for an id that // was already answered ("Duplicate tool output for call_id"), so the repeats stay out of the // wire body and their text is appended to the result that already answered the call. const answeredToolResults = new Map<string, { content: unknown }>(); const mintCallId = (): string => { let id = ""; do { id = `call_ocx_minted_${++mintedIdSeq}`; } while (seenWireCallIds.has(id)); seenWireCallIds.add(id); return id; }; const releaseDeferredBarriers = (): void => { if (deferredBarrierMessages.length === 0) return; out.push(...deferredBarrierMessages); deferredBarrierMessages = []; }; const flushToolResultImages = (): void => { if (pendingToolResultImageParts.length === 0) return; out.push({ role: "user", content: [ { type: "text", text: "[ocx] image output from the preceding tool result(s):" }, ...pendingToolResultImageParts, ], }); pendingToolResultImageParts = []; }; const flushToolResultAudio = (): void => { if (pendingToolResultAudioParts.length === 0) return; out.push({ role: "user", content: [ { type: "text", text: "[ocx] audio output from the preceding tool result(s):" }, ...pendingToolResultAudioParts, ], }); pendingToolResultAudioParts = []; }; const flushPendingToolCalls = (): void => { if (pendingToolCalls.length === 0) return; for (const call of pendingToolCalls) { out.push({ role: "tool", tool_call_id: call.id, content: `[ocx] no tool result was recorded for "${call.name}"; execution status unknown — do not treat this as success, failure, or user-provided input.`, }); } pendingToolCalls = []; flushToolResultImages(); flushToolResultAudio(); releaseDeferredBarriers(); }; /** Append a repeated result for an already-answered call to the answer that call already got. */ const appendAnsweredToolResultText = ( message: { content: unknown }, text: string, ): void => { if (text.length === 0) return; const current = message.content; // `toolResultTextForWire` always returns text for a `role:"tool"` reply, so the answer is a // string; an unexpected shape still keeps both halves rather than dropping the repeat. message.content = typeof current === "string" && current.length > 0 ? `${current}\n\n${text}` : typeof current === "string" ? text : [current, text]; }; const nativeOpenAI = isNativeOpenAIChatTarget(provider); // Leading-system chat templates reject non-leading system and every developer role while a // later user renders in place: Qwen3.8-27B, Flash-Next, and the OrcaSAQ-2-Cyber-27B GGUF family. // Gateways serve them under namespaced ids (LiteLLM's openai/Qwen3.8-27B, #6674), so any // number of leading path segments is accepted; the final segment names the checkpoint. // Orca's GGUF marker must precede any colon quant tag; other Orca variants are unchanged. const leadingSystemTemplate = provider.singleLeadingSystemMessage !== true && !nativeOpenAI && /^(?:[^/]+\/)*(?:flash-next|Qwen3\.8-Flash-Next|Qwen3\.8-27B|qwen3-8-27b(?:-(?:fp8|lora))?|OrcaSAQ-2-Cyber-27B(?=[^:/\s]*GGUF)[^:/\s]*(?::[\w-]+)?)$/i.test(parsed.modelId); // Which role a developer message carries, and why the unrecorded state folds, is stated once // in ./developer-role.ts and read from there by the native passthrough as well. Either way the // message keeps the slot it arrived in — only the role changes, never the position. const developerWireRole = translatedChatDeveloperWireRole(provider); // A developer message keeps the slot it arrived in. Hoisting its text into the leading // system block moved a mid-conversation instruction ahead of every turn it was written to // follow, and the caller saw an ordinary answer either way (#5213). The Claude inbound mints // chronological developer items for exactly this reason (#4161), so the two halves of the // route were working against each other on every host but api.openai.com. Placement is now // uniform; which ROLE that slot carries is decided separately below. // // One destination already had the chronological behaviour, keyed to a model and a registry // id, because hoisting a newly appended reminder rewrites the reusable prompt prefix. That is // a property of prompt-prefix caching rather than of that destination, and it is now what // every destination gets. const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider) ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice) : undefined; const systemParts = [ ...(context.systemPrompt ?? []), ...(toolCatalogNudge ? [toolCatalogNudge] : []), ]; if (systemParts.length > 0) { const wireModelId = provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(parsed.modelId) : parsed.modelId; const sys = identifyRoutedModel(systemParts.join("\n\n"), wireModelId); out.push({ role: "system", content: sys }); } for (const msg of context.messages) { switch (msg.role) { case "user": case "developer": { const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[]; const hasImages = parts?.some(p => p.type === "image") ?? false; const hasAudio = parts?.some(p => p.type === "audio") ?? false; // A document has a structured counterpart on this wire, so it needs the parts array for // the same reason an image does: flattening it to a string would drop the bytes. const hasStructured = hasImages || hasAudio || (parts?.some(p => p.type === "document") ?? false); let chatMsg: Record<string, unknown>; if (msg.role === "developer" && !hasStructured) { const text = typeof msg.content === "string" ? msg.content : parts!.map(p => (p as OcxTextContent).text).join(""); // A non-text timeline part (video, for example) serializes to nothing here. The // generic user path drops such a message, and emitting a content-free system // message instead is rejected by some upstreams. Native OpenAI keeps its existing // empty-developer wire, which is a separate question from placement. if (!nativeOpenAI && text.length === 0) break; chatMsg = { role: leadingSystemTemplate ? "user" : developerWireRole, content: text }; } else if (typeof msg.content === "string") { chatMsg = { role: "user", content: msg.content }; } else if (!hasStructured) { // A video part has no `text`, so joining it produced "" and the whole message // was dropped: a video-only or text-plus-video turn vanished silently. OpenAI's // Chat Completions wire has no video content part, so state the omission // instead of losing it. Scoped to this adapter's wire, not a claim about video // support in general — native Chat passthrough and Google inline video are // unaffected. chatMsg = { role: "user", content: parts!.map(p => (p.type === "video" ? VIDEO_UNSUPPORTED_MARKER : (p as OcxTextContent).text)).join(""), }; } else { const chatParts = parts!.map(p => { if (p.type === "image") { return { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }; } if (p.type === "audio") { return { type: "input_audio", input_audio: { data: p.data, format: p.format } }; } // Chat Completions carries an attached document as a file part with inline bytes, // the direct counterpart of the Anthropic document block the caller sent. if (p.type === "document") { return { type: "file", file: { file_data: inlineDocumentDataUrl(p), ...(p.filename !== undefined ? { filename: p.filename } : {}), }, }; } // Previously this produced { type: "text", text: undefined } for a video // part — a malformed part, worse than a drop because it can fail upstream // schema validation. if (p.type === "video") return { type: "text", text: VIDEO_UNSUPPORTED_MARKER }; return { type: "text", text: (p as OcxTextContent).text }; }); // A developer message with images keeps the user-compatible shape it has always had on // this wire. One carrying only a document has no such precedent, and demoting it would // undo the role this adapter just finished preserving. chatMsg = { role: msg.role === "developer" && !hasImages && !hasAudio ? developerWireRole : "user", content: chatParts, }; if (provider.singleLeadingSystemMessage === true && chatMsg.role !== "user") { // Keep document bytes in a user-compatible slot; only their accompanying text is // instruction content. Use the same tool barrier so instruction order is retained. const instruction = { role: developerWireRole, content: chatParts.filter(p => p.type === "text") }; if (instruction.content.length > 0) { (pendingToolCalls.length > 0 ? deferredBarrierMessages : out).push(instruction); } chatMsg = { role: "user", content: chatParts.filter(p => p.type !== "text") }; } } if (pendingToolCalls.length > 0) deferredBarrierMessages.push(chatMsg); else out.push(chatMsg); break; } case "assistant": { const aMsg = msg as OcxAssistantMessage; const textParts = aMsg.content.filter(p => p.type === "text") as OcxTextContent[]; const thinkingParts = aMsg.content.filter(p => p.type === "thinking") as OcxThinkingContent[]; const toolCalls = aMsg.content.filter(p => p.type === "toolCall") as OcxToolCall[]; const chatMsg: Record<string, unknown> = { role: "assistant" }; if (textParts.length > 0) chatMsg.content = textParts.map(p => p.text).join(""); let reasoningContent = thinkingParts.map(p => p.thinking).join(""); // Reflection/Stealth replay a placeholder even on a tool-less turn, but never on an // empty turn inside an unfinished tool batch: that turn is dropped below, and a // fabricated reasoning block there would split the call from its real result. const reflectionPlaceholder = isReflectionThinkingModel(parsed.modelId) && chatReasoningReplayPolicy(provider, parsed.modelId).placeholder && !(pendingToolCalls.length > 0 && !chatMsg.content && toolCalls.length === 0 && thinkingParts.length === 0); if ( reasoningContent.length === 0 && (toolCalls.length > 0 || thinkingParts.length > 0 || reflectionPlaceholder) && wireSerializesThinking ) { const cached = toolCalls .map(tc => (tc.id ? peekReasoningForCall(tc.id, replayCacheScope) : undefined)) .filter((text): text is string => typeof text === "string" && text.length > 0); // Parallel calls share one preceding reasoning block, which is // recorded under every call id — join unique texts only. if (cached.length > 0) { reasoningContent = [...new Set(cached)].join("\n"); } else if (!mistralThinking && chatReasoningReplayPolicy(provider, parsed.modelId).placeholder) { // Fallback (extends #950 and #1193; fixes #5421): the replay cache is // bounded (64 entries / 256 KiB / 1 h TTL) and always misses on // long sessions, and some thinking/tool rounds carry no recorded // reasoning at all. DeepSeek thinking mode rejects replay without // reasoning_content with HTTP 400, so inject a // minimal placeholder rather than emit a bare continuation the // upstream will reject. Scoped to requiresReasoningPlaceholderModels // (defaulting to the preserve list): preserve-listed providers with // toggleable thinking (MiniMax low effort) opt out with `[]` so // non-thinking histories are never given a fabricated placeholder. reasoningContent = " "; } } if (reasoningContent.length > 0 && wireSerializesThinking) { if (mistralThinking) { chatMsg.content = mistralThinkingContent(reasoningContent, chatMsg.content as string | undefined); } else if (modelInList(provider.reasoningDetailsModels, parsed.modelId)) { // MiniMax requires structured details rather than reasoning_content. chatMsg.reasoning_details = [reasoningDetailSegmentForWire(reasoningContent)]; } else { chatMsg.reasoning_content = reasoningContent; } } const hasReplayedReasoning = chatMsg.reasoning_content !== undefined || chatMsg.reasoning_details !== undefined || (mistralThinking && Array.isArray(chatMsg.content)); // A turn with no answer text, tools or reasoning carries nothing. Between a call and its // result it would also split the pair, so drop it there; a standalone empty answer keeps // its slot so templates that require strict user/assistant alternation still accept it. const carriesNothing = !chatMsg.content && toolCalls.length === 0 && !hasReplayedReasoning; if (carriesNothing && (chatMsg.content === undefined || pendingToolCalls.length > 0)) break; flushPendingToolCalls(); const wireToolCalls = toolCalls.map(tc => { let id = tc.id; if (!id) id = mintCallId(); else seenWireCallIds.add(id); return { tc, id }; }); if (wireToolCalls.length > 0) { chatMsg.tool_calls = wireToolCalls.map(({ tc, id }) => ({ id, type: "function", function: { name: namespacedToolName(tc.namespace, tc.name), arguments: JSON.stringify(tc.arguments) }, })); if (!chatMsg.content) chatMsg.content = emptyAssistantContent(provider, parsed.modelId); } if (hasReplayedReasoning && chatMsg.content === undefined && chatMsg.tool_calls === undefined) { chatMsg.content = emptyAssistantContent(provider, parsed.modelId); } out.push(chatMsg); pendingToolCalls = wireToolCalls.map(({ tc, id }) => ({ id, name: namespacedToolName(tc.namespace, tc.name) })); break; } case "toolResult": { let toolCallId = msg.toolCallId; const matchIdx = toolCallId ? pendingToolCalls.findIndex(c => c.id === toolCallId) : -1; if (matchIdx >= 0 && toolCallId) { const toolMsg = { role: "tool", tool_call_id: toolCallId, content: toolResultTextForWire(msg.content, provider.annotateEmptyToolOutputs === true), }; out.push(toolMsg); answeredToolResults.set(toolCallId, toolMsg); pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content)); pendingToolResultAudioParts.push(...toolResultAudioChatParts(msg.content)); pendingToolCalls.splice(matchIdx, 1); if (pendingToolCalls.length === 0) { flushToolResultImages(); flushToolResultAudio(); releaseDeferredBarriers(); } } else if ( toolCallId && answeredToolResults.has(toolCallId) && !pendingToolCalls.some(c => c.id === toolCallId) ) { const answer = answeredToolResults.get(toolCallId)!; const text = toolResultTextForWire(msg.content, provider.annotateEmptyToolOutputs === true); if (out[out.length - 1] === answer && deferredBarrierMessages.length === 0) { // Adjacent results can share one reply without moving anything across a later turn. appendAnsweredToolResultText(answer, text); pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content)); pendingToolResultAudioParts.push(...toolResultAudioChatParts(msg.content)); if (pendingToolCalls.length === 0) { flushToolResultImages(); flushToolResultAudio(); } } else { // Chat cannot repeat a tool reply. Keep late text and media together at their // recorded position, identified by call ID; an open tool block must close first. const media = typeof msg.content === "string" ? [] : msg.content.flatMap(part => [ ...toolResultImageChatParts([part]), ...toolResultAudioChatParts([part]), ]); const carrier = { role: "user", content: [ { type: "text", text: `[ocx] additional output for tool call ${toolCallId}:\n${text}` }, ...media, ] }; (pendingToolCalls.length > 0 ? deferredBarrierMessages : out).push(carrier); } } else { if (!toolCallId) toolCallId = `call_orphan_${out.length}`; flushPendingToolCalls(); const name = safeToolName(msg.toolName); const cachedReasoning = toolCallId && wireSerializesThinking ? peekReasoningForCall(toolCallId, replayCacheScope) : undefined; // Same fallback as the main-assistant path: never emit a bare orphan // tool_call continuation on a thinking-mode provider — inject a // placeholder when the replay cache missed (the bounded cache can // always miss on long sessions), or DeepSeek thinking mode 400s. // Gate on the preserve list too: reasoning_content is only ever // serialized for preserve-listed models, so a requires-only custom // entry must not fabricate it on this path (P2 on #1205). // `||` (not `??`): the cache never stores empty strings, but treat a // falsy hit as a miss so the placeholder still fires. const orphanReasoning = cachedReasoning || (!mistralThinking && wireSerializesThinking && chatReasoningReplayPolicy(provider, parsed.modelId).placeholder ? " " : undefined); const orphanReasoningFields: Record<string, unknown> = !orphanReasoning ? {} : mistralThinking ? { content: mistralThinkingContent(orphanReasoning) } : modelInList(provider.reasoningDetailsModels, parsed.modelId) ? { reasoning_details: [reasoningDetailSegmentForWire(orphanReasoning)] } : { reasoning_content: orphanReasoning }; out.push({ role: "assistant", content: emptyAssistantContent(provider, parsed.modelId), ...orphanReasoningFields, tool_calls: [{ id: toolCallId, type: "function", function: { name, arguments: "{}" }, }], }); seenWireCallIds.add(toolCallId); const toolMsg = { role: "tool", tool_call_id: toolCallId, content: toolResultTextForWire(msg.content, provider.annotateEmptyToolOutputs === true), }; out.push(toolMsg); answeredToolResults.set(toolCallId, toolMsg); pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content)); pendingToolResultAudioParts.push(...toolResultAudioChatParts(msg.content)); flushToolResultImages(); flushToolResultAudio(); } break; } } } flushPendingToolCalls(); releaseDeferredBarriers(); return limitMistralChatImages(singleLeadingSystemMessages(out, provider), provider, parsed.modelId) as unknown[]; } export function safeToolName(name: string | undefined): string { const raw = name && name.trim().length > 0 ? name : "tool_result"; const sanitized = raw.replace(/[^A-Za-z0-9_-]/g, "_"); return sanitized; } export function emptyAssistantContent(provider: OcxProviderConfig, modelId = ""): string | { type: "text"; text: string }[] { // Kimi K3.1 Pro rejects Ark's legacy empty-text array during tool continuations. const upstreamModelId = provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(modelId) : modelId; const kimi31Pro = /^kimi-k3-1-pro(?:-\d{6})?$/.test(upstreamModelId); return isVolcengineArkPaygChatTarget(provider) && !kimi31Pro ? [{ type: "text", text: "" }] : ""; } /** Reconstruct completed text-only thinking; never invent signatures or placeholder reasoning. */ function mistralThinkingContent(thinking: string, text?: string): unknown[] { return [ { type: "thinking", thinking: [{ type: "text", text: thinking }] }, ...(text ? [{ type: "text", text }] : []), ]; }