@ai-sdk/google 3.0.66 → 3.0.68

package/src/interactions/parse-google-interactions-outputs.ts

@@ -0,0 +1,257 @@
+import type { JSONValue, LanguageModelV3Content } from '@ai-sdk/provider';
+import type { GoogleInteractionsContentBlock } from './google-interactions-api';
+import {
+  annotationsToSources,
+  builtinToolResultToSources,
+} from './extract-google-interactions-sources';
+import type {
+  GoogleInteractionsAnnotation,
+  GoogleInteractionsBuiltinToolResultContent,
+} from './google-interactions-prompt';
+
+export type ParseGoogleInteractionsOutputsResult = {
+  content: Array<LanguageModelV3Content>;
+  hasFunctionCall: boolean;
+};
+
+/*
+ * Builds a `providerMetadata.google` payload for an output part so the
+ * Interactions converter on the next turn can read both the per-block
+ * `signature` (round-trip) and the parent `interactionId` (history compaction
+ * under `previousInteractionId`).
+ */
+function googleProviderMetadata({
+  signature,
+  interactionId,
+}: {
+  signature?: string | null;
+  interactionId?: string;
+}): { providerMetadata: { google: Record<string, string> } } | object {
+  const google: Record<string, string> = {};
+  if (signature != null) {
+    google.signature = signature;
+  }
+  if (interactionId != null) {
+    google.interactionId = interactionId;
+  }
+  return Object.keys(google).length > 0 ? { providerMetadata: { google } } : {};
+}
+
+/**
+ * Set of built-in tool *call* discriminators emitted by the Interactions API.
+ */
+const BUILTIN_TOOL_CALL_TYPES = new Set([
+  'google_search_call',
+  'code_execution_call',
+  'url_context_call',
+  'file_search_call',
+  'google_maps_call',
+  'mcp_server_tool_call',
+]);
+
+/**
+ * Set of built-in tool *result* discriminators.
+ */
+const BUILTIN_TOOL_RESULT_TYPES = new Set([
+  'google_search_result',
+  'code_execution_result',
+  'url_context_result',
+  'file_search_result',
+  'google_maps_result',
+  'mcp_server_tool_result',
+]);
+
+function builtinToolNameFromCallType(type: string): string {
+  return type.replace(/_call$/, '');
+}
+
+function builtinToolNameFromResultType(type: string): string {
+  return type.replace(/_result$/, '');
+}
+
+/**
+ * Walks the `outputs[]` array of an Interaction response and emits AI SDK
+ * `LanguageModelV3Content[]`. Surfaces:
+ *
+ * - `text` blocks (with annotations -> source parts)
+ * - `thought` blocks (reasoning)
+ * - `function_call` blocks (client-executed tool calls)
+ * - Built-in tool `*_call` / `*_result` blocks (Google Search, Code Execution,
+ *   URL Context, File Search, Google Maps, MCP Server) as
+ *   `tool-call`/`tool-result` parts with `providerExecuted: true`.
+ * - `text_annotation`-derived sources from the URL / file / place citations
+ *   carried on text blocks.
+ */
+export function parseGoogleInteractionsOutputs({
+  outputs,
+  generateId,
+  interactionId,
+}: {
+  outputs: Array<GoogleInteractionsContentBlock> | null | undefined;
+  generateId: () => string;
+  /**
+   * Top-level `Interaction.id` on the response. Stamped onto each output
+   * part's `providerMetadata.google.interactionId` so the converter can drop
+   * matching assistant turns when `previousInteractionId` is used on the
+   * next turn (compaction).
+   */
+  interactionId?: string;
+}): ParseGoogleInteractionsOutputsResult {
+  const content: Array<LanguageModelV3Content> = [];
+  let hasFunctionCall = false;
+
+  if (outputs == null) {
+    return { content, hasFunctionCall };
+  }
+
+  for (const block of outputs) {
+    if (block == null || typeof block !== 'object') continue;
+    const type = (block as { type?: string }).type;
+    if (typeof type !== 'string') continue;
+
+    switch (type) {
+      case 'text': {
+        const text = (block as { text?: string }).text ?? '';
+        const annotations = (
+          block as { annotations?: Array<GoogleInteractionsAnnotation> }
+        ).annotations;
+        content.push({
+          type: 'text',
+          text,
+          ...googleProviderMetadata({ interactionId }),
+        });
+        const sources = annotationsToSources({ annotations, generateId });
+        for (const source of sources) {
+          content.push(source);
+        }
+        break;
+      }
+      case 'thought': {
+        const thought = block as {
+          signature?: string;
+          summary?: Array<{ type: string; text?: string }>;
+        };
+        const summary = Array.isArray(thought.summary) ? thought.summary : [];
+        const text = summary
+          .filter(
+            item => item?.type === 'text' && typeof item.text === 'string',
+          )
+          .map(item => item.text as string)
+          .join('\n');
+        content.push({
+          type: 'reasoning',
+          text,
+          ...googleProviderMetadata({
+            signature: thought.signature,
+            interactionId,
+          }),
+        });
+        break;
+      }
+      case 'image': {
+        const image = block as {
+          data?: string;
+          mime_type?: string;
+          uri?: string;
+        };
+        if (image.data != null && image.data.length > 0) {
+          content.push({
+            type: 'file',
+            mediaType: image.mime_type ?? 'image/png',
+            data: image.data,
+            ...googleProviderMetadata({ interactionId }),
+          });
+        } else if (image.uri != null && image.uri.length > 0) {
+          /*
+           * V3 `LanguageModelV3File` only supports inline data (`string` /
+           * `Uint8Array`). URL-only image outputs cannot be represented as a
+           * file content part on the v3 spec; surface the URI through provider
+           * metadata so callers can still recover it.
+           */
+          content.push({
+            type: 'file',
+            mediaType: image.mime_type ?? 'image/png',
+            data: '',
+            providerMetadata: {
+              google: {
+                ...(interactionId != null ? { interactionId } : {}),
+                imageUri: image.uri,
+              },
+            },
+          });
+        }
+        break;
+      }
+      case 'function_call': {
+        hasFunctionCall = true;
+        const call = block as {
+          id: string;
+          name: string;
+          arguments?: Record<string, unknown> | null;
+          signature?: string | null;
+        };
+        content.push({
+          type: 'tool-call',
+          toolCallId: call.id,
+          toolName: call.name,
+          input: JSON.stringify(call.arguments ?? {}),
+          ...googleProviderMetadata({
+            signature: call.signature,
+            interactionId,
+          }),
+        });
+        break;
+      }
+      default: {
+        if (BUILTIN_TOOL_CALL_TYPES.has(type)) {
+          const call = block as {
+            id?: string;
+            arguments?: Record<string, unknown>;
+            name?: string;
+            server_name?: string;
+          };
+          const toolName =
+            type === 'mcp_server_tool_call'
+              ? (call.name ?? 'mcp_server_tool')
+              : builtinToolNameFromCallType(type);
+          const input = JSON.stringify(call.arguments ?? {});
+          content.push({
+            type: 'tool-call',
+            toolCallId: call.id ?? generateId(),
+            toolName,
+            input,
+            providerExecuted: true,
+          });
+        } else if (BUILTIN_TOOL_RESULT_TYPES.has(type)) {
+          const result = block as {
+            call_id?: string;
+            result?: unknown;
+            is_error?: boolean;
+            name?: string;
+          };
+          const toolName =
+            type === 'mcp_server_tool_result'
+              ? (result.name ?? 'mcp_server_tool')
+              : builtinToolNameFromResultType(type);
+          content.push({
+            type: 'tool-result',
+            toolCallId: result.call_id ?? generateId(),
+            toolName,
+            result: (result.result ?? null) as NonNullable<JSONValue>,
+          });
+          const sources = builtinToolResultToSources({
+            block:
+              block as unknown as GoogleInteractionsBuiltinToolResultContent,
+            generateId,
+          });
+          for (const source of sources) {
+            content.push(source);
+          }
+        }
+        break;
+      }
+    }
+  }
+
+  return { content, hasFunctionCall };
+}

