@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
771 lines (705 loc) • 38 kB
text/typescript
/**
* Pure Gemini Interactions API request and Chat Completions response projections.
*
* Request side: an Interactions create body becomes one Chat Completions body. Unknown fields are
* ignored (the API grows them often); a field this proxy cannot honor and that would change the
* answer (an agent, background execution, a hosted tool, non-text output, safety_settings) is a
* typed 400. The routed provider applies its own safety policy. Response side: a buffered Chat
* completion becomes an Interaction resource, and a
* Chat SSE chunk sequence becomes the Interactions SSE vocabulary (interaction.created, step.start,
* step.delta, step.stop, interaction.completed). Field names follow
* https://ai.google.dev/api/interactions-api; usage uses its total_* names.
*/
import { isTranslatorBudgetExceededError, type TranslatorBudget } from "../../lib/translator-budget";
import { GeminiCodecError, MAX_GEMINI_TOOL_CALLS, normalizeSchema } from "./gemini";
type Obj = Record<string, unknown>;
export class InteractionsCodecError extends Error {
readonly status = 400;
readonly code = "invalid_interactions_request";
constructor(message: string) { super(message); this.name = "InteractionsCodecError"; }
}
function fail(message: string): never { throw new InteractionsCodecError(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;
}
/** Lower-case schema types with the generateContent codec's rule, reporting failures as this codec's 400. */
function schema(value: unknown): unknown {
try { return normalizeSchema(value); } catch (error) {
if (error instanceof GeminiCodecError) fail(error.message);
throw error;
}
}
export interface InteractionsRequestPlan {
model: string;
stream: boolean;
store: boolean;
previousInteractionId?: string;
/** function_result call ids with no function_call earlier in this input. */
unmatchedResultIds: string[];
/** System messages built from system_instruction and developer/system turns, in order. */
systemMessages: Obj[];
/** The conversation messages this request adds (no system role). */
inputMessages: Obj[];
/** The input as Interactions steps, kept for a stored interaction's GET resource. */
inputSteps: Obj[];
/** The Chat body without messages; the handler sets messages. */
chat: Obj;
}
const BASE64 = /^[A-Za-z0-9+/_-]+={0,2}$/;
/** One Interactions content item as a Chat content part. Text and inline base64 images only. */
function contentPart(raw: unknown): Obj {
const item = object(raw, "content");
const type = item.type === undefined && typeof item.text === "string" ? "text" : text(item.type, "content type");
if (type === "text") return { type: "text", text: text(item.text, "text content") };
if (type === "image") {
if (item.data === undefined) fail("unsupported content: image without inline data");
const mime = text(item.mime_type ?? item.mimeType, "image mime_type", true).toLowerCase();
if (!/^image\/[a-z0-9.+-]+$/.test(mime)) fail("unsupported content: image mime_type");
const data = text(item.data, "image data", true);
if (!BASE64.test(data)) fail("Invalid image data encoding");
return { type: "image_url", image_url: { url: `data:${mime};base64,${data}` } };
}
return fail(`unsupported content type: ${type}`);
}
/** Chat user content: a string when text-only, parts when an image is present. */
function userContent(parts: Obj[]): string | Obj[] {
return parts.some(part => part.type !== "text") ? parts : parts.map(part => part.text as string).join("\n");
}
function contentList(value: unknown, label: string): Obj[] {
if (typeof value === "string") return [{ type: "text", text: value }];
if (isObj(value)) return [contentPart(value)];
return array(value, label).map(contentPart);
}
function contentText(value: unknown, label: string): string {
return contentList(value, label).map(part => {
if (part.type !== "text") fail(`unsupported content in ${label}`);
return part.text as string;
}).join("");
}
function systemInstructionText(value: unknown): string {
if (typeof value === "string") return value;
const source = object(value, "system_instruction");
if (typeof source.text === "string") return source.text;
if (source.parts !== undefined) return array(source.parts, "system_instruction parts").map(part => text(object(part, "system_instruction part").text, "system_instruction text")).join("\n");
return fail("Invalid system_instruction");
}
const STEP_TYPES = new Set(["user_input", "model_output", "thought", "function_call", "function_result"]);
const CONTENT_TYPES = new Set(["text", "image", "audio", "video", "document"]);
interface InputState {
system: Obj[];
messages: Obj[];
steps: Obj[];
assistant?: { content: string; calls: Obj[] };
pendingSignature?: string;
calls: Set<string>;
unmatched: string[];
callCount: number;
}
function flushAssistant(state: InputState): void {
const pending = state.assistant;
if (!pending) return;
state.assistant = undefined;
if (!pending.content && !pending.calls.length) return;
state.messages.push({ role: "assistant", content: pending.content || null, ...(pending.calls.length ? { tool_calls: pending.calls } : {}) });
}
function assistantOf(state: InputState): { content: string; calls: Obj[] } {
state.assistant ??= { content: "", calls: [] };
return state.assistant;
}
function resultText(value: unknown): string {
if (typeof value === "string") return value;
if (Array.isArray(value)) return contentText(value, "function_result result");
if (isObj(value)) return JSON.stringify(value);
return fail("Invalid function_result result");
}
function applyStep(state: InputState, raw: unknown): void {
const step = object(raw, "step");
const role = step.role === undefined ? undefined : text(step.role, "role");
const type = step.type === undefined && role !== undefined ? "turn" : text(step.type, "step type");
if (type === "turn") {
const content = step.content ?? step.parts;
if (role === "user") {
flushAssistant(state);
state.messages.push({ role: "user", content: userContent(contentList(content, "turn content")) });
state.steps.push({ type: "user_input", content: contentList(content, "turn content").map(part => part.type === "text" ? part : { type: "image" }) });
return;
}
if (role === "model" || role === "assistant") {
const text = contentText(content, "turn content");
assistantOf(state).content += text;
state.steps.push({ type: "model_output", content: [{ type: "text", text }] });
return;
}
// A conversation-level instruction applies from its position on, so it stays in the sequence;
// only the request-level system_instruction leads the conversation.
if (role === "system" || role === "developer") { flushAssistant(state); state.messages.push({ role: "system", content: contentText(content, "turn content") }); return; }
return fail(`unsupported role: ${role}`);
}
if (!STEP_TYPES.has(type)) fail(`unsupported step type: ${type}`);
state.steps.push({ ...step });
if (type === "user_input") {
flushAssistant(state);
state.messages.push({ role: "user", content: userContent(contentList(step.content ?? [], "user_input content")) });
return;
}
if (type === "model_output") { assistantOf(state).content += contentText(step.content ?? [], "model_output content"); return; }
if (type === "thought") {
// Thought summaries are not conversation text. A signature belongs to the next function call.
const signature = step.signature;
if (signature !== undefined) state.pendingSignature = text(signature, "thought signature", true);
return;
}
if (type === "function_call") {
if (++state.callCount > MAX_GEMINI_TOOL_CALLS) fail("Too many function calls");
const id = text(step.id, "function_call id", true);
if (state.calls.has(id)) fail("Duplicate function_call id");
const name = text(step.name, "function_call name", true);
const args = step.arguments === undefined ? {} : object(step.arguments, "function_call arguments");
const signature = state.pendingSignature;
state.pendingSignature = undefined;
state.calls.add(id);
assistantOf(state).calls.push({
id, type: "function", function: { name, arguments: JSON.stringify(args) },
...(signature ? { extra_content: { google: { thought_signature: signature } } } : {}),
});
return;
}
// function_result
flushAssistant(state);
const callId = text(step.call_id, "function_result call_id", true);
if (!state.calls.has(callId)) state.unmatched.push(callId);
const body = resultText(step.result);
if (step.is_error !== undefined && typeof step.is_error !== "boolean") fail("Invalid function_result is_error");
state.messages.push({ role: "tool", tool_call_id: callId, content: step.is_error === true ? JSON.stringify({ error: body }) : body });
}
function isContentItem(value: unknown): boolean {
return isObj(value) && ((typeof value.type === "string" && CONTENT_TYPES.has(value.type)) || (value.type === undefined && value.role === undefined && typeof value.text === "string"));
}
function inputMessages(input: unknown, state: InputState): void {
if (typeof input === "string") {
state.messages.push({ role: "user", content: input });
state.steps.push({ type: "user_input", content: [{ type: "text", text: input }] });
return;
}
if (isContentItem(input)) {
state.messages.push({ role: "user", content: userContent([contentPart(input)]) });
state.steps.push({ type: "user_input", content: [{ ...(input as Obj) }] });
return;
}
if (isObj(input)) { applyStep(state, input); flushAssistant(state); return; }
const items = array(input, "input");
if (items.length && items.every(isContentItem)) {
state.messages.push({ role: "user", content: userContent(items.map(contentPart)) });
state.steps.push({ type: "user_input", content: items.map(item => ({ ...(item as Obj) })) });
return;
}
for (const item of items) {
if (isContentItem(item)) fail("input mixes content items with steps");
applyStep(state, item);
}
flushAssistant(state);
}
function functionTools(value: unknown): Obj[] {
return array(value, "tools").map(raw => {
const tool = object(raw, "tool");
const type = text(tool.type, "tool type");
if (type !== "function") fail(`unsupported tool type: ${type}`);
const name = text(tool.name, "function name", true);
if (tool.description !== undefined) text(tool.description, "function description");
const parameters = tool.parameters ?? { type: "object", properties: {} };
object(parameters, "function parameters");
return { type: "function", function: { name, ...(typeof tool.description === "string" ? { description: tool.description } : {}), parameters: schema(parameters) } };
});
}
function toolChoice(value: unknown): unknown {
if (typeof value === "string") {
if (value === "auto" || value === "validated") return undefined;
if (value === "any") return "required";
if (value === "none") return "none";
return fail("Unsupported tool_choice");
}
const allowed = object(object(value, "tool_choice").allowed_tools, "tool_choice allowed_tools");
const mode = allowed.mode === undefined ? "auto" : text(allowed.mode, "allowed_tools mode");
const names = allowed.tools === undefined ? [] : array(allowed.tools, "allowed_tools tools").map(name => text(name, "allowed tool name", true));
if (mode === "none") return "none";
const entries = names.map(name => ({ type: "function", function: { name } }));
if (mode === "auto" || mode === "validated") return entries.length ? { type: "allowed_tools", allowed_tools: { mode: "auto", tools: entries } } : undefined;
if (mode === "any") {
// Same semantics as the generateContent codec: one allowed function is a forced call.
if (entries.length === 1) return entries[0];
return entries.length ? { type: "allowed_tools", allowed_tools: { mode: "required", tools: entries } } : "required";
}
return fail("Unsupported tool_choice mode");
}
const THINKING_LEVELS = new Set(["minimal", "low", "medium", "high", "xhigh"]);
function generationConfig(raw: unknown, chat: Obj): unknown {
if (raw === undefined) return undefined;
const config = object(raw, "generation_config");
for (const [key, chatKey] of [["temperature", "temperature"], ["top_p", "top_p"]] as const) {
if (config[key] !== undefined) chat[chatKey] = finiteNumber(config[key], key);
}
if (config.seed !== undefined) {
if (typeof config.seed !== "number" || !Number.isSafeInteger(config.seed)) fail("Invalid seed");
chat.seed = config.seed;
}
if (config.stop_sequences !== undefined) chat.stop = array(config.stop_sequences, "stop_sequences").map(stop => text(stop, "stop sequence"));
if (config.max_output_tokens !== undefined) {
const max = config.max_output_tokens;
if (typeof max !== "number" || !Number.isSafeInteger(max) || max < 1) fail("Invalid max_output_tokens");
chat.max_tokens = max;
}
if (config.thinking_level !== undefined) {
const level = text(config.thinking_level, "thinking_level").toLowerCase();
if (!THINKING_LEVELS.has(level)) fail("Invalid thinking_level");
chat.reasoning_effort = level;
}
if (config.thinking_summaries !== undefined) {
const summaries = text(config.thinking_summaries, "thinking_summaries");
if (summaries !== "auto" && summaries !== "none") fail("Invalid thinking_summaries");
// An explicit "none" must reach the Chat conversion, whose default is to summarize.
chat.include_reasoning = summaries === "auto";
}
return config.tool_choice;
}
function responseFormat(value: unknown): Obj | undefined {
const formats = Array.isArray(value) ? value : [value];
if (formats.length !== 1) fail("response_format must name one text format");
const format = object(formats[0], "response_format");
const type = format.type === undefined ? "text" : text(format.type, "response_format type");
if (type !== "text") fail(`unsupported response_format type: ${type}`);
const mime = format.mime_type === undefined ? undefined : text(format.mime_type, "response_format mime_type");
if (mime !== undefined && mime !== "application/json" && mime !== "text/plain") fail("unsupported response_format mime_type");
if (mime === "text/plain" || (mime === undefined && format.schema === undefined)) return undefined;
if (format.schema === undefined) return { type: "json_object" };
return { type: "json_schema", json_schema: { name: "response", schema: schema(object(format.schema, "response_format schema")) } };
}
const UNSUPPORTED_FIELDS = ["webhook_config", "environment", "agent_config", "safety_settings"] as const;
/** Project an Interactions create body onto a Chat Completions plan. */
export function interactionsToChat(input: unknown): InteractionsRequestPlan {
const body = object(input, "request");
const hasModel = body.model !== undefined;
const hasAgent = body.agent !== undefined;
if (hasModel === hasAgent) fail("request requires exactly one of model or agent");
if (hasAgent) fail("agent interactions require a native Interactions upstream");
const rawModel = text(body.model, "model", true).trim();
const model = rawModel.startsWith("models/") ? rawModel.slice("models/".length) : rawModel;
if (!model) fail("Invalid model");
if (body.stream !== undefined && typeof body.stream !== "boolean") fail("stream must be a boolean");
if (body.store !== undefined && typeof body.store !== "boolean") fail("store must be a boolean");
if (body.background !== undefined && typeof body.background !== "boolean") fail("background must be a boolean");
if (body.background === true) fail("background interactions are not supported");
// Fields that would change where or how the interaction runs; ignoring them would change the answer.
for (const field of UNSUPPORTED_FIELDS) if (body[field] !== undefined) fail(`${field} is not supported`);
const previous = body.previous_interaction_id === undefined ? undefined : text(body.previous_interaction_id, "previous_interaction_id", true);
if (body.response_modalities !== undefined) {
const modalities = array(body.response_modalities, "response_modalities").map(value => text(value, "response modality").toLowerCase());
if (modalities.some(value => value !== "text")) fail("only text output is supported");
}
if (body.input === undefined) fail("Invalid input");
const state: InputState = { system: [], messages: [], steps: [], calls: new Set(), unmatched: [], callCount: 0 };
if (body.system_instruction !== undefined) {
const instruction = systemInstructionText(body.system_instruction);
if (instruction) state.system.push({ role: "system", content: instruction });
}
inputMessages(body.input, state);
const stream = body.stream === true;
const chat: Obj = { model, stream };
if (body.tools !== undefined) {
const tools = functionTools(body.tools);
if (tools.length) chat.tools = tools;
}
const configChoice = generationConfig(body.generation_config, chat);
const choiceSource = body.tool_choice ?? configChoice;
if (choiceSource !== undefined && chat.tools !== undefined) {
const choice = toolChoice(choiceSource);
if (choice !== undefined) chat.tool_choice = choice;
}
if (body.response_format !== undefined) {
const format = responseFormat(body.response_format);
if (format) chat.response_format = format;
}
return {
model, stream, store: body.store !== false,
...(previous !== undefined ? { previousInteractionId: previous } : {}),
unmatchedResultIds: state.unmatched,
systemMessages: state.system,
inputMessages: state.messages,
inputSteps: state.steps,
chat,
};
}
export interface InteractionMeta { id: string; model: string; created: string; previousInteractionId?: string }
/** ocx-int- plus 128 random bits as lower-case hex. */
export function newInteractionId(): string {
return "ocx-int-" + Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString("hex");
}
export function interactionTimestamp(at = Date.now()): string {
return new Date(Math.floor(at / 1000) * 1000).toISOString().replace(".000Z", "Z");
}
const STATUS_BY_FINISH: Readonly<Record<string, string>> = {
stop: "completed",
tool_calls: "requires_action",
function_call: "requires_action",
length: "incomplete",
content_filter: "incomplete",
};
function interactionStatus(finish: unknown): string | undefined {
return typeof finish === "string" && Object.hasOwn(STATUS_BY_FINISH, finish) ? STATUS_BY_FINISH[finish] : undefined;
}
function nonNegativeInt(value: unknown): number | undefined {
return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
}
/** Chat usage as Interactions usage (Google's total_* names; output excludes thoughts). */
export function interactionUsage(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;
return {
total_input_tokens: prompt ?? 0,
total_cached_tokens: nonNegativeInt(promptDetails.cached_tokens) ?? 0,
total_output_tokens: Math.max(0, (completion ?? 0) - thoughts),
total_thought_tokens: thoughts,
total_tokens: (prompt ?? 0) + (completion ?? 0),
};
}
function callArguments(raw: unknown): Obj {
let args: unknown = {};
if (typeof raw === "string") {
if (raw.trim()) { try { args = JSON.parse(raw); } catch { throw new Error("Invalid Chat tool arguments"); } }
} else if (raw !== undefined && raw !== null) args = raw;
if (!isObj(args)) throw new Error("Invalid Chat tool arguments");
return args;
}
function callSignature(call: Obj): string | undefined {
const extra = call.extra_content;
if (!isObj(extra) || !isObj(extra.google)) return undefined;
const signature = extra.google.thought_signature;
return typeof signature === "string" && signature ? signature : undefined;
}
/** The output steps of one assistant answer: thought, model_output, then function calls. */
function outputSteps(reasoning: string, content: string, calls: { id: string; name: string; arguments: Obj; signature?: string }[]): Obj[] {
const steps: Obj[] = [];
if (reasoning) steps.push({ type: "thought", summary: [{ type: "text", text: reasoning }] });
if (content) steps.push({ type: "model_output", content: [{ type: "text", text: content }] });
for (const call of calls) {
if (call.signature) steps.push({ type: "thought", signature: call.signature });
steps.push({ type: "function_call", id: call.id, name: call.name, arguments: call.arguments });
}
return steps;
}
/** The assistant message a stored interaction keeps for the next turn. */
export interface InteractionAnswer { reasoning: string; content: string; calls: { id: string; name: string; arguments: Obj; signature?: string }[]; status: string; usage?: Obj }
export function interactionAssistantMessage(answer: InteractionAnswer): Obj | undefined {
if (!answer.content && !answer.calls.length) return undefined;
return {
role: "assistant",
content: answer.content || null,
...(answer.calls.length ? { tool_calls: answer.calls.map(call => ({
id: call.id, type: "function", function: { name: call.name, arguments: JSON.stringify(call.arguments) },
...(call.signature ? { extra_content: { google: { thought_signature: call.signature } } } : {}),
})) } : {}),
};
}
export function interactionResource(meta: InteractionMeta, answer: InteractionAnswer, updated = meta.created): Obj {
return {
id: meta.id, object: "interaction", status: answer.status, created: meta.created, updated, model: meta.model,
...(meta.previousInteractionId ? { previous_interaction_id: meta.previousInteractionId } : {}),
steps: outputSteps(answer.reasoning, answer.content, answer.calls),
...(answer.usage ? { usage: answer.usage } : {}),
};
}
/** A complete Chat completion as the answer of one interaction. Throws when it did not finish cleanly. */
export function chatCompletionAnswer(input: unknown): InteractionAnswer {
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 status = interactionStatus(choice.finish_reason);
if (!status) throw new Error("Chat completion did not finish successfully");
const message = object(choice.message, "Chat message");
const thought = message.reasoning_content ?? message.reasoning;
if (message.content != null && typeof message.content !== "string") throw new Error("Invalid Chat content");
const calls: InteractionAnswer["calls"] = [];
if (message.tool_calls !== undefined) {
if (!Array.isArray(message.tool_calls)) throw new Error("Invalid Chat tool calls");
message.tool_calls.forEach((raw, index) => {
const call = object(raw, "Chat tool call");
const fn = object(call.function, "Chat tool function");
const signature = callSignature(call);
calls.push({ id: typeof call.id === "string" && call.id ? call.id : `call_interaction_${index}`, name: text(fn.name, "tool name", true), arguments: callArguments(fn.arguments), ...(signature ? { signature } : {}) });
});
}
const usage = interactionUsage(body.usage);
return { reasoning: typeof thought === "string" ? thought : "", content: (message.content as string | null | undefined) ?? "", calls, status, ...(usage ? { usage } : {}) };
}
export interface InteractionsSseEvent { event: string; data: Obj }
type StreamTool = { id?: string; name: string; arguments: string; signature?: string };
type RetainedAnswer = Pick<InteractionAnswer, "reasoning" | "content" | "calls"> & {
bytes: number;
remainingEntryBytes: number;
};
const RETAINED_SCOPE = { kind: "retained_collectors" } as const;
export interface InteractionsStreamState {
meta: InteractionMeta;
budget: TranslatorBudget;
created: boolean;
index: number;
open?: "thought" | "model_output";
retained?: RetainedAnswer;
finishReason?: unknown;
usage?: Obj;
tools: Map<number, StreamTool>;
toolMetadataBytes: number;
toolsEmitted: boolean;
}
export function createInteractionsStreamState(meta: InteractionMeta, budget: TranslatorBudget, remainingEntryBytes = 0): InteractionsStreamState {
const retained = remainingEntryBytes > 0
? { reasoning: "", content: "", calls: [], bytes: 0, remainingEntryBytes }
: undefined;
return { meta, budget, created: false, index: -1, retained, tools: new Map(), toolMetadataBytes: 0, toolsEmitted: false };
}
function discardRetainedAnswer(state: InteractionsStreamState): void {
if (!state.retained) return;
state.budget.releaseRetained(state.retained.bytes, RETAINED_SCOPE);
state.retained = undefined;
}
function reserveStoredOutput(state: InteractionsStreamState, liveBytes: number, entryBytes: number): RetainedAnswer | undefined {
const retained = state.retained;
if (!retained) return undefined;
if (entryBytes <= retained.remainingEntryBytes) {
try {
state.budget.chargeRetained(liveBytes, RETAINED_SCOPE);
retained.bytes += liveBytes;
retained.remainingEntryBytes -= entryBytes;
return retained;
} catch (error) {
if (!isTranslatorBudgetExceededError(error)) throw error;
}
}
// Storage is best effort. Drop the prefix and keep emitting the full wire response.
discardRetainedAnswer(state);
return undefined;
}
function retainStreamText(state: InteractionsStreamState, field: "reasoning" | "content", value: string): void {
if (!state.retained) return;
const bytes = Buffer.byteLength(value);
const encodedBytes = Buffer.byteLength(JSON.stringify(value)) - 2;
// Answer text appears in both the Chat history and the resource. Thoughts appear only in the resource.
const retained = reserveStoredOutput(state, bytes, field === "content" ? 2 * encodedBytes : encodedBytes);
if (retained) retained[field] += value;
}
function retainStreamCall(state: InteractionsStreamState, call: InteractionAnswer["calls"][number], args: string): void {
if (!state.retained) return;
const metadata = [call.id, call.name, call.signature ?? ""];
const argsBytes = Buffer.byteLength(args);
const bytes = argsBytes + metadata.reduce((total, value) => total + Buffer.byteLength(value), 0);
const entryBytes = argsBytes + Buffer.byteLength(JSON.stringify(args)) - 2
+ metadata.reduce((total, value) => total + 2 * (Buffer.byteLength(JSON.stringify(value)) - 2), 0);
reserveStoredOutput(state, bytes, entryBytes)?.calls.push(call);
}
/** Release the fragment buffer once the whole calls have been emitted, or when the stream stops. */
function releaseStreamTools(state: InteractionsStreamState): void {
for (const index of state.tools.keys()) state.budget.closeCall(String(index));
state.tools.clear();
state.budget.releaseRetained(state.toolMetadataBytes, { kind: "tool_args" });
state.toolMetadataBytes = 0;
}
export function disposeInteractionsStream(state: InteractionsStreamState): void {
discardRetainedAnswer(state);
releaseStreamTools(state);
state.budget.dispose();
}
function chargeToolMetadata(state: InteractionsStreamState, value: string, previous = ""): void {
const delta = Buffer.byteLength(value) - Buffer.byteLength(previous);
if (delta > 0) state.budget.chargeRetained(delta, { kind: "tool_args" });
if (delta < 0) state.budget.releaseRetained(-delta, { kind: "tool_args" });
state.toolMetadataBytes += delta;
}
function sse(event: string, data: Obj): InteractionsSseEvent {
return { event, data: { ...data, event_type: event } };
}
function createdEvent(state: InteractionsStreamState): InteractionsSseEvent[] {
if (state.created) return [];
state.created = true;
const { id, model, created } = state.meta;
return [sse("interaction.created", { interaction: { id, object: "interaction", status: "in_progress", model, created, updated: created } })];
}
function closeStep(state: InteractionsStreamState, events: InteractionsSseEvent[]): void {
if (state.open === undefined) return;
events.push(sse("step.stop", { index: state.index }));
state.open = undefined;
}
function openStep(state: InteractionsStreamState, type: "thought" | "model_output", events: InteractionsSseEvent[]): void {
if (state.open === type) return;
closeStep(state, events);
state.index++;
state.open = type;
events.push(sse("step.start", { index: state.index, step: { type } }));
}
/** Consume one parsed Chat chunk. The caller owns settlement and may discard these events on failure. */
export function consumeInteractionsChatChunk(state: InteractionsStreamState, input: unknown): InteractionsSseEvent[] {
const body = object(input, "Chat chunk");
if (body.error !== undefined) throw new Error("Chat stream error");
const events = createdEvent(state);
if (body.usage != null) state.usage = interactionUsage(body.usage);
if (!Array.isArray(body.choices) || body.choices.length > 1) throw new Error("Invalid Chat chunk choices");
if (!body.choices.length) return events;
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 thought = delta.reasoning_content ?? delta.reasoning;
if (thought != null) {
const value = text(thought, "Chat reasoning");
if (value) {
openStep(state, "thought", events);
retainStreamText(state, "reasoning", value);
events.push(sse("step.delta", { index: state.index, delta: { type: "thought_summary", content: { type: "text", text: value } } }));
}
}
if (delta.content != null) {
const value = text(delta.content, "Chat content");
if (value) {
openStep(state, "model_output", events);
retainStreamText(state, "content", value);
events.push(sse("step.delta", { index: state.index, delta: { type: "text", 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");
chargeToolMetadata(state, id, current.id);
current.id = id;
}
const signature = callSignature(call);
if (signature) {
chargeToolMetadata(state, signature, current.signature);
current.signature = signature;
}
if (call.function !== undefined) {
const fn = object(call.function, "tool function");
if (fn.name !== undefined) {
const name = text(fn.name, "tool name");
chargeToolMetadata(state, name);
current.name += name;
}
if (fn.arguments !== undefined) {
const args = text(fn.arguments, "tool arguments");
state.budget.chargeRetained(Buffer.byteLength(args), { kind: "tool_args", callId: String(index) });
current.arguments += args;
}
}
state.tools.set(index, current);
}
}
if (choice.finish_reason != null) {
state.finishReason = choice.finish_reason;
if (state.tools.size) {
closeStep(state, events);
for (const [index, tool] of [...state.tools.entries()].sort((a, b) => a[0] - b[0])) {
const args = callArguments(tool.arguments);
const id = tool.id ?? `call_interaction_${index}`;
const name = text(tool.name, "tool name", true);
if (tool.signature) {
state.index++;
events.push(sse("step.start", { index: state.index, step: { type: "thought" } }));
events.push(sse("step.delta", { index: state.index, delta: { type: "thought_signature", signature: tool.signature } }));
events.push(sse("step.stop", { index: state.index }));
}
state.index++;
events.push(sse("step.start", { index: state.index, step: { type: "function_call", id, name, arguments: {} } }));
const wireArgs = JSON.stringify(args);
events.push(sse("step.delta", { index: state.index, delta: { type: "arguments_delta", arguments: wireArgs } }));
events.push(sse("step.stop", { index: state.index }));
retainStreamCall(state, { id, name, arguments: args, ...(tool.signature ? { signature: tool.signature } : {}) }, wireArgs);
}
releaseStreamTools(state);
state.toolsEmitted = true;
}
}
return events;
}
/** The answer a finished stream produced, or undefined when it did not finish cleanly. */
export function interactionsStreamAnswer(state: InteractionsStreamState): InteractionAnswer | undefined {
const status = interactionStatus(state.finishReason);
if (!status || (state.tools.size > 0 && !state.toolsEmitted)) return undefined;
const { retained, usage } = state;
return { reasoning: retained?.reasoning ?? "", content: retained?.content ?? "", calls: retained?.calls ?? [], status, ...(usage ? { usage } : {}) };
}
/** The closing events. Call only after the outer handler confirms settlement. */
export function interactionsStreamTerminal(state: InteractionsStreamState, answer: Pick<InteractionAnswer, "status" | "usage">, updated = state.meta.created): InteractionsSseEvent[] {
const events = createdEvent(state);
closeStep(state, events);
const { id, model, created } = state.meta;
events.push(sse("interaction.completed", { interaction: { id, object: "interaction", status: answer.status, model, created, updated, ...(answer.usage ? { usage: answer.usage } : {}) } }));
return events;
}
const ERROR_CODES: Readonly<Record<number, string>> = {
400: "invalid_argument", 401: "unauthenticated", 403: "permission_denied", 404: "not_found", 413: "invalid_argument",
429: "resource_exhausted", 499: "cancelled", 501: "unimplemented", 503: "unavailable", 504: "deadline_exceeded",
};
/** The failure events a stream ends with after it was committed. */
export function interactionsStreamFailure(state: InteractionsStreamState, status: number, message: string): InteractionsSseEvent[] {
const events = createdEvent(state);
events.push(sse("error", { error: { code: ERROR_CODES[status] ?? "internal", message } }));
return events;
}
export function encodeInteractionsEvents(events: InteractionsSseEvent[]): Uint8Array[] {
const encoder = new TextEncoder();
return events.map(event => encoder.encode(`event: ${event.event}\ndata: ${JSON.stringify(event.data)}\n\n`));
}
function toolCallIds(message: Obj | undefined): string[] {
if (!message || message.role !== "assistant" || !Array.isArray(message.tool_calls)) return [];
return message.tool_calls.flatMap(call => (isObj(call) && typeof call.id === "string" ? [call.id] : []));
}
/** Call ids of the history's last assistant turn that no later tool message answered. */
export function pendingCallIds(history: Obj[]): Set<string> {
let last = -1;
for (let i = history.length - 1; i >= 0; i--) if (history[i]!.role === "assistant") { last = i; break; }
const pending = new Set(toolCallIds(history[last]));
for (const message of history.slice(last + 1)) if (message.role === "tool" && typeof message.tool_call_id === "string") pending.delete(message.tool_call_id);
return pending;
}
/**
* Continue a stored history with a chained input. A leading assistant message that only resends the
* pending calls is dropped (they are already in history). Returns undefined when a function_result the
* input does not define is not one of the pending calls answered at the very start of the input.
*/
export function chainInput(history: Obj[], plan: Pick<InteractionsRequestPlan, "inputMessages" | "unmatchedResultIds">): Obj[] | undefined {
const pending = pendingCallIds(history);
let input = plan.inputMessages;
const first = input[0];
const resent = toolCallIds(first);
if (first && resent.length && !first.content && resent.every(id => pending.has(id))) input = input.slice(1);
if (!plan.unmatchedResultIds.length) return input;
const leading = new Set<string>();
for (const message of input) {
if (message.role !== "tool") break;
if (typeof message.tool_call_id === "string") leading.add(message.tool_call_id);
}
return plan.unmatchedResultIds.every(id => pending.has(id) && leading.has(id)) ? input : undefined;
}