Feat: Adding Gemini tools - URL Context and Grounding with Google Search (RooCodeInc#5959)

* feat: Adding more settings and control over Gemini

- with topP, topK, maxOutputTokens
- allow users to enable URL context and Grounding Research

* feat: Adding parameter titles and descriptions + translation to all languages

* feat: adding more translations

* feat: adding `contextLimit` implementation from `maxContextWindow` PR + working with profile-specific thresholding

* feat: max value for context limit to model's limit + converting description and titles to settings for translation purposes

* feat: all languages translated

* feat: changing profile-specific threshold in context management setting will also change in Gemini context management

- sync between Context Management Settting <-> Gemini Context Management with regards to thresholding

* feat: max value of maxOutputTokens is model's maxTokens + adding more tests

* feat: improve unit tests and adding `data-testid` to slider and checkbox components

* fix: small changes in geminiContextManagement descriptions + minor fix

* fix: Switching from "Gemini Context Management" to "Token Management

- better naming and correct purpose

* fix: input field showed NaN -> annoying UX

* fix: Removing redundant "tokens" after the "set context limit"'s checkbox + removing the lengthy description

* fix: Changing the translation to be consistent with the english one

* fix: more translations

* fix: translations

* fix: removing contextLimit and token management related code

- due to the decision in: RooCodeInc#3717

* fix: removing `contextLimit` test and removing token management in translations

* fix: changing from `Advanced Features` to `Tools` to be consistent with Gemini docs/AI studio

* fix: adding `try-catch` block for `generateContentStream`

* feat: Include citations + improved type safety

* feat: adding citation for streams (generateContextStream)

* fix: set default values for `topP`, `topK` and `maxOutputTokens`

* fix: changing UI/UX according to the review/feedback from `daniel-lxs`

* fix: updating the `Gemini.spec.tsx` unit test

- testing when it is hidden
- testing when users click on the collapsible trigger and model configuration appears

* fix: more changes from the feedback/review from `daniel-lxs`

* fix: adding sources at the end of the stream to preserve

* fix: change the description for grounding with google search and url context

* fix: adding translations

* fix: removing redundant extra translations - a mistake made by the agent

* fix: remove duplicate translation keys in geminiSections and geminiParameters

- Fixed duplicate keys in 13 localization files (es, fr, hi, id, it, ja, ko, nl, pl, pt-BR, ru, tr, vi)
- Removed second occurrence of geminiSections and geminiParameters keys
- Kept first occurrence which contains more comprehensive descriptions
- All JSON files validated for syntax correctness
- Translation completeness verified with missing translations script

Resolves duplicate key issue identified in PR RooCodeInc#4895

* fix: delete topK, topP and maxOutputTokens from Gemini

* fix: deleting topK, topP and maxOutputTokens from translations/locales

* fix: adjust spacing between labels and descriptions + sentence casing

* fix: adding maxOutputTokens back and removing unknown type

* fix: internalizing error Gemini error message

* fix: updating tests in Gemini and Vertex to adjust to the new error logging

* fix: address PR review feedback for Gemini tools feature

- Fix Hindi translation grammatical error in settings.json
- Internationalize 'Sources:' string and error messages in gemini.ts
- Add comprehensive error scenario tests to gemini-handler.spec.ts
- Remove unused currentModelId prop from Gemini component
- Update all locale files with new translation keys

---------

Co-authored-by: Roo Code <[email protected]>
Co-authored-by: Matt Rubens <[email protected]>
Co-authored-by: Daniel Riccio <[email protected]>

Author: 4 people

packages/types/src/provider-settings.ts

@@ -171,6 +171,8 @@ const lmStudioSchema = baseProviderSettingsSchema.extend({
 const geminiSchema = apiModelIdProviderModelSchema.extend({
 	geminiApiKey: z.string().optional(),
 	googleGeminiBaseUrl: z.string().optional(),
+	enableUrlContext: z.boolean().optional(),
+	enableGrounding: z.boolean().optional(),
 })
 
 const geminiCliSchema = apiModelIdProviderModelSchema.extend({

src/api/providers/__tests__/gemini-handler.spec.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi } from "vitest"
+import { t } from "i18next"
+import { GeminiHandler } from "../gemini"
+import type { ApiHandlerOptions } from "../../../shared/api"
+
+describe("GeminiHandler backend support", () => {
+	it("passes tools for URL context and grounding in config", async () => {
+		const options = {
+			apiProvider: "gemini",
+			enableUrlContext: true,
+			enableGrounding: true,
+		} as ApiHandlerOptions
+		const handler = new GeminiHandler(options)
+		const stub = vi.fn().mockReturnValue((async function* () {})())
+		// @ts-ignore access private client
+		handler["client"].models.generateContentStream = stub
+		await handler.createMessage("instr", [] as any).next()
+		const config = stub.mock.calls[0][0].config
+		expect(config.tools).toEqual([{ urlContext: {} }, { googleSearch: {} }])
+	})
+
+	it("completePrompt passes config overrides without tools when URL context and grounding disabled", async () => {
+		const options = {
+			apiProvider: "gemini",
+			enableUrlContext: false,
+			enableGrounding: false,
+		} as ApiHandlerOptions
+		const handler = new GeminiHandler(options)
+		const stub = vi.fn().mockResolvedValue({ text: "ok" })
+		// @ts-ignore access private client
+		handler["client"].models.generateContent = stub
+		const res = await handler.completePrompt("hi")
+		expect(res).toBe("ok")
+		const promptConfig = stub.mock.calls[0][0].config
+		expect(promptConfig.tools).toBeUndefined()
+	})
+
+	describe("error scenarios", () => {
+		it("should handle grounding metadata extraction failure gracefully", async () => {
+			const options = {
+				apiProvider: "gemini",
+				enableGrounding: true,
+			} as ApiHandlerOptions
+			const handler = new GeminiHandler(options)
+
+			const mockStream = async function* () {
+				yield {
+					candidates: [
+						{
+							groundingMetadata: {
+								// Invalid structure - missing groundingChunks
+							},
+							content: { parts: [{ text: "test response" }] },
+						},
+					],
+					usageMetadata: { promptTokenCount: 10, candidatesTokenCount: 5 },
+				}
+			}
+
+			const stub = vi.fn().mockReturnValue(mockStream())
+			// @ts-ignore access private client
+			handler["client"].models.generateContentStream = stub
+
+			const messages = []
+			for await (const chunk of handler.createMessage("test", [] as any)) {
+				messages.push(chunk)
+			}
+
+			// Should still return the main content without sources
+			expect(messages.some((m) => m.type === "text" && m.text === "test response")).toBe(true)
+			expect(messages.some((m) => m.type === "text" && m.text?.includes("Sources:"))).toBe(false)
+		})
+
+		it("should handle malformed grounding metadata", async () => {
+			const options = {
+				apiProvider: "gemini",
+				enableGrounding: true,
+			} as ApiHandlerOptions
+			const handler = new GeminiHandler(options)
+
+			const mockStream = async function* () {
+				yield {
+					candidates: [
+						{
+							groundingMetadata: {
+								groundingChunks: [
+									{ web: null }, // Missing URI
+									{ web: { uri: "https://example.com" } }, // Valid
+									{}, // Missing web property entirely
+								],
+							},
+							content: { parts: [{ text: "test response" }] },
+						},
+					],
+					usageMetadata: { promptTokenCount: 10, candidatesTokenCount: 5 },
+				}
+			}
+
+			const stub = vi.fn().mockReturnValue(mockStream())
+			// @ts-ignore access private client
+			handler["client"].models.generateContentStream = stub
+
+			const messages = []
+			for await (const chunk of handler.createMessage("test", [] as any)) {
+				messages.push(chunk)
+			}
+
+			// Should only include valid citations
+			const sourceMessage = messages.find((m) => m.type === "text" && m.text?.includes("[2]"))
+			expect(sourceMessage).toBeDefined()
+			if (sourceMessage && "text" in sourceMessage) {
+				expect(sourceMessage.text).toContain("https://example.com")
+				expect(sourceMessage.text).not.toContain("[1]")
+				expect(sourceMessage.text).not.toContain("[3]")
+			}
+		})
+
+		it("should handle API errors when tools are enabled", async () => {
+			const options = {
+				apiProvider: "gemini",
+				enableUrlContext: true,
+				enableGrounding: true,
+			} as ApiHandlerOptions
+			const handler = new GeminiHandler(options)
+
+			const mockError = new Error("API rate limit exceeded")
+			const stub = vi.fn().mockRejectedValue(mockError)
+			// @ts-ignore access private client
+			handler["client"].models.generateContentStream = stub
+
+			await expect(async () => {
+				const generator = handler.createMessage("test", [] as any)
+				await generator.next()
+			}).rejects.toThrow(t("common:errors.gemini.generate_stream", { error: "API rate limit exceeded" }))
+		})
+	})
+})

src/api/providers/__tests__/gemini.spec.ts

@@ -4,6 +4,7 @@ import { Anthropic } from "@anthropic-ai/sdk"
 
 import { type ModelInfo, geminiDefaultModelId } from "@roo-code/types"
 
+import { t } from "i18next"
 import { GeminiHandler } from "../gemini"
 
 const GEMINI_20_FLASH_THINKING_NAME = "gemini-2.0-flash-thinking-exp-1219"
@@ -129,7 +130,7 @@ describe("GeminiHandler", () => {
 			;(handler["client"].models.generateContent as any).mockRejectedValue(mockError)
 
 			await expect(handler.completePrompt("Test prompt")).rejects.toThrow(
-				"Gemini completion error: Gemini API error",
+				t("common:errors.gemini.generate_complete_prompt", { error: "Gemini API error" }),
 			)
 		})
 

src/api/providers/__tests__/vertex.spec.ts

@@ -7,6 +7,7 @@ import { Anthropic } from "@anthropic-ai/sdk"
 
 import { ApiStreamChunk } from "../../transform/stream"
 
+import { t } from "i18next"
 import { VertexHandler } from "../vertex"
 
 describe("VertexHandler", () => {
@@ -105,7 +106,7 @@ describe("VertexHandler", () => {
 			;(handler["client"].models.generateContent as any).mockRejectedValue(mockError)
 
 			await expect(handler.completePrompt("Test prompt")).rejects.toThrow(
-				"Gemini completion error: Vertex API error",
+				t("common:errors.gemini.generate_complete_prompt", { error: "Vertex API error" }),
 			)
 		})