@tanstack/ai-gemini 0.23.0 → 0.24.1

package/dist/esm/tools/tool-converter.js

@@ -1,3 +1,4 @@
+import { getGeminiProviderToolKind } from "./gemini-provider-tool.js";
 import { convertCodeExecutionToolToAdapterFormat } from "./code-execution-tool.js";
 import { convertComputerUseToolToAdapterFormat } from "./computer-use-tool.js";
 import { convertFileSearchToolToAdapterFormat } from "./file-search-tool.js";
@@ -5,6 +6,7 @@ import { convertGoogleMapsToolToAdapterFormat } from "./google-maps-tool.js";
 import { convertGoogleSearchRetrievalToolToAdapterFormat } from "./google-search-retriveal-tool.js";
 import { convertGoogleSearchToolToAdapterFormat } from "./google-search-tool.js";
 import { convertUrlContextToolToAdapterFormat } from "./url-context-tool.js";
+import { assertUniqueToolNames } from "@tanstack/ai/adapter-internals";
 //#region src/tools/tool-converter.ts
 /**
 * Converts standard Tool format to Gemini-specific tool format
@@ -27,9 +29,10 @@ import { convertUrlContextToolToAdapterFormat } from "./url-context-tool.js";
 */
 function convertToolsToProviderFormat(tools) {
 	if (!tools || tools.length === 0) return [];
+	assertUniqueToolNames(tools);
 	const result = [];
 	const functionDeclarations = [];
-	for (const tool of tools) switch (tool.name) {
+	for (const tool of tools) switch (getGeminiProviderToolKind(tool)) {
 		case "code_execution":
 			result.push(convertCodeExecutionToolToAdapterFormat(tool));
 			break;
@@ -51,7 +54,7 @@ function convertToolsToProviderFormat(tools) {
 		case "url_context":
 			result.push(convertUrlContextToolToAdapterFormat(tool));
 			break;
-		default:
+		case void 0:
 			if (!tool.description) throw new Error(`Tool ${tool.name} requires a description for Gemini adapter`);
 			functionDeclarations.push({
 				name: tool.name,
@@ -62,7 +65,6 @@ function convertToolsToProviderFormat(tools) {
 					required: []
 				}
 			});
-			break;
 	}
 	if (functionDeclarations.length > 0) result.push({ functionDeclarations });
 	return result;

package/dist/esm/tools/tool-converter.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-converter.js","names":[],"sources":["../../../src/tools/tool-converter.ts"],"sourcesContent":["import { convertCodeExecutionToolToAdapterFormat } from './code-execution-tool'\nimport { convertComputerUseToolToAdapterFormat } from './computer-use-tool'\nimport { convertFileSearchToolToAdapterFormat } from './file-search-tool'\nimport { convertGoogleMapsToolToAdapterFormat } from './google-maps-tool'\nimport { convertGoogleSearchRetrievalToolToAdapterFormat } from './google-search-retriveal-tool'\nimport { convertGoogleSearchToolToAdapterFormat } from './google-search-tool'\nimport { convertUrlContextToolToAdapterFormat } from './url-context-tool'\nimport type { Tool } from '@tanstack/ai'\nimport type { ToolUnion } from '@google/genai'\n\n/**\n * Converts standard Tool format to Gemini-specific tool format\n *\n * @param tools - Array of standard Tool objects\n * @returns Array of Gemini-specific tool definitions\n *\n * @example\n * ```typescript\n * const tools: Tool[] = [{\n *   name: \"get_weather\",\n *   description: \"Get weather for a location\",\n *   inputSchema: z.object({\n *     location: z.string()\n *   })\n * }];\n *\n * const geminiTools = convertToolsToProviderFormat(tools);\n * ```\n */\nexport function convertToolsToProviderFormat<TTool extends Tool>(\n  tools: Array<TTool> | undefined,\n): Array<ToolUnion> {\n  if (!tools || tools.length === 0) {\n    return []\n  }\n  const result: Array<ToolUnion> = []\n  const functionDeclarations: Array<{\n    name: string\n    description?: string\n    parameters?: any\n  }> = []\n\n  // Process each tool and group function declarations together\n  for (const tool of tools) {\n    const name = tool.name\n\n    switch (name) {\n      case 'code_execution':\n        result.push(convertCodeExecutionToolToAdapterFormat(tool))\n        break\n      case 'computer_use':\n        result.push(convertComputerUseToolToAdapterFormat(tool))\n        break\n      case 'file_search':\n        result.push(convertFileSearchToolToAdapterFormat(tool))\n        break\n      case 'google_maps':\n        result.push(convertGoogleMapsToolToAdapterFormat(tool))\n        break\n      case 'google_search_retrieval':\n        result.push(convertGoogleSearchRetrievalToolToAdapterFormat(tool))\n        break\n      case 'google_search':\n        result.push(convertGoogleSearchToolToAdapterFormat(tool))\n        break\n      case 'url_context':\n        result.push(convertUrlContextToolToAdapterFormat(tool))\n        break\n      default:\n        // Collect function declarations to group together\n        // Description is required for Gemini function declarations\n        if (!tool.description) {\n          throw new Error(\n            `Tool ${tool.name} requires a description for Gemini adapter`,\n          )\n        }\n\n        // Tool schemas are already converted to JSON Schema in the ai layer\n        functionDeclarations.push({\n          name: tool.name,\n          description: tool.description,\n          parameters: tool.inputSchema ?? {\n            type: 'object',\n            properties: {},\n            required: [],\n          },\n        })\n        break\n    }\n  }\n\n  // If we have function declarations, add them as a single tool\n  if (functionDeclarations.length > 0) {\n    result.push({\n      functionDeclarations: functionDeclarations,\n    })\n  }\n\n  return result\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,6BACd,OACkB;CAClB,IAAI,CAAC,SAAS,MAAM,WAAW,GAC7B,OAAO,CAAC;CAEV,MAAM,SAA2B,CAAC;CAClC,MAAM,uBAID,CAAC;CAGN,KAAK,MAAM,QAAQ,OAGjB,QAFa,KAAK,MAElB;EACE,KAAK;GACH,OAAO,KAAK,wCAAwC,IAAI,CAAC;GACzD;EACF,KAAK;GACH,OAAO,KAAK,sCAAsC,IAAI,CAAC;GACvD;EACF,KAAK;GACH,OAAO,KAAK,qCAAqC,IAAI,CAAC;GACtD;EACF,KAAK;GACH,OAAO,KAAK,qCAAqC,IAAI,CAAC;GACtD;EACF,KAAK;GACH,OAAO,KAAK,gDAAgD,IAAI,CAAC;GACjE;EACF,KAAK;GACH,OAAO,KAAK,uCAAuC,IAAI,CAAC;GACxD;EACF,KAAK;GACH,OAAO,KAAK,qCAAqC,IAAI,CAAC;GACtD;EACF;GAGE,IAAI,CAAC,KAAK,aACR,MAAM,IAAI,MACR,QAAQ,KAAK,KAAK,2CACpB;GAIF,qBAAqB,KAAK;IACxB,MAAM,KAAK;IACX,aAAa,KAAK;IAClB,YAAY,KAAK,eAAe;KAC9B,MAAM;KACN,YAAY,CAAC;KACb,UAAU,CAAC;IACb;GACF,CAAC;GACD;CACJ;CAIF,IAAI,qBAAqB,SAAS,GAChC,OAAO,KAAK,EACY,qBACxB,CAAC;CAGH,OAAO;AACT"}
+{"version":3,"file":"tool-converter.js","names":[],"sources":["../../../src/tools/tool-converter.ts"],"sourcesContent":["import { assertUniqueToolNames } from '@tanstack/ai/adapter-internals'\nimport { convertCodeExecutionToolToAdapterFormat } from './code-execution-tool'\nimport { convertComputerUseToolToAdapterFormat } from './computer-use-tool'\nimport { convertFileSearchToolToAdapterFormat } from './file-search-tool'\nimport { getGeminiProviderToolKind } from './gemini-provider-tool'\nimport { convertGoogleMapsToolToAdapterFormat } from './google-maps-tool'\nimport { convertGoogleSearchRetrievalToolToAdapterFormat } from './google-search-retriveal-tool'\nimport { convertGoogleSearchToolToAdapterFormat } from './google-search-tool'\nimport { convertUrlContextToolToAdapterFormat } from './url-context-tool'\nimport type { Tool } from '@tanstack/ai'\nimport type { ToolUnion } from '@google/genai'\n\n/**\n * Converts standard Tool format to Gemini-specific tool format\n *\n * @param tools - Array of standard Tool objects\n * @returns Array of Gemini-specific tool definitions\n *\n * @example\n * ```typescript\n * const tools: Tool[] = [{\n *   name: \"get_weather\",\n *   description: \"Get weather for a location\",\n *   inputSchema: z.object({\n *     location: z.string()\n *   })\n * }];\n *\n * const geminiTools = convertToolsToProviderFormat(tools);\n * ```\n */\nexport function convertToolsToProviderFormat<TTool extends Tool>(\n  tools: Array<TTool> | undefined,\n): Array<ToolUnion> {\n  if (!tools || tools.length === 0) {\n    return []\n  }\n  assertUniqueToolNames(tools)\n  const result: Array<ToolUnion> = []\n  const functionDeclarations: Array<{\n    name: string\n    description?: string\n    parameters?: any\n  }> = []\n\n  // Process each tool and group function declarations together\n  for (const tool of tools) {\n    switch (getGeminiProviderToolKind(tool)) {\n      case 'code_execution':\n        result.push(convertCodeExecutionToolToAdapterFormat(tool))\n        break\n      case 'computer_use':\n        result.push(convertComputerUseToolToAdapterFormat(tool))\n        break\n      case 'file_search':\n        result.push(convertFileSearchToolToAdapterFormat(tool))\n        break\n      case 'google_maps':\n        result.push(convertGoogleMapsToolToAdapterFormat(tool))\n        break\n      case 'google_search_retrieval':\n        result.push(convertGoogleSearchRetrievalToolToAdapterFormat(tool))\n        break\n      case 'google_search':\n        result.push(convertGoogleSearchToolToAdapterFormat(tool))\n        break\n      case 'url_context':\n        result.push(convertUrlContextToolToAdapterFormat(tool))\n        break\n      case undefined:\n        // Collect function declarations to group together\n        // Description is required for Gemini function declarations\n        if (!tool.description) {\n          throw new Error(\n            `Tool ${tool.name} requires a description for Gemini adapter`,\n          )\n        }\n\n        // Tool schemas are already converted to JSON Schema in the ai layer\n        functionDeclarations.push({\n          name: tool.name,\n          description: tool.description,\n          parameters: tool.inputSchema ?? {\n            type: 'object',\n            properties: {},\n            required: [],\n          },\n        })\n        break\n    }\n  }\n\n  // If we have function declarations, add them as a single tool\n  if (functionDeclarations.length > 0) {\n    result.push({\n      functionDeclarations: functionDeclarations,\n    })\n  }\n\n  return result\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,6BACd,OACkB;CAClB,IAAI,CAAC,SAAS,MAAM,WAAW,GAC7B,OAAO,CAAC;CAEV,sBAAsB,KAAK;CAC3B,MAAM,SAA2B,CAAC;CAClC,MAAM,uBAID,CAAC;CAGN,KAAK,MAAM,QAAQ,OACjB,QAAQ,0BAA0B,IAAI,GAAtC;EACE,KAAK;GACH,OAAO,KAAK,wCAAwC,IAAI,CAAC;GACzD;EACF,KAAK;GACH,OAAO,KAAK,sCAAsC,IAAI,CAAC;GACvD;EACF,KAAK;GACH,OAAO,KAAK,qCAAqC,IAAI,CAAC;GACtD;EACF,KAAK;GACH,OAAO,KAAK,qCAAqC,IAAI,CAAC;GACtD;EACF,KAAK;GACH,OAAO,KAAK,gDAAgD,IAAI,CAAC;GACjE;EACF,KAAK;GACH,OAAO,KAAK,uCAAuC,IAAI,CAAC;GACxD;EACF,KAAK;GACH,OAAO,KAAK,qCAAqC,IAAI,CAAC;GACtD;EACF,KAAK,KAAA;GAGH,IAAI,CAAC,KAAK,aACR,MAAM,IAAI,MACR,QAAQ,KAAK,KAAK,2CACpB;GAIF,qBAAqB,KAAK;IACxB,MAAM,KAAK;IACX,aAAa,KAAK;IAClB,YAAY,KAAK,eAAe;KAC9B,MAAM;KACN,YAAY,CAAC;KACb,UAAU,CAAC;IACb;GACF,CAAC;CAEL;CAIF,IAAI,qBAAqB,SAAS,GAChC,OAAO,KAAK,EACY,qBACxB,CAAC;CAGH,OAAO;AACT"}

package/dist/esm/tools/url-context-tool.js

@@ -1,14 +1,14 @@
-import { brandProviderTool } from "@tanstack/ai";
+import { brandGeminiProviderTool } from "./gemini-provider-tool.js";
 //#region src/tools/url-context-tool.ts
 function convertUrlContextToolToAdapterFormat(_tool) {
 	return { urlContext: {} };
 }
 function urlContextTool() {
-	return brandProviderTool({
+	return brandGeminiProviderTool({
 		name: "url_context",
 		description: "",
 		metadata: {}
-	});
+	}, "url_context");
 }
 //#endregion
 export { convertUrlContextToolToAdapterFormat, urlContextTool };

package/dist/esm/tools/url-context-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"url-context-tool.js","names":[],"sources":["../../../src/tools/url-context-tool.ts"],"sourcesContent":["import { brandProviderTool } from '@tanstack/ai'\nimport type { ProviderTool, Tool } from '@tanstack/ai'\n\nexport interface UrlContextToolConfig {}\n\n/** @deprecated Renamed to `UrlContextToolConfig`. Will be removed in a future release. */\nexport type UrlContextTool = UrlContextToolConfig\n\nexport type GeminiUrlContextTool = ProviderTool<'gemini', 'url_context'>\n\nexport function convertUrlContextToolToAdapterFormat(_tool: Tool) {\n  return {\n    urlContext: {},\n  }\n}\n\nexport function urlContextTool(): GeminiUrlContextTool {\n  return brandProviderTool<GeminiUrlContextTool>({\n    name: 'url_context',\n    description: '',\n    metadata: {},\n  })\n}\n"],"mappings":";;AAUA,SAAgB,qCAAqC,OAAa;CAChE,OAAO,EACL,YAAY,CAAC,EACf;AACF;AAEA,SAAgB,iBAAuC;CACrD,OAAO,kBAAwC;EAC7C,MAAM;EACN,aAAa;EACb,UAAU,CAAC;CACb,CAAC;AACH"}
+{"version":3,"file":"url-context-tool.js","names":[],"sources":["../../../src/tools/url-context-tool.ts"],"sourcesContent":["import { brandGeminiProviderTool } from './gemini-provider-tool'\nimport type { ProviderTool, Tool } from '@tanstack/ai'\n\nexport interface UrlContextToolConfig {}\n\n/** @deprecated Renamed to `UrlContextToolConfig`. Will be removed in a future release. */\nexport type UrlContextTool = UrlContextToolConfig\n\nexport type GeminiUrlContextTool = ProviderTool<'gemini', 'url_context'>\n\nexport function convertUrlContextToolToAdapterFormat(_tool: Tool) {\n  return {\n    urlContext: {},\n  }\n}\n\nexport function urlContextTool(): GeminiUrlContextTool {\n  return brandGeminiProviderTool<GeminiUrlContextTool>(\n    {\n      name: 'url_context',\n      description: '',\n      metadata: {},\n    },\n    'url_context',\n  )\n}\n"],"mappings":";;AAUA,SAAgB,qCAAqC,OAAa;CAChE,OAAO,EACL,YAAY,CAAC,EACf;AACF;AAEA,SAAgB,iBAAuC;CACrD,OAAO,wBACL;EACE,MAAM;EACN,aAAa;EACb,UAAU,CAAC;CACb,GACA,aACF;AACF"}

package/dist/esm/usage.js

@@ -25,9 +25,7 @@ function flattenModalityTokenCounts(modalities) {
 			case "VIDEO":
 				result.videoTokens = (result.videoTokens ?? 0) + count;
 				break;
-			case "DOCUMENT":
-				result.documentTokens = (result.documentTokens ?? 0) + count;
-				break;
+			case "DOCUMENT": result.documentTokens = (result.documentTokens ?? 0) + count;
 		}
 	}
 	return result;

package/dist/esm/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","names":[],"sources":["../../src/usage.ts"],"sourcesContent":["import { buildBaseUsage } from '@tanstack/ai'\nimport type { TokenUsage } from '@tanstack/ai'\nimport type {\n  GenerateContentResponseUsageMetadata,\n  ModalityTokenCount,\n} from '@google/genai'\n\n/**\n * Flattened modality token counts for normalized usage reporting.\n * Maps Gemini's ModalityTokenCount array to individual fields.\n */\nexport interface FlattenedModalityTokens {\n  /** Text tokens */\n  textTokens?: number\n  /** Image tokens */\n  imageTokens?: number\n  /** Audio tokens */\n  audioTokens?: number\n  /** Video tokens */\n  videoTokens?: number\n  /** Document tokens (e.g. PDF inputs) */\n  documentTokens?: number\n}\n\n/**\n * Flattens Gemini's ModalityTokenCount array into individual token fields.\n * Extracts TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT modality counts into a\n * normalized structure.\n */\nexport function flattenModalityTokenCounts(\n  modalities?: Array<ModalityTokenCount>,\n): FlattenedModalityTokens {\n  if (!modalities || modalities.length === 0) {\n    return {}\n  }\n\n  const result: FlattenedModalityTokens = {}\n\n  for (const item of modalities) {\n    if (!item.modality || item.tokenCount === undefined) {\n      continue\n    }\n\n    const modality = item.modality.toUpperCase()\n    const count = item.tokenCount\n\n    switch (modality) {\n      case 'TEXT':\n        result.textTokens = (result.textTokens ?? 0) + count\n        break\n      case 'IMAGE':\n        result.imageTokens = (result.imageTokens ?? 0) + count\n        break\n      case 'AUDIO':\n        result.audioTokens = (result.audioTokens ?? 0) + count\n        break\n      case 'VIDEO':\n        result.videoTokens = (result.videoTokens ?? 0) + count\n        break\n      case 'DOCUMENT':\n        result.documentTokens = (result.documentTokens ?? 0) + count\n        break\n    }\n  }\n\n  return result\n}\n\n/**\n * Checks if a FlattenedModalityTokens object has any values set.\n */\nexport function hasModalityTokens(tokens: FlattenedModalityTokens): boolean {\n  return (\n    tokens.textTokens !== undefined ||\n    tokens.imageTokens !== undefined ||\n    tokens.audioTokens !== undefined ||\n    tokens.videoTokens !== undefined ||\n    tokens.documentTokens !== undefined\n  )\n}\n\n/**\n * Gemini-specific provider usage details.\n * These fields are unique to Gemini and placed in providerUsageDetails.\n */\nexport type GeminiProviderUsageDetails = {\n  /**\n   * The traffic type for this request.\n   * Can indicate whether request was handled by different service tiers.\n   */\n  trafficType?: string\n  /**\n   * Number of tokens in the results from tool executions,\n   * which are provided back to the model as input.\n   */\n  toolUsePromptTokenCount?: number\n  /**\n   * Detailed breakdown by modality of the token counts from\n   * the results of tool executions.\n   */\n  toolUsePromptTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n  /**\n   * Detailed breakdown of cache tokens by modality.\n   * More granular than the normalized cachedTokens field.\n   */\n  cacheTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n}\n\n/**\n * Build normalized TokenUsage from Gemini's usageMetadata.\n * Handles modality breakdowns and thinking tokens. Returns `undefined` when the\n * provider reported no usage metadata, so callers omit the field rather than\n * fabricating zeroed totals.\n */\nexport function buildGeminiUsage(\n  usageMetadata: GenerateContentResponseUsageMetadata | undefined | null,\n): TokenUsage<GeminiProviderUsageDetails> | undefined {\n  if (!usageMetadata) return undefined\n\n  const promptTokens = usageMetadata.promptTokenCount ?? 0\n  const completionTokens = usageMetadata.candidatesTokenCount ?? 0\n\n  const result = buildBaseUsage<GeminiProviderUsageDetails>({\n    promptTokens: promptTokens,\n    completionTokens: completionTokens,\n    totalTokens:\n      usageMetadata.totalTokenCount ?? promptTokens + completionTokens,\n  })\n\n  // Add prompt token details\n  // Flatten modality breakdown for prompt\n  const promptModalities = flattenModalityTokenCounts(\n    usageMetadata.promptTokensDetails,\n  )\n  const cachedTokens = usageMetadata.cachedContentTokenCount\n\n  const promptTokensDetails = {\n    ...(hasModalityTokens(promptModalities) ? promptModalities : {}),\n    ...(cachedTokens !== undefined && cachedTokens > 0 ? { cachedTokens } : {}),\n  }\n\n  // Add completion token details\n  // Flatten modality breakdown for candidates (output)\n  const completionModalities = flattenModalityTokenCounts(\n    usageMetadata.candidatesTokensDetails,\n  )\n  const thoughtsTokens = usageMetadata.thoughtsTokenCount\n\n  const completionTokensDetails = {\n    ...(hasModalityTokens(completionModalities) ? completionModalities : {}),\n    // Map thoughtsTokenCount to reasoningTokens for consistency with OpenAI\n    ...(thoughtsTokens !== undefined && thoughtsTokens > 0\n      ? { reasoningTokens: thoughtsTokens }\n      : {}),\n  }\n\n  // Add provider-specific details\n  const providerDetails: GeminiProviderUsageDetails = {\n    ...(usageMetadata.trafficType\n      ? { trafficType: usageMetadata.trafficType }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokenCount !== undefined &&\n    usageMetadata.toolUsePromptTokenCount > 0\n      ? { toolUsePromptTokenCount: usageMetadata.toolUsePromptTokenCount }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokensDetails &&\n    usageMetadata.toolUsePromptTokensDetails.length > 0\n      ? {\n          toolUsePromptTokensDetails:\n            usageMetadata.toolUsePromptTokensDetails.map((item) => ({\n              modality: item.modality || 'UNKNOWN',\n              tokenCount: item.tokenCount ?? 0,\n            })),\n        }\n      : {}),\n    ...(usageMetadata.cacheTokensDetails &&\n    usageMetadata.cacheTokensDetails.length > 0\n      ? {\n          cacheTokensDetails: usageMetadata.cacheTokensDetails.map((item) => ({\n            modality: item.modality || 'UNKNOWN',\n            tokenCount: item.tokenCount ?? 0,\n          })),\n        }\n      : {}),\n  }\n\n  // Add prompt token details if available\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n  // Add provider details if available\n  if (Object.keys(providerDetails).length > 0) {\n    result.providerUsageDetails = providerDetails\n  }\n  // Add completion token details if available\n  if (Object.keys(completionTokensDetails).length > 0) {\n    result.completionTokensDetails = completionTokensDetails\n  }\n\n  return result\n}\n"],"mappings":";;;;;;;AA6BA,SAAgB,2BACd,YACyB;CACzB,IAAI,CAAC,cAAc,WAAW,WAAW,GACvC,OAAO,CAAC;CAGV,MAAM,SAAkC,CAAC;CAEzC,KAAK,MAAM,QAAQ,YAAY;EAC7B,IAAI,CAAC,KAAK,YAAY,KAAK,eAAe,KAAA,GACxC;EAGF,MAAM,WAAW,KAAK,SAAS,YAAY;EAC3C,MAAM,QAAQ,KAAK;EAEnB,QAAQ,UAAR;GACE,KAAK;IACH,OAAO,cAAc,OAAO,cAAc,KAAK;IAC/C;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,kBAAkB,OAAO,kBAAkB,KAAK;IACvD;EACJ;CACF;CAEA,OAAO;AACT;;;;AAKA,SAAgB,kBAAkB,QAA0C;CAC1E,OACE,OAAO,eAAe,KAAA,KACtB,OAAO,gBAAgB,KAAA,KACvB,OAAO,gBAAgB,KAAA,KACvB,OAAO,gBAAgB,KAAA,KACvB,OAAO,mBAAmB,KAAA;AAE9B;;;;;;;AAyCA,SAAgB,iBACd,eACoD;CACpD,IAAI,CAAC,eAAe,OAAO,KAAA;CAE3B,MAAM,eAAe,cAAc,oBAAoB;CACvD,MAAM,mBAAmB,cAAc,wBAAwB;CAE/D,MAAM,SAAS,eAA2C;EAC1C;EACI;EAClB,aACE,cAAc,mBAAmB,eAAe;CACpD,CAAC;CAID,MAAM,mBAAmB,2BACvB,cAAc,mBAChB;CACA,MAAM,eAAe,cAAc;CAEnC,MAAM,sBAAsB;EAC1B,GAAI,kBAAkB,gBAAgB,IAAI,mBAAmB,CAAC;EAC9D,GAAI,iBAAiB,KAAA,KAAa,eAAe,IAAI,EAAE,aAAa,IAAI,CAAC;CAC3E;CAIA,MAAM,uBAAuB,2BAC3B,cAAc,uBAChB;CACA,MAAM,iBAAiB,cAAc;CAErC,MAAM,0BAA0B;EAC9B,GAAI,kBAAkB,oBAAoB,IAAI,uBAAuB,CAAC;EAEtE,GAAI,mBAAmB,KAAA,KAAa,iBAAiB,IACjD,EAAE,iBAAiB,eAAe,IAClC,CAAC;CACP;CAGA,MAAM,kBAA8C;EAClD,GAAI,cAAc,cACd,EAAE,aAAa,cAAc,YAAY,IACzC,CAAC;EACL,GAAI,cAAc,4BAA4B,KAAA,KAC9C,cAAc,0BAA0B,IACpC,EAAE,yBAAyB,cAAc,wBAAwB,IACjE,CAAC;EACL,GAAI,cAAc,8BAClB,cAAc,2BAA2B,SAAS,IAC9C,EACE,4BACE,cAAc,2BAA2B,KAAK,UAAU;GACtD,UAAU,KAAK,YAAY;GAC3B,YAAY,KAAK,cAAc;EACjC,EAAE,EACN,IACA,CAAC;EACL,GAAI,cAAc,sBAClB,cAAc,mBAAmB,SAAS,IACtC,EACE,oBAAoB,cAAc,mBAAmB,KAAK,UAAU;GAClE,UAAU,KAAK,YAAY;GAC3B,YAAY,KAAK,cAAc;EACjC,EAAE,EACJ,IACA,CAAC;CACP;CAGA,IAAI,OAAO,KAAK,mBAAmB,CAAC,CAAC,SAAS,GAC5C,OAAO,sBAAsB;CAG/B,IAAI,OAAO,KAAK,eAAe,CAAC,CAAC,SAAS,GACxC,OAAO,uBAAuB;CAGhC,IAAI,OAAO,KAAK,uBAAuB,CAAC,CAAC,SAAS,GAChD,OAAO,0BAA0B;CAGnC,OAAO;AACT"}
+{"version":3,"file":"usage.js","names":[],"sources":["../../src/usage.ts"],"sourcesContent":["import { buildBaseUsage } from '@tanstack/ai'\nimport type { TokenUsage } from '@tanstack/ai'\nimport type {\n  GenerateContentResponseUsageMetadata,\n  ModalityTokenCount,\n} from '@google/genai'\n\n/**\n * Flattened modality token counts for normalized usage reporting.\n * Maps Gemini's ModalityTokenCount array to individual fields.\n */\nexport interface FlattenedModalityTokens {\n  /** Text tokens */\n  textTokens?: number\n  /** Image tokens */\n  imageTokens?: number\n  /** Audio tokens */\n  audioTokens?: number\n  /** Video tokens */\n  videoTokens?: number\n  /** Document tokens (e.g. PDF inputs) */\n  documentTokens?: number\n}\n\n/**\n * Flattens Gemini's ModalityTokenCount array into individual token fields.\n * Extracts TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT modality counts into a\n * normalized structure.\n */\nexport function flattenModalityTokenCounts(\n  modalities?: Array<ModalityTokenCount>,\n): FlattenedModalityTokens {\n  if (!modalities || modalities.length === 0) {\n    return {}\n  }\n\n  const result: FlattenedModalityTokens = {}\n\n  for (const item of modalities) {\n    if (!item.modality || item.tokenCount === undefined) {\n      continue\n    }\n\n    const modality = item.modality.toUpperCase()\n    const count = item.tokenCount\n\n    switch (modality) {\n      case 'TEXT':\n        result.textTokens = (result.textTokens ?? 0) + count\n        break\n      case 'IMAGE':\n        result.imageTokens = (result.imageTokens ?? 0) + count\n        break\n      case 'AUDIO':\n        result.audioTokens = (result.audioTokens ?? 0) + count\n        break\n      case 'VIDEO':\n        result.videoTokens = (result.videoTokens ?? 0) + count\n        break\n      case 'DOCUMENT':\n        result.documentTokens = (result.documentTokens ?? 0) + count\n        break\n    }\n  }\n\n  return result\n}\n\n/**\n * Checks if a FlattenedModalityTokens object has any values set.\n */\nexport function hasModalityTokens(tokens: FlattenedModalityTokens): boolean {\n  return (\n    tokens.textTokens !== undefined ||\n    tokens.imageTokens !== undefined ||\n    tokens.audioTokens !== undefined ||\n    tokens.videoTokens !== undefined ||\n    tokens.documentTokens !== undefined\n  )\n}\n\n/**\n * Gemini-specific provider usage details.\n * These fields are unique to Gemini and placed in providerUsageDetails.\n */\nexport type GeminiProviderUsageDetails = {\n  /**\n   * The traffic type for this request.\n   * Can indicate whether request was handled by different service tiers.\n   */\n  trafficType?: string\n  /**\n   * Number of tokens in the results from tool executions,\n   * which are provided back to the model as input.\n   */\n  toolUsePromptTokenCount?: number\n  /**\n   * Detailed breakdown by modality of the token counts from\n   * the results of tool executions.\n   */\n  toolUsePromptTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n  /**\n   * Detailed breakdown of cache tokens by modality.\n   * More granular than the normalized cachedTokens field.\n   */\n  cacheTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n}\n\n/**\n * Build normalized TokenUsage from Gemini's usageMetadata.\n * Handles modality breakdowns and thinking tokens. Returns `undefined` when the\n * provider reported no usage metadata, so callers omit the field rather than\n * fabricating zeroed totals.\n */\nexport function buildGeminiUsage(\n  usageMetadata: GenerateContentResponseUsageMetadata | undefined | null,\n): TokenUsage<GeminiProviderUsageDetails> | undefined {\n  if (!usageMetadata) return undefined\n\n  const promptTokens = usageMetadata.promptTokenCount ?? 0\n  const completionTokens = usageMetadata.candidatesTokenCount ?? 0\n\n  const result = buildBaseUsage<GeminiProviderUsageDetails>({\n    promptTokens: promptTokens,\n    completionTokens: completionTokens,\n    totalTokens:\n      usageMetadata.totalTokenCount ?? promptTokens + completionTokens,\n  })\n\n  // Add prompt token details\n  // Flatten modality breakdown for prompt\n  const promptModalities = flattenModalityTokenCounts(\n    usageMetadata.promptTokensDetails,\n  )\n  const cachedTokens = usageMetadata.cachedContentTokenCount\n\n  const promptTokensDetails = {\n    ...(hasModalityTokens(promptModalities) ? promptModalities : {}),\n    ...(cachedTokens !== undefined && cachedTokens > 0 ? { cachedTokens } : {}),\n  }\n\n  // Add completion token details\n  // Flatten modality breakdown for candidates (output)\n  const completionModalities = flattenModalityTokenCounts(\n    usageMetadata.candidatesTokensDetails,\n  )\n  const thoughtsTokens = usageMetadata.thoughtsTokenCount\n\n  const completionTokensDetails = {\n    ...(hasModalityTokens(completionModalities) ? completionModalities : {}),\n    // Map thoughtsTokenCount to reasoningTokens for consistency with OpenAI\n    ...(thoughtsTokens !== undefined && thoughtsTokens > 0\n      ? { reasoningTokens: thoughtsTokens }\n      : {}),\n  }\n\n  // Add provider-specific details\n  const providerDetails: GeminiProviderUsageDetails = {\n    ...(usageMetadata.trafficType\n      ? { trafficType: usageMetadata.trafficType }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokenCount !== undefined &&\n    usageMetadata.toolUsePromptTokenCount > 0\n      ? { toolUsePromptTokenCount: usageMetadata.toolUsePromptTokenCount }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokensDetails &&\n    usageMetadata.toolUsePromptTokensDetails.length > 0\n      ? {\n          toolUsePromptTokensDetails:\n            usageMetadata.toolUsePromptTokensDetails.map((item) => ({\n              modality: item.modality || 'UNKNOWN',\n              tokenCount: item.tokenCount ?? 0,\n            })),\n        }\n      : {}),\n    ...(usageMetadata.cacheTokensDetails &&\n    usageMetadata.cacheTokensDetails.length > 0\n      ? {\n          cacheTokensDetails: usageMetadata.cacheTokensDetails.map((item) => ({\n            modality: item.modality || 'UNKNOWN',\n            tokenCount: item.tokenCount ?? 0,\n          })),\n        }\n      : {}),\n  }\n\n  // Add prompt token details if available\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n  // Add provider details if available\n  if (Object.keys(providerDetails).length > 0) {\n    result.providerUsageDetails = providerDetails\n  }\n  // Add completion token details if available\n  if (Object.keys(completionTokensDetails).length > 0) {\n    result.completionTokensDetails = completionTokensDetails\n  }\n\n  return result\n}\n"],"mappings":";;;;;;;AA6BA,SAAgB,2BACd,YACyB;CACzB,IAAI,CAAC,cAAc,WAAW,WAAW,GACvC,OAAO,CAAC;CAGV,MAAM,SAAkC,CAAC;CAEzC,KAAK,MAAM,QAAQ,YAAY;EAC7B,IAAI,CAAC,KAAK,YAAY,KAAK,eAAe,KAAA,GACxC;EAGF,MAAM,WAAW,KAAK,SAAS,YAAY;EAC3C,MAAM,QAAQ,KAAK;EAEnB,QAAQ,UAAR;GACE,KAAK;IACH,OAAO,cAAc,OAAO,cAAc,KAAK;IAC/C;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK,YACH,OAAO,kBAAkB,OAAO,kBAAkB,KAAK;EAE3D;CACF;CAEA,OAAO;AACT;;;;AAKA,SAAgB,kBAAkB,QAA0C;CAC1E,OACE,OAAO,eAAe,KAAA,KACtB,OAAO,gBAAgB,KAAA,KACvB,OAAO,gBAAgB,KAAA,KACvB,OAAO,gBAAgB,KAAA,KACvB,OAAO,mBAAmB,KAAA;AAE9B;;;;;;;AAyCA,SAAgB,iBACd,eACoD;CACpD,IAAI,CAAC,eAAe,OAAO,KAAA;CAE3B,MAAM,eAAe,cAAc,oBAAoB;CACvD,MAAM,mBAAmB,cAAc,wBAAwB;CAE/D,MAAM,SAAS,eAA2C;EAC1C;EACI;EAClB,aACE,cAAc,mBAAmB,eAAe;CACpD,CAAC;CAID,MAAM,mBAAmB,2BACvB,cAAc,mBAChB;CACA,MAAM,eAAe,cAAc;CAEnC,MAAM,sBAAsB;EAC1B,GAAI,kBAAkB,gBAAgB,IAAI,mBAAmB,CAAC;EAC9D,GAAI,iBAAiB,KAAA,KAAa,eAAe,IAAI,EAAE,aAAa,IAAI,CAAC;CAC3E;CAIA,MAAM,uBAAuB,2BAC3B,cAAc,uBAChB;CACA,MAAM,iBAAiB,cAAc;CAErC,MAAM,0BAA0B;EAC9B,GAAI,kBAAkB,oBAAoB,IAAI,uBAAuB,CAAC;EAEtE,GAAI,mBAAmB,KAAA,KAAa,iBAAiB,IACjD,EAAE,iBAAiB,eAAe,IAClC,CAAC;CACP;CAGA,MAAM,kBAA8C;EAClD,GAAI,cAAc,cACd,EAAE,aAAa,cAAc,YAAY,IACzC,CAAC;EACL,GAAI,cAAc,4BAA4B,KAAA,KAC9C,cAAc,0BAA0B,IACpC,EAAE,yBAAyB,cAAc,wBAAwB,IACjE,CAAC;EACL,GAAI,cAAc,8BAClB,cAAc,2BAA2B,SAAS,IAC9C,EACE,4BACE,cAAc,2BAA2B,KAAK,UAAU;GACtD,UAAU,KAAK,YAAY;GAC3B,YAAY,KAAK,cAAc;EACjC,EAAE,EACN,IACA,CAAC;EACL,GAAI,cAAc,sBAClB,cAAc,mBAAmB,SAAS,IACtC,EACE,oBAAoB,cAAc,mBAAmB,KAAK,UAAU;GAClE,UAAU,KAAK,YAAY;GAC3B,YAAY,KAAK,cAAc;EACjC,EAAE,EACJ,IACA,CAAC;CACP;CAGA,IAAI,OAAO,KAAK,mBAAmB,CAAC,CAAC,SAAS,GAC5C,OAAO,sBAAsB;CAG/B,IAAI,OAAO,KAAK,eAAe,CAAC,CAAC,SAAS,GACxC,OAAO,uBAAuB;CAGhC,IAAI,OAAO,KAAK,uBAAuB,CAAC,CAAC,SAAS,GAChD,OAAO,0BAA0B;CAGnC,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-gemini",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Google Gemini adapter for TanStack AI chat, images, speech, audio generation, and structured outputs.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -59,13 +59,13 @@
     "@tanstack/ai-utils": "^0.4.0"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.44.1"
+    "@tanstack/ai": "^0.46.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.14",
-    "vite": "^8.1.4",
+    "@vitest/coverage-v8": "4.1.10",
+    "vite": "^8.2.1",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.44.1"
+    "@tanstack/ai": "0.46.0"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/image.ts

@@ -7,18 +7,20 @@ import {
 } from '../utils'
 import { buildGeminiUsage } from '../usage'
 import {
+  isGeminiNativeImageModel,
   parseNativeImageSize,
   sizeToAspectRatio,
   validateImageSize,
   validateNumberOfImages,
   validatePrompt,
 } from '../image/image-provider-options'
-import type { GEMINI_IMAGE_MODELS } from '../model-meta'
+import type { GeminiImageModels } from '../model-meta'
 import type {
+  GeminiAnyImageProviderOptions,
   GeminiImageModelInputModalitiesByName,
   GeminiImageModelProviderOptionsByName,
   GeminiImageModelSizeByName,
-  GeminiImageProviderOptions,
+  GeminiNativeImageProviderOptions,
 } from '../image/image-provider-options'
 import type {
   GeneratedImage,
@@ -35,6 +37,7 @@ import type {
   GenerateImagesConfig,
   GenerateImagesResponse,
   GoogleGenAI,
+  ImageConfig,
   Part,
 } from '@google/genai'
 import type { GeminiClientConfig } from '../utils/client'
@@ -45,7 +48,7 @@ import type { GeminiClientConfig } from '../utils/client'
 export interface GeminiImageConfig extends GeminiClientConfig {}
 
 /** Model type for Gemini Image */
-export type GeminiImageModel = (typeof GEMINI_IMAGE_MODELS)[number]
+export type GeminiImageModel = GeminiImageModels
 
 /**
  * Gemini Image Generation Adapter
@@ -65,7 +68,7 @@ export class GeminiImageAdapter<
   TModel extends GeminiImageModel,
 > extends BaseImageAdapter<
   TModel,
-  GeminiImageProviderOptions,
+  GeminiAnyImageProviderOptions,
   GeminiImageModelProviderOptionsByName,
   GeminiImageModelSizeByName,
   GeminiImageModelInputModalitiesByName
@@ -75,7 +78,7 @@ export class GeminiImageAdapter<
 
   // Type-only property - never assigned at runtime
   declare '~types': {
-    providerOptions: GeminiImageProviderOptions
+    providerOptions: GeminiAnyImageProviderOptions
     modelProviderOptionsByName: GeminiImageModelProviderOptionsByName
     modelSizeByName: GeminiImageModelSizeByName
     modelInputModalitiesByName: GeminiImageModelInputModalitiesByName
@@ -89,7 +92,7 @@ export class GeminiImageAdapter<
   }
 
   async generateImages(
-    options: ImageGenerationOptions<GeminiImageProviderOptions>,
+    options: ImageGenerationOptions<GeminiAnyImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
     const { model, logger } = options
 
@@ -121,7 +124,7 @@ export class GeminiImageAdapter<
         )
       }
 
-      if (this.isGeminiImageModel(model)) {
+      if (isGeminiNativeImageModel(model)) {
         return await this.generateWithGeminiApi(options, resolved)
       }
 
@@ -155,29 +158,40 @@ export class GeminiImageAdapter<
     }
   }
 
-  private isGeminiImageModel(model: string): boolean {
-    return model.startsWith('gemini-')
-  }
-
   private async generateWithGeminiApi(
-    options: ImageGenerationOptions<GeminiImageProviderOptions>,
+    options: ImageGenerationOptions<GeminiNativeImageProviderOptions>,
     resolved: ResolvedMediaPrompt,
   ): Promise<ImageGenerationResult> {
     const { model, size, numberOfImages, modelOptions } = options
 
     const parsedSize = size ? parseNativeImageSize(size) : undefined
 
-    // GeminiImageProviderOptions is Imagen-shaped — most fields
-    // (personGeneration, safetyFilterLevel, addWatermark, outputMimeType,
-    // outputCompressionQuality, guidanceScale, enhancePrompt,
-    // includeSafetyAttributes, includeRaiReason, outputGcsUri, labels,
-    // negativePrompt, language) are only valid on GenerateImagesConfig and
-    // would be rejected by the Gemini-native generateContent path. Pick only
-    // the fields that are valid on GenerateContentConfig instead of spreading
-    // the whole options object.
-    const nativeConfig: GenerateContentConfig = {}
-    if (modelOptions?.seed !== undefined) {
-      nativeConfig.seed = modelOptions.seed
+    // The portable `size` option is the baseline; modelOptions.imageConfig is
+    // the provider escape hatch and wins per field, so a caller passing only
+    // `imageConfig.imageSize` keeps the aspectRatio derived from `size`.
+    const imageConfig: ImageConfig = {
+      ...(parsedSize?.aspectRatio && { aspectRatio: parsedSize.aspectRatio }),
+      ...(parsedSize?.resolution && { imageSize: parsedSize.resolution }),
+      ...modelOptions?.imageConfig,
+    }
+
+    // Named picks, never a wholesale spread: the Imagen-shaped fields of
+    // GeminiImageProviderOptions (personGeneration, safetyFilterLevel,
+    // addWatermark, outputMimeType, …) are only valid on GenerateImagesConfig
+    // and would be rejected by generateContent. Picking by name means no
+    // Imagen field can reach this path even if one slips past the per-model
+    // provider-options map.
+    const nativeConfig: GenerateContentConfig = {
+      ...(modelOptions?.seed !== undefined && { seed: modelOptions.seed }),
+      ...(modelOptions?.safetySettings !== undefined && {
+        safetySettings: modelOptions.safetySettings,
+      }),
+      ...(modelOptions?.thinkingConfig !== undefined && {
+        thinkingConfig: modelOptions.thinkingConfig,
+      }),
+      ...(modelOptions?.systemInstruction !== undefined && {
+        systemInstruction: modelOptions.systemInstruction,
+      }),
     }
 
     const config: GenerateContentConfig = {
@@ -186,16 +200,7 @@ export class GeminiImageAdapter<
       // IMPORTANT: responseModalities is a protected default — set it AFTER
       // nativeConfig so nothing can silently disable image output.
       responseModalities: ['TEXT', 'IMAGE'],
-      ...(parsedSize && {
-        imageConfig: {
-          ...(parsedSize.aspectRatio && {
-            aspectRatio: parsedSize.aspectRatio,
-          }),
-          ...(parsedSize.resolution && {
-            imageSize: parsedSize.resolution,
-          }),
-        },
-      }),
+      ...(Object.keys(imageConfig).length > 0 && { imageConfig }),
     }
 
     const contents = this.buildContents(resolved, numberOfImages)
@@ -321,7 +326,7 @@ export class GeminiImageAdapter<
   }
 
   private buildImagenConfig(
-    options: ImageGenerationOptions<GeminiImageProviderOptions>,
+    options: ImageGenerationOptions<GeminiAnyImageProviderOptions>,
   ): GenerateImagesConfig {
     const { size, numberOfImages, modelOptions } = options
 
@@ -329,11 +334,62 @@ export class GeminiImageAdapter<
     // vendor `GenerateImagesConfig` fields are `field?: T` (no `| undefined`),
     // so we can only assign the property when we actually have a value.
     const sizeAspectRatio = size ? sizeToAspectRatio(size) : undefined
+
+    // Named picks, never a wholesale spread — the mirror image of the native
+    // path below. A native-only field (safetySettings, thinkingConfig,
+    // imageConfig, systemInstruction) belongs to GenerateContentConfig and is
+    // rejected by generateImages with 400 INVALID_ARGUMENT, so it must not be
+    // able to reach here even when the caller's `modelOptions` was typed
+    // against both shapes at once (e.g. an adapter inferred from a union of
+    // model names).
     return {
       numberOfImages: numberOfImages ?? 1,
-      // Map size to aspect ratio if provided (modelOptions.aspectRatio will override)
+      // Map size to aspect ratio if provided; modelOptions.aspectRatio,
+      // picked after it, overrides.
       ...(sizeAspectRatio !== undefined && { aspectRatio: sizeAspectRatio }),
-      ...modelOptions,
+      ...(modelOptions?.aspectRatio !== undefined && {
+        aspectRatio: modelOptions.aspectRatio,
+      }),
+      ...(modelOptions?.personGeneration !== undefined && {
+        personGeneration: modelOptions.personGeneration,
+      }),
+      ...(modelOptions?.safetyFilterLevel !== undefined && {
+        safetyFilterLevel: modelOptions.safetyFilterLevel,
+      }),
+      ...(modelOptions?.seed !== undefined && { seed: modelOptions.seed }),
+      ...(modelOptions?.addWatermark !== undefined && {
+        addWatermark: modelOptions.addWatermark,
+      }),
+      ...(modelOptions?.language !== undefined && {
+        language: modelOptions.language,
+      }),
+      ...(modelOptions?.negativePrompt !== undefined && {
+        negativePrompt: modelOptions.negativePrompt,
+      }),
+      ...(modelOptions?.outputMimeType !== undefined && {
+        outputMimeType: modelOptions.outputMimeType,
+      }),
+      ...(modelOptions?.outputCompressionQuality !== undefined && {
+        outputCompressionQuality: modelOptions.outputCompressionQuality,
+      }),
+      ...(modelOptions?.guidanceScale !== undefined && {
+        guidanceScale: modelOptions.guidanceScale,
+      }),
+      ...(modelOptions?.enhancePrompt !== undefined && {
+        enhancePrompt: modelOptions.enhancePrompt,
+      }),
+      ...(modelOptions?.includeSafetyAttributes !== undefined && {
+        includeSafetyAttributes: modelOptions.includeSafetyAttributes,
+      }),
+      ...(modelOptions?.includeRaiReason !== undefined && {
+        includeRaiReason: modelOptions.includeRaiReason,
+      }),
+      ...(modelOptions?.outputGcsUri !== undefined && {
+        outputGcsUri: modelOptions.outputGcsUri,
+      }),
+      ...(modelOptions?.labels !== undefined && {
+        labels: modelOptions.labels,
+      }),
     }
   }
 
@@ -392,6 +448,18 @@ export class GeminiImageAdapter<
   }
 }
 
+/** @deprecated Shut down 2026-06-25. Use `gemini-3.1-flash-image`. */
+export function createGeminiImage(
+  model: 'gemini-3.1-flash-image-preview',
+  apiKey: string,
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<'gemini-3.1-flash-image-preview'>
+/** @deprecated Shut down 2026-06-25. Use `gemini-3-pro-image`. */
+export function createGeminiImage(
+  model: 'gemini-3-pro-image-preview',
+  apiKey: string,
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<'gemini-3-pro-image-preview'>
 /**
  * Creates a Gemini image adapter with explicit API key.
  * Type resolution happens here at the call site.
@@ -411,6 +479,11 @@ export class GeminiImageAdapter<
  * });
  * ```
  */
+export function createGeminiImage<TModel extends GeminiImageModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<TModel>
 export function createGeminiImage<TModel extends GeminiImageModel>(
   model: TModel,
   apiKey: string,
@@ -419,6 +492,16 @@ export function createGeminiImage<TModel extends GeminiImageModel>(
   return new GeminiImageAdapter({ apiKey, ...config }, model)
 }
 
+/** @deprecated Shut down 2026-06-25. Use `gemini-3.1-flash-image`. */
+export function geminiImage(
+  model: 'gemini-3.1-flash-image-preview',
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<'gemini-3.1-flash-image-preview'>
+/** @deprecated Shut down 2026-06-25. Use `gemini-3-pro-image`. */
+export function geminiImage(
+  model: 'gemini-3-pro-image-preview',
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<'gemini-3-pro-image-preview'>
 /**
  * Creates a Gemini image adapter with automatic API key detection from environment variables.
  * Type resolution happens here at the call site.
@@ -443,6 +526,10 @@ export function createGeminiImage<TModel extends GeminiImageModel>(
  * });
  * ```
  */
+export function geminiImage<TModel extends GeminiImageModel>(
+  model: TModel,
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<TModel>
 export function geminiImage<TModel extends GeminiImageModel>(
   model: TModel,
   config?: Omit<GeminiImageConfig, 'apiKey'>,

package/src/experimental/text-interactions/adapter.ts

@@ -6,6 +6,11 @@ import {
   generateId,
   getGeminiApiKeyFromEnv,
 } from '../../utils/client'
+import {
+  getGeminiProviderToolKind,
+  getGeminiProviderToolMetadata,
+} from '../../tools/gemini-provider-tool'
+import { assertUniqueToolNames } from '@tanstack/ai/adapter-internals'
 import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 import type {
   GeminiChatModelToolCapabilitiesByName,
@@ -122,9 +127,9 @@ type ResolveInputModalities<TModel extends string> =
 
 /**
  * Resolve tool capabilities for a specific model. Reuses the chat-model
- * capability map: `google_maps` / `google_search_retrieval` /
- * `mcp_server` are rejected at runtime by `convertToolsToInteractionsFormat`,
- * but per-model gating happens here at compile time.
+ * capability map: `google_maps` / `google_search_retrieval` are rejected at
+ * runtime by `convertToolsToInteractionsFormat`, but per-model gating happens
+ * here at compile time.
  */
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof GeminiChatModelToolCapabilitiesByName
@@ -153,8 +158,11 @@ type ResolveToolCapabilities<TModel extends string> =
  * corresponding per-tool variants) carrying the raw Interactions delta;
  * see {@link GeminiInteractionsCustomEvent}. `computer_use` is accepted
  * in the request but the Interactions API does not currently stream
- * per-delta CUSTOM events for it. `google_search_retrieval`,
- * `google_maps`, and `mcp_server` are not supported on this adapter.
+ * per-delta CUSTOM events for it. The `google_search_retrieval` and
+ * `google_maps` provider-tool factories are not supported on this adapter and
+ * throw a targeted error. There is no Gemini `mcp_server` factory, so a tool
+ * merely *named* `mcp_server` is an ordinary function and is sent as a function
+ * declaration like any other.
  *
  * @experimental Interactions API is in Beta per Google; shapes may change.
  * @see https://ai.google.dev/gemini-api/docs/interactions
@@ -781,20 +789,29 @@ function convertToolsToInteractionsFormat<TTool extends Tool>(
   tools: Array<TTool> | undefined,
 ): Array<InteractionsTool> | undefined {
   if (!tools || tools.length === 0) return undefined
+  assertUniqueToolNames(tools)
 
   const result: Array<InteractionsTool> = []
 
   for (const tool of tools) {
-    switch (tool.name) {
+    switch (getGeminiProviderToolKind(tool)) {
       case 'google_search': {
-        const metadata = (tool.metadata ?? {}) as {
-          search_types?: Array<'web_search' | 'image_search'>
+        const metadata = (getGeminiProviderToolMetadata(tool) ?? {}) as {
+          searchTypes?: {
+            webSearch?: unknown
+            imageSearch?: unknown
+          }
+        }
+        const searchTypes: Array<'web_search' | 'image_search'> = []
+        if (metadata.searchTypes?.webSearch !== undefined) {
+          searchTypes.push('web_search')
+        }
+        if (metadata.searchTypes?.imageSearch !== undefined) {
+          searchTypes.push('image_search')
         }
         result.push({
           type: 'google_search',
-          ...(metadata.search_types
-            ? { search_types: metadata.search_types }
-            : {}),
+          ...(searchTypes.length > 0 ? { search_types: searchTypes } : {}),
         })
         break
       }
@@ -807,7 +824,7 @@ function convertToolsToInteractionsFormat<TTool extends Tool>(
         break
       }
       case 'file_search': {
-        const metadata = (tool.metadata ?? {}) as {
+        const metadata = (getGeminiProviderToolMetadata(tool) ?? {}) as {
           fileSearchStoreNames?: Array<string>
           topK?: number
           metadataFilter?: string
@@ -825,7 +842,7 @@ function convertToolsToInteractionsFormat<TTool extends Tool>(
         break
       }
       case 'computer_use': {
-        const metadata = (tool.metadata ?? {}) as {
+        const metadata = (getGeminiProviderToolMetadata(tool) ?? {}) as {
           environment?: string
           excludedPredefinedFunctions?: Array<string>
         }
@@ -856,11 +873,7 @@ function convertToolsToInteractionsFormat<TTool extends Tool>(
         throw new Error(
           '`google_maps` is not yet supported on the Gemini Interactions API. Use `geminiText()` for Google Maps grounding.',
         )
-      case 'mcp_server':
-        throw new Error(
-          '`mcp_server` is not yet supported on the `geminiTextInteractions()` adapter.',
-        )
-      default: {
+      case undefined: {
         if (!tool.description) {
           throw new Error(
             `Tool ${tool.name} requires a description for the Gemini Interactions adapter`,