@exvio/os-backend-core 0.4.0

package/src/ai/providers/gemini.ts

@@ -0,0 +1,919 @@
+import {
+  ApiError,
+  FunctionCallingConfigMode,
+  GoogleGenAI,
+  type EmbedContentParameters,
+  type EmbedContentResponse,
+  type Content,
+  type GenerateContentConfig,
+  type GenerateContentParameters,
+  type GenerateContentResponse,
+  type GoogleGenAIOptions,
+  type Part,
+} from '@google/genai'
+
+import { AIError, aiErrorFromHttpStatus } from '../errors.ts'
+import { isSupportedAIJSONSchema, matchesAIJSONSchema } from '../schema.ts'
+import type {
+  AIChatOutput,
+  AIEmbeddingOutput,
+  AIFinishReason,
+  AIOperation,
+  AIMessage,
+  AIProvider,
+  AIProviderChatRequest,
+  AIProviderContentRequest,
+  AIProviderEmbedRequest,
+  AIProviderFactory,
+  AIProviderFactoryContext,
+  AIProviderObjectRequest,
+  AIProviderTextRequest,
+  AIResult,
+  AIStreamEvent,
+  AIUsage,
+  AIContentPart,
+  AIToolCall,
+  AIToolChoice,
+  AIToolDefinition,
+} from '../types.ts'
+
+const GEMINI_ENDPOINT = 'https://generativelanguage.googleapis.com'
+const TOOL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_.:-]{0,127}$/
+
+/** The narrow SDK surface used by the provider, exposed for transport-free tests. */
+export interface GeminiClientLike {
+  readonly models: {
+    generateContent(parameters: GenerateContentParameters): Promise<GenerateContentResponse>
+    generateContentStream(
+      parameters: GenerateContentParameters,
+    ): Promise<AsyncGenerator<GenerateContentResponse, void, unknown>>
+    embedContent(parameters: EmbedContentParameters): Promise<EmbedContentResponse>
+  }
+}
+
+export type GeminiClientFactory = (options: GoogleGenAIOptions) => GeminiClientLike
+
+export interface GeminiProviderFactoryOptions {
+  /** Tests inject a fake client here. Production uses the maintained Google SDK. */
+  readonly createClient?: GeminiClientFactory
+}
+
+/**
+ * Creates a stateless provider factory. `create` builds a fresh SDK client for
+ * every invocation, so an API key can never bleed across tenant requests.
+ */
+export function createGeminiProviderFactory(
+  options: GeminiProviderFactoryOptions = {},
+): AIProviderFactory {
+  const createClient = options.createClient ?? ((clientOptions) => new GoogleGenAI(clientOptions))
+
+  const factory: AIProviderFactory = (context: AIProviderFactoryContext): AIProvider => {
+      if (!options.createClient && context.fetch !== globalThis.fetch) {
+        throw new AIError({
+          code: 'invalid_config',
+          message: 'Gemini does not support the configured custom fetch transport',
+          provider: context.name,
+        })
+      }
+      const apiKey = context.config.apiKey?.trim()
+      if (!apiKey) {
+        throw new AIError({
+          code: 'not_configured',
+          message: 'Gemini is not configured',
+          provider: context.name,
+        })
+      }
+
+      // The Gemini adapter intentionally accepts only Google's API origin. A
+      // configurable arbitrary base URL would forward the tenant API key to it.
+      const endpoint = normalizeGeminiEndpoint(
+        context.config.endpoint ?? context.config.baseUrl,
+        context.name,
+      )
+      const client = createClient({
+        apiKey,
+        ...(endpoint ? { httpOptions: { baseUrl: endpoint } } : {}),
+      })
+      return new GeminiProvider(client, context.name)
+  }
+  Object.defineProperty(factory, 'defaultEndpoint', {
+    value: GEMINI_ENDPOINT,
+    enumerable: true,
+    writable: false,
+    configurable: false,
+  })
+  return Object.freeze(factory)
+}
+
+export const geminiProviderFactory = createGeminiProviderFactory()
+
+/** Convenient constructor matching the other built-in provider subpaths. */
+export function createGeminiProvider(): AIProviderFactory {
+  return geminiProviderFactory
+}
+
+class GeminiProvider implements AIProvider {
+  readonly name: string
+  readonly capabilities = Object.freeze({
+    text: true,
+    content: true,
+    chat: true,
+    streaming: true,
+    object: true,
+    embedding: true,
+    tools: true,
+  })
+
+  constructor(
+    private readonly client: GeminiClientLike,
+    private readonly provider: string,
+  ) {
+    this.name = provider
+  }
+
+  async generateText(request: AIProviderTextRequest): Promise<AIResult<string>> {
+    assertRequestBase(request, this.provider)
+    if (typeof request.prompt !== 'string' || request.prompt.length === 0) {
+      throw invalidRequest(this.provider, request.model, 'Gemini prompt must not be empty')
+    }
+
+    return this.generateTextLike(request, request.prompt)
+  }
+
+  async generateContent(request: AIProviderContentRequest): Promise<AIResult<string>> {
+    assertRequestBase(request, this.provider)
+    if (!Array.isArray(request.content) || request.content.length === 0) {
+      throw invalidRequest(this.provider, request.model, 'Gemini content must not be empty')
+    }
+
+    return this.generateTextLike(request, [{ role: 'user', parts: toGeminiParts(request.content) }])
+  }
+
+  async generateChat(request: AIProviderChatRequest): Promise<AIResult<AIChatOutput>> {
+    assertRequestBase(request, this.provider)
+    validateChat(request, this.provider)
+
+    try {
+      const response = await this.client.models.generateContent({
+        model: request.model,
+        contents: toGeminiMessages(request.messages, this.provider, request.model),
+        config: buildGenerationConfig(request, buildToolConfig(request, this.provider)),
+      })
+      const toolCalls = extractToolCalls(
+        response,
+        request.tools ?? [],
+        this.provider,
+        request.model,
+      )
+      const text = extractText(response)
+      const finishReason = normalizeFinishReason(response, toolCalls.length > 0)
+
+      if (finishReason === 'content_filter') {
+        throw contentFiltered(this.provider, response.modelVersion ?? request.model, 'chat')
+      }
+
+      if (text.trim().length === 0 && toolCalls.length === 0) {
+        throw emptyResponse(this.provider, request.model)
+      }
+
+      return {
+        output: { text, toolCalls },
+        ...responseMetadata(response, this.provider, request.model, finishReason),
+      }
+    } catch (error) {
+      throw mapGeminiError(error, this.provider, request.model, request.signal)
+    }
+  }
+
+  async *streamChat(request: AIProviderChatRequest): AsyncIterable<AIStreamEvent> {
+    assertRequestBase(request, this.provider)
+    validateChat(request, this.provider)
+
+    let emitted = false
+    let text = ''
+    const toolCalls: AIToolCall[] = []
+    const seenToolCallIds = new Set<string>()
+    let lastResponse: GenerateContentResponse | undefined
+    let promptBlocked = false
+
+    try {
+      const stream = await this.client.models.generateContentStream({
+        model: request.model,
+        contents: toGeminiMessages(request.messages, this.provider, request.model),
+        config: buildGenerationConfig(request, buildToolConfig(request, this.provider)),
+      })
+
+      for await (const chunk of stream) {
+        lastResponse = chunk
+        promptBlocked ||= isPromptBlocked(chunk)
+        const delta = extractText(chunk)
+        if (delta.length > 0) {
+          emitted = true
+          text += delta
+          yield { type: 'text-delta', delta }
+        }
+
+        const chunkCalls = extractToolCalls(
+          chunk,
+          request.tools ?? [],
+          this.provider,
+          request.model,
+          toolCalls.length,
+        )
+        for (const toolCall of chunkCalls) {
+          if (seenToolCallIds.has(toolCall.id)) {
+            throw invalidToolArguments(this.provider, request.model)
+          }
+          seenToolCallIds.add(toolCall.id)
+          emitted = true
+          toolCalls.push(toolCall)
+          yield { type: 'tool-call', toolCall }
+        }
+      }
+
+      if (!lastResponse) {
+        throw new AIError({
+          code: 'invalid_response',
+          message: 'Gemini stream ended without a response',
+          provider: this.provider,
+          model: request.model,
+        })
+      }
+
+      const finishReason = promptBlocked
+        ? 'content_filter'
+        : normalizeFinishReason(lastResponse, toolCalls.length > 0)
+      if (finishReason === 'content_filter') {
+        throw contentFiltered(this.provider, lastResponse.modelVersion ?? request.model, 'stream')
+      }
+      if (!emitted) {
+        throw emptyResponse(this.provider, request.model)
+      }
+
+      yield {
+        type: 'finish',
+        result: {
+          output: { text, toolCalls },
+          ...responseMetadata(lastResponse, this.provider, request.model, finishReason),
+        },
+      }
+    } catch (error) {
+      const mapped = mapGeminiError(error, this.provider, request.model, request.signal)
+      if (emitted && mapped.code !== 'invalid_response' && mapped.code !== 'content_filtered') {
+        throw new AIError({
+          code: 'invalid_response',
+          message: 'Gemini stream was interrupted',
+          provider: this.provider,
+          model: request.model,
+        })
+      }
+      throw mapped
+    }
+  }
+
+  async generateObject(request: AIProviderObjectRequest<unknown>): Promise<AIResult<unknown>> {
+    assertRequestBase(request, this.provider)
+    if (typeof request.prompt !== 'string' || request.prompt.length === 0) {
+      throw invalidRequest(this.provider, request.model, 'Gemini prompt must not be empty')
+    }
+    if (
+      !isPlainRecord(request.schema.jsonSchema)
+      || !isJsonValue(request.schema.jsonSchema)
+      || !isSupportedAIJSONSchema(request.schema.jsonSchema)
+    ) {
+      throw invalidRequest(this.provider, request.model, 'Gemini structured output schema is invalid')
+    }
+
+    try {
+      const response = await this.client.models.generateContent({
+        model: request.model,
+        contents: request.prompt,
+        config: buildGenerationConfig(request, {
+          responseMimeType: 'application/json',
+          responseJsonSchema: request.schema.jsonSchema,
+        }),
+      })
+      const finishReason = normalizeFinishReason(response, false)
+      if (finishReason === 'content_filter') {
+        throw contentFiltered(this.provider, response.modelVersion ?? request.model, 'object')
+      }
+      const text = extractText(response)
+      if (text.trim().length === 0) throw emptyResponse(this.provider, request.model)
+
+      let decoded: unknown
+      try {
+        decoded = JSON.parse(text)
+      } catch {
+        throw structuredOutputError(this.provider, request.model)
+      }
+
+      return {
+        output: decoded,
+        ...responseMetadata(response, this.provider, request.model),
+      }
+    } catch (error) {
+      throw mapGeminiError(error, this.provider, request.model, request.signal)
+    }
+  }
+
+  async embed(request: AIProviderEmbedRequest): Promise<AIResult<AIEmbeddingOutput>> {
+    assertRequestBase(request, this.provider)
+    if (!Array.isArray(request.input) || request.input.length === 0) {
+      throw invalidRequest(this.provider, request.model, 'Gemini embedding input must not be empty')
+    }
+    if (request.input.some((input) => typeof input !== 'string' || input.length === 0)) {
+      throw invalidRequest(this.provider, request.model, 'Gemini embedding inputs must be non-empty strings')
+    }
+    if (request.dimensions !== undefined && (!Number.isSafeInteger(request.dimensions) || request.dimensions <= 0)) {
+      throw invalidRequest(this.provider, request.model, 'Gemini embedding dimensions must be positive')
+    }
+
+    try {
+      const response = await this.client.models.embedContent({
+        model: request.model,
+        contents: [...request.input],
+        config: {
+          abortSignal: request.signal,
+          httpOptions: requestHttpOptions(request.timeoutMs),
+          ...(request.dimensions ? { outputDimensionality: request.dimensions } : {}),
+        },
+      })
+      const embeddings = response.embeddings?.map((embedding) => embedding.values)
+      if (
+        !embeddings
+        || embeddings.length !== request.input.length
+        || embeddings.some((values) => (
+          !Array.isArray(values)
+          || values.length === 0
+          || values.some((value) => typeof value !== 'number' || !Number.isFinite(value))
+        ))
+      ) {
+        throw new AIError({
+          code: 'invalid_response',
+          message: 'Gemini returned invalid embeddings',
+          provider: this.provider,
+          model: request.model,
+        })
+      }
+
+      return {
+        output: { embeddings: embeddings as number[][] },
+        provider: this.provider,
+        model: request.model,
+        usage: null,
+        finishReason: 'stop',
+        requestId: requestIdFromResponse(response),
+      }
+    } catch (error) {
+      throw mapGeminiError(error, this.provider, request.model, request.signal)
+    }
+  }
+
+  private async generateTextLike(
+    request: AIProviderTextRequest | AIProviderContentRequest,
+    contents: GenerateContentParameters['contents'],
+  ): Promise<AIResult<string>> {
+    try {
+      const response = await this.client.models.generateContent({
+        model: request.model,
+        contents,
+        config: buildGenerationConfig(request),
+      })
+      const finishReason = normalizeFinishReason(response, false)
+      if (finishReason === 'content_filter') {
+        throw contentFiltered(
+          this.provider,
+          response.modelVersion ?? request.model,
+          'prompt' in request ? 'text' : 'content',
+        )
+      }
+      const text = extractText(response)
+      if (text.trim().length === 0) throw emptyResponse(this.provider, request.model)
+      return {
+        output: text,
+        ...responseMetadata(response, this.provider, request.model),
+      }
+    } catch (error) {
+      throw mapGeminiError(error, this.provider, request.model, request.signal)
+    }
+  }
+}
+
+function normalizeGeminiEndpoint(endpoint: string | undefined, provider: string): string | undefined {
+  if (endpoint === undefined) return undefined
+
+  let parsed: URL
+  try {
+    parsed = new URL(endpoint)
+  } catch {
+    throw new AIError({ code: 'endpoint_not_allowed', message: 'Gemini endpoint is not allowed', provider })
+  }
+  const expected = new URL(GEMINI_ENDPOINT)
+  if (
+    parsed.protocol !== 'https:'
+    || parsed.username !== ''
+    || parsed.password !== ''
+    || parsed.origin !== expected.origin
+    || (parsed.pathname !== '' && parsed.pathname !== '/')
+    || parsed.search !== ''
+    || parsed.hash !== ''
+  ) {
+    throw new AIError({ code: 'endpoint_not_allowed', message: 'Gemini endpoint is not allowed', provider })
+  }
+  return parsed.origin
+}
+
+function assertRequestBase(
+  request:
+    | AIProviderTextRequest
+    | AIProviderContentRequest
+    | AIProviderChatRequest
+    | AIProviderObjectRequest
+    | AIProviderEmbedRequest,
+  provider: string,
+): void {
+  if (typeof request.model !== 'string' || request.model.trim().length === 0) {
+    throw invalidRequest(provider, '', 'Gemini model must not be empty')
+  }
+  if (!Number.isSafeInteger(request.timeoutMs) || request.timeoutMs <= 0) {
+    throw invalidRequest(provider, request.model, 'Gemini timeout must be a positive integer')
+  }
+  const maxOutputTokens = 'maxOutputTokens' in request ? request.maxOutputTokens : undefined
+  if (maxOutputTokens !== undefined && (
+    !Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0
+  )) {
+    throw invalidRequest(provider, request.model, 'Gemini maxOutputTokens must be positive')
+  }
+  const temperature = 'temperature' in request ? request.temperature : undefined
+  if (temperature !== undefined && !Number.isFinite(temperature)) {
+    throw invalidRequest(provider, request.model, 'Gemini temperature must be finite')
+  }
+}
+
+function buildGenerationConfig(
+  request: AIProviderTextRequest | AIProviderContentRequest | AIProviderChatRequest | AIProviderObjectRequest,
+  toolConfig: Partial<GenerateContentConfig> = {},
+): GenerateContentConfig {
+  const systemMessages = 'messages' in request
+    ? request.messages
+      .filter((message) => message.role === 'system')
+      .map((message) => message.content)
+    : []
+  const systemInstruction = [request.systemInstruction, ...systemMessages]
+    .filter((value): value is string => typeof value === 'string' && value.length > 0)
+    .join('\n\n')
+  return {
+    abortSignal: request.signal,
+    httpOptions: requestHttpOptions(request.timeoutMs),
+    ...(systemInstruction ? { systemInstruction } : {}),
+    ...(request.maxOutputTokens !== undefined ? { maxOutputTokens: request.maxOutputTokens } : {}),
+    ...(request.temperature !== undefined ? { temperature: request.temperature } : {}),
+    ...(request.topP !== undefined ? { topP: request.topP } : {}),
+    ...(request.stopSequences !== undefined ? { stopSequences: [...request.stopSequences] } : {}),
+    ...(request.disableThinking ? { thinkingConfig: { thinkingBudget: 0 } } : {}),
+    ...(request.responseFormat === 'json' ? { responseMimeType: 'application/json' } : {}),
+    ...toolConfig,
+  }
+}
+
+function requestHttpOptions(timeoutMs: number): NonNullable<GenerateContentConfig['httpOptions']> {
+  return {
+    timeout: timeoutMs,
+    // Retry belongs to the shared runtime. Disable the SDK's own retry loop so
+    // attempts, cancellation and stream replay rules remain observable.
+    retryOptions: { attempts: 1 },
+  }
+}
+
+function buildToolConfig(
+  request: AIProviderChatRequest,
+  provider: string,
+): Partial<GenerateContentConfig> {
+  const declarations = request.tools ?? []
+  if (declarations.length > 512) {
+    throw invalidRequest(provider, request.model, 'Gemini accepts at most 512 tools')
+  }
+  for (const declaration of declarations) validateToolDeclaration(declaration, provider, request.model)
+
+  const choice = request.toolChoice ?? 'auto'
+  if ((choice === 'required' || typeof choice === 'object') && declarations.length === 0) {
+    throw invalidRequest(provider, request.model, 'Gemini tool choice requires declared tools')
+  }
+
+  const tools = declarations.length > 0
+    ? [{
+        functionDeclarations: declarations.map((declaration) => ({
+          name: declaration.name,
+          ...(declaration.description ? { description: declaration.description } : {}),
+          parametersJsonSchema: declaration.parameters,
+        })),
+      }]
+    : undefined
+
+  const functionCallingConfig = toGeminiToolChoice(choice, declarations, provider, request.model)
+  return {
+    ...(tools ? { tools } : {}),
+    ...(tools || choice !== 'auto' ? { toolConfig: { functionCallingConfig } } : {}),
+  }
+}
+
+function toGeminiToolChoice(
+  choice: AIToolChoice,
+  declarations: readonly AIToolDefinition[],
+  provider: string,
+  model: string,
+) {
+  if (choice === 'none') return { mode: FunctionCallingConfigMode.NONE }
+  if (choice === 'required') return { mode: FunctionCallingConfigMode.ANY }
+  if (choice === 'auto') return { mode: FunctionCallingConfigMode.AUTO }
+
+  if (
+    typeof choice.name !== 'string'
+    || !declarations.some((declaration) => declaration.name === choice.name)
+  ) {
+    throw invalidRequest(provider, model, 'Gemini named tool choice is not declared')
+  }
+  return {
+    mode: FunctionCallingConfigMode.ANY,
+    allowedFunctionNames: [choice.name],
+  }
+}
+
+function validateToolDeclaration(declaration: AIToolDefinition, provider: string, model: string): void {
+  if (!TOOL_NAME_PATTERN.test(declaration.name)) {
+    throw invalidRequest(provider, model, 'Gemini tool name is invalid')
+  }
+  if (
+    !isPlainRecord(declaration.parameters)
+    || !isJsonValue(declaration.parameters)
+    || !isSupportedAIJSONSchema(declaration.parameters)
+  ) {
+    throw invalidRequest(provider, model, 'Gemini tool schema must be a JSON object')
+  }
+}
+
+function validateChat(request: AIProviderChatRequest, provider: string): void {
+  if (!Array.isArray(request.messages) || request.messages.length === 0) {
+    throw invalidRequest(provider, request.model, 'Gemini chat messages must not be empty')
+  }
+  const last = request.messages.at(-1)
+  if (last?.role !== 'user' && last?.role !== 'tool') {
+    throw invalidRequest(provider, request.model, 'Gemini chat must end with a user or tool message')
+  }
+  buildToolConfig(request, provider)
+}
+
+function toGeminiParts(parts: readonly AIContentPart[]): Part[] {
+  return parts.map((part) => part.type === 'text'
+    ? { text: part.text }
+    : { inlineData: { mimeType: part.mimeType, data: part.data } })
+}
+
+function toGeminiMessages(
+  messages: readonly AIMessage[],
+  provider: string,
+  model: string,
+): GenerateContentParameters['contents'] {
+  const toolNames = new Map<string, string>()
+  for (const message of messages) {
+    if (message.role !== 'assistant') continue
+    for (const call of message.toolCalls ?? []) toolNames.set(call.id, call.name)
+  }
+
+  const contents: Content[] = []
+  for (const message of messages) {
+    if (message.role === 'system') continue
+    if (message.role === 'user') {
+      const parts = typeof message.content === 'string'
+        ? [{ text: message.content }]
+        : toGeminiParts(message.content)
+      if (parts.length === 0) throw invalidRequest(provider, model, 'Gemini user message must not be empty')
+      contents.push({ role: 'user', parts })
+      continue
+    }
+
+    if (message.role === 'assistant') {
+      const parts: Part[] = []
+      if (message.content.length > 0) parts.push({ text: message.content })
+      for (const call of message.toolCalls ?? []) {
+        if (!TOOL_NAME_PATTERN.test(call.name) || !isPlainRecord(call.arguments) || !isJsonValue(call.arguments)) {
+          throw invalidRequest(provider, model, 'Gemini assistant tool call is invalid')
+        }
+        parts.push({
+          functionCall: {
+            ...(call.id ? { id: call.id } : {}),
+            name: call.name,
+            args: call.arguments as Record<string, unknown>,
+          },
+        })
+      }
+      if (parts.length === 0) throw invalidRequest(provider, model, 'Gemini assistant message must not be empty')
+      contents.push({ role: 'model', parts })
+      continue
+    }
+
+    const toolName = message.toolName ?? toolNames.get(message.toolCallId)
+    if (!toolName || !TOOL_NAME_PATTERN.test(toolName) || message.toolCallId.length === 0) {
+      throw invalidRequest(provider, model, 'Gemini tool result is invalid')
+    }
+    contents.push({
+      role: 'user',
+      parts: [{
+        functionResponse: {
+          id: message.toolCallId,
+          name: toolName,
+          response: { output: parseToolResult(message.content) },
+        },
+      }],
+    })
+  }
+  return contents
+}
+
+function parseToolResult(content: string): unknown {
+  try {
+    const value: unknown = JSON.parse(content)
+    return isJsonValue(value) ? value : content
+  } catch {
+    return content
+  }
+}
+
+function extractText(response: GenerateContentResponse): string {
+  const parts = response.candidates?.[0]?.content?.parts ?? []
+  return parts
+    .filter((part) => !part.thought && typeof part.text === 'string')
+    .map((part) => part.text as string)
+    .join('')
+}
+
+function extractToolCalls(
+  response: GenerateContentResponse,
+  declarations: readonly AIToolDefinition[],
+  provider: string,
+  model: string,
+  indexOffset = 0,
+): AIToolCall[] {
+  const byName = new Map(declarations.map((declaration) => [declaration.name, declaration]))
+  const nativeCalls = (response.candidates?.[0]?.content?.parts ?? [])
+    .map((part) => part.functionCall)
+    .filter((call): call is NonNullable<typeof call> => call !== undefined)
+
+  return nativeCalls.map((call, index) => {
+    if (
+      typeof call.name !== 'string'
+      || !TOOL_NAME_PATTERN.test(call.name)
+      || !isPlainRecord(call.args)
+      || !isJsonValue(call.args)
+      || (call.partialArgs?.length ?? 0) > 0
+    ) {
+      throw invalidToolArguments(provider, model)
+    }
+
+    const declaration = byName.get(call.name)
+    if (!declaration || !matchesAIJSONSchema(call.args, declaration.parameters)) {
+      throw invalidToolArguments(provider, model)
+    }
+
+    return {
+      id: typeof call.id === 'string' && call.id.length > 0
+        ? call.id
+        : `gemini_${call.name}_${indexOffset + index}`,
+      name: call.name,
+      arguments: call.args,
+    }
+  })
+}
+
+function responseMetadata(
+  response: GenerateContentResponse,
+  provider: string,
+  requestedModel: string,
+  finishReason = normalizeFinishReason(response, false),
+): Omit<AIResult<never>, 'output'> {
+  return {
+    provider,
+    model: nonEmpty(response.modelVersion) ?? requestedModel,
+    usage: normalizeUsage(response),
+    finishReason,
+    providerFinishReason: response.candidates?.[0]?.finishReason,
+    requestId: nonEmpty(response.responseId) ?? requestIdFromResponse(response),
+  }
+}
+
+function normalizeUsage(response: GenerateContentResponse): AIUsage | null {
+  const usage = response.usageMetadata
+  if (!usage) return null
+
+  const reportedInputTokens = tokenCount(usage.promptTokenCount)
+  const reportedOutputTokens = tokenCount(usage.candidatesTokenCount)
+  const reportedTotalTokens = tokenCount(usage.totalTokenCount)
+  const cachedInputTokens = tokenCount(usage.cachedContentTokenCount)
+  const reasoningTokens = tokenCount(usage.thoughtsTokenCount)
+  const toolInputTokens = tokenCount(usage.toolUsePromptTokenCount)
+  if (
+    reportedInputTokens === undefined
+    || reportedOutputTokens === undefined
+    || reportedTotalTokens === undefined
+    || (usage.cachedContentTokenCount !== undefined && cachedInputTokens === undefined)
+    || (usage.thoughtsTokenCount !== undefined && reasoningTokens === undefined)
+    || (usage.toolUsePromptTokenCount !== undefined && toolInputTokens === undefined)
+  ) return null
+
+  // Gemini reports thought tokens and tool-result prompt tokens outside the
+  // visible candidate/prompt buckets. Fold them into the billable neutral
+  // input/output totals while retaining reasoning as an output subset.
+  const inputTokens = reportedInputTokens + (toolInputTokens ?? 0)
+  const outputTokens = reportedOutputTokens + (reasoningTokens ?? 0)
+  const totalTokens = reportedTotalTokens
+  if (
+    !Number.isSafeInteger(inputTokens)
+    || !Number.isSafeInteger(outputTokens)
+    || totalTokens < inputTokens + outputTokens
+    || (cachedInputTokens ?? 0) > inputTokens
+  ) return null
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+    ...(cachedInputTokens !== undefined
+      ? { cacheMissInputTokens: Math.max(0, inputTokens - cachedInputTokens) }
+      : {}),
+    ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+  }
+}
+
+function normalizeFinishReason(response: GenerateContentResponse, hasToolCalls: boolean): AIFinishReason {
+  if (isPromptBlocked(response)) return 'content_filter'
+  if (hasToolCalls) return 'tool_calls'
+  switch (response.candidates?.[0]?.finishReason) {
+    case 'STOP':
+      return 'stop'
+    case 'MAX_TOKENS':
+      return 'length'
+    case 'SAFETY':
+    case 'RECITATION':
+    case 'LANGUAGE':
+    case 'BLOCKLIST':
+    case 'PROHIBITED_CONTENT':
+    case 'SPII':
+    case 'IMAGE_SAFETY':
+    case 'IMAGE_PROHIBITED_CONTENT':
+    case 'IMAGE_RECITATION':
+      return 'content_filter'
+    default:
+      return 'other'
+  }
+}
+
+function isPromptBlocked(response: GenerateContentResponse): boolean {
+  const reason = response.promptFeedback?.blockReason
+  return typeof reason === 'string'
+    && reason.length > 0
+    && reason !== 'BLOCKED_REASON_UNSPECIFIED'
+}
+
+function requestIdFromResponse(response: GenerateContentResponse | EmbedContentResponse): string | undefined {
+  const headers = response.sdkHttpResponse?.headers
+  if (!headers) return undefined
+  for (const [name, value] of Object.entries(headers)) {
+    const normalized = name.toLowerCase()
+    if ((normalized === 'x-request-id' || normalized === 'x-goog-request-id') && value.length > 0) {
+      return value
+    }
+  }
+  return undefined
+}
+
+function mapGeminiError(
+  error: unknown,
+  provider: string,
+  model: string,
+  signal: AbortSignal,
+): AIError {
+  if (error instanceof AIError) return error
+
+  if (signal.aborted) {
+    if (signal.reason instanceof AIError) return signal.reason
+    const timedOut = isNamedError(signal.reason, 'TimeoutError')
+    return new AIError({
+      code: timedOut ? 'timeout' : 'aborted',
+      message: timedOut ? 'Gemini request timed out' : 'Gemini request was aborted',
+      provider,
+      model,
+      retryable: timedOut,
+    })
+  }
+
+  if (isNamedError(error, 'AbortError')) {
+    return new AIError({ code: 'aborted', message: 'Gemini request was aborted', provider, model })
+  }
+  if (isNamedError(error, 'TimeoutError')) {
+    return new AIError({
+      code: 'timeout',
+      message: 'Gemini request timed out',
+      provider,
+      model,
+      retryable: true,
+    })
+  }
+
+  const status = error instanceof ApiError
+    ? error.status
+    : isPlainRecord(error) && typeof error.status === 'number'
+      ? error.status
+      : undefined
+  if (status !== undefined) {
+    if (status === 400 || status === 404 || status === 422) {
+      return new AIError({
+        code: 'invalid_request',
+        message: 'Gemini rejected the request',
+        provider,
+        model,
+        status,
+      })
+    }
+    return aiErrorFromHttpStatus(status, { provider, model })
+  }
+
+  return new AIError({
+    code: 'network',
+    message: 'Gemini provider request failed',
+    provider,
+    model,
+    retryable: true,
+  })
+}
+
+function invalidRequest(provider: string, model: string, message: string): AIError {
+  return new AIError({ code: 'invalid_request', message, provider, ...(model ? { model } : {}) })
+}
+
+function invalidToolArguments(provider: string, model: string): AIError {
+  return new AIError({
+    code: 'invalid_response',
+    message: 'Gemini returned invalid tool arguments',
+    provider,
+    model,
+  })
+}
+
+function emptyResponse(provider: string, model: string): AIError {
+  return new AIError({
+    code: 'invalid_response',
+    message: 'Gemini returned an empty response',
+    provider,
+    model,
+  })
+}
+
+function contentFiltered(provider: string, model: string, operation: AIOperation): AIError {
+  return new AIError({
+    code: 'content_filtered',
+    message: 'AI provider blocked the response for safety reasons',
+    provider,
+    model,
+    operation,
+  })
+}
+
+function structuredOutputError(provider: string, model: string): AIError {
+  return new AIError({
+    code: 'invalid_response',
+    message: 'Gemini returned invalid structured output',
+    provider,
+    model,
+  })
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function tokenCount(value: number | undefined): number | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined
+}
+
+function isNamedError(value: unknown, name: string): boolean {
+  return value instanceof Error && value.name === name
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function isJsonValue(value: unknown, seen = new WeakSet<object>()): boolean {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true
+  if (typeof value === 'number') return Number.isFinite(value)
+  if (typeof value !== 'object') return false
+  if (seen.has(value)) return false
+  seen.add(value)
+  const valid = Array.isArray(value)
+    ? value.every((item) => isJsonValue(item, seen))
+    : isPlainRecord(value) && Object.values(value).every((item) => isJsonValue(item, seen))
+  seen.delete(value)
+  return valid
+}