UNPKG

@bitkyc08/opencodex

Version:

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

471 lines (442 loc) • 24.1 kB
/** * Pure Gemini generateContent request and Chat Completions response projections. * * Request side: a Gemini body becomes one Chat Completions body. Unknown fields are ignored (the * Gemini API grows them often); a field this proxy cannot honor and that would change the answer * (a second candidate, a non-image inline part) is a typed 400 instead of a silent drop. * Response side: a buffered Chat completion or a Chat SSE chunk sequence becomes Gemini * GenerateContentResponse objects. A streamed tool call is accumulated and emitted as one * complete functionCall part, because Gemini clients expect whole calls. */ import { normalizedClientExtraContent } from "../../responses/provider-opaque-metadata"; type Obj = Record<string, unknown>; export const MAX_GEMINI_TOOL_CALLS = 1_024; export const MAX_GEMINI_SCHEMA_DEPTH = 64; export class GeminiCodecError extends Error { readonly status = 400; readonly code = "invalid_gemini_request"; constructor(message: string) { super(message); this.name = "GeminiCodecError"; } } function fail(message: string): never { throw new GeminiCodecError(message); } const isObj = (value: unknown): value is Obj => !!value && typeof value === "object" && !Array.isArray(value); function object(value: unknown, label: string): Obj { if (!isObj(value)) fail(`Invalid ${label}`); return value; } function array(value: unknown, label: string): unknown[] { if (!Array.isArray(value)) fail(`Invalid ${label}`); return value; } function text(value: unknown, label: string, nonempty = false): string { if (typeof value !== "string" || (nonempty && !value.trim())) fail(`Invalid ${label}`); return value; } function finiteNumber(value: unknown, label: string): number { if (typeof value !== "number" || !Number.isFinite(value)) fail(`Invalid ${label}`); return value; } const snake = (key: string) => key.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`); /** Gemini JSON is camelCase, but the REST surface also accepts snake_case; read either. */ function field(source: Obj, key: string): unknown { return source[key] !== undefined ? source[key] : source[snake(key)]; } /** Schema keywords whose values are data, not schemas: they are copied, never normalized. */ const SCHEMA_LITERAL_KEYS = new Set(["enum", "const", "default", "example", "examples"]); /** Schema keywords whose values map names to schemas: the names are data, every value is a schema. */ const SCHEMA_MAP_KEYS = new Set(["properties", "patternProperties", "$defs", "definitions"]); /** Gemini declares schema types in upper case ("OBJECT"); Chat tools want JSON Schema's lower case. */ export function normalizeSchema(value: unknown, depth = 0): unknown { if (depth > MAX_GEMINI_SCHEMA_DEPTH) fail("Schema nesting too deep"); if (Array.isArray(value)) return value.map(item => normalizeSchema(item, depth + 1)); if (!isObj(value)) return value; const out: Obj = {}; for (const [key, item] of Object.entries(value)) { out[key] = key === "type" && typeof item === "string" ? item.toLowerCase() : SCHEMA_LITERAL_KEYS.has(key) ? item : SCHEMA_MAP_KEYS.has(key) && isObj(item) ? Object.fromEntries(Object.entries(item).map(([name, schema]) => [name, normalizeSchema(schema, depth + 1)])) : normalizeSchema(item, depth + 1); } return out; } function chatTools(value: unknown): Obj[] { const tools: Obj[] = []; for (const raw of array(value, "tools")) { const declarations = field(object(raw, "tool"), "functionDeclarations"); // Hosted Gemini tools (search, code execution) have no Chat equivalent and are not declarations. if (declarations === undefined) continue; for (const rawDeclaration of array(declarations, "functionDeclarations")) { const declaration = object(rawDeclaration, "function declaration"); const name = text(declaration.name, "function name", true); if (declaration.description !== undefined) text(declaration.description, "function description"); const schema = field(declaration, "parametersJsonSchema") ?? declaration.parameters ?? { type: "object", properties: {} }; object(schema, "function parameters"); tools.push({ type: "function", function: { name, ...(typeof declaration.description === "string" ? { description: declaration.description } : {}), parameters: normalizeSchema(schema), }, }); } } return tools; } function toolChoice(toolConfig: unknown): unknown { if (toolConfig === undefined) return undefined; const config = field(object(toolConfig, "toolConfig"), "functionCallingConfig"); if (config === undefined) return undefined; const calling = object(config, "functionCallingConfig"); const mode = calling.mode === undefined ? "AUTO" : text(calling.mode, "function calling mode").toUpperCase(); const namesRaw = field(calling, "allowedFunctionNames"); const names = namesRaw === undefined ? [] : array(namesRaw, "allowedFunctionNames").map(name => text(name, "allowed function name", true)); const entries = names.map(name => ({ type: "function", function: { name } })); if (mode === "NONE") return "none"; // VALIDATED lets the model answer in text or call an allowed function, so it never forces a call. if (mode === "AUTO" || mode === "MODE_UNSPECIFIED" || mode === "VALIDATED") return entries.length ? { type: "allowed_tools", allowed_tools: { mode: "auto", tools: entries } } : undefined; if (mode === "ANY") { if (entries.length === 1) return entries[0]; return entries.length ? { type: "allowed_tools", allowed_tools: { mode: "required", tools: entries } } : "required"; } return fail("Unsupported function calling mode"); } function responseFormat(config: Obj): Obj | undefined { const mime = config.responseMimeType === undefined && config.response_mime_type === undefined ? undefined : text(field(config, "responseMimeType"), "responseMimeType"); const schema = field(config, "responseJsonSchema") ?? field(config, "responseSchema"); if (mime !== undefined && mime !== "application/json" && mime !== "text/plain") fail("Unsupported responseMimeType"); if (mime === "text/plain" || (mime === undefined && schema === undefined)) return undefined; if (schema === undefined) return { type: "json_object" }; object(schema, "response schema"); return { type: "json_schema", json_schema: { name: "response", schema: normalizeSchema(schema) } }; } const REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh"]); function reasoning(config: unknown): Obj { if (config === undefined) return {}; const thinking = object(config, "thinkingConfig"); const out: Obj = {}; const level = field(thinking, "thinkingLevel"); const budget = field(thinking, "thinkingBudget"); if (level !== undefined) { const effort = text(level, "thinkingLevel").toLowerCase(); if (REASONING_EFFORTS.has(effort)) out.reasoning_effort = effort; } else if (budget !== undefined) { const tokens = finiteNumber(budget, "thinkingBudget"); // -1 asks the model to decide, which is the upstream default. if (tokens === 0) out.reasoning_effort = "none"; else if (tokens > 0) out.reasoning_effort = tokens <= 2_048 ? "low" : tokens <= 12_288 ? "medium" : "high"; } // An explicit false must reach the Chat conversion, whose default is to summarize. const includeThoughts = field(thinking, "includeThoughts"); if (typeof includeThoughts === "boolean") out.include_reasoning = includeThoughts; return out; } function generationSettings(raw: unknown, result: Obj): void { if (raw === undefined) return; const config = object(raw, "generationConfig"); const numeric: ReadonlyArray<readonly [string, string]> = [ ["temperature", "temperature"], ["topP", "top_p"], ["presencePenalty", "presence_penalty"], ["frequencyPenalty", "frequency_penalty"], ]; for (const [key, chatKey] of numeric) { const value = field(config, key); if (value !== undefined) result[chatKey] = finiteNumber(value, key); } const maxTokens = field(config, "maxOutputTokens"); if (maxTokens !== undefined) { if (typeof maxTokens !== "number" || !Number.isSafeInteger(maxTokens) || maxTokens < 1) fail("Invalid maxOutputTokens"); result.max_tokens = maxTokens; } const seed = field(config, "seed"); if (seed !== undefined) { if (typeof seed !== "number" || !Number.isSafeInteger(seed)) fail("Invalid seed"); result.seed = seed; } const stops = field(config, "stopSequences"); if (stops !== undefined) result.stop = array(stops, "stopSequences").map(stop => text(stop, "stop sequence")); const candidates = field(config, "candidateCount"); if (candidates !== undefined && candidates !== 1) fail("candidateCount other than 1 is unsupported"); const format = responseFormat(config); if (format) result.response_format = format; Object.assign(result, reasoning(field(config, "thinkingConfig"))); } function partsOf(content: Obj): Obj[] { return array(field(content, "parts"), "parts").map(part => object(part, "part")); } function systemText(value: unknown): string { if (typeof value === "string") return value; return partsOf(object(value, "systemInstruction")).map(part => (part.text === undefined ? "" : text(part.text, "system text"))).join("\n"); } const BASE64 = /^[A-Za-z0-9+/_-]+={0,2}$/; function inlineImage(raw: unknown): Obj { const data = object(raw, "inlineData"); const mime = text(field(data, "mimeType"), "inline data media type", true).toLowerCase(); if (!/^image\/[a-z0-9.+-]+$/.test(mime)) fail("Unsupported inline data media type"); const bytes = text(data.data, "inline data", true); if (!BASE64.test(bytes)) fail("Invalid inline data encoding"); return { type: "image_url", image_url: { url: `data:${mime};base64,${bytes}` } }; } interface PendingCall { id: string; name: string; matched: boolean } /** Convert Gemini contents to Chat messages, matching each functionResponse to a prior functionCall. */ function chatMessages(contents: unknown, system: unknown): Obj[] { const messages: Obj[] = []; if (system !== undefined) { const instruction = systemText(system); if (instruction) messages.push({ role: "system", content: instruction }); } const byId = new Map<string, PendingCall>(); const byName = new Map<string, PendingCall[]>(); let callCount = 0; array(contents, "contents").forEach((rawContent, ci) => { const content = object(rawContent, "content"); const role = content.role === undefined ? "user" : text(content.role, "role"); if (role !== "user" && role !== "model" && role !== "function" && role !== "tool") fail("Unsupported role"); const parts = partsOf(content); for (const part of parts) { if (field(part, "fileData") !== undefined || field(part, "executableCode") !== undefined || field(part, "codeExecutionResult") !== undefined) fail("Unsupported part"); } if (role === "model") { const texts: string[] = []; const calls: Obj[] = []; // A thought signature on a thought part or a signature-only part belongs to the next call of // this turn (Gemini 3 signs the first call); it never crosses into another turn. let pendingSignature: string | undefined; parts.forEach((part, pi) => { const rawSignature = field(part, "thoughtSignature"); const partSignature = typeof rawSignature === "string" && rawSignature ? rawSignature : undefined; if (typeof part.text === "string") { // Replayed thought summaries are not conversation content. if (part.thought !== true) texts.push(part.text); else if (partSignature) pendingSignature = partSignature; return; } const rawCall = field(part, "functionCall"); if (rawCall === undefined) { if (field(part, "inlineData") !== undefined || field(part, "functionResponse") !== undefined) fail("Unsupported model part"); if (partSignature) pendingSignature = partSignature; return; } if (++callCount > MAX_GEMINI_TOOL_CALLS) fail("Too many function calls"); const call = object(rawCall, "functionCall"); const name = text(call.name, "function name", true); const args = call.args === undefined ? {} : object(call.args, "function arguments"); const id = call.id === undefined ? `call_gemini_${ci}_${pi}` : text(call.id, "function call id", true); if (byId.has(id)) fail("Duplicate function call id"); const pending: PendingCall = { id, name, matched: false }; byId.set(id, pending); byName.set(name, [...(byName.get(name) ?? []), pending]); const signature = partSignature ?? pendingSignature; pendingSignature = undefined; // The Chat carrier for Gemini's opaque state; normalized so a malformed value is dropped. const extra = normalizedClientExtraContent(signature === undefined ? undefined : { google: { thought_signature: signature } }); calls.push({ id, type: "function", function: { name, arguments: JSON.stringify(args) }, ...(extra ?? {}) }); }); const body = texts.join(""); if (body || calls.length) messages.push({ role: "assistant", content: body || null, ...(calls.length ? { tool_calls: calls } : {}) }); return; } const tools: Obj[] = []; const user: Obj[] = []; let hasImage = false; for (const part of parts) { const rawResponse = field(part, "functionResponse"); if (rawResponse !== undefined) { const response = object(rawResponse, "functionResponse"); const name = text(response.name, "function name", true); const id = response.id === undefined ? undefined : text(response.id, "function response id", true); let target = id === undefined ? undefined : byId.get(id); if (!target || target.matched || target.name !== name) target = byName.get(name)?.find(candidate => !candidate.matched); if (!target) fail("Unmatched function response"); target.matched = true; tools.push({ role: "tool", tool_call_id: target.id, content: JSON.stringify(response.response ?? {}) }); // Chat tool messages carry text only, so a tool's images follow the tool batch in the user turn, labelled with their call. const nested = field(response, "parts"); for (const [ni, rawNested] of (nested === undefined ? [] : array(nested, "functionResponse parts")).entries()) { const media = field(object(rawNested, "functionResponse part"), "inlineData"); if (media === undefined) fail("Unsupported functionResponse part"); if (ni === 0) user.push({ type: "text", text: `Image output of ${name} (call ${target.id}):` }); user.push(inlineImage(media)); hasImage = true; } } else if (typeof part.text === "string") { if (part.thought !== true) user.push({ type: "text", text: part.text }); } else if (field(part, "inlineData") !== undefined) { user.push(inlineImage(field(part, "inlineData"))); hasImage = true; } } // Tool results must directly follow the assistant turn that asked for them. messages.push(...tools); if (user.length) messages.push({ role: "user", content: hasImage ? user : user.map(item => item.text as string).join("\n") }); }); return messages; } /** Project a generateContent body for `model` onto a Chat Completions body. */ export function geminiToChat(model: string, input: unknown, stream: boolean): Obj { const body = object(input, "request"); const result: Obj = { model: text(model, "model", true), stream, messages: chatMessages(body.contents, field(body, "systemInstruction")) }; if (body.tools !== undefined) { const tools = chatTools(body.tools); if (tools.length) { result.tools = tools; const choice = toolChoice(field(body, "toolConfig")); if (choice !== undefined) result.tool_choice = choice; } } generationSettings(field(body, "generationConfig"), result); return result; } function nonNegativeInt(value: unknown): number | undefined { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined; } function usageMetadata(value: unknown): Obj | undefined { if (!isObj(value)) return undefined; const prompt = nonNegativeInt(value.prompt_tokens); const completion = nonNegativeInt(value.completion_tokens); if (prompt === undefined && completion === undefined) return undefined; const details = isObj(value.completion_tokens_details) ? value.completion_tokens_details : {}; const promptDetails = isObj(value.prompt_tokens_details) ? value.prompt_tokens_details : {}; const thoughts = nonNegativeInt(details.reasoning_tokens) ?? 0; const cached = nonNegativeInt(promptDetails.cached_tokens) ?? 0; const out: Obj = { promptTokenCount: prompt ?? 0, // Chat counts reasoning inside completion tokens; Gemini reports it separately. candidatesTokenCount: Math.max(0, (completion ?? 0) - thoughts), totalTokenCount: (prompt ?? 0) + (completion ?? 0), }; if (thoughts > 0) out.thoughtsTokenCount = thoughts; if (cached > 0) out.cachedContentTokenCount = cached; return out; } const FINISH_REASONS: Readonly<Record<string, string>> = { stop: "STOP", tool_calls: "STOP", function_call: "STOP", length: "MAX_TOKENS", content_filter: "SAFETY", }; function finishReason(value: unknown): string | undefined { return typeof value === "string" && Object.hasOwn(FINISH_REASONS, value) ? FINISH_REASONS[value] : undefined; } function candidate(parts: Obj[], reason?: string): Obj { return { content: { role: "model", parts }, ...(reason ? { finishReason: reason } : {}), index: 0 }; } /** The thought signature a Chat tool call carries, if any (normalized). */ function chatCallSignature(extra: unknown): string | undefined { return normalizedClientExtraContent(extra)?.extra_content.google.thought_signature; } function functionCallPart(id: unknown, name: string, argumentsJson: unknown, index: number, signature?: string): Obj { let args: unknown = {}; if (typeof argumentsJson === "string") { if (argumentsJson.trim()) { try { args = JSON.parse(argumentsJson); } catch { throw new Error("Invalid Chat tool arguments"); } } } else if (argumentsJson !== undefined && argumentsJson !== null) args = argumentsJson; if (!isObj(args)) throw new Error("Invalid Chat tool arguments"); return { functionCall: { id: typeof id === "string" && id ? id : `call_gemini_response_${index}`, name, args }, ...(signature ? { thoughtSignature: signature } : {}), }; } /** A complete Chat completion as a GenerateContentResponse. Throws when the completion did not finish cleanly. */ export function chatToGeminiResponse(model: string, input: unknown): Obj { const body = object(input, "Chat response"); if (!Array.isArray(body.choices) || body.choices.length !== 1) throw new Error("Invalid Chat choices"); const choice = object(body.choices[0], "Chat choice"); const reason = finishReason(choice.finish_reason); if (!reason) throw new Error("Chat completion did not finish successfully"); const message = object(choice.message, "Chat message"); const parts: Obj[] = []; const thought = message.reasoning_content ?? message.reasoning; if (typeof thought === "string" && thought) parts.push({ text: thought, thought: true }); if (message.content != null) { if (typeof message.content !== "string") throw new Error("Invalid Chat content"); if (message.content) parts.push({ text: message.content }); } if (message.tool_calls !== undefined) { if (!Array.isArray(message.tool_calls)) throw new Error("Invalid Chat tool calls"); message.tool_calls.forEach((raw, i) => { const call = object(raw, "Chat tool call"); const fn = object(call.function, "Chat tool function"); parts.push(functionCallPart(call.id, text(fn.name, "tool name", true), fn.arguments, i, chatCallSignature(call.extra_content))); }); } if (!parts.length) parts.push({ text: "" }); const usage = usageMetadata(body.usage); return { candidates: [candidate(parts, reason)], ...(usage ? { usageMetadata: usage } : {}), modelVersion: model }; } type StreamTool = { id?: string; name: string; arguments: string; signature?: string }; export interface GeminiStreamState { model: string; finishReason?: unknown; usage?: Obj; tools: Map<number, StreamTool>; toolsEmitted: boolean; } export function createGeminiStreamState(model: string): GeminiStreamState { return { model, tools: new Map(), toolsEmitted: false }; } function streamChunk(state: GeminiStreamState, parts: Obj[]): Obj { return { candidates: [candidate(parts)], modelVersion: state.model }; } /** Consume one parsed Chat chunk. The caller owns settlement and may discard these records on failure. */ export function consumeGeminiChatChunk(state: GeminiStreamState, input: unknown): Obj[] { const body = object(input, "Chat chunk"); if (body.error !== undefined) throw new Error("Chat stream error"); if (body.usage != null) state.usage = usageMetadata(body.usage); if (!Array.isArray(body.choices) || body.choices.length > 1) throw new Error("Invalid Chat chunk choices"); if (!body.choices.length) return []; const choice = object(body.choices[0], "Chat choice"); const delta = object(choice.delta, "Chat delta"); if (state.finishReason !== undefined) throw new Error("Chat chunk after finish"); const records: Obj[] = []; const thought = delta.reasoning_content ?? delta.reasoning; if (thought != null) { const value = text(thought, "Chat reasoning"); if (value) records.push(streamChunk(state, [{ text: value, thought: true }])); } if (delta.content != null) { const value = text(delta.content, "Chat content"); if (value) records.push(streamChunk(state, [{ text: value }])); } if (delta.tool_calls !== undefined) { if (!Array.isArray(delta.tool_calls) || state.toolsEmitted) throw new Error("Invalid Chat tool delta"); for (const raw of delta.tool_calls) { const call = object(raw, "tool delta"); if (!Number.isSafeInteger(call.index) || (call.index as number) < 0) throw new Error("Invalid tool index"); const index = call.index as number; if (!state.tools.has(index) && state.tools.size >= MAX_GEMINI_TOOL_CALLS) throw new Error("Too many tool calls"); const current = state.tools.get(index) ?? { name: "", arguments: "" }; if (call.id !== undefined) { const id = text(call.id, "tool id", true); if (current.id && current.id !== id) throw new Error("Conflicting tool id"); current.id = id; } const signature = chatCallSignature(call.extra_content); if (signature) current.signature = signature; if (call.function !== undefined) { const fn = object(call.function, "tool function"); if (fn.name !== undefined) current.name += text(fn.name, "tool name"); if (fn.arguments !== undefined) current.arguments += text(fn.arguments, "tool arguments"); } state.tools.set(index, current); } } if (choice.finish_reason != null) { state.finishReason = choice.finish_reason; if (state.tools.size) { const parts = [...state.tools.entries()].sort((a, b) => a[0] - b[0]) .map(([index, tool]) => functionCallPart(tool.id, text(tool.name, "tool name", true), tool.arguments, index, tool.signature)); records.push(streamChunk(state, parts)); state.toolsEmitted = true; } } return records; } /** The closing chunk with the finish reason and usage. Call only after the outer handler confirms settlement. */ export function geminiStreamTerminal(state: GeminiStreamState): Obj | undefined { const reason = finishReason(state.finishReason); if (!reason || (state.tools.size > 0 && !state.toolsEmitted)) return undefined; return { candidates: [candidate([{ text: "" }], reason)], ...(state.usage ? { usageMetadata: state.usage } : {}), modelVersion: state.model, }; }