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