@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
471 lines (450 loc) • 20.7 kB
text/typescript
/**
* Chat Completions -> IR, directly (the Antigravity direct lane).
*
* The bridge decodes a Chat conversation twice: `chatCompletionsToResponsesBody`
* (`src/chat/inbound.ts`) projects it into Responses items, then `parseRequest`
* (`src/responses/parser.ts`) turns those items into the IR. This module walks the Chat messages
* once and builds the IR conversation itself: system text, messages, tool calls and results,
* prior reasoning and the tool catalog. It is the request-side twin of the direct client encoders
* (`src/protocols/encoders/`).
*
* Contract: for every Chat body the bridge accepts, `chatConversationToIr(body, model)` equals
* the `context` of `parseRequest(chatCompletionsToResponsesBody(body))`, and every body the bridge
* refuses is refused here with the same `ChatCompletionsRequestError` message in the same order.
* `tests/responses/protocol-chat-ir-parity.test.ts` holds both sides over a fixture corpus. The rules
* mirrored here are the Chat translator's walk (leading-system hoist, held mid-batch
* instructions, tool-call naming, legacy function pairing) and the parser's assembly for the item
* kinds that walk produces (pending reasoning, the assistant placeholder, reasoning that arrives
* after its call, tool-result naming).
*
* Request settings (model, stream, reasoning, limits, tool choice, format) are not decoded here:
* they travel through the Responses core on `chatSettingsToResponsesBody`, so effort policy,
* tier and routing keep their single owner.
*/
import { providerMetadataFromResponsesFunctionCall } from "../../responses/provider-opaque-metadata";
import {
assistantReasoningText,
ChatCompletionsRequestError,
contentToText,
fileFromPart,
videoFromPart,
} from "../../chat/inbound";
import { chatImageUrlFromPart } from "../../chat/image-parts";
import { untranslatedChatInputMedia, untranslatedInputMediaMessage } from "../../responses/input-media";
import { inlineDocumentFromDataUrl } from "../../responses/inline-document";
import { functionCallArgumentsFromText } from "../../responses/parser";
import { normalizeVisualizationContext } from "../../responses/visualization-directives";
import { hasRoutedIdentity, nameRoutedIdentity } from "../../adapters/identity";
import { createToolChoiceResolver, namespacedToolName } from "../../types";
import type {
OcxAssistantMessage,
OcxContentPart,
OcxContext,
OcxMessage,
OcxParsedRequest,
OcxThinkingContent,
OcxTool,
OcxToolCall,
} from "../../types";
import type { PolicyRequestEvidence } from "../../routing/evaluator";
type Rec = Record<string, unknown>;
function isRec(value: unknown): value is Rec {
return !!value && typeof value === "object" && !Array.isArray(value);
}
/** The parser's request-time naming of a proxy-authored identity sentence (#5217). */
function nameDestination(text: string, modelId: string): string {
return hasRoutedIdentity(text) ? nameRoutedIdentity(text, modelId) : text;
}
function imageDetail(part: Rec): string | undefined {
const detail = isRec(part.image_url) ? part.image_url.detail : part.detail;
return detail === "auto" || detail === "low" || detail === "high" ? detail : undefined;
}
/** One file part as the IR carries inline bytes: a document, or the marker when undecodable. */
function filePart(part: Rec): OcxContentPart | null {
const file = fileFromPart(part);
if (!file) return null;
const fileData = file.file_data as string;
const filename = typeof file.filename === "string" ? file.filename : undefined;
return inlineDocumentFromDataUrl(fileData, filename)
?? { type: "text", text: filename ? `[file: ${filename}]` : "[file: inline data]" };
}
/** User or tool content parts in source order; `media: false` keeps only text and images. */
function contentParts(content: unknown, media = true): OcxContentPart[] {
if (typeof content === "string") return content.length > 0 ? [{ type: "text", text: content }] : [];
if (!Array.isArray(content)) return [];
const parts: OcxContentPart[] = [];
for (const raw of content) {
if (typeof raw === "string") {
if (raw.length > 0) parts.push({ type: "text", text: raw });
continue;
}
if (!isRec(raw)) continue;
if ((raw.type === "text" || raw.type === "input_text" || raw.type === "output_text") && typeof raw.text === "string") {
parts.push({ type: "text", text: raw.text });
continue;
}
const imageUrl = chatImageUrlFromPart(raw);
if (imageUrl) {
const detail = imageDetail(raw);
parts.push({ type: "image", imageUrl, ...(detail ? { detail } : {}) });
continue;
}
const video = videoFromPart(raw);
if (video) {
if (media) parts.push({ type: "video", videoUrl: video.url, ...(video.processing ? { processing: video.processing } : {}) });
continue;
}
if (!media) continue;
const file = filePart(raw);
if (file) parts.push(file);
}
return parts;
}
/** The parser collapses a lone text part to a plain string; images and documents stay structured. */
function collapsed(parts: OcxContentPart[]): string | OcxContentPart[] {
return parts.length === 1 && parts[0]!.type === "text" ? parts[0]!.text : parts;
}
function assistantTextParts(content: unknown): Array<{ type: "text"; text: string }> {
if (typeof content === "string") return content.length > 0 ? [{ type: "text", text: content }] : [];
if (!Array.isArray(content)) return [];
const parts: Array<{ type: "text"; text: string }> = [];
for (const raw of content) {
if (typeof raw === "string") {
if (raw.length > 0) parts.push({ type: "text", text: raw });
continue;
}
if (isRec(raw) && (raw.type === "text" || raw.type === "output_text") && typeof raw.text === "string") {
parts.push({ type: "text", text: raw.text });
}
}
return parts;
}
/**
* The parser keeps an unsigned reasoning item's serialized form as its placeholder signature.
* The Chat translator's item is `{type, summary, content}` with one text in each, so the value is
* spelled out rather than produced by a Responses round trip.
*/
function unsignedReasoningSignature(text: string): string {
return JSON.stringify({
type: "reasoning",
summary: [{ type: "summary_text", text }],
content: [{ type: "reasoning_text", text }],
});
}
/**
* The parser's parameter normalization. The bridge's schema parse hands the parser a shallow
* copy of the caller's record, so this copies too: a sanitizer that edits the catalog in place
* must not reach the caller's body, which the lane may still need to re-decode.
* Shared with the direct Messages decoder (`messages-ir.ts`), whose tools pass the same schema.
*/
export function normalizedParameters(raw: unknown): Record<string, unknown> {
// The bridge's `z.record` copies own keys except `__proto__`, which JSON.parse can create.
const copy: Record<string, unknown> = {};
if (isRec(raw)) {
for (const key of Object.keys(raw)) {
if (key !== "__proto__") copy[key] = raw[key];
}
}
if (isRec(raw) && raw.type === "object") return copy;
return { ...copy, type: "object" };
}
function functionTool(name: string, description: unknown, parameters: unknown, strict: unknown): OcxTool {
const tool: OcxTool = {
name,
description: typeof description === "string" ? description : "",
parameters: normalizedParameters(isRec(parameters) ? parameters : undefined),
};
if (typeof strict === "boolean") tool.strict = strict;
return tool;
}
/** `tools` then legacy `functions`, deduplicated by name as the parser's catalog merge does. */
function toolCatalog(raw: Rec): OcxTool[] {
const declared: OcxTool[] = [];
if (Array.isArray(raw.tools)) {
for (const entry of raw.tools) {
if (!isRec(entry) || entry.type !== "function") continue;
if (typeof entry.name === "string" && entry.name.length > 0) {
declared.push(functionTool(entry.name, entry.description, entry.parameters, entry.strict));
} else if (isRec(entry.function) && typeof entry.function.name === "string" && entry.function.name.length > 0) {
const fn = entry.function;
declared.push(functionTool(fn.name as string, fn.description, fn.parameters, fn.strict));
}
}
}
if (raw.functions !== undefined) {
if (!Array.isArray(raw.functions)) throw new ChatCompletionsRequestError("functions must be an array");
for (const entry of raw.functions) {
if (!isRec(entry) || typeof entry.name !== "string" || entry.name.length === 0) {
throw new ChatCompletionsRequestError("functions entries require a name");
}
declared.push(functionTool(entry.name, entry.description, entry.parameters, undefined));
}
}
const seen = new Set<string>();
return declared.filter(tool => {
const key = namespacedToolName(tool.namespace, tool.name);
if (seen.has(key)) return false;
seen.add(key);
return true;
});
}
export interface ChatIrConversation {
/** The model the conversation was decoded for; identity naming and placeholders depend on it. */
modelId: string;
context: OcxContext;
}
/**
* Decode a Chat body's conversation straight into the IR context. Throws
* `ChatCompletionsRequestError` exactly where `chatCompletionsToResponsesBody` would.
*/
export function chatConversationToIr(raw: unknown, modelId: string): ChatIrConversation {
if (!isRec(raw) || !Array.isArray(raw.messages) || raw.messages.length === 0) {
throw new ChatCompletionsRequestError("messages must be a non-empty array");
}
const unsupportedMedia = untranslatedChatInputMedia(raw);
if (unsupportedMedia) throw new ChatCompletionsRequestError(untranslatedInputMediaMessage(unsupportedMedia));
const now = Date.now();
const systemParts: string[] = [];
const messages: OcxMessage[] = [];
let emitted = false;
const pending: OcxThinkingContent[] = [];
const knownNameByCallId = new Map<string, string>();
const legacyAwaiting: Array<{ callId: string; name: string }> = [];
let legacyCallSequence = 0;
const awaitingToolResult = new Set<string>();
const heldInstructions: string[] = [];
const pushDeveloper = (text: string): void => {
emitted = true;
pending.length = 0;
messages.push({ role: "developer", content: nameDestination(text, modelId), timestamp: now });
};
const releaseHeldInstructions = (): void => {
if (heldInstructions.length === 0) return;
pushDeveloper(heldInstructions.join("\n\n"));
heldInstructions.length = 0;
};
const beginConversationTurn = (): void => {
releaseHeldInstructions();
awaitingToolResult.clear();
legacyAwaiting.length = 0;
};
const assistantHolder = (): OcxAssistantMessage => {
const last = messages[messages.length - 1];
let holder: OcxAssistantMessage;
if (last && last.role === "assistant") holder = last;
else {
holder = { role: "assistant", content: [], model: modelId, timestamp: now };
messages.push(holder);
}
if (pending.length > 0) {
holder.content.push(...pending);
pending.length = 0;
}
return holder;
};
const pushToolCall = (callId: string, name: string, args: string, extra?: unknown): void => {
emitted = true;
// Same normalized carrier the bridge reads (src/chat/inbound.ts), so both lanes agree.
const providerMetadata = providerMetadataFromResponsesFunctionCall({ extra_content: extra });
const call: OcxToolCall = { type: "toolCall", id: callId, name, arguments: functionCallArgumentsFromText(callId, args), ...(providerMetadata ? { providerMetadata } : {}) };
assistantHolder().content.push(call);
awaitingToolResult.add(callId);
};
const toolOwner = (callId: string): { name: string; namespace?: string } => {
for (let i = messages.length - 1; i >= 0; i--) {
const message = messages[i]!;
if (message.role !== "assistant") continue;
for (const part of message.content) {
if (part.type === "toolCall" && part.id === callId) return { name: part.name, namespace: part.namespace };
}
}
return { name: "" };
};
const pushToolResult = (callId: string, content: string | OcxContentPart[]): void => {
emitted = true;
// Reasoning replayed after the call it belongs to joins that call's assistant turn (#950).
if (pending.length > 0) {
for (let i = messages.length - 1; i >= 0; i--) {
const message = messages[i]!;
if (message.role !== "assistant") continue;
if (message.content.some(part => part.type === "toolCall" && part.id === callId)) {
message.content = [...pending, ...message.content];
break;
}
}
}
pending.length = 0;
const owner = toolOwner(callId);
messages.push({
role: "toolResult", toolCallId: callId, toolName: owner.name, toolNamespace: owner.namespace,
content, isError: false, timestamp: now,
});
awaitingToolResult.delete(callId);
if (awaitingToolResult.size === 0) releaseHeldInstructions();
};
for (const msg of raw.messages) {
if (!isRec(msg)) continue;
const role = typeof msg.role === "string" ? msg.role : "";
switch (role) {
case "system":
case "developer": {
if (!emitted) {
const text = contentToText(msg.content).trim();
if (text) systemParts.push(text);
break;
}
const text = contentToText(msg.content).trim();
if (!text) break;
if (awaitingToolResult.size > 0) heldInstructions.push(text);
else pushDeveloper(text);
break;
}
case "user": {
beginConversationTurn();
const parts = contentParts(msg.content);
if (parts.length > 0) {
emitted = true;
pending.length = 0;
messages.push({ role: "user", content: collapsed(parts), timestamp: now });
}
break;
}
case "assistant": {
beginConversationTurn();
const reasoningText = assistantReasoningText(msg);
if (reasoningText !== undefined) {
emitted = true;
const part: OcxThinkingContent = {
type: "thinking",
thinking: reasoningText,
signature: unsignedReasoningSignature(reasoningText),
};
// Consecutive unsigned reasoning folds into one block, as the parser does.
const previous = pending[pending.length - 1];
if (previous && !previous.redacted) {
pending[pending.length - 1] = { ...part, thinking: `${previous.thinking}\n${part.thinking}` };
} else {
pending.push(part);
}
}
const text = assistantTextParts(msg.content);
if (text.length > 0) {
emitted = true;
messages.push({
role: "assistant",
content: pending.length > 0 ? [...pending, ...text] : text,
model: modelId,
timestamp: now,
});
pending.length = 0;
}
if (msg.tool_calls !== undefined && Array.isArray(msg.tool_calls)) {
for (const entry of msg.tool_calls) {
if (!isRec(entry)) continue;
const fn = isRec(entry.function) ? entry.function : null;
let name = typeof fn?.name === "string" ? fn.name : typeof entry.name === "string" ? entry.name : "";
const args = typeof fn?.arguments === "string"
? fn.arguments
: typeof entry.arguments === "string"
? entry.arguments
: JSON.stringify(fn?.arguments ?? entry.arguments ?? {});
const callId = typeof entry.id === "string" && entry.id.length > 0
? entry.id
: typeof entry.call_id === "string" && entry.call_id.length > 0
? entry.call_id
: `call_${crypto.randomUUID().replace(/-/g, "").slice(0, 24)}`;
if (!name) name = knownNameByCallId.get(callId) ?? "";
if (!name) throw new ChatCompletionsRequestError("tool_calls entries require function.name");
knownNameByCallId.set(callId, name);
pushToolCall(callId, name, args, entry.extra_content);
}
}
if (msg.function_call !== undefined && msg.function_call !== null) {
const value = msg.function_call;
if (!isRec(value) || typeof value.name !== "string" || value.name.length === 0) {
throw new ChatCompletionsRequestError("assistant function_call requires a name");
}
const args = typeof value.arguments === "string" ? value.arguments : JSON.stringify(value.arguments ?? {});
const callId = `call_legacy_${String(++legacyCallSequence).padStart(4, "0")}`;
knownNameByCallId.set(callId, value.name);
pushToolCall(callId, value.name, args);
legacyAwaiting.push({ callId, name: value.name });
}
break;
}
case "function": {
if (Array.isArray(msg.content) && msg.content.some(part => isRec(part) && chatImageUrlFromPart(part))) {
throw new ChatCompletionsRequestError(
"Legacy function-result image translation is not implemented. Use tool_calls and role:tool with tool_call_id.",
);
}
const name = typeof msg.name === "string" ? msg.name : "";
if (!name) throw new ChatCompletionsRequestError("function messages require a name");
const pendingIndex = legacyAwaiting.findIndex(call => call.name === name);
if (pendingIndex < 0) throw new ChatCompletionsRequestError(`function result has no pending call named ${name}`);
const [call] = legacyAwaiting.splice(pendingIndex, 1);
pushToolResult(call!.callId, contentToText(msg.content));
break;
}
case "tool": {
const callId = typeof msg.tool_call_id === "string" ? msg.tool_call_id
: typeof msg.tool_use_id === "string" ? msg.tool_use_id
: "";
if (!callId) throw new ChatCompletionsRequestError("tool messages require tool_call_id");
const parts = contentParts(msg.content, false);
pushToolResult(callId, parts.some(part => part.type === "image") ? parts : contentToText(msg.content));
break;
}
default:
break;
}
}
releaseHeldInstructions();
if (!emitted && systemParts.length === 0) {
throw new ChatCompletionsRequestError("messages must include at least one user/assistant/tool turn");
}
const tools = toolCatalog(raw);
const context: OcxContext = {
...(systemParts.length > 0 ? { systemPrompt: [nameDestination(systemParts.join("\n\n"), modelId)] } : {}),
messages,
...(tools.length > 0 ? { tools } : {}),
};
return { modelId, context: normalizeVisualizationContext(context) };
}
/**
* Put a directly decoded conversation onto the request the core parsed from the settings-only
* body. The conversation is re-decoded if the core settled a different model id than the one the
* ingress decoded for, because identity naming and assistant placeholders carry it. The tool
* choice is checked against the decoded catalog, which the settings-only parse could not see.
*/
export function withDirectChatConversation(
base: OcxParsedRequest,
chatBody: unknown,
decoded: ChatIrConversation,
): OcxParsedRequest {
const conversation = decoded.modelId === base.modelId ? decoded : chatConversationToIr(chatBody, base.modelId);
const choice = base.options.toolChoice;
if (choice && typeof choice === "object") {
const selectors = "allowedTools" in choice ? choice.allowedTools : [choice.name];
const resolver = createToolChoiceResolver(conversation.context.tools ?? []);
for (const selector of selectors) {
if (resolver.candidateCount(selector) > 1) throw new Error(`ambiguous tool_choice name: ${selector}`);
}
}
return { ...base, context: conversation.context };
}
/**
* The policy-routing evidence the core would have read from the bridge body
* (`evidenceFromBody`): a non-empty tool catalog, and an image in a user message. An image in a
* tool result sits under `output` on the bridge body, which that scan does not read, so it is
* not evidence here either.
*/
export function chatIrRouteEvidence(conversation: ChatIrConversation): PolicyRequestEvidence {
const tools = (conversation.context.tools?.length ?? 0) > 0;
const image = conversation.context.messages.some(message => message.role === "user"
&& Array.isArray(message.content) && message.content.some(part => part.type === "image"));
return {
...(tools ? { toolsRequired: true } : {}),
...(image ? { imageInputRequired: true } : {}),
};
}