package/src/interactions/poll-google-interactions.ts

@@ -0,0 +1,110 @@
+import {
+  createJsonResponseHandler,
+  delay,
+  getFromApi,
+  type FetchFunction,
+} from '@ai-sdk/provider-utils';
+import { googleFailedResponseHandler } from '../google-error';
+import {
+  googleInteractionsResponseSchema,
+  type GoogleInteractionsResponse,
+} from './google-interactions-api';
+import type { GoogleInteractionsStatus } from './google-interactions-prompt';
+
+const TERMINAL_STATUSES: ReadonlySet<GoogleInteractionsStatus | string> =
+  new Set(['completed', 'failed', 'cancelled', 'incomplete']);
+
+export function isTerminalStatus(
+  status: GoogleInteractionsStatus | string | null | undefined,
+): boolean {
+  return status != null && TERMINAL_STATUSES.has(status);
+}
+
+/*
+ * Default polling cadence for background interactions. Starts at 1 s, doubles
+ * each tick up to a 10 s ceiling, and gives up after 30 minutes -- agent runs
+ * such as deep research can take tens of minutes server-side, so we err on
+ * the long side rather than truncate a real run. Override per-call via
+ * `providerOptions.google.pollingTimeoutMs`.
+ */
+const DEFAULT_INITIAL_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 10000;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+export type PollGoogleInteractionResult = {
+  response: GoogleInteractionsResponse;
+  rawResponse: unknown;
+  responseHeaders: Record<string, string> | undefined;
+};
+
+/**
+ * Polls `GET {baseURL}/interactions/{id}` until the response status is
+ * terminal (`completed` / `failed` / `cancelled` / `incomplete`). Throws if
+ * the polling loop exceeds `timeoutMs`, the response has no `id` to poll on,
+ * or the abort signal fires.
+ */
+export async function pollGoogleInteractionUntilTerminal({
+  baseURL,
+  interactionId,
+  headers,
+  fetch,
+  abortSignal,
+  initialDelayMs = DEFAULT_INITIAL_DELAY_MS,
+  maxDelayMs = DEFAULT_MAX_DELAY_MS,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}: {
+  baseURL: string;
+  interactionId: string | null | undefined;
+  headers: Record<string, string | undefined>;
+  fetch?: FetchFunction;
+  abortSignal?: AbortSignal;
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  timeoutMs?: number;
+}): Promise<PollGoogleInteractionResult> {
+  if (interactionId == null || interactionId.length === 0) {
+    throw new Error(
+      'google.interactions: cannot poll a background interaction without an id. ' +
+        'The POST response did not include an interaction id.',
+    );
+  }
+
+  const startedAt = Date.now();
+  let nextDelayMs = initialDelayMs;
+  const url = `${baseURL}/interactions/${encodeURIComponent(interactionId)}`;
+
+  while (true) {
+    if (abortSignal?.aborted) {
+      throw new DOMException('Polling was aborted', 'AbortError');
+    }
+
+    if (Date.now() - startedAt > timeoutMs) {
+      throw new Error(
+        `google.interactions: timed out polling interaction ${interactionId} after ${timeoutMs}ms.`,
+      );
+    }
+
+    await delay(nextDelayMs, { abortSignal });
+
+    const {
+      value: response,
+      rawValue: rawResponse,
+      responseHeaders,
+    } = await getFromApi({
+      url,
+      headers,
+      failedResponseHandler: googleFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        googleInteractionsResponseSchema,
+      ),
+      abortSignal,
+      fetch,
+    });
+
+    if (isTerminalStatus(response.status)) {
+      return { response, rawResponse, responseHeaders };
+    }
+
+    nextDelayMs = Math.min(nextDelayMs * 2, maxDelayMs);
+  }
+}

package/src/interactions/prepare-google-interactions-tools.ts

@@ -0,0 +1,245 @@
+import type {
+  LanguageModelV3CallOptions,
+  SharedV3Warning,
+} from '@ai-sdk/provider';
+import type {
+  GoogleInteractionsTool,
+  GoogleInteractionsToolChoice,
+} from './google-interactions-prompt';
+
+export type PrepareGoogleInteractionsToolsResult = {
+  tools: Array<GoogleInteractionsTool> | undefined;
+  toolChoice: GoogleInteractionsToolChoice | undefined;
+  toolWarnings: Array<SharedV3Warning>;
+};
+
+/**
+ * Maps AI SDK tool definitions and `toolChoice` onto the Gemini Interactions
+ * `tools[]` and `tool_choice` request fields.
+ *
+ * AI SDK function tools (`{ type: 'function', name, description, inputSchema }`)
+ * map to Interactions `{ type: 'function', name, description, parameters }`,
+ * with `parameters` passed through as plain JSON Schema (per
+ * `googleapis/js-genai` `samples/interactions_tool_call_with_functions.ts` and
+ * `src/interactions/resources/interactions.ts` `Function.parameters: unknown`).
+ *
+ * Provider-defined tools (`{ type: 'provider', id: 'google.<name>', args }`)
+ * map to the discriminated `Tool` union (TASK-7). The full set of
+ * provider-defined tool ids supported here:
+ *
+ * - `google.google_search`     -> `{ type: 'google_search', search_types? }`
+ * - `google.code_execution`    -> `{ type: 'code_execution' }`
+ * - `google.url_context`       -> `{ type: 'url_context' }`
+ * - `google.file_search`       -> `{ type: 'file_search', file_search_store_names?, top_k?, metadata_filter? }`
+ * - `google.google_maps`       -> `{ type: 'google_maps', latitude?, longitude?, enable_widget? }`
+ * - `google.computer_use`      -> `{ type: 'computer_use', environment?, excludedPredefinedFunctions? }`
+ * - `google.mcp_server`        -> `{ type: 'mcp_server', name?, url?, headers?, allowed_tools? }`
+ * - `google.retrieval`         -> `{ type: 'retrieval', retrieval_types?, vertex_ai_search_config? }`
+ *
+ * `toolChoice` shapes:
+ * - `'auto'`     -> `'auto'`
+ * - `'required'` -> `'any'`
+ * - `'none'`     -> `'none'`
+ * - `{ type: 'tool', toolName }` -> `{ allowed_tools: { mode: 'validated', tools: [name] } }`
+ *   (Interactions `AllowedTools.tools` is an `Array<string>` of function
+ *   names, not tool descriptors -- see `src/interactions/resources/interactions.ts`
+ *   line ~151).
+ */
+export function prepareGoogleInteractionsTools({
+  tools,
+  toolChoice,
+}: {
+  tools: LanguageModelV3CallOptions['tools'];
+  toolChoice?: LanguageModelV3CallOptions['toolChoice'];
+}): PrepareGoogleInteractionsToolsResult {
+  const toolWarnings: Array<SharedV3Warning> = [];
+
+  const normalized = tools?.length ? tools : undefined;
+
+  if (normalized == null) {
+    return { tools: undefined, toolChoice: undefined, toolWarnings };
+  }
+
+  const interactionsTools: Array<GoogleInteractionsTool> = [];
+
+  for (const tool of normalized) {
+    if (tool.type === 'function') {
+      interactionsTools.push({
+        type: 'function',
+        name: tool.name,
+        description: tool.description ?? '',
+        parameters: tool.inputSchema,
+      });
+      continue;
+    }
+
+    if (tool.type === 'provider') {
+      const args = (tool.args ?? {}) as Record<string, unknown>;
+      switch (tool.id) {
+        case 'google.google_search': {
+          const searchTypesArg = args.searchTypes as
+            | { webSearch?: unknown; imageSearch?: unknown }
+            | undefined;
+          let search_types:
+            | Array<'web_search' | 'image_search' | 'enterprise_web_search'>
+            | undefined;
+          if (searchTypesArg != null && typeof searchTypesArg === 'object') {
+            const list: Array<
+              'web_search' | 'image_search' | 'enterprise_web_search'
+            > = [];
+            if (searchTypesArg.webSearch != null) list.push('web_search');
+            if (searchTypesArg.imageSearch != null) list.push('image_search');
+            if (list.length > 0) {
+              search_types = list;
+            }
+          }
+          interactionsTools.push({
+            type: 'google_search',
+            ...(search_types != null ? { search_types } : {}),
+          });
+          break;
+        }
+        case 'google.code_execution': {
+          interactionsTools.push({ type: 'code_execution' });
+          break;
+        }
+        case 'google.url_context': {
+          interactionsTools.push({ type: 'url_context' });
+          break;
+        }
+        case 'google.file_search': {
+          interactionsTools.push({
+            type: 'file_search',
+            ...(args.fileSearchStoreNames != null
+              ? {
+                  file_search_store_names:
+                    args.fileSearchStoreNames as Array<string>,
+                }
+              : {}),
+            ...(args.topK != null ? { top_k: args.topK as number } : {}),
+            ...(args.metadataFilter != null
+              ? { metadata_filter: args.metadataFilter as string }
+              : {}),
+          });
+          break;
+        }
+        case 'google.google_maps': {
+          interactionsTools.push({
+            type: 'google_maps',
+            ...(args.latitude != null
+              ? { latitude: args.latitude as number }
+              : {}),
+            ...(args.longitude != null
+              ? { longitude: args.longitude as number }
+              : {}),
+            ...(args.enableWidget != null
+              ? { enable_widget: args.enableWidget as boolean }
+              : {}),
+          });
+          break;
+        }
+        case 'google.computer_use': {
+          interactionsTools.push({
+            type: 'computer_use',
+            environment:
+              (args.environment as 'browser' | undefined) ?? 'browser',
+            ...(args.excludedPredefinedFunctions != null
+              ? {
+                  excludedPredefinedFunctions:
+                    args.excludedPredefinedFunctions as Array<string>,
+                }
+              : {}),
+          });
+          break;
+        }
+        case 'google.mcp_server': {
+          interactionsTools.push({
+            type: 'mcp_server',
+            ...(args.name != null ? { name: args.name as string } : {}),
+            ...(args.url != null ? { url: args.url as string } : {}),
+            ...(args.headers != null
+              ? { headers: args.headers as Record<string, string> }
+              : {}),
+            ...(args.allowedTools != null
+              ? { allowed_tools: args.allowedTools as Array<unknown> }
+              : {}),
+          });
+          break;
+        }
+        case 'google.retrieval': {
+          const vertexAiSearchConfig =
+            (args.vertexAiSearchConfig as
+              | { datastores?: Array<string>; engine?: string }
+              | undefined) ?? undefined;
+          interactionsTools.push({
+            type: 'retrieval',
+            ...(args.retrievalTypes != null
+              ? {
+                  retrieval_types:
+                    args.retrievalTypes as Array<'vertex_ai_search'>,
+                }
+              : { retrieval_types: ['vertex_ai_search'] }),
+            ...(vertexAiSearchConfig != null
+              ? { vertex_ai_search_config: vertexAiSearchConfig }
+              : {}),
+          });
+          break;
+        }
+        default: {
+          toolWarnings.push({
+            type: 'unsupported',
+            feature: `provider-defined tool ${tool.id}`,
+            details: `provider-defined tool ${tool.id} is not supported by google.interactions; tool dropped.`,
+          });
+          break;
+        }
+      }
+      continue;
+    }
+
+    toolWarnings.push({
+      type: 'unsupported',
+      feature: `tool of type ${(tool as { type: string }).type}`,
+      details:
+        'Only function tools and google.* provider-defined tools are supported by google.interactions; tool dropped.',
+    });
+  }
+
+  /*
+   * `tool_choice` on the Interactions API governs function calling only -- the
+   * API rejects requests with `tool_choice` set when no `function` tools are
+   * present (`{"error":{"message":"Function calling config is set without
+   * function_declarations."}}`). Drop `tool_choice` when the resolved tool
+   * list is empty or contains no function tools.
+   */
+  const hasFunctionTool = interactionsTools.some(t => t.type === 'function');
+
+  let mappedToolChoice: GoogleInteractionsToolChoice | undefined;
+  if (toolChoice != null && hasFunctionTool) {
+    switch (toolChoice.type) {
+      case 'auto':
+        mappedToolChoice = 'auto';
+        break;
+      case 'required':
+        mappedToolChoice = 'any';
+        break;
+      case 'none':
+        mappedToolChoice = 'none';
+        break;
+      case 'tool':
+        mappedToolChoice = {
+          allowed_tools: {
+            mode: 'validated',
+            tools: [toolChoice.toolName],
+          },
+        };
+        break;
+    }
+  }
+
+  return {
+    tools: interactionsTools.length > 0 ? interactionsTools : undefined,
+    toolChoice: mappedToolChoice,
+    toolWarnings,
+  };
+